biomejs
diff --git a/‎.github/PULL_REQUEST_TEMPLATE.md‎
Lines changed: 8 additions & 0 deletions b/‎.github/PULL_REQUEST_TEMPLATE.md‎
Lines changed: 8 additions & 0 deletions
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 30 additions & 14 deletions b/‎CONTRIBUTING.md‎
Lines changed: 30 additions & 14 deletions
@@ -11,6 +11,14 @@
 
 <!-- Link any relevant issues if necessary or include a transcript of any Discord discussion. -->
 
+<!-- If you create a user-facing change, please write a changeset: https://github.com/biomejs/biome/blob/main/CONTRIBUTING.md#writing-a-changeset (your changeset is often a good starting point for this summary as well) -->
+
 ## Test Plan
 
 <!-- What demonstrates that your implementation is correct? -->
+
+## Docs
+
+<!-- If you're submitting a new rule or action (or an option for them), the documentation is part of the code. Make sure rules and actions have example usages, and that all options are documented. -->
+
+<!-- For other features, please submit a documentation PR to the `next` branch of our website: https://github.com/biomejs/website/. Link the PR here once it's ready. -->
@@ -365,7 +365,12 @@ We are using [action-semantic-pull-request](https://github.com/amannn/action-sem
 When creating a new pull request, it's preferable to use a conventional commit-formatted title, as this title will be used as the default commit message on the squashed commit after merging.
 See the [dedicated section](#commit-messages) about conventional commit format.
 
-Please use the template provided.
+When creating a PR, follow the following instructions:
+- if you fix a bug (code or documentation), send a PR to the maintenance branch `main`.
+- if you add a **new nursery rule**, send a PR to the maintenance branch `main`. Nursery rules don't follow semantic versioning.
+- if you promote a rule from nursery, send a PR to the `next` branch.
+- if you implement a new feature that affects end users, send a PR to the `next` branch.
+- if you implement a new feature that _doesn't affect end users_, send a PR to the maintenance `main` branch.
 
 ### Changelog
 
@@ -408,26 +413,29 @@ We are very strict about `major` changes in the `@biomejs/biome` package. To bet
 - `minor`: new features available to the users.
 - `major`: a change that breaks a user API.
 
+When choosing `minor` or `major`, make sure your PR targets the `next` branch instead of `main`.
 #### Writing a changeset
 
 The description of the changeset should follow the these guidelines:
 
+- Our changesets should be about _user-facing_ changes. Internal changes don't
+  need changesets.
 - Use the past tense when describing what you did, e.g. "Added new feature", "Fixed edge case".
 - Use the present tense when describing Biome behavior, e.g. "Biome now supports ...".
-- If you fixed a bug, please add the link to the issue, e.g. "Fixed [#4444](https://github.com/biomejs/biome/issues/4444)".
+- If you fixed a bug, please start with a link to the issue, e.g. "Fixed [#4444](https://github.com/biomejs/biome/issues/4444): ...".
 - If you reference a rule, please add the link to the rule on the website, e.g. "Added the rule [`useAwesomeThing`](https://biomejs.dev/linter/rules/use-awesome-thing/)" (even if the website isn't updated yet, the URL is pretty predictable...).
 - Similarly, if you reference an assist, please add the link to the assist on the website, e.g. "Added the assist [`awesomeAction`](https://biomejs.dev/assist/actions/awesome-action/)".
-- Whenever applicable, add a code block to show your new changes. For example, for a new
-  rule you might want to show an invalid case, for the formatter you might want to show
-  how the new formatting changes, and so on.
-- End each sentence with fullstops.
+- Whenever applicable, add a code block to show your new changes. For example, for a new rule you should show an invalid case, while for the formatter you should show how the new formatting changes, and so on.
+- End every sentence with a full stop (`.`).
 
 If in doubt, take a look at existing or past changesets.
 
 ### Documentation
 
-If your PR requires some update on the website (new features, breaking changes, etc.), you should create a new PR once the previous PR is successfully merged.
-When adding new features, the documentation should be part of a new PR, which will be merged right before the release.
+If your PR involves new features, or changes to existing features, documentation must be updated as well. For rules, assists, and their options, this is done using inline [rustdoc](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html) documentation.
+
+When other documentation updates are required, such as new formatter options, a PR should be created against the `next` branch of [our website](https://github.com/biomejs/website/). When doing so, please link the documentation PR from the PR that introduces the feature.
 
 ### Versioning
 
@@ -446,24 +454,32 @@ Even minor versions are dedicated to official releases, e.g. `*.6.*`.
 
 ### Regular releases
 
-When releasing a new version of a Biome, follow these steps:
+When releasing a new **minor** or **major** version of a Biome, follow these steps:
+
+1. [ ] Create a PR from `next` to `main`. Make sure that code conflicts are fixed and the new features have relative docs PR.
+
+1. [ ] Merge `next` to `main`.
 
 1. [ ] **Update to the same `version` in all crates** if you publish crates, if applicable. (`Cargo.toml` and `crates/**/Cargo.toml`)
 
 1. [ ] Linter rules have a `version` metadata directly defined in their implementation.
-   This field is set to `next` for newly created rules.
+   This field is set to `"next"` for newly created rules.
    This field must be updated to the new version.
 
-1. [ ] Merge the PR `ci: release`, and the release workflow will run. Once these workflows finish compiling the final artefact, **they need to be approved manually** by a member of the **Core Contributors**.
+1. [ ] Merge the `ci: release` PR, and the release workflow will run. Once these workflows finish compiling the final artefact, **they need to be approved manually** by a member of the **Core Contributors**.
 
-1. [ ] In the [website repository](https://github.com/biomejs/website), merge `next` into `main` with a PR. Usually, `next` contains the docs of new rules/actions. As well as the docs of new options.
-
-1. [ ] Open a new PR in the [website repository](https://github.com/biomejs/website) to update the website with the new version number:
+1. [ ] Update the generated documentation in the `next` branch of the [website](https://github.com/biomejs/website):
    `BIOME_VERSION=<version> pnpm run codegen:all`.
    This will also copy the configuration schema in the right place.
 
+1. [ ] Merge the website's `next` branch into `main` with a PR. Once merged, the documentation will automatically deploy.
+
 1. [ ] After releasing a major version number, you may want to update the `update-preview-version.mjs` script to make sure that future previews indicate a version number with a higher patch version than is currently indicated in the `package.json` manifests.
 
+1. [ ] Make sure you create new `next` branches for both the main repository and the website.
+
+**patch** releases only require a merging of the `ci: release` PR, and should leave the `next` branches untouched.
+
 ## Resources
 
 We have several resources explaining about Biome. They will help you understand the project and codebase.