diff options
Diffstat (limited to 'docs/dev/style.md')
-rw-r--r-- | docs/dev/style.md | 21 |
1 files changed, 21 insertions, 0 deletions
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 | ||
84 | If 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. | 84 | If 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 | ||
86 | To make writing the release notes easier, you can mark a pull request as a feature, fix, internal change, or minor. | ||
87 | Minor changes are excluded from the release notes, while the other types are distributed in their corresponding sections. | ||
88 | There 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 | |||
93 | These comments don't have to be added by the PR author. | ||
94 | Editing 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. |
87 | But many users read changelogs. | 97 | But many users read changelogs. |
98 | Including 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. |
154 | This makes it much easier to understand. | 165 | This makes it much easier to understand. |
166 | More than one mark per test / code branch doesn't add significantly to understanding. | ||
167 | |||
168 | ## `#[should_panic]` | ||
169 | |||
170 | Do not use `#[should_panic]` tests. | ||
171 | Instead, 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. | ||
175 | Panic messages in the logs from the `#[should_panic]` tests are confusing. | ||
155 | 176 | ||
156 | ## Function Preconditions | 177 | ## Function Preconditions |
157 | 178 | ||