src/tools/rust-analyzer/docs/dev/README.md

   1 # Contributing Quick Start
   2
   3 rust-analyzer is an ordinary Rust project, which is organized as a Cargo workspace, builds on stable and doesn't depend on C libraries.
   4 So, just
   5
   6 ```
   7 $ cargo test
   8 ```
   9
  10 should be enough to get you started!
  11
  12 To learn more about how rust-analyzer works, see [./architecture.md](./architecture.md).
  13 It also explains the high-level layout of the source code.
  14 Do skim through that document.
  15
  16 We also publish rustdoc docs to pages: https://rust-lang.github.io/rust-analyzer/ide/.
  17 Note though, that the internal documentation is very incomplete.
  18
  19 Various organizational and process issues are discussed in this document.
  20
  21 # Getting in Touch
  22
  23 rust-analyzer is a part of the [RLS-2.0 working
  24 group](https://github.com/rust-lang/compiler-team/tree/6a769c13656c0a6959ebc09e7b1f7c09b86fb9c0/working-groups/rls-2.0).
  25 Discussion happens in this Zulip stream:
  26
  27 https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Frust-analyzer
  28
  29 # Issue Labels
  30
  31 * [good-first-issue](https://github.com/rust-lang/rust-analyzer/labels/good%20first%20issue)
  32   are good issues to get into the project.
  33 * [E-has-instructions](https://github.com/rust-lang/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-has-instructions)
  34   issues have links to the code in question and tests.
  35 * [Broken Window](https://github.com/rust-lang/rust-analyzer/issues?q=is:issue+is:open+label:%22Broken+Window%22)
  36   are issues which are not necessarily critical by themselves, but which should be fixed ASAP regardless, to avoid accumulation of technical debt.
  37 * [E-easy](https://github.com/rust-lang/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy),
  38   [E-medium](https://github.com/rust-lang/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-medium),
  39   [E-hard](https://github.com/rust-lang/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-hard),
  40   [E-unknown](https://github.com/rust-lang/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-unknown),
  41   labels are *estimates* for how hard would be to write a fix. Each triaged issue should have one of these labels.
  42 * [S-actionable](https://github.com/rust-lang/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AS-actionable) and
  43   [S-unactionable](https://github.com/rust-lang/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AS-unactionable)
  44   specify if there are concrete steps to resolve or advance an issue. Roughly, actionable issues need only work to be fixed,
  45   while unactionable ones are blocked either on user feedback (providing a reproducible example), or on larger architectural
  46   work or decisions. This classification is descriptive, not prescriptive, and might be wrong: Any unactionable issue might have a simple fix that we missed.
  47   Each triaged issue should have one of these labels.
  48 * [fun](https://github.com/rust-lang/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3Afun)
  49   is for cool, but probably hard stuff.
  50 * [Design](https://github.com/rust-lang/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%Design)
  51   is for moderate/large scale architecture discussion.
  52   Also a kind of fun.
  53   These issues should generally include a link to a Zulip discussion thread.
  54
  55 # Code Style & Review Process
  56
  57 Do see [./style.md](./style.md).
  58
  59 # Cookbook
  60
  61 ## CI
  62
  63 We use GitHub Actions for CI.
  64 Most of the things, including formatting, are checked by `cargo test`.
  65 If `cargo test` passes locally, that's a good sign that CI will be green as well.
  66 The only exception is that some long-running tests are skipped locally by default.
  67 Use `env RUN_SLOW_TESTS=1 cargo test` to run the full suite.
  68
  69 We use bors to enforce the [not rocket science](https://graydon2.dreamwidth.org/1597.html) rule.
  70
  71 ## Launching rust-analyzer
  72
  73 Debugging the language server can be tricky.
  74 LSP is rather chatty, so driving it from the command line is not really feasible, driving it via VS Code requires interacting with two processes.
  75
  76 For this reason, the best way to see how rust-analyzer works is to **find a relevant test and execute it**.
  77 VS Code & Emacs include an action for running a single test.
  78
  79 Launching a VS Code instance with a locally built language server is also possible.
  80 There's **"Run Extension (Debug Build)"** launch configuration for this in VS Code.
  81
  82 In general, I use one of the following workflows for fixing bugs and implementing features:
  83
  84 If the problem concerns only internal parts of rust-analyzer (i.e. I don't need to touch the `rust-analyzer` crate or TypeScript code), there is a unit-test for it.
  85 So, I use **rust-analyzer: Run** action in VS Code to run this single test, and then just do printf-driven development/debugging.
  86 As a sanity check after I'm done, I use `cargo xtask install --server` and **Reload Window** action in VS Code to verify that the thing works as I expect.
  87
  88 If the problem concerns only the VS Code extension, I use **Run Installed Extension** launch configuration from `launch.json`.
  89 Notably, this uses the usual `rust-analyzer` binary from `PATH`.
  90 For this, it is important to have the following in your `settings.json` file:
  91 ```json
  92 {
  93     "rust-analyzer.server.path": "rust-analyzer"
  94 }
  95 ```
  96 After I am done with the fix, I use `cargo xtask install --client` to try the new extension for real.
  97
  98 If I need to fix something in the `rust-analyzer` crate, I feel sad because it's on the boundary between the two processes, and working there is slow.
  99 I usually just `cargo xtask install --server` and poke changes from my live environment.
 100 Note that this uses `--release`, which is usually faster overall, because loading stdlib into debug version of rust-analyzer takes a lot of time.
 101 To speed things up, sometimes I open a temporary hello-world project which has `"rust-analyzer.cargo.sysroot": null` in `.code/settings.json`.
 102 This flag causes rust-analyzer to skip loading the sysroot, which greatly reduces the amount of things rust-analyzer needs to do, and makes printf's more useful.
 103 Note that you should only use the `eprint!` family of macros for debugging: stdout is used for LSP communication, and `print!` would break it.
 104
 105 If I need to fix something simultaneously in the server and in the client, I feel even more sad.
 106 I don't have a specific workflow for this case.
 107
 108 Additionally, I use `cargo run --release -p rust-analyzer -- analysis-stats path/to/some/rust/crate` to run a batch analysis.
 109 This is primarily useful for performance optimizations, or for bug minimization.
 110
 111 ## TypeScript Tests
 112
 113 If you change files under `editors/code` and would like to run the tests and linter, install npm and run:
 114
 115 ```bash
 116 cd editors/code
 117 npm ci
 118 npm run lint
 119 ```
 120 ## How to ...
 121
 122 * ... add an assist? [#7535](https://github.com/rust-lang/rust-analyzer/pull/7535)
 123 * ... add a new protocol extension? [#4569](https://github.com/rust-lang/rust-analyzer/pull/4569)
 124 * ... add a new configuration option? [#7451](https://github.com/rust-lang/rust-analyzer/pull/7451)
 125 * ... add a new completion? [#6964](https://github.com/rust-lang/rust-analyzer/pull/6964)
 126 * ... allow new syntax in the parser? [#7338](https://github.com/rust-lang/rust-analyzer/pull/7338)
 127
 128 ## Logging
 129
 130 Logging is done by both rust-analyzer and VS Code, so it might be tricky to figure out where logs go.
 131
 132 Inside rust-analyzer, we use the [`tracing`](https://docs.rs/tracing/) crate for logging,
 133 and [`tracing-subscriber`](https://docs.rs/tracing-subscriber) for logging frontend.
 134 By default, log goes to stderr, but the stderr itself is processed by VS Code.
 135 `--log-file <PATH>` CLI argument allows logging to file.
 136 Setting the `RA_LOG_FILE=<PATH>` environment variable will also log to file, it will also override `--log-file`.
 137
 138 To see stderr in the running VS Code instance, go to the "Output" tab of the panel and select `rust-analyzer`.
 139 This shows `eprintln!` as well.
 140 Note that `stdout` is used for the actual protocol, so `println!` will break things.
 141
 142 To log all communication between the server and the client, there are two choices:
 143
 144 * You can log on the server side, by running something like
 145   ```
 146   env RA_LOG=lsp_server=debug code .
 147   ```
 148 * You can log on the client side, by enabling `"rust-analyzer.trace.server": "verbose"` workspace setting.
 149   These logs are shown in a separate tab in the output and could be used with LSP inspector.
 150   Kudos to [@DJMcNab](https://github.com/DJMcNab) for setting this awesome infra up!
 151
 152
 153 There are also several VS Code commands which might be of interest:
 154
 155 * `rust-analyzer: Status` shows some memory-usage statistics.
 156
 157 * `rust-analyzer: Syntax Tree` shows syntax tree of the current file/selection.
 158
 159 * `rust-analyzer: View Hir` shows the HIR expressions within the function containing the cursor.
 160
 161   You can hover over syntax nodes in the opened text file to see the appropriate
 162   rust code that it refers to and the rust editor will also highlight the proper
 163   text range.
 164
 165   If you trigger Go to Definition in the inspected Rust source file,
 166   the syntax tree read-only editor should scroll to and select the
 167   appropriate syntax node token.
 168
 169   ![demo](https://user-images.githubusercontent.com/36276403/78225773-6636a480-74d3-11ea-9d9f-1c9d42da03b0.png)
 170
 171 ## Profiling
 172
 173 We have a built-in hierarchical profiler, you can enable it by using `RA_PROFILE` env-var:
 174
 175 ```
 176 RA_PROFILE=*             // dump everything
 177 RA_PROFILE=foo|bar|baz   // enabled only selected entries
 178 RA_PROFILE=*@3>10        // dump everything, up to depth 3, if it takes more than 10 ms
 179 ```
 180
 181 In particular, I have `export RA_PROFILE='*>10'` in my shell profile.
 182
 183 We also have a "counting" profiler which counts number of instances of popular structs.
 184 It is enabled by `RA_COUNT=1`.
 185
 186 To measure time for from-scratch analysis, use something like this:
 187
 188 ```
 189 $ cargo run --release -p rust-analyzer -- analysis-stats ../chalk/
 190 ```
 191
 192 For measuring time of incremental analysis, use either of these:
 193
 194 ```
 195 $ cargo run --release -p rust-analyzer -- analysis-bench ../chalk/ --highlight ../chalk/chalk-engine/src/logic.rs
 196 $ cargo run --release -p rust-analyzer -- analysis-bench ../chalk/ --complete ../chalk/chalk-engine/src/logic.rs:94:0
 197 ```
 198
 199 Look for `fn benchmark_xxx` tests for a quick way to reproduce performance problems.
 200
 201 ## Release Process
 202
 203 Release process is handled by `release`, `dist` and `promote` xtasks, `release` being the main one.
 204
 205 `release` assumes that you have checkouts of `rust-analyzer`, `rust-analyzer.github.io`, and `rust-lang/rust` in the same directory:
 206
 207 ```
 208 ./rust-analyzer
 209 ./rust-analyzer.github.io
 210 ./rust-rust-analyzer  # Note the name!
 211 ```
 212
 213 The remote for `rust-analyzer` must be called `upstream` (I use `origin` to point to my fork).
 214 In addition, for `xtask promote` (see below), `rust-rust-analyzer` must have a `rust-analyzer` remote pointing to this repository on GitHub.
 215
 216 `release` calls the GitHub API calls to scrape pull request comments and categorize them in the changelog.
 217 This step uses the `curl` and `jq` applications, which need to be available in `PATH`.
 218 Finally, you need to obtain a GitHub personal access token and set the `GITHUB_TOKEN` environment variable.
 219
 220 Release steps:
 221
 222 1. Set the `GITHUB_TOKEN` environment variable.
 223 2. Inside rust-analyzer, run `cargo xtask release`. This will:
 224    * checkout the `release` branch
 225    * reset it to `upstream/nightly`
 226    * push it to `upstream`. This triggers GitHub Actions which:
 227      * runs `cargo xtask dist` to package binaries and VS Code extension
 228      * makes a GitHub release
 229      * publishes the VS Code extension to the marketplace
 230    * call the GitHub API for PR details
 231    * create a new changelog in `rust-analyzer.github.io`
 232 3. While the release is in progress, fill in the changelog
 233 4. Commit & push the changelog
 234 5. Tweet
 235 6. Inside `rust-analyzer`, run `cargo xtask promote` -- this will create a PR to rust-lang/rust updating rust-analyzer's subtree.
 236    Self-approve the PR.
 237
 238 If the GitHub Actions release fails because of a transient problem like a timeout, you can re-run the job from the Actions console.
 239 If it fails because of something that needs to be fixed, remove the release tag (if needed), fix the problem, then start over.
 240 Make sure to remove the new changelog post created when running `cargo xtask release` a second time.
 241
 242 We release "nightly" every night automatically and promote the latest nightly to "stable" manually, every week.
 243
 244 We don't do "patch" releases, unless something truly egregious comes up.
 245 To do a patch release, cherry-pick the fix on top of the current `release` branch and push the branch.
 246 There's no need to write a changelog for a patch release, it's OK to include the notes about the fix into the next weekly one.
 247 Note: we tag releases by dates, releasing a patch release on the same day should work (by overwriting a tag), but I am not 100% sure.
 248
 249 ## Permissions
 250
 251 There are three sets of people with extra permissions:
 252
 253 * rust-analyzer GitHub organization [**admins**](https://github.com/orgs/rust-analyzer/people?query=role:owner) (which include current t-compiler leads).
 254   Admins have full access to the org.
 255 * [**review**](https://github.com/orgs/rust-analyzer/teams/review) team in the organization.
 256   Reviewers have `r+` access to all of organization's repositories and publish rights on crates.io.
 257   They also have direct commit access, but all changes should via bors queue.
 258   It's ok to self-approve if you think you know what you are doing!
 259   bors should automatically sync the permissions.
 260   Feel free to request a review or assign any PR to a reviewer with the relevant expertise to bring the work to their attention.
 261   Don't feel pressured to review assigned PRs though.
 262   If you don't feel like reviewing for whatever reason, someone else will pick the review up!
 263 * [**triage**](https://github.com/orgs/rust-analyzer/teams/triage) team in the organization.
 264   This team can label and close issues.
 265
 266 Note that at the time being you need to be a member of the org yourself to view the links.