# Reqsign Release

> Release Apache Reqsign through the Apache RC, vote, dist, tag, crates.io, and announcement flow.

- Skill: `apache/reqsign-release` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add apache/reqsign-release`
- Raw SKILL.md: https://api.skillmd.com/api/skills/apache/reqsign-release/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: apache (https://skillmd.com/u/apache)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/apache/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.

   ```bash
   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.

   ```bash
   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:

```bash
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.

```bash
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.

```bash
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:

```bash
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.

```bash
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:

```bash
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:

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

Body:

```text
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:

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

   Body:

   ```text
   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.

   ```bash
   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.

   ```bash
   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.

   ```bash
   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.

   ```bash
   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.

