|
| 1 | +# Prepare Release |
| 2 | + |
| 3 | +Prepare a GitHub release after confirming the target version and release type. |
| 4 | + |
| 5 | +## Requirements |
| 6 | + |
| 7 | +1. Describe the release workflow before taking action: |
| 8 | + - Confirm whether the release should be published as a prerelease or a release. |
| 9 | + - After the release type is confirmed, check for an open milestone that is a concrete version and not a spec milestone such as `4.x` or `4.5.x`. |
| 10 | + - If a valid open milestone exists, ask the user to confirm that version with a yes/no question. |
| 11 | + - If no valid open milestone exists, require the user to provide the release version. |
| 12 | + - Verify whether the tag already exists. |
| 13 | + - Verify whether a GitHub release already exists for the version. |
| 14 | + - Create or update the GitHub release with the title set to the version. |
| 15 | +2. Ask the user for both: |
| 16 | + - Release type: prerelease or release |
| 17 | + - Release version (or milestone confirmation yes/no when a valid milestone exists) |
| 18 | +3. Use the release version as both: |
| 19 | + - Tag name |
| 20 | + - Release title |
| 21 | +4. If the user selects prerelease: |
| 22 | + - Create the release with the prerelease flag enabled. |
| 23 | +5. If the user selects release: |
| 24 | + - Create the release without the prerelease flag. |
| 25 | + - Ensure the release is linked to the repository announcement discussion for that version. |
| 26 | +6. Treat milestone titles such as `v4.x` or `v4.5.x` as spec milestones and do not suggest them as the release version. |
| 27 | +7. If a release already exists for the selected tag: |
| 28 | + - Do not fail or stop at `gh release create`. |
| 29 | + - Inspect the existing release and update it instead. |
| 30 | + - If the requested type is release and the existing release is a prerelease, convert it to a full release. |
| 31 | + - If the requested type is release and there is no linked discussion, link or create the announcement discussion during the update. |
| 32 | +8. Keep the response concise and operational. |
| 33 | +9. Prefer plain non-interactive `gh` commands. |
| 34 | + - Do not prefix commands with `GH_PAGER=cat` by default. |
| 35 | + - Only disable the pager when command output would otherwise not be captured reliably. |
| 36 | + |
| 37 | +## Operational Steps |
| 38 | + |
| 39 | +1. Ask: |
| 40 | + - Is this a prerelease or a release? |
| 41 | + |
| 42 | +Ask for the release type first. |
| 43 | + |
| 44 | +After release type is selected, check open milestones before asking for a version. |
| 45 | + |
| 46 | +Use standard `gh` commands by default. |
| 47 | +Only disable the pager when needed to make command output reliably readable in the execution environment. |
| 48 | + |
| 49 | +1. Summarize the plan: |
| 50 | + - Confirm whether this should be a prerelease or a release. |
| 51 | + - Inspect open milestones and find the latest concrete version milestone. |
| 52 | + - If found, ask the user to confirm that version with yes/no. |
| 53 | + - If not found, ask the user to provide a release version. |
| 54 | + - Verify whether the tag already exists. |
| 55 | + - Verify whether a GitHub release already exists for that tag. |
| 56 | + - Create or update the GitHub release using the version as the tag and title. |
| 57 | + - Apply the prerelease flag only when requested. |
| 58 | + - When publishing a full release, ensure the `Announcements` discussion is linked. |
| 59 | + |
| 60 | +2. After the release type is selected, inspect open milestones and find the latest non-spec milestone: |
| 61 | + |
| 62 | +```bash |
| 63 | +gh api repos/{owner}/{repo}/milestones --paginate --jq '.[] | select(.state == "open") | .title' |
| 64 | +``` |
| 65 | + |
| 66 | +Suggestion rules: |
| 67 | + |
| 68 | +- Exclude milestone titles that match spec patterns such as `v4.x` or `v4.5.x`. |
| 69 | +- Prefer the latest milestone that looks like a concrete release version such as `v4.5.0`. |
| 70 | +- If a valid milestone exists, ask: `Use <MILESTONE_VERSION> as the release version? (yes/no)`. |
| 71 | +- If the answer is yes, use that version. |
| 72 | +- If the answer is no, ask the user to provide the release version explicitly. |
| 73 | +- If no valid milestone exists, ask the user to provide the release version explicitly. |
| 74 | + |
| 75 | +1. Confirm release version: |
| 76 | + |
| 77 | +- Ensure a final release version is confirmed from either: |
| 78 | + - Milestone confirmation (yes), or |
| 79 | + - User-provided version. |
| 80 | + |
| 81 | +1. Check whether the tag already exists: |
| 82 | + |
| 83 | +```bash |
| 84 | +gh api repos/{owner}/{repo}/git/ref/tags/<RELEASE_VERSION> |
| 85 | +``` |
| 86 | + |
| 87 | +If the tag already exists, proceed only if that is intentional for the repository workflow. |
| 88 | + |
| 89 | +1. Check whether a GitHub release already exists for the selected version: |
| 90 | + |
| 91 | +```bash |
| 92 | +gh api repos/{owner}/{repo}/releases/tags/<RELEASE_VERSION> |
| 93 | +``` |
| 94 | + |
| 95 | +Decision rules: |
| 96 | + |
| 97 | +- If the release does not exist, create it. |
| 98 | +- If the release exists, inspect whether it is draft, prerelease, or already a full release. |
| 99 | +- If the user selected `prerelease`, update the existing release to keep or set `prerelease=true` as needed. |
| 100 | +- If the user selected `release`, update the existing release to set `prerelease=false`. |
| 101 | +- Do not attempt `gh release create` again when a release already exists for the tag. |
| 102 | + |
| 103 | +1. When the user selected `release`, ensure the announcement discussion is linked: |
| 104 | + |
| 105 | +- Prefer the repository discussion category named `Announcements`. |
| 106 | +- If needed, inspect repository discussion categories before updating the release. |
| 107 | +- When creating a release, use `discussion_category_name` with `Announcements`. |
| 108 | +- When updating an existing release, use the release update API with `discussion_category_name=Announcements`. |
| 109 | +- If a discussion is already linked, preserve it. |
| 110 | + |
| 111 | +1. Create the release: |
| 112 | + |
| 113 | +Prerelease: |
| 114 | + |
| 115 | +```bash |
| 116 | +gh release create <RELEASE_VERSION> --repo {owner}/{repo} --title '<RELEASE_VERSION>' --prerelease |
| 117 | +``` |
| 118 | + |
| 119 | +Release: |
| 120 | + |
| 121 | +```bash |
| 122 | +gh api repos/{owner}/{repo}/releases -X POST -f tag_name='<RELEASE_VERSION>' -f name='<RELEASE_VERSION>' -F prerelease=false -f discussion_category_name='Announcements' |
| 123 | +``` |
| 124 | + |
| 125 | +Update existing release to full release and link announcement discussion: |
| 126 | + |
| 127 | +```bash |
| 128 | +gh api repos/{owner}/{repo}/releases/<RELEASE_ID> -X PATCH -F prerelease=false -F make_latest=true -f discussion_category_name='Announcements' |
| 129 | +``` |
| 130 | + |
| 131 | +1. Report: |
| 132 | + |
| 133 | +- Release version |
| 134 | +- Release type |
| 135 | +- Whether a valid milestone version was found |
| 136 | +- Whether the milestone version was confirmed (yes/no) |
| 137 | +- Whether the version was milestone-confirmed or user-provided |
| 138 | +- Whether the tag already existed |
| 139 | +- Whether a GitHub release already existed for the version |
| 140 | +- Whether the GitHub release was created or updated successfully |
| 141 | +- Whether the release ended as prerelease or full release |
| 142 | +- Whether the announcement discussion was linked |
0 commit comments