aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/dev/README.md33
-rw-r--r--docs/dev/lsp-extensions.md20
-rw-r--r--docs/dev/style.md21
-rw-r--r--docs/user/generated_config.adoc6
-rw-r--r--docs/user/manual.adoc76
5 files changed, 113 insertions, 43 deletions
diff --git a/docs/dev/README.md b/docs/dev/README.md
index 9c0eb1358..16b23adc6 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -208,20 +208,26 @@ Release process is handled by `release`, `dist` and `promote` xtasks, `release`
208 208
209Additionally, it assumes that remote for `rust-analyzer` is called `upstream` (I use `origin` to point to my fork). 209Additionally, it assumes that remote for `rust-analyzer` is called `upstream` (I use `origin` to point to my fork).
210 210
211`release` calls the GitHub API calls to scrape pull request comments and categorize them in the changelog.
212This step uses the `curl` and `jq` applications, which need to be available in `PATH`.
213Finally, you need to obtain a GitHub personal access token and set the `GITHUB_TOKEN` environment variable.
214
211Release steps: 215Release steps:
212 216
2131. Inside rust-analyzer, run `cargo xtask release`. This will: 2171. Set the `GITHUB_TOKEN` environment variable.
2182. Inside rust-analyzer, run `cargo xtask release`. This will:
214 * checkout the `release` branch 219 * checkout the `release` branch
215 * reset it to `upstream/nightly` 220 * reset it to `upstream/nightly`
216 * push it to `upstream`. This triggers GitHub Actions which: 221 * push it to `upstream`. This triggers GitHub Actions which:
217 * runs `cargo xtask dist` to package binaries and VS Code extension 222 * runs `cargo xtask dist` to package binaries and VS Code extension
218 * makes a GitHub release 223 * makes a GitHub release
219 * pushes VS Code extension to the marketplace 224 * pushes VS Code extension to the marketplace
220 * create new changelog in `rust-analyzer.github.io` 225 * call the GitHub API for PR details
2212. While the release is in progress, fill in the changelog 226 * create a new changelog in `rust-analyzer.github.io`
2223. Commit & push the changelog 2273. While the release is in progress, fill in the changelog
2234. Tweet 2284. Commit & push the changelog
2245. Inside `rust-analyzer`, run `cargo xtask promote` -- this will create a PR to rust-lang/rust updating rust-analyzer's submodule. 2295. Tweet
2306. Inside `rust-analyzer`, run `cargo xtask promote` -- this will create a PR to rust-lang/rust updating rust-analyzer's submodule.
225 Self-approve the PR. 231 Self-approve the PR.
226 232
227If the GitHub Actions release fails because of a transient problem like a timeout, you can re-run the job from the Actions console. 233If the GitHub Actions release fails because of a transient problem like a timeout, you can re-run the job from the Actions console.
@@ -229,18 +235,27 @@ If it fails because of something that needs to be fixed, remove the release tag
229Make sure to remove the new changelog post created when running `cargo xtask release` a second time. 235Make sure to remove the new changelog post created when running `cargo xtask release` a second time.
230 236
231We release "nightly" every night automatically and promote the latest nightly to "stable" manually, every week. 237We release "nightly" every night automatically and promote the latest nightly to "stable" manually, every week.
238
232We don't do "patch" releases, unless something truly egregious comes up. 239We don't do "patch" releases, unless something truly egregious comes up.
240To do a patch release, cherry-pick the fix on top of the current `release` branch and push the branch.
241There'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.
242Note: 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.
233 243
234## Permissions 244## Permissions
235 245
236There are three sets of people with extra permissions: 246There are three sets of people with extra permissions:
237 247
238* rust-analyzer GitHub organization **admins** (which include current t-compiler leads). 248* rust-analyzer GitHub organization [**admins**](https://github.com/orgs/rust-analyzer/people?query=role:owner) (which include current t-compiler leads).
239 Admins have full access to the org. 249 Admins have full access to the org.
240* **review** team in the organization. 250* [**review**](https://github.com/orgs/rust-analyzer/teams/review) team in the organization.
241 Reviewers have `r+` access to all of organization's repositories and publish rights on crates.io. 251 Reviewers have `r+` access to all of organization's repositories and publish rights on crates.io.
242 They also have direct commit access, but all changes should via bors queue. 252 They also have direct commit access, but all changes should via bors queue.
243 It's ok to self-approve if you think you know what you are doing! 253 It's ok to self-approve if you think you know what you are doing!
244 bors should automatically sync the permissions. 254 bors should automatically sync the permissions.
245* **triage** team in the organization. 255 Feel free to request a review or assign any PR to a reviewer with the relevant expertise to bring the work to their attention.
256 Don't feel pressured to review assigned PRs though.
257 If you don't feel like reviewing for whatever reason, someone else will pick the review up!
258* [**triage**](https://github.com/orgs/rust-analyzer/teams/triage) team in the organization.
246 This team can label and close issues. 259 This team can label and close issues.
260
261Note that at the time being you need to be a member of the org yourself to view the links.
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index a46121bb2..f0f981802 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -1,8 +1,8 @@
1<!--- 1<!---
2lsp_ext.rs hash: faae991334a151d0 2lsp_ext.rs hash: 28a9d5a24b7ca396
3 3
4If you need to change the above hash to make the test pass, please check if you 4If you need to change the above hash to make the test pass, please check if you
5need to adjust this doc as well and ping this issue: 5need to adjust this doc as well and ping this issue:
6 6
7 https://github.com/rust-analyzer/rust-analyzer/issues/4604 7 https://github.com/rust-analyzer/rust-analyzer/issues/4604
8 8
@@ -46,6 +46,7 @@ If this capability is set, `WorkspaceEdit`s returned from `codeAction` requests
46```typescript 46```typescript
47interface SnippetTextEdit extends TextEdit { 47interface SnippetTextEdit extends TextEdit {
48 insertTextFormat?: InsertTextFormat; 48 insertTextFormat?: InsertTextFormat;
49 annotationId?: ChangeAnnotationIdentifier;
49} 50}
50``` 51```
51 52
@@ -421,7 +422,7 @@ Reloads project information (that is, re-executes `cargo metadata`).
421 422
422## Server Status 423## Server Status
423 424
424**Experimental Client Capability:** `{ "serverStatus": boolean }` 425**Experimental Client Capability:** `{ "serverStatusNotification": boolean }`
425 426
426**Method:** `experimental/serverStatus` 427**Method:** `experimental/serverStatus`
427 428
@@ -432,11 +433,13 @@ interface ServerStatusParams {
432 /// `ok` means that the server is completely functional. 433 /// `ok` means that the server is completely functional.
433 /// 434 ///
434 /// `warning` means that the server is partially functional. 435 /// `warning` means that the server is partially functional.
435 /// It can server requests, but some results might be wrong due to, 436 /// It can answer correctly to most requests, but some results
436 /// for example, some missing dependencies. 437 /// might be wrong due to, for example, some missing dependencies.
437 /// 438 ///
438 /// `error` means that the server is not functional. For example, 439 /// `error` means that the server is not functional. For example,
439 /// there's a fatal build configuration problem. 440 /// there's a fatal build configuration problem. The server might
441 /// still give correct answers to simple requests, but most results
442 /// will be incomplete or wrong.
440 health: "ok" | "warning" | "error", 443 health: "ok" | "warning" | "error",
441 /// Is there any pending background work which might change the status? 444 /// Is there any pending background work which might change the status?
442 /// For example, are dependencies being downloaded? 445 /// For example, are dependencies being downloaded?
@@ -450,6 +453,9 @@ This notification is sent from server to client.
450The client can use it to display *persistent* status to the user (in modline). 453The client can use it to display *persistent* status to the user (in modline).
451It is similar to the `showMessage`, but is intended for stares rather than point-in-time events. 454It is similar to the `showMessage`, but is intended for stares rather than point-in-time events.
452 455
456Note that this functionality is intended primarily to inform the end user about the state of the server.
457In particular, it's valid for the client to completely ignore this extension.
458Clients are discouraged from but are allowed to use the `health` status to decide if it's worth sending a request to the server.
453 459
454## Syntax Tree 460## Syntax Tree
455 461
@@ -620,7 +626,7 @@ This request is sent from client to server to move item under cursor or selectio
620 626
621**Request:** `MoveItemParams` 627**Request:** `MoveItemParams`
622 628
623**Response:** `TextDocumentEdit | null` 629**Response:** `SnippetTextEdit[]`
624 630
625```typescript 631```typescript
626export interface MoveItemParams { 632export interface MoveItemParams {
diff --git a/docs/dev/style.md b/docs/dev/style.md
index 468dedff2..6ab60b50e 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -83,8 +83,19 @@ This makes it easier to prepare a changelog.
83 83
84If the change adds a new user-visible functionality, consider recording a GIF with [peek](https://github.com/phw/peek) and pasting it into the PR description. 84If the change adds a new user-visible functionality, consider recording a GIF with [peek](https://github.com/phw/peek) and pasting it into the PR description.
85 85
86To make writing the release notes easier, you can mark a pull request as a feature, fix, internal change, or minor.
87Minor changes are excluded from the release notes, while the other types are distributed in their corresponding sections.
88There are two ways to mark this:
89
90* use a `feat: `, `feature: `, `fix: `, `internal: ` or `minor: ` prefix in the PR title
91* write `changelog [feature|fix|internal|skip] [description]` in a comment or in the PR description; the description is optional, and will replace the title if included.
92
93These comments don't have to be added by the PR author.
94Editing a comment or the PR description or title is also fine, as long as it happens before the release.
95
86**Rationale:** clean history is potentially useful, but rarely used. 96**Rationale:** clean history is potentially useful, but rarely used.
87But many users read changelogs. 97But many users read changelogs.
98Including a description and GIF suitable for the changelog means less work for the maintainers on the release day.
88 99
89## Clippy 100## Clippy
90 101
@@ -152,6 +163,16 @@ Do not reuse marks between several tests.
152 163
153**Rationale:** marks provide an easy way to find the canonical test for each bit of code. 164**Rationale:** marks provide an easy way to find the canonical test for each bit of code.
154This makes it much easier to understand. 165This makes it much easier to understand.
166More than one mark per test / code branch doesn't add significantly to understanding.
167
168## `#[should_panic]`
169
170Do not use `#[should_panic]` tests.
171Instead, explicitly check for `None`, `Err`, etc.
172
173**Rationale:** `#[should_panic]` is a tool for library authors, to makes sure that API does not fail silently, when misused.
174`rust-analyzer` is not a library, we don't need to test for API misuse, and we have to handle any user input without panics.
175Panic messages in the logs from the `#[should_panic]` tests are confusing.
155 176
156## Function Preconditions 177## Function Preconditions
157 178
diff --git a/docs/user/generated_config.adoc b/docs/user/generated_config.adoc
index e0ee35b4e..e28423e99 100644
--- a/docs/user/generated_config.adoc
+++ b/docs/user/generated_config.adoc
@@ -147,6 +147,12 @@ have more false positives than usual.
147-- 147--
148List of rust-analyzer diagnostics to disable. 148List of rust-analyzer diagnostics to disable.
149-- 149--
150[[rust-analyzer.diagnostics.remapPrefix]]rust-analyzer.diagnostics.remapPrefix (default: `{}`)::
151+
152--
153Map of prefixes to be substituted when parsing diagnostic file paths.
154This should be the reverse mapping of what is passed to `rustc` as `--remap-path-prefix`.
155--
150[[rust-analyzer.diagnostics.warningsAsHint]]rust-analyzer.diagnostics.warningsAsHint (default: `[]`):: 156[[rust-analyzer.diagnostics.warningsAsHint]]rust-analyzer.diagnostics.warningsAsHint (default: `[]`)::
151+ 157+
152-- 158--
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
index 7510736e9..58722aaa3 100644
--- a/docs/user/manual.adoc
+++ b/docs/user/manual.adoc
@@ -429,24 +429,32 @@ However, if you use some other build system, you'll have to describe the structu
429[source,TypeScript] 429[source,TypeScript]
430---- 430----
431interface JsonProject { 431interface JsonProject {
432 /// Path to the directory with *source code* of sysroot crates. 432 /// Path to the directory with *source code* of
433 /// sysroot crates.
434 ///
435 /// It should point to the directory where std,
436 /// core, and friends can be found:
433 /// 437 ///
434 /// It should point to the directory where std, core, and friends can be found:
435 /// https://github.com/rust-lang/rust/tree/master/library. 438 /// https://github.com/rust-lang/rust/tree/master/library.
436 /// 439 ///
437 /// If provided, rust-analyzer automatically adds dependencies on sysroot 440 /// If provided, rust-analyzer automatically adds
438 /// crates. Conversely, if you omit this path, you can specify sysroot 441 /// dependencies on sysroot crates. Conversely,
439 /// dependencies yourself and, for example, have several different "sysroots" in 442 /// if you omit this path, you can specify sysroot
440 /// one graph of crates. 443 /// dependencies yourself and, for example, have
444 /// several different "sysroots" in one graph of
445 /// crates.
441 sysroot_src?: string; 446 sysroot_src?: string;
442 /// The set of crates comprising the current project. 447 /// The set of crates comprising the current
443 /// Must include all transitive dependencies as well as sysroot crate (libstd, libcore and such). 448 /// project. Must include all transitive
449 /// dependencies as well as sysroot crate (libstd,
450 /// libcore and such).
444 crates: Crate[]; 451 crates: Crate[];
445} 452}
446 453
447interface Crate { 454interface Crate {
448 /// Optional crate name used for display purposes, without affecting semantics. 455 /// Optional crate name used for display purposes,
449 /// See the `deps` key for semantically-significant crate names. 456 /// without affecting semantics. See the `deps`
457 /// key for semantically-significant crate names.
450 display_name?: string; 458 display_name?: string;
451 /// Path to the root module of the crate. 459 /// Path to the root module of the crate.
452 root_module: string; 460 root_module: string;
@@ -454,45 +462,59 @@ interface Crate {
454 edition: "2015" | "2018" | "2021"; 462 edition: "2015" | "2018" | "2021";
455 /// Dependencies 463 /// Dependencies
456 deps: Dep[]; 464 deps: Dep[];
457 /// Should this crate be treated as a member of current "workspace". 465 /// Should this crate be treated as a member of
466 /// current "workspace".
458 /// 467 ///
459 /// By default, inferred from the `root_module` (members are the crates which reside 468 /// By default, inferred from the `root_module`
460 /// inside the directory opened in the editor). 469 /// (members are the crates which reside inside
470 /// the directory opened in the editor).
461 /// 471 ///
462 /// Set this to `false` for things like standard library and 3rd party crates to 472 /// Set this to `false` for things like standard
463 /// enable performance optimizations (rust-analyzer assumes that non-member crates 473 /// library and 3rd party crates to enable
464 /// don't change). 474 /// performance optimizations (rust-analyzer
475 /// assumes that non-member crates don't change).
465 is_workspace_member?: boolean; 476 is_workspace_member?: boolean;
466 /// Optionally specify the (super)set of `.rs` files comprising this crate. 477 /// Optionally specify the (super)set of `.rs`
478 /// files comprising this crate.
467 /// 479 ///
468 /// By default, rust-analyzer assumes that only files under `root_module.parent` can belong to a crate. 480 /// By default, rust-analyzer assumes that only
469 /// `include_dirs` are included recursively, unless a subdirectory is in `exclude_dirs`. 481 /// files under `root_module.parent` can belong
482 /// to a crate. `include_dirs` are included
483 /// recursively, unless a subdirectory is in
484 /// `exclude_dirs`.
470 /// 485 ///
471 /// Different crates can share the same `source`. 486 /// Different crates can share the same `source`.
472 /// 487 ///
473 /// If two crates share an `.rs` file in common, they *must* have the same `source`. 488 /// If two crates share an `.rs` file in common,
474 /// rust-analyzer assumes that files from one source can't refer to files in another source. 489 /// they *must* have the same `source`.
490 /// rust-analyzer assumes that files from one
491 /// source can't refer to files in another source.
475 source?: { 492 source?: {
476 include_dirs: string[], 493 include_dirs: string[],
477 exclude_dirs: string[], 494 exclude_dirs: string[],
478 }, 495 },
479 /// The set of cfgs activated for a given crate, like `["unix", "feature=\"foo\"", "feature=\"bar\""]`. 496 /// The set of cfgs activated for a given crate, like
497 /// `["unix", "feature=\"foo\"", "feature=\"bar\""]`.
480 cfg: string[]; 498 cfg: string[];
481 /// Target triple for this Crate. 499 /// Target triple for this Crate.
482 /// 500 ///
483 /// Used when running `rustc --print cfg` to get target-specific cfgs. 501 /// Used when running `rustc --print cfg`
502 /// to get target-specific cfgs.
484 target?: string; 503 target?: string;
485 /// Environment variables, used for the `env!` macro 504 /// Environment variables, used for
505 /// the `env!` macro
486 env: : { [key: string]: string; }, 506 env: : { [key: string]: string; },
487 507
488 /// For proc-macro crates, path to compiles proc-macro (.so file). 508 /// For proc-macro crates, path to compiled
509 /// proc-macro (.so file).
489 proc_macro_dylib_path?: string; 510 proc_macro_dylib_path?: string;
490} 511}
491 512
492interface Dep { 513interface Dep {
493 /// Index of a crate in the `crates` array. 514 /// Index of a crate in the `crates` array.
494 crate: number, 515 crate: number,
495 /// Name as should appear in the (implicit) `extern crate name` declaration. 516 /// Name as should appear in the (implicit)
517 /// `extern crate name` declaration.
496 name: string, 518 name: string,
497} 519}
498---- 520----
@@ -541,7 +563,7 @@ include::./generated_assists.adoc[]
541== Diagnostics 563== Diagnostics
542 564
543While most errors and warnings provided by rust-analyzer come from the `cargo check` integration, there's a growing number of diagnostics implemented using rust-analyzer's own analysis. 565While most errors and warnings provided by rust-analyzer come from the `cargo check` integration, there's a growing number of diagnostics implemented using rust-analyzer's own analysis.
544These diagnostics don't respect `#[allow]` or `#[deny]` attributes yet, but can be turned off using the `rust-analyzer.diagnostics.enable`, `rust-analyzer.diagnostics.enableExperimental` or `rust-analyzer.diagnostics.disabled` settings. 566Some of these diagnostics don't respect `\#[allow]` or `\#[deny]` attributes yet, but can be turned off using the `rust-analyzer.diagnostics.enable`, `rust-analyzer.diagnostics.enableExperimental` or `rust-analyzer.diagnostics.disabled` settings.
545 567
546include::./generated_diagnostic.adoc[] 568include::./generated_diagnostic.adoc[]
547 569