diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 64 |
1 files changed, 12 insertions, 52 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c952078cf..a2efc7afa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md | |||
| @@ -1,58 +1,18 @@ | |||
| 1 | The project is in its early stages: contributions are welcome and would be | 1 | The project is in its early stages: contributions are welcome and would be |
| 2 | **very** helpful, but the project is not _yet_ optimized for contribution. | 2 | **very** helpful, but the project is not _yet_ optimized for contribution. |
| 3 | Moreover, it is doubly experimental, so there's no guarantee that any work here | 3 | Moreover, it is doubly experimental, so there's no guarantee that any work here |
| 4 | would reach production. That said, here are some areas where contributions would | 4 | would reach production. |
| 5 | be **especially** welcome: | ||
| 6 | 5 | ||
| 7 | - Designing internal data structures: RFC only outlines the constraints, it's an | 6 | To get an idea of how rust-analyzer works, take a look at the [ARCHITECTURE.md](./ARCHITECTURE.md) |
| 8 | open question how to satisfy them in the optimal way. See `ARCHITECTURE.md` | 7 | document. |
| 9 | for current design questions. | ||
| 10 | 8 | ||
| 11 | - Porting libsyntax parser to rust-analyzer: currently rust-analyzer parses only | 9 | Useful labels on the issue tracker: |
| 12 | a tiny subset of Rust. This should be fixed by porting parsing functions from | 10 | * [E-mentor](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-mentor) |
| 13 | libsyntax one by one. Take a look at the [libsyntax parser] for "what to port" | 11 | issues have links to the code in question and tests, |
| 14 | and at the [Kotlin parser] for "how to port". | 12 | * [E-easy](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy), |
| 13 | [E-medium](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-medium), | ||
| 14 | [E-hard](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-hard), | ||
| 15 | labels are *estimates* for how hard would be to write a fix. | ||
| 15 | 16 | ||
| 16 | - Writing validators: by design, rust-analyzer is very lax about the input. For | 17 | There's no formal PR check list: everything that passes CI (we use [bors](https://bors.tech/)) is valid, |
| 17 | example, the lexer happily accepts unclosed strings. The idea is that there | 18 | but it's a good idea to write nice commit messages, test code thoroughly, maintain consistent style, etc. |
| 18 | should be a higher level visitor, which walks the syntax tree after parsing | ||
| 19 | and produces all the warnings. Alas, there's no such visitor yet :( Would you | ||
| 20 | like to write one? :) | ||
| 21 | |||
| 22 | - Creating tests: it would be tremendously helpful to read each of libsyntax and | ||
| 23 | rust-analyzer parser functions and crate a small separate test cases to cover | ||
| 24 | each and every edge case. | ||
| 25 | |||
| 26 | - Building stuff with rust-analyzer: it would be really cool to compile | ||
| 27 | rust-analyzer to WASM and add _client side_ syntax validation to rust | ||
| 28 | playground! | ||
| 29 | |||
| 30 | Do take a look at the issue tracker. | ||
| 31 | |||
| 32 | If you don't know where to start, or have _any_ questions or suggestions, don't | ||
| 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 | ||