reqsign-release

Apache Reqsign Release Skill

Use this skill when preparing or executing an Apache Reqsign release.

Hard Rules

• Do not push the formal vX.Y.Z tag before the Apache vote passes.
• The voted release candidate tag is vX.Y.Z-rc.N; it must be a signed tag.
• The formal vX.Y.Z tag must point to the exact same commit as the voted RC tag, even if main has advanced after the vote started.
• Every crate in the current publish plan must exist with the exact apache/reqsign, release.yml, release Trusted Publisher and trustpub_only enabled before creating the RC tag.
• The repo release workflow publishes only formal vX.Y.Z tags. It uses short-lived GitHub OIDC credentials and never a long-lived crates.io token.
• Source release artifacts live under Apache dist:
  • RC: https://dist.apache.org/repos/dist/dev/reqsign/reqsign-X.Y.Z/
  • Final: https://dist.apache.org/repos/dist/release/reqsign/reqsign-X.Y.Z/
• If a wrong formal tag is pushed early, immediately cancel the Release workflow, delete the remote tag, and verify crates.io did not publish anything.

Release Preparation

1. Sync live state.

   git fetch origin main --tags
   git status --short --branch
   git tag --list 'vX.Y.Z*' --sort=version:refname
   git ls-remote --tags origin 'refs/tags/vX.Y.Z*'
   svn ls https://dist.apache.org/repos/dist/dev/reqsign/reqsign-X.Y.Z/ || true
   svn ls https://dist.apache.org/repos/dist/release/reqsign/reqsign-X.Y.Z/ || true
   

2. Prepare version bump on a PR.

   Typical version policy:

   • reqsign: patch bump, for example 0.20.0 -> 0.20.1.
   • Crate with new public capability: minor bump, for example reqsign-aliyun-oss 3.0.0 -> 3.1.0.
   • Other workspace crates published in the same workspace release: patch bump.
   • Keep root [workspace.dependencies] version requirements aligned with each crate manifest.

3. Validate the publish plan and packages.

   python3 -m unittest discover \
     -s .github/scripts/release_rust \
     -p "test_*.py"
   python3 .github/scripts/release_rust/plan.py
   cargo publish --workspace --dry-run --allow-dirty
   

4. Merge the version bump PR into main.

   Do not create the RC tag from an unmerged side branch unless the release manager explicitly accepts that the voted commit will not be on main.

Bootstrap Rust Crates

Wait until the intended crate-name set is present on the apache/reqsign main branch. The release manager chooses the exact reservation time, normally about three days before the planned release. At that time, check out the current main commit and run:

release/scripts/bootstrap-rust-crates.sh

This command performs the transition to a bootstrapped publish plan. Run it without asking for a second confirmation after a PMC release manager explicitly chooses the reservation time. Do not run it for release status checks or dry-run planning. Publishing a 0.0.0 package is externally visible and irreversible, but it is a namespace reservation rather than an ASF software release.

The helper:

• Requires a clean checkout at the current apache/reqsign main.
• Verifies that the rust-bootstrap environment has required reviewers.
• Dispatches the input-free bootstrap_rust_crates.yml workflow.
• Resolves the exact run, verifies its headSha, and waits for completion.
• Blocks while the protected environment awaits PMC approval.
• Verifies publicly that every crate in the checked publish plan exists and has trustpub_only enabled.

The protected job authenticates ownership and audits the complete publish plan before any write. Established crates must already have exactly one Trusted Publisher with:

• Repository owner: apache
• Repository name: reqsign
• Workflow filename: release.yml
• Environment: release

The job never changes an established crate. Migrate those crates through crates.io before using the bootstrap workflow and enable trustpub_only on each. For a missing name, the workflow publishes a dependency-free 0.0.0 placeholder, creates the expected Trusted Publisher, enables trustpub_only, and reconciles partial placeholders on rerun.

ASF Infrastructure provisions the release and rust-bootstrap environments from .asf.yaml. A PMC release manager must add CARGO_REGISTRY_BOOTSTRAP_TOKEN to the rust-bootstrap environment. The token must have only the publish-new and trusted-publishing endpoint scopes, with crate scopes restricted to reqsign package names. Never expose it to the normal release workflow.

Run the helper again if the publish plan gains another crate after a successful bootstrap.

Create RC Tag

Create the RC tag from the merged version-bump commit on main.

Before tagging, confirm that the bootstrap workflow succeeded for the current publish plan and that no later commit added another crate.

git fetch origin main --tags
git switch --detach origin/main
git tag -s vX.Y.Z-rc.N -m "vX.Y.Z-rc.N"
git tag -v vX.Y.Z-rc.N
git push origin vX.Y.Z-rc.N

The RC tag should not trigger the formal publish workflow.

Build Source Artifact

Create the Apache source artifact from the RC tag.

rm -rf /tmp/reqsign-release-X.Y.Z
mkdir -p /tmp/reqsign-release-X.Y.Z/dist

git archive \
  --format=tar.gz \
  --prefix=apache-reqsign-X.Y.Z/ \
  -o /tmp/reqsign-release-X.Y.Z/dist/apache-reqsign-X.Y.Z.tar.gz \
  vX.Y.Z-rc.N

cd /tmp/reqsign-release-X.Y.Z/dist
gpg --armor --detach-sign apache-reqsign-X.Y.Z.tar.gz
shasum -a 512 apache-reqsign-X.Y.Z.tar.gz > apache-reqsign-X.Y.Z.tar.gz.sha512

gpg --verify apache-reqsign-X.Y.Z.tar.gz.asc apache-reqsign-X.Y.Z.tar.gz
shasum -a 512 -c apache-reqsign-X.Y.Z.tar.gz.sha512
tar -tzf apache-reqsign-X.Y.Z.tar.gz | rg '(^|/)LICENSE$|(^|/)NOTICE$|(^|/)Cargo.toml$'

Confirm the signing key is present in Apache Reqsign KEYS:

svn cat https://dist.apache.org/repos/dist/release/reqsign/KEYS | rg 'xuanwo@apache.org|Xuanwo|KEY_FINGERPRINT'

Upload RC Artifacts

Upload to Apache dev dist.

rm -rf /tmp/reqsign-dist-dev-X.Y.Z
svn co --depth=empty https://dist.apache.org/repos/dist/dev/reqsign /tmp/reqsign-dist-dev-X.Y.Z

cd /tmp/reqsign-dist-dev-X.Y.Z
mkdir reqsign-X.Y.Z
cp /tmp/reqsign-release-X.Y.Z/dist/* reqsign-X.Y.Z/
svn add reqsign-X.Y.Z
svn status
svn commit --force-interactive -m "Prepare reqsign X.Y.Z release candidate"

Verify the remote copy:

svn ls https://dist.apache.org/repos/dist/dev/reqsign/reqsign-X.Y.Z/
rm -rf /tmp/reqsign-verify-X.Y.Z
svn co https://dist.apache.org/repos/dist/dev/reqsign/reqsign-X.Y.Z /tmp/reqsign-verify-X.Y.Z
cd /tmp/reqsign-verify-X.Y.Z
shasum -a 512 -c apache-reqsign-X.Y.Z.tar.gz.sha512
gpg --verify apache-reqsign-X.Y.Z.tar.gz.asc apache-reqsign-X.Y.Z.tar.gz

Start Vote

Create a GitHub Discussion in apache/reqsign General. Confirm that the vote is forwarded to dev@reqsign.apache.org and that the mailing-list thread is linked from the Discussion before counting the voting period.

Title:

[VOTE] Release Apache Reqsign X.Y.Z - Vote Round 1

Body:

Hello, Apache Reqsign Community,

This is a call for a vote to release Apache Reqsign version X.Y.Z.

The release candidate:

https://dist.apache.org/repos/dist/dev/reqsign/reqsign-X.Y.Z/

Keys to verify the release candidate:

https://downloads.apache.org/reqsign/KEYS

Git tag for the release candidate:

https://github.com/apache/reqsign/releases/tag/vX.Y.Z-rc.N

The tag points to commit:

COMMIT_SHA

Please download, verify, and test.

The VOTE will be open for at least 72 hours and until the necessary number of votes are reached.

- [ ] +1 approve
- [ ] +0 no opinion
- [ ] -1 disapprove with the reason

Checklist for reference:

- [ ] Download links are valid.
- [ ] Checksums and signatures are valid.
- [ ] LICENSE/NOTICE files exist.
- [ ] No unexpected binary files.
- [ ] All source files have ASF headers.
- [ ] Can compile from source.

Thanks,
NAME

After Vote Passes

1. Verify vote state.

   Confirm at least three binding +1 votes from Reqsign PMC members and no blocking -1 votes.

2. Publish vote result.

   Create a GitHub Discussion in General.

   Title:

   [RESULT][VOTE] Release Apache Reqsign X.Y.Z - Vote Round 1
   

   Body:

   Hello, Apache Reqsign Community,
   
   The vote to release Apache Reqsign X.Y.Z has passed.
   
   The vote PASSED with N +1 binding votes, no +0 or -1 votes.
   
   Binding votes:
   
   - VOTER_1
   - VOTER_2
   - VOTER_3
   
   Vote thread: VOTE_THREAD_URL
   
   Thanks,
   NAME
   

3. Push the formal signed tag.

   Use the exact voted RC commit.

   git checkout vX.Y.Z-rc.N
   test "$(git rev-parse vX.Y.Z-rc.N^{})" = "COMMIT_SHA"
   git tag -s vX.Y.Z -m "vX.Y.Z"
   git tag -v vX.Y.Z
   git push origin vX.Y.Z
   

4. Move ASF artifacts from dev to release.

   svn mv --force-interactive \
     https://dist.apache.org/repos/dist/dev/reqsign/reqsign-X.Y.Z \
     https://dist.apache.org/repos/dist/release/reqsign/reqsign-X.Y.Z \
     -m "Release reqsign X.Y.Z"
   

5. Monitor the GitHub Release workflow.

   gh run list --repo apache/reqsign --workflow Release --limit 5
   gh run view RUN_ID --repo apache/reqsign --json status,conclusion,url,jobs
   

   The workflow validates the complete workspace package set, then publishes crates in dependency order. Every package attempt receives a new OIDC-derived crates.io token that is revoked immediately afterward. Reruns skip versions already published by an earlier partial run.

6. Verify crates.io versions.

   for c in \
     reqsign reqsign-core reqsign-aliyun-oss reqsign-aws-core reqsign-aws-v4 \
     reqsign-aws-v4a reqsign-azure-storage \
     reqsign-command-execute-tokio reqsign-file-read-tokio reqsign-google \
     reqsign-http-send-reqwest reqsign-huaweicloud-obs reqsign-oracle \
     reqsign-tencent-cos reqsign-volcengine-tos
   do
     cargo info "$c" --registry crates-io | sed -n '1,4p'
   done
   

7. Create a GitHub Release.

   Use the formal tag and include source artifact links, notable changes, and crate versions.

Recovery Notes

• If main advances after the vote starts, formal vX.Y.Z still points to the RC commit, not latest origin/main.
• If SVN authentication fails, retry with --force-interactive; run svn cleanup if a killed commit leaves the working copy locked.
• If crates.io publishing fails after some packages succeed, rerun the exact formal-tag workflow. Do not create another tag or use a long-lived token; the publisher resumes after matching already-published versions.
• If the bootstrap workflow fails, inspect the authenticated preflight first. It deliberately refuses to modify established crates or continue with unexpected repository or Trusted Publisher metadata.