docs: correct what is editable on an immutable release - #45730
Conversation
github-actions
Bot
added
the
triage
How to review these changes 👓Thank you for your contribution. To review these changes, choose one of the following options: A Hubber will need to deploy your changes internally to review. Table of review linksNote: Please update the URL for your staging server or codespace. The table shows the files in the
Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server 🤖 This comment is automatically generated. |
9099d47 to
42bd42e
Compare
There was a problem hiding this comment.
🟡 Changes recommended
The restriction list omits that an immutable release’s tag cannot be deleted while the release exists.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Corrects documentation about editable fields on immutable releases.
Changes:
- Clarifies immutable release restrictions.
- Documents prerelease verification and promotion.
File summaries
| File | Description |
|---|---|
managing-releases-in-a-repository.md |
Updates editing guidance. |
immutable-releases.md |
Documents editable fields and verification workflow. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 1
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
"Managing releases in a repository" claimed that only the title and release notes can be edited after an immutable release is published. Measured against a repository with immutable releases enabled, a published release also accepts changes to its pre-release and latest flags and stays immutable; what is rejected is uploading or deleting assets and moving the tag. The allowlist also contradicted the concepts page, which lists exactly those two protections. Replace it with a denylist, and document on the concepts page that a release can be published as a pre-release, verified over the public download path a draft does not offer, and then promoted.
42bd42e to
2e0f6d2
Compare
subatoi
left a comment
subatoi
left a comment
There was a problem hiding this comment.
Thank you, @koistya—I've made some suggested changes before we can merge this. If you'd prefer that I apply these myself so you don't need to do any further work but can still have the attribution, that's fine, please just say so. Thanks again
Review feedback: the new "What you can still change" heading and the prerelease-verify-promote paragraph were both extra structure on a short concepts page. Move the editable-fields sentence next to the protections it bounds, and point at the release-creation docs instead of restating the process.
subatoi
added
Waiting on contributor
and removed
triage
|
@subatoi fixed |
|
Thanks very much for contributing! Your pull request has been merged 🎉 You should see your changes appear on the site in approximately 24 hours. If you're looking for your next contribution, check out our help wanted issues ⚡ |
Why:
Closes: #45718
"Managing releases in a repository" says that under immutable releases you "can only edit the title and release notes after a release is published." That allowlist is wrong, and it contradicts Immutable releases, which lists exactly two enforced protections: Git tags cannot be moved, and release assets cannot be modified or deleted.
Measured on a repository with immutable releases enabled, against a published prerelease carrying one asset:
PATCH /repos/{owner}/{repo}/releases/{release_id}withprerelease=falseandmake_latest=legacy; the release stays"immutable": true.Cannot upload assets to an immutable release), deleting an asset, and moving the tag (push declined by repository rules).Read literally, the old note also rules out promoting a verified prerelease to latest — a release process immutability actually supports.
What's being changed:
managing-releases-in-a-repository.md— the note under "Editing a release" becomes a denylist matching the concepts page: no adding, replacing, or deleting assets, and no moving or deleting the tag while the release exists.immutable-releases.md— a sentence under "What immutable releases protect" bounds those protections to the assets and tag; "Best practices" now links to the release-creation instructions rather than restating them.Both name the editable fields explicitly rather than as examples of a larger set:
name,body,prereleaseandmake_latestwere measured;tag_name,target_commitish,draftanddiscussion_category_namewere not, so the wording claims nothing about them.Check off the following: