Repository navigation
docs: document patch release and backport policy - #31993
Conversation
- Better introduces the actual semantic versioning scheme - Clarifies the support policy for hotfixes
ianjevans
left a comment
There was a problem hiding this comment.
Just a few suggestions and comments.
Co-authored-by: Ian Evans <5760366+ianjevans@users.noreply.github.com>
|
I have read the CLA Document and I hereby sign the CLA 1 out of 2 committers have signed the CLA. |
ianjevans
left a comment
There was a problem hiding this comment.
Looks good, approving so it can merge after resolving the "fields" issue.
There was a problem hiding this comment.
Documentation Check review for the current head. One blocking item (line 118). Other items are non-blocking suggestions. See the summary comment.
Automated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong.
| - Receives only critical bugfixes and security patches | ||
| - Ideal for regulated environments or large deployments with strict upgrade cycles | ||
| Two releases each year are designated as Extended Support Releases (ESRs). | ||
| Each ESR is supported for 12 months from the date of its `.0` release. |
There was a problem hiding this comment.
Blocking: (Copy Editor) Put a non-breaking space between the number and the unit. The prose rule requires 12 months (numbers-units-and-dates.md#non-breaking-space-between-number-and-unit). The line is added by this PR. Existing precedent: docs/admin/setup/data-retention.md uses 1 year.
| Each ESR is supported for 12 months from the date of its `.0` release. | |
| Each ESR is supported for 12 months from the date of its `.0` release. |
There was a problem hiding this comment.
Fixed in fc2de09: now 12 months.
Reply generated by Coder Agents on behalf of @nickvigilante.
| This means that you should apply the latest patch release to your Coder deployment to get the latest bug fixes and security patches. | ||
| The Coder Support Team may ask you during troubleshooting to apply the latest patch release as a troubleshooting step. | ||
|
|
||
| Every fix is merged to `main` first, then backported to the release branches that are eligible for it: |
There was a problem hiding this comment.
(Reader Advocate) The merge-to-main step is contributor process, already covered in CONTRIBUTING.md. An operator reading this reference page needs only the backport outcome. Also, "eligible" is never defined on this page; the criterion appears later at line 58.
| Every fix is merged to `main` first, then backported to the release branches that are eligible for it: | |
| Fixes are backported to the release branches that are eligible for them: |
There was a problem hiding this comment.
Fixed in fc2de09: applied the suggestion. The merge-to-main step is covered in CONTRIBUTING.md.
Reply generated by Coder Agents on behalf of @nickvigilante.
| | Mainline | Bug fixes and security patches | | ||
| | Stable | Bug fixes and security patches | | ||
| | Security Support | Security patches and CVE fixes | | ||
| | Extended Support Release | Critical bug fixes and security patches | |
There was a problem hiding this comment.
(Newcomer) The table says ESR receives "critical bug fixes", but the page never defines "critical", so a reader cannot tell whether their bug qualifies. Line 58 gives only the general criterion (severity and likelihood). Define "critical" on this page or link the severity policy. The definition has to come from the policy owner, so no replacement text is proposed.
There was a problem hiding this comment.
Valid, but not changed in this PR. The definition of "critical" has to come from the backport policy owner, which is one of the open items in the PR description. I'll add it, or link the severity policy, once the owner confirms.
Reply generated by Coder Agents on behalf of @nickvigilante.
| The Coder Team decides which releases receive a bug fix based on its severity and how likely users on each release are to encounter the bug. | ||
| A fix might ship only in mainline and stable, in which case the supported path for older releases is to upgrade to a supported release. | ||
|
|
||
| Fixes that require a database schema change aren't backported. |
There was a problem hiding this comment.
(Fact Checker) No workflow enforces this. .github/workflows/backport.yaml and cherry-pick.yaml apply the backport label uniformly and do not filter on schema changes. The sentence states an unwritten team practice as a product fact. Cite the written policy, or soften it to match the practice. The PR checklist already flags this for owner confirmation.
There was a problem hiding this comment.
Confirmed: no workflow enforces this, and I found no written policy in CONTRIBUTING.md. Left as-is for now because the exact wording is a policy decision, and it's already on the owner-confirmation checklist in the PR description. I'll cite the written policy or soften the sentence once the owner responds.
Reply generated by Coder Agents on behalf of @nickvigilante.
| Fixes that require a database schema change aren't backported. | ||
| They ship in the next minor release. | ||
|
|
||
| To request a patch release for an issue that affects your deployment, [contact Coder support](../support/index.md) with your Coder version, the impact, and any deadline. |
There was a problem hiding this comment.
(Reader Advocate) The actionable request sits after three paragraphs and a table of backport mechanics. Move this sentence and the preview sentence to directly after line 47, so the action follows the "apply the latest patch" guidance. Also, the three items it asks for (version, impact, deadline) are not listed in docs/support/index.md on this head. They exist only in open PR #31992, so merge that PR with this one or before it.
There was a problem hiding this comment.
Fixed in fc2de09: moved the request and preview sentences to directly after the "apply the latest patch" guidance. The dependency on #31992 is real, so that PR needs to merge first or together with this one.
Reply generated by Coder Agents on behalf of @nickvigilante.
| To install a specific version, use our GitHub [releases page](https://github.com/coder/coder/releases). | ||
|
|
||
| You can also use our `install.sh` script with the `stable` flag to install the latest stable release: | ||
| To install a specific version, use the [coder/coder releases page on GitHub](https://github.com/coder/coder/releases). |
There was a problem hiding this comment.
(Cartographer) This PR removed the only copyable install.sh --stable command from this section. install.sh still supports --stable and --version, and docs/install/server/rpm.md documents them, but this page no longer gives a command. Restore the example after the link, or point to the install page for the flags.
| To install a specific version, use the [coder/coder releases page on GitHub](https://github.com/coder/coder/releases). | |
| To install a specific version, use the [coder/coder releases page on GitHub](https://github.com/coder/coder/releases). | |
| You can also use the `install.sh` script with the `--stable` flag to install the latest stable release: | |
| ```sh | |
| curl -fsSL https://coder.com/install.sh | sh -s -- --stable | |
| ``` |
There was a problem hiding this comment.
Fixed in fc2de09: restored the install.sh --stable example.
Reply generated by Coder Agents on behalf of @nickvigilante.
| Biannually released version of Coder | ||
| - **Release Candidates:** | ||
| Ad-hoc builds to validate in-development features | ||
| Coder will occasionally ship release candidates, which are ad-hoc builds meant to validate in-development features. |
There was a problem hiding this comment.
(Newcomer) The list above says "four primary release channels", and this sentence introduces release candidates without saying whether they are a fifth channel. Say so explicitly:
| Coder will occasionally ship release candidates, which are ad-hoc builds meant to validate in-development features. | |
| Coder also occasionally ships release candidates (RCs), which are ad-hoc builds meant to validate in-development features. RCs are separate from the four primary channels and are described [below](#release-candidates). |
There was a problem hiding this comment.
Fixed in fc2de09: applied the suggestion, so RCs are described as separate from the four primary channels.
Reply generated by Coder Agents on behalf of @nickvigilante.
Documentation CheckBlocking
Design notes
Related open PRs
Findings for agents- id: language-1
persona: language
class: rule
blocking: true
file: docs/reference/releases.md
line: 118
quote: "Each ESR is supported for 12 months from the date of its `.0` release."
rule: docs/.style/style-guide/numbers-units-and-dates.md#non-breaking-space-between-number-and-unit
fix: "Each ESR is supported for 12 months from the date of its `.0` release."
- id: audience-1
persona: audience
class: suggestion
blocking: false
file: docs/reference/releases.md
line: 49
- id: learner-2
persona: learner
class: suggestion
blocking: false
file: docs/reference/releases.md
line: 56
- id: accuracy-1
persona: accuracy
class: suggestion
blocking: false
file: docs/reference/releases.md
line: 61
- id: audience-4
persona: audience
class: suggestion
blocking: false
file: docs/reference/releases.md
line: 64
- id: coverage-1
persona: coverage
class: suggestion
blocking: false
file: docs/reference/releases.md
line: 148
- id: learner-5
persona: learner
class: suggestion
blocking: false
file: docs/reference/releases.md
line: 76Automated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong. |
Adds a Patch releases and backports section to the Releases page. The page says mainline and stable receive "all bugfixes" but doesn't explain how patches reach each release:
mainfirst.cherry-pick/backportlabels inCONTRIBUTING.md.previewimage.Pairs with the Support page change in DOCS-1731 ("contact Coder support" link).
Needs policy owner confirmation before merge
Linear: DOCS-1732
Supersedes #31946, reopened under a human author for attribution.