Skip to content

docs: document patch release and backport policy - #31993

Merged
nickvigilante merged 5 commits into
mainfrom
docs/releases-patch-backport-policy
Nov 17, 2026
Merged

nickvigilante merged 5 commits into
mainfrom
docs/releases-patch-backport-policy

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

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:

  • Patch releases are unscheduled, and fixes land on main first.
  • A table of which fixes each channel receives, consistent with the existing channel descriptions and the cherry-pick / backport labels in CONTRIBUTING.md.
  • Bug-fix backports depend on severity and on how likely each release is to hit the bug; upgrading is the supported path otherwise.
  • Fixes that need a database schema change aren't backported and ship in the next minor.
  • How to request a patch release, plus a pointer to the preview image.

Pairs with the Support page change in DOCS-1731 ("contact Coder support" link).

Needs policy owner confirmation before merge

  • Who owns backport policy (Product or release management)?
  • The no-schema-changes-on-release-branches rule, as stated
  • The severity/likelihood framing for which releases get a bug fix
  • Whether there's a severity bar for an out-of-cycle patch worth publishing

Linear: DOCS-1732

Supersedes #31946, reopened under a human author for attribution.

@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:55 — with GitHub Actions Inactive
@nickvigilante nickvigilante added the community Pull Requests and issues created by the community. label Nov 10, 2026
@nickvigilante nickvigilante self-assigned this Nov 10, 2026
@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:55 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:55 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:55 — with GitHub Actions Inactive
- Better introduces the actual semantic versioning scheme
- Clarifies the support policy for hotfixes
@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 22:02 — with GitHub Actions Inactive
@nickvigilante
nickvigilante marked this pull request as ready for review November 10, 2026 22:02
@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 22:02 — with GitHub Actions Inactive

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a few suggestions and comments.

Comment thread docs/reference/releases.md Resolved
Comment thread docs/reference/releases.md Resolved
Comment thread docs/reference/releases.md Resolved
Comment thread docs/reference/releases.md Resolved
Co-authored-by: Ian Evans <5760366+ianjevans@users.noreply.github.com>
@github-actions

Copy link
Copy Markdown
Contributor


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


1 out of 2 committers have signed the CLA.
✅ (nickvigilante)[https://github.com/nickvigilante]
❌ @coder[bot]
You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

ianjevans
ianjevans previously approved these changes Nov 12, 2026

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, approving so it can merge after resolving the "fields" issue.

@coderagents coderagents Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/reference/releases.md Outdated
- 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: (Copy Editor) Put a non-breaking space between the number and the unit. The prose rule requires 12&nbsp;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&nbsp;year.

Suggested change
Each ESR is supported for 12 months from the date of its `.0` release.
Each ESR is supported for 12&nbsp;months from the date of its `.0` release.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in fc2de09: now 12&nbsp;months.

Reply generated by Coder Agents on behalf of @nickvigilante.

Comment thread docs/reference/releases.md Outdated
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:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(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.

Suggested change
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:

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/reference/releases.md Outdated
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(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.

Suggested change
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
```

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in fc2de09: restored the install.sh --stable example.

Reply generated by Coder Agents on behalf of @nickvigilante.

Comment thread docs/reference/releases.md Outdated
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(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:

Suggested change
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).

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@coderagents

coderagents Bot commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Documentation Check

Blocking

  • docs/reference/releases.md (open) - Line 118: add a non-breaking space in "12 months" (prose rule, numbers-units-and-dates)

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&nbsp;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: 76

Automated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong.

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@nickvigilante
nickvigilante merged commit 6e2ff20 into main Nov 17, 2026
31 of 33 checks passed
@nickvigilante
nickvigilante deleted the docs/releases-patch-backport-policy branch November 17, 2026 01:00
@nickvigilante
nickvigilante temporarily deployed to main November 17, 2026 01:00 — with GitHub Actions Inactive
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 17, 2026

This branch had an error being deployed

1 failed and 1 inactive deployments
main — fc2de09c Deployed Nov 17, 2026 by nickvigilante via cla #258334
docs-preview — fc2de09c Deployed Nov 17, 2026 by nickvigilante via cleanup #149
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

community Pull Requests and issues created by the community.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants