docs: be more specific with changeset guidelines#8282
Conversation
|
WalkthroughThis pull request updates CONTRIBUTING.md's changeset guidance: clarifies that changesets cover user-facing changes and that refactors without behaviour changes typically don't need one; adds formatting and concision rules (1–3 sentences) and when to include examples for new rules, rule/formatter/parser changes; prescribes past tense for actions and present tense for Biome behaviour; replaces the "If in doubt" line with guidance to check existing changesets and recent CHANGELOG.md entries; and tweaks bug-fix and rule-reference wording. No public APIs or exported signatures are changed. Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CONTRIBUTING.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
CONTRIBUTING.md
📄 CodeRabbit inference engine (AGENTS.md)
Review and follow the contribution guidelines defined in CONTRIBUTING.md
Files:
CONTRIBUTING.md
🧠 Learnings (5)
📓 Common learnings
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.013Z
Learning: Applies to **/.changeset/*.md : Changeset descriptions should be user-facing, use past tense for actions taken (e.g., 'Added new feature'), and present tense for Biome behavior (e.g., 'Biome now supports...'). Include issue links, rule links, and code examples where applicable.
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.014Z
Learning: For bugfix/feature PRs visible to Biome toolchain users or affecting published crates, create a changeset using the `just new-changeset` command with appropriate package selection, change type (major/minor/patch), and description.
📚 Learning: 2025-11-24T18:03:52.013Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.013Z
Learning: Applies to **/.changeset/*.md : Changeset descriptions should be user-facing, use past tense for actions taken (e.g., 'Added new feature'), and present tense for Biome behavior (e.g., 'Biome now supports...'). Include issue links, rule links, and code examples where applicable.
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:03:52.014Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.014Z
Learning: For bugfix/feature PRs visible to Biome toolchain users or affecting published crates, create a changeset using the `just new-changeset` command with appropriate package selection, change type (major/minor/patch), and description.
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.146Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.146Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : The first paragraph of rule documentation must be a single line and serves as the brief description for the rule overview page
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.146Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.146Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : Rule documentation must have a '## Options' section after the '## Examples' section if the rule supports options, with each option having its own h3 header
Applied to files:
CONTRIBUTING.md
🪛 LanguageTool
CONTRIBUTING.md
[uncategorized] ~448-~448: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...For example, if you refactored some code but the user-facing behavior didn't chang...
(COMMA_COMPOUND_SENTENCE_2)
[uncategorized] ~450-~450: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...lear.** Changesets are not documentation and they are not test cases. They should ...
(COMMA_COMPOUND_SENTENCE)
[style] ~451-~451: This phrasing can be overused. Try elevating your writing with a more formal alternative.
Context: ...nged, allowing the reader to dig deeper if they want to. A good changeset is usually between 1 ...
(IF_YOU_WANT)
[grammar] ~455-~455: Consider removing ‘would’. (Usually, ‘would’ does not occur in a conditional clause, unless to make a request or give a polite order.)
Context: ...ice versa) is usually sufficient. If it would be formatted better on multiple lines, use...
(CONDITIONAL_CLAUSE)
[locale-violation] ~463-~463: In British English, “have a look” is more commonly used.
Context: ...e with a full stop (.). If in doubt, take a look at existing changesets, or the most rec...
(TAKE_A_LOOK)
🔇 Additional comments (1)
CONTRIBUTING.md (1)
443-462: Solid expansion of changeset guidance.The new detail about different change types (new rules, rule changes, formatter, parser) is concrete and actionable. The emphasis on past/present tense aligns with learnings and helps contributors write user-facing descriptions consistently. Formatting improvements with bold emphasis enhance scannability.
ematipico
left a comment
There was a problem hiding this comment.
Great improvement! I left some suggestions. I liked the second suggestion from the bot too
0772999 to
d7a3d45
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
CONTRIBUTING.md (3)
450-451: Grammar & phrasing: add missing commas and refine proportionality guidance.Three issues here:
Line 450: Missing comma before "and". "Changesets are not documentation**,** and they are not test cases."
Line 451: "if they want to" is overused phrasing per style guides; simpler alternatives: "if needed" or simply remove it.
Line 451: The proportionality concept is now qualified ("at least if it concerns a feature that is relevant to them"), which improves clarity from the prior version, but the whole sentence remains lengthy. Consider:
A good changeset is usually 1–3 sentences. Longer changesets signal to readers that a change warrants attention. Use proportionality: bigger user impact → longer entry.
This is more direct than the current phrasing.
Proposed diff:
- A good changeset is usually between 1 and 3 sentences long. **Longer changesets indicate to the user that they should pay more attention to the change, at least if it concerns a feature that is relevant to them.** Consider the impact of your change on the user when writing the changeset. The key is to provide just enough information for the user to understand the change without overwhelming them with details. + A good changeset is usually between 1 and 3 sentences long. **Longer changesets signal to the user that a change warrants closer attention.** Consider the scope and impact of your change on the user when writing the changeset. Provide just enough information for the user to understand the change without overwhelming them with details.
452-455: Grammar: fix awkward conditional on line 455.Line 455: "If it would be formatted better on multiple lines, use a code block." The conditional with "would" is awkward. Simplify to:
If better formatted across multiple lines, use a code block.
or
If formatting on multiple lines improves clarity, use a code block.
Proposed diff:
- For parser changes, a brief inline example of the what can now be parsed that couldn't before (or vice versa) is usually sufficient. If it would be formatted better on multiple lines, use a code block. + For parser changes, a brief inline example of what can now be parsed (or vice versa) is usually sufficient. If better formatted across multiple lines, use a code block.
463-463: Minor locale preference note."Take a look" is flagged by LanguageTool as more British English preferring "have a look". This is a very minor preference and either phrasing is acceptable; no change needed unless you'd like consistency with your regional English variant.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CONTRIBUTING.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
CONTRIBUTING.md
📄 CodeRabbit inference engine (AGENTS.md)
Review and follow the contribution guidelines defined in CONTRIBUTING.md
Files:
CONTRIBUTING.md
🧠 Learnings (12)
📓 Common learnings
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.024Z
Learning: Applies to **/.changeset/*.md : Changeset descriptions should be user-facing, use past tense for actions taken (e.g., 'Added new feature'), and present tense for Biome behavior (e.g., 'Biome now supports...'). Include issue links, rule links, and code examples where applicable.
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.024Z
Learning: For bugfix/feature PRs visible to Biome toolchain users or affecting published crates, create a changeset using the `just new-changeset` command with appropriate package selection, change type (major/minor/patch), and description.
📚 Learning: 2025-11-24T18:03:52.024Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.024Z
Learning: Applies to **/.changeset/*.md : Changeset descriptions should be user-facing, use past tense for actions taken (e.g., 'Added new feature'), and present tense for Biome behavior (e.g., 'Biome now supports...'). Include issue links, rule links, and code examples where applicable.
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:03:52.024Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.024Z
Learning: For bugfix/feature PRs visible to Biome toolchain users or affecting published crates, create a changeset using the `just new-changeset` command with appropriate package selection, change type (major/minor/patch), and description.
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : Rule names should follow the 'use<Concept>' prefix when a rule's sole intention is to mandate a single concept (e.g., `useValidLang` for valid HTML lang attribute values)
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : The 'language' field in 'declare_lint_rule!' should be set to the specific JavaScript dialect (jsx, ts, tsx) if the rule only applies to that dialect, otherwise use 'js'
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : Rules can declare a 'recommended' field in 'declare_lint_rule!' to indicate if they should be enabled by default
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : Rules ported from other ecosystems should include a 'sources' field in the 'declare_lint_rule!' macro with RuleSource metadata (e.g., '::ESLint')
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : The first paragraph of rule documentation must be a single line and serves as the brief description for the rule overview page
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_rule_options/lib/**/*.rs : Rule options must be defined in the `biome_rule_options` crate in a file matching the rule name (e.g., 'use_this_convention.rs' for rule `useThisConvention`)
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-10-25T07:02:26.457Z
Learnt from: ematipico
Repo: biomejs/biome PR: 7856
File: .changeset/yellow-crews-guess.md:1-5
Timestamp: 2025-10-25T07:02:26.457Z
Learning: The Biome documentation website uses kebab-case URL slugs for rule pages (e.g., `/linter/rules/no-continue/`), not camelCase.
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : Rule documentation must have a '## Options' section after the '## Examples' section if the rule supports options, with each option having its own h3 header
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:03:52.024Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.024Z
Learning: Applies to **/*.rs : Use rustdoc inline documentation for rules, assists, and their options. Create corresponding documentation PRs for other documentation updates against the `next` branch of the website repository.
Applied to files:
CONTRIBUTING.md
🪛 LanguageTool
CONTRIBUTING.md
[uncategorized] ~448-~448: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...For example, if you refactored some code but the user-facing behavior didn't chang...
(COMMA_COMPOUND_SENTENCE_2)
[uncategorized] ~450-~450: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...lear.** Changesets are not documentation and they are not test cases. They should ...
(COMMA_COMPOUND_SENTENCE)
[style] ~451-~451: This phrasing can be overused. Try elevating your writing with a more formal alternative.
Context: ...nged, allowing the reader to dig deeper if they want to. A good changeset is usually between 1 ...
(IF_YOU_WANT)
[grammar] ~455-~455: Consider removing ‘would’. (Usually, ‘would’ does not occur in a conditional clause, unless to make a request or give a polite order.)
Context: ...ice versa) is usually sufficient. If it would be formatted better on multiple lines, use...
(CONDITIONAL_CLAUSE)
[locale-violation] ~463-~463: In British English, “have a look” is more commonly used.
Context: ...e with a full stop (.). If in doubt, take a look at existing changesets, or the most rec...
(TAKE_A_LOOK)
🔇 Additional comments (2)
CONTRIBUTING.md (2)
447-449: Clarity on user-facing changes.The bullet point effectively sets the foundation. User-facing changes requiring changesets and refactoring-only PRs not needing them are well explained.
456-461: Explicit tense rules and existing guidance.Lines 456–457 are clear and actionable. Past/present tense split is now explicit, and bug-fix/rule-reference guidance (lines 458–461) remains solid.
d7a3d45 to
9e353bb
Compare
9e353bb to
b3b7d9e
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
CONTRIBUTING.md (1)
450-451: Minor style: Consider replacing "if they want to" with more formal wording.The phrase "allowing the reader to dig deeper if they want to" in line 450 is clear but somewhat colloquial. Per the static analysis suggestion, try elevating this to something like: "allowing readers to dig deeper if desired" or simply "allowing readers to dig deeper as needed."
- They should give a **quick overview** of what changed, allowing the reader to dig deeper if they want to. A good changeset is usually between 1 and 3 sentences long. **Longer changesets indicate to the user that they should pay more attention to the change, at least if it concerns a feature that is relevant to them.** + They should give a **quick overview** of what changed, allowing readers to dig deeper as needed. A good changeset is usually between 1 and 3 sentences long. **Longer changesets indicate to the user that they should pay more attention to the change, at least if it concerns a feature that is relevant to them.**
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CONTRIBUTING.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
CONTRIBUTING.md
📄 CodeRabbit inference engine (AGENTS.md)
Review and follow the contribution guidelines defined in CONTRIBUTING.md
Files:
CONTRIBUTING.md
🧠 Learnings (12)
📓 Common learnings
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.024Z
Learning: Applies to **/.changeset/*.md : Changeset descriptions should be user-facing, use past tense for actions taken (e.g., 'Added new feature'), and present tense for Biome behavior (e.g., 'Biome now supports...'). Include issue links, rule links, and code examples where applicable.
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.024Z
Learning: For bugfix/feature PRs visible to Biome toolchain users or affecting published crates, create a changeset using the `just new-changeset` command with appropriate package selection, change type (major/minor/patch), and description.
Learnt from: CR
Repo: biomejs/biome PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-24T18:06:16.692Z
Learning: Applies to CONTRIBUTING.md : Review and follow the contribution guidelines defined in CONTRIBUTING.md
📚 Learning: 2025-11-24T18:03:52.024Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.024Z
Learning: Applies to **/.changeset/*.md : Changeset descriptions should be user-facing, use past tense for actions taken (e.g., 'Added new feature'), and present tense for Biome behavior (e.g., 'Biome now supports...'). Include issue links, rule links, and code examples where applicable.
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:03:52.024Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.024Z
Learning: For bugfix/feature PRs visible to Biome toolchain users or affecting published crates, create a changeset using the `just new-changeset` command with appropriate package selection, change type (major/minor/patch), and description.
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : Rule names should follow the 'use<Concept>' prefix when a rule's sole intention is to mandate a single concept (e.g., `useValidLang` for valid HTML lang attribute values)
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : The 'language' field in 'declare_lint_rule!' should be set to the specific JavaScript dialect (jsx, ts, tsx) if the rule only applies to that dialect, otherwise use 'js'
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : Rules can declare a 'recommended' field in 'declare_lint_rule!' to indicate if they should be enabled by default
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : Rules ported from other ecosystems should include a 'sources' field in the 'declare_lint_rule!' macro with RuleSource metadata (e.g., '::ESLint')
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : The first paragraph of rule documentation must be a single line and serves as the brief description for the rule overview page
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_rule_options/lib/**/*.rs : Rule options must be defined in the `biome_rule_options` crate in a file matching the rule name (e.g., 'use_this_convention.rs' for rule `useThisConvention`)
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-10-25T07:02:26.457Z
Learnt from: ematipico
Repo: biomejs/biome PR: 7856
File: .changeset/yellow-crews-guess.md:1-5
Timestamp: 2025-10-25T07:02:26.457Z
Learning: The Biome documentation website uses kebab-case URL slugs for rule pages (e.g., `/linter/rules/no-continue/`), not camelCase.
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:04:42.160Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:04:42.160Z
Learning: Applies to crates/biome_analyze/**/biome_*_analyze/lib/src/**/!(mod).rs : Rule documentation must have a '## Options' section after the '## Examples' section if the rule supports options, with each option having its own h3 header
Applied to files:
CONTRIBUTING.md
📚 Learning: 2025-11-24T18:03:52.024Z
Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:03:52.024Z
Learning: Applies to **/*.rs : Use rustdoc inline documentation for rules, assists, and their options. Create corresponding documentation PRs for other documentation updates against the `next` branch of the website repository.
Applied to files:
CONTRIBUTING.md
🪛 LanguageTool
CONTRIBUTING.md
[style] ~451-~451: This phrasing can be overused. Try elevating your writing with a more formal alternative.
Context: ...nged, allowing the reader to dig deeper if they want to. A good changeset is usually between 1 ...
(IF_YOU_WANT)
[locale-violation] ~463-~463: In British English, “have a look” is more commonly used.
Context: ...e with a full stop (.). If in doubt, take a look at existing changesets, or the most rec...
(TAKE_A_LOOK)
🔇 Additional comments (1)
CONTRIBUTING.md (1)
447-463: Well structured guidance; successfully addresses previous feedback.The refactored changeset guidance is comprehensive and aligns well with the learnings. The specific examples for new rules (line 452), rule changes (line 453), formatter changes (line 454), and parser changes (line 455) are crisp and actionable. The tense guidance (lines 456–457) and the concrete "check existing changesets and CHANGELOG.md" advice (line 463) are significant improvements over the vaguer "If in doubt" messaging.
The proportionality concept from the PR description is implicit in the proportionality-focused rewording of line 451. To be slightly more explicit, you might refine that line to: "Longer changesets signal importance to users—use them only when the change genuinely warrants emphasis." But the current phrasing is reasonable and fits the "Chill" review tone.
Based on learnings, the guidance now consistently reflects the requirement for user-facing, past-tense action descriptions and present-tense Biome behaviour, and recommends code examples for rule/parser/formatter changes.
Summary
I reviewed several recent PRs with these issues, but I realized that we need to make an actual policy decision on what is best.
These guideline changes are what I feel like is best. Feel free to tear it apart if you disagree :)
My goal is that changesets should be proportional in vertical size to the impact they have on our users. For example, a simple bug fix should be a small changelog entry, while a huge major change (like adding the
!!syntax for includes) should be big enough to alert users and have them take note.Test Plan
Docs