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
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 rules out a release process that immutability actually supports: publish a prerelease, verify the assets over the public download path, then promote it. A draft release is not public, so that path cannot be exercised before publication.
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 the tag, with the title, notes, pre-release and latest flags still editable.immutable-releases.md— adds a "What you can still change" section, and a sentence under "Best practices" for the publish-as-prerelease, verify, promote flow, using the UI labels fromdata/reusables/releases/edit-release.md.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: