diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 88 |
1 files changed, 54 insertions, 34 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 41954c02e..c952078cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md | |||
| @@ -1,38 +1,58 @@ | |||
| 1 | The project is in its early stages: contributions are welcome and | 1 | The project is in its early stages: contributions are welcome and would be |
| 2 | would be **very** helpful, but the project is not *yet* optimized for | 2 | **very** helpful, but the project is not _yet_ optimized for contribution. |
| 3 | contribution. Moreover, it is doubly experimental, so there's no | 3 | Moreover, it is doubly experimental, so there's no guarantee that any work here |
| 4 | guarantee that any work here would reach production. That said, here | 4 | would reach production. That said, here are some areas where contributions would |
| 5 | are some areas where contributions would be **especially** welcome: | 5 | be **especially** welcome: |
| 6 | 6 | ||
| 7 | 7 | - Designing internal data structures: RFC only outlines the constraints, it's an | |
| 8 | * Designing internal data structures: RFC only outlines the | 8 | open question how to satisfy them in the optimal way. See `ARCHITECTURE.md` |
| 9 | constraints, it's an open question how to satisfy them in the | 9 | for current design questions. |
| 10 | optimal way. See `ARCHITECTURE.md` for current design questions. | 10 | |
| 11 | 11 | - Porting libsyntax parser to rust-analyzer: currently rust-analyzer parses only | |
| 12 | * Porting libsyntax parser to rust-analyzer: currently rust-analyzer parses | 12 | a tiny subset of Rust. This should be fixed by porting parsing functions from |
| 13 | only a tiny subset of Rust. This should be fixed by porting parsing | 13 | libsyntax one by one. Take a look at the [libsyntax parser] for "what to port" |
| 14 | functions from libsyntax one by one. Take a look at the | 14 | and at the [Kotlin parser] for "how to port". |
| 15 | [libsyntax parser](https://github.com/rust-lang/rust/blob/6b99adeb11313197f409b4f7c4083c2ceca8a4fe/src/libsyntax/parse/parser.rs) | 15 | |
| 16 | for "what to port" and at the | 16 | - Writing validators: by design, rust-analyzer is very lax about the input. For |
| 17 | [Kotlin parser](https://github.com/JetBrains/kotlin/blob/4d951de616b20feca92f3e9cc9679b2de9e65195/compiler/frontend/src/org/jetbrains/kotlin/parsing/KotlinParsing.java) | 17 | example, the lexer happily accepts unclosed strings. The idea is that there |
| 18 | for "how to port". | 18 | should be a higher level visitor, which walks the syntax tree after parsing |
| 19 | 19 | and produces all the warnings. Alas, there's no such visitor yet :( Would you | |
| 20 | * Writing validators: by design, rust-analyzer is very lax about the | 20 | like to write one? :) |
| 21 | input. For example, the lexer happily accepts unclosed strings. The | 21 | |
| 22 | idea is that there should be a higher level visitor, which walks the | 22 | - Creating tests: it would be tremendously helpful to read each of libsyntax and |
| 23 | syntax tree after parsing and produces all the warnings. Alas, | 23 | rust-analyzer parser functions and crate a small separate test cases to cover |
| 24 | there's no such visitor yet :( Would you like to write one? :) | 24 | each and every edge case. |
| 25 | 25 | ||
| 26 | * Creating tests: it would be tremendously helpful to read each of | 26 | - Building stuff with rust-analyzer: it would be really cool to compile |
| 27 | libsyntax and rust-analyzer parser functions and crate a small separate | 27 | rust-analyzer to WASM and add _client side_ syntax validation to rust |
| 28 | test cases to cover each and every edge case. | ||
| 29 | |||
| 30 | * Building stuff with rust-analyzer: it would be really cool to compile | ||
| 31 | rust-analyzer to WASM and add *client side* syntax validation to rust | ||
| 32 | playground! | 28 | playground! |
| 33 | 29 | ||
| 34 | |||
| 35 | Do take a look at the issue tracker. | 30 | Do take a look at the issue tracker. |
| 36 | 31 | ||
| 37 | If you don't know where to start, or have *any* questions or suggestions, | 32 | If you don't know where to start, or have _any_ questions or suggestions, don't |
| 38 | don't hesitate to chat at [Gitter](https://gitter.im/libsyntax2/Lobby)! | 33 | hesitate to chat at [Gitter]! |
| 34 | |||
| 35 | # Code generation | ||
| 36 | |||
| 37 | Some of the components of this repository are generated through automatic | ||
| 38 | processes. These are outlined below: | ||
| 39 | |||
| 40 | - `gen-kinds`: The kinds of tokens are reused in several places, so a generator | ||
| 41 | is used. This process uses [tera] to generate, using data in [grammar.ron], | ||
| 42 | the files: | ||
| 43 | - [ast/generated.rs][ast generated] in `ra_syntax` based on | ||
| 44 | [ast/generated.tera.rs][ast source] | ||
| 45 | - [syntax_kinds/generated.rs][syntax_kinds generated] in `ra_syntax` based on | ||
| 46 | [syntax_kinds/generated.tera.rs][syntax_kinds source] | ||
| 47 | |||
| 48 | [libsyntax parser]: | ||
| 49 | https://github.com/rust-lang/rust/blob/6b99adeb11313197f409b4f7c4083c2ceca8a4fe/src/libsyntax/parse/parser.rs | ||
| 50 | [kotlin parser]: | ||
| 51 | https://github.com/JetBrains/kotlin/blob/4d951de616b20feca92f3e9cc9679b2de9e65195/compiler/frontend/src/org/jetbrains/kotlin/parsing/KotlinParsing.java | ||
| 52 | [gitter]: https://gitter.im/libsyntax2/Lobby | ||
| 53 | [tera]: https://tera.netlify.com/ | ||
| 54 | [grammar.ron]: ./crates/ra_syntax/src/grammar.ron | ||
| 55 | [ast generated]: ./crates/ra_syntax/src/ast/generated.rs | ||
| 56 | [ast source]: ./crates/ra_syntax/src/ast/generated.tera.rs | ||
| 57 | [syntax_kinds generated]: ./crates/ra_syntax/src/syntax_kinds/generated.rs | ||
| 58 | [syntax_kinds source]: ./crates/ra_syntax/src/syntax_kinds/generated.tera.rs | ||