Skip to content

chore: refine the release skill after the 0.7.3 release #338

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tisonkun merged 2 commits into from
Oct 1, 2026
Merged

chore: refine the release skill after the 0.7.3 release #338

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a9197ee
chore: refine the release skill after the 0.7.3 release
orthur2 Sep 23, 2026
e3c55bb
chore: drop the automated signing key note
orthur2 Sep 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .agents/skills/release/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ For a semver-major release, including a pre-1.0 minor bump, document and review

## 4. Push the RC and verify the ATR candidate

Use the release manager's personal OpenPGP code-signing key. It must be valid for signing, have a user ID containing their `<asf-id>@apache.org` address, and have its public key published in the [KEYS](https://downloads.apache.org/incubator/asyncband/KEYS) file. List the matching local keys and set `SIGNING_KEY_FINGERPRINT` to the selected key's primary fingerprint:
Use the release manager's personal OpenPGP code-signing key. It must be valid for signing, have a user ID containing their `<asf-id>@apache.org` address, and have its public key published in the [KEYS](https://downloads.apache.org/incubator/asyncband/KEYS) file. A new release manager appends their exported public key to that file in `https://dist.apache.org/repos/dist/release/incubator/asyncband`, keeping every existing key; ATR imports the committee's keys from there. List the matching local keys and set `SIGNING_KEY_FINGERPRINT` to the selected key's primary fingerprint:

```shell
gpg --list-secret-keys --with-fingerprint '<asf-id>@apache.org'
Expand All @@ -92,7 +92,7 @@ git push https://github.com/apache/asyncband.git "${RC_TAG}"
Follow both workflows for this tag:

- `Release` checks the `${VERSION}` Cargo package.
- `Compose source release` builds `apache-asyncband-${VERSION}-incubating-src.tar.gz` and its checksum. Approve its `release` environment job to sign with the automated project key and upload the archive, `.asc`, and `.sha512` to ATR project `asyncband`, version `${VERSION}`.
- `Compose source release` builds `apache-asyncband-${VERSION}-incubating-src.tar.gz` and its checksum. After a `release` environment reviewer listed in `.asf.yaml` approves its job, which the release manager can do when listed there, it signs with the automated project key and uploads the archive, `.asc`, and `.sha512` to ATR project `asyncband`, version `${VERSION}`.

Open the candidate in [ATR](https://releases.apache.org/projects/asyncband), inspect its checks, and record its URL, ATR revision, workflow run, and SHA-512 in the issue. Download that revision and complete [verification](references/verification.md) and `license-audit` on the actual distributions before voting. The `release_verifier` and `license_auditor` agents can perform these checks independently; reuse completed checks for the same candidate.

Expand All @@ -118,7 +118,7 @@ git tag --sign --local-user "${SIGNING_KEY_FINGERPRINT}" "v${VERSION}" --message
git push https://github.com/apache/asyncband.git "v${VERSION}"
```

Approve the final tag's `release` environment deployment in `release.yml`, then verify crates.io, docs.rs, and the ASF downloads. Use ATR's Announce action after both distributions are available; review the message and recipients and record the announcement. Submit the changelog publication-date PR, confirm any superseded-release archival, and close the tracking issue after its required items are complete. Remove the detached worktree and scratch directory when no longer needed.
Have a `release` environment reviewer approve the final tag's deployment in `release.yml`, then verify crates.io, docs.rs, and the ASF downloads. Update the Downloads page in `apache/asyncband-site` to the new release and publish it before announcing; the announcement points readers there, and archiving the prior release removes the files that page lists. Use ATR's Announce action after both distributions are available; review the message and recipients and record the announcement. Submit the changelog publication-date PR, confirm any superseded-release archival, and close the tracking issue after its required items are complete. Remove the detached worktree and scratch directory when no longer needed.

## Resume or recover

Expand Down
9 changes: 5 additions & 4 deletions .agents/skills/release/references/atr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,16 +27,17 @@ Fill the tracking issue's ATR vote page and communication links as each step com

1. Open the uploaded `${VERSION}` draft in Compose. Confirm the revision and checksum recorded in the tracking issue, inspect ATR's checks, and complete the candidate verification and artifact license review. Resolve blockers and review any concerns before acknowledging them. If ATR's commit field is empty, enter the frozen `RELEASE_COMMIT` using its commit-hash form.
2. Open the voting form. Set the first-round recipient to `dev@asyncband.apache.org`, the second-round recipient to `general@incubator.apache.org`, and the minimum duration to at least 72 hours. The second round uses that duration too.
3. Review the generated subject and body. Identify Apache Asyncband (Incubating), `${VERSION}`, and the RC; include the ATR candidate/revision, RC tag and commit, source checksum, KEYS and signer information, changelog, and verification evidence. Link ATR as the location of the voted files. Submit **Send vote email** when sending the vote is authorized, then record its archive link and closing time.
3. Review the generated subject and body. Identify Apache Asyncband (Incubating), `${VERSION}`, and the RC; include the ATR candidate/revision, RC tag and commit, source checksum, KEYS and signer information, changelog, and verification evidence. Link ATR as the location of the voted files. Write the body as plain text for the mailing lists: no Markdown or backticks, prose wrapped near 72 characters, each label and its URL on separate lines, and no line break inside a word or checksum. Submit **Send vote email** when sending the vote is authorized, then record its archive link and closing time.
4. Cast your own first-round vote with the checks you performed, either on the ATR vote page or by replying in the thread. A release manager has no implicit `+1`, so only an explicit vote counts towards the round. See the [ASF voting process](https://www.apache.org/foundation/voting.html).
Comment on lines +30 to +31

@tisonkun tisonkun Sep 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I think we may try to see if ATR supports defining the email template as code instead of defining it on the platform. Then we can keep the email template in our repository. Then we don't need Point 3 at all, but that can be a follow-up to investigate.

@orthur2 orthur2 Sep 30, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Agreed. And I took a look at the ATR code. Its "Export .asf.yaml" already writes start_vote_template, start_vote_subject, announce_release_template and a few other template fields under project.policy, so it seems we could keep the templates in our .asf.yaml, since we already have atr_sync on. I haven't checked yet whether the asfyaml side accepts those keys. I'll look into how to optimize this part later.

@tisonkun tisonkun Sep 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This can be a follow-up PR that we review separately BTW.


If publication is authorized, automatic publication can publish the source after IPMC approval; confirm the download suffix is `${VERSION}` when selecting it. Otherwise, publish in Finish after both votes pass.

## Resolve both rounds

Each round needs at least 72 hours, at least three eligible `+1` votes, and more eligible `+1` than `-1` votes. Eligibility is PPMC membership for round one and IPMC membership for round two. Allow at least six days for the two sequential votes. See the [Incubator vote rules](https://incubator.apache.org/cookbook/#two-phase-vote-on-podling-releases).
Each round needs at least 72 hours, at least three eligible `+1` votes, and more eligible `+1` than `-1` votes. Eligibility is PPMC membership for round one and IPMC membership for round two. Allow at least six days for the two sequential votes. See the [Incubator vote rules](https://incubator.apache.org/cookbook/#two-phase-vote-on-podling-releases). ATR neither resolves an email vote nor sends a reminder when it ends, so resolve each round after its closing time.

1. After the PPMC period, open the vote resolution page. Compare ATR's email tally with the thread, including voters' roles and any carried IPMC votes, and review the result body. Select `Passed` only if the requirements are met, then resolve the vote.
2. ATR sends the PPMC result and automatically starts the IPMC vote on the selected second-round list. Confirm delivery and record both links. Check that the IPMC thread includes the PPMC result, its `lists.apache.org` tally link, and any IPMC votes carried from round one; supplement that thread with any missing evidence.
2. ATR sends the PPMC result and automatically starts the IPMC vote on the selected second-round list. Confirm delivery and record both links. ATR renders that message from the project's stored vote template rather than from the first round's message, so candidate details written by hand do not carry over. Check that the IPMC thread includes the PPMC result, its `lists.apache.org` tally link, and any IPMC votes carried from round one; supplement that thread with any missing evidence.
3. After the IPMC period, review its binding tally, including eligible votes carried from round one and counting only each voter's latest vote, and review the result body before resolving it as `Passed`. ATR sends the result, also reports the passing result to the first-round thread, and moves the release to Finish. Record both vote results before final publication.

## Publish and announce
Expand All @@ -53,7 +54,7 @@ Use the website to review the tally, edit emails, and publish. For scripted oper

## Recover without replacing voted files

- Failed or uncertain upload: inspect ATR before retrying. If all three files arrived and verification succeeds, record that revision even if the GitHub run reported a late failure. Otherwise, retry before voting and verify the resulting revision; signing/upload can produce a new signature and revision. If the GitHub source bundle expired, rerun composition from the same RC and compare the recorded checksum.
- Failed or uncertain upload: inspect ATR before retrying. If all three files arrived and verification succeeds, record that revision even if the GitHub run reported a late failure. Otherwise, retry before voting and verify the resulting revision; signing/upload can produce a new signature and revision. When the cause is outside the repository, such as a signing key or an ATR setting, rerun the failed job in the same run once it is resolved: the composed source bundle is reused, a `release` environment reviewer approves it again, and GitHub accepts reruns for 30 days. If the GitHub source bundle expired, rerun composition from the same RC and compare the recorded checksum.
- Source or workflow correction: use a new reviewed commit and refresh affected checks. If an RC already exists, use a new RC number. A workflow rerun uses the old tagged workflow, so changing `main` cannot repair it.
- Rejected or cancelled vote: resolve that outcome in ATR, which returns the release to Compose. Preserve the previous tag and vote history in the issue, then prepare and verify the replacement candidate. Do not modify an active vote's files.
- Vote or publication error: inspect the current round, mail-delivery status, Finish state, and destination files before retrying. Resume a completed transition; do not resend an IPMC vote or republish matching files merely to obtain a green status.
1 change: 1 addition & 0 deletions .agents/skills/release/references/tracking-issue.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ Checklist:
- [ ] Confirm ATR publishes the voted revision to ASF distribution; record the SVN revision and download URL.
- [ ] Push the signed final tag at the approved commit and approve/verify crates.io publication.
- [ ] Verify ASF downloads and signatures, crates.io, and docs.rs.
- [ ] Update the website Downloads page to this release and confirm it is live.
- [ ] Send the announcement through ATR and record its archive link.
- [ ] Merge the publication-date changelog PR and confirm superseded-release archival as applicable.
- [ ] Close this issue after the preceding required items are complete.
Expand Down
Loading