From 3be552b481da189a68bbcfaa62c809f3713c64d0 Mon Sep 17 00:00:00 2001 From: tison Date: Fri, 11 Sep 2026 17:48:43 +0800 Subject: [PATCH 1/3] chore: add a shared release workflow skill --- .agents/skills/release/SKILL.md | 66 ++++++ .../skills/release/references/candidate.md | 133 +++++++++++ .../skills/release/references/publication.md | 89 +++++++ .agents/skills/release/references/setup.md | 60 +++++ AGENTS.md | 2 + RELEASE.md | 224 +----------------- licenserc.toml | 1 + 7 files changed, 352 insertions(+), 223 deletions(-) create mode 100644 .agents/skills/release/SKILL.md create mode 100644 .agents/skills/release/references/candidate.md create mode 100644 .agents/skills/release/references/publication.md create mode 100644 .agents/skills/release/references/setup.md diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md new file mode 100644 index 0000000..58317fe --- /dev/null +++ b/.agents/skills/release/SKILL.md @@ -0,0 +1,66 @@ +--- +name: release +description: Prepare, resume, or verify Apache Asyncband releases when release-manager work is requested, including candidate artifacts, votes, publication, and recovery. +--- + + + +# Release Apache Asyncband + +Help the release manager carry out the requested release work, explain the current state, and propose practical next steps. Keep coordination in the main conversation; use the shared license-audit skill for the licensing review. The release manager and project community make release decisions. + +## Resume the requested work + +Establish the requested scope and what has already happened from the conversation, current checkout, and relevant external records. Read the affected parts of `asyncband/Cargo.toml`, `Cargo.lock`, `CHANGELOG.md`, `.github/workflows/release.yml`, `.asf.yaml`, and `xtask/src/main.rs` when needed. Use live GitHub, ASF distribution, mailing-list archives, and registry records to resolve uncertain state. Load only the reference for the current phase; an existing candidate does not require repeating preparation or setup. + +Carry forward the user's existing authorization. A status check, review, or plan stays read-only. For execution, complete authorized work and prepare any proposed external action before asking about authorization that is actually missing. Sending vote or announcement messages, publishing, merging, or changing tags needs authorization for that action; opening this skill does not provide it. Preserve the user's work when selecting a checkout or creating a release worktree. + +Keep these values and supporting links in the conversation so work can resume across turns: + +- `VERSION`: the final crate version, such as `0.7.2`; RCs do not change the package version. +- `RC`: the positive candidate number; `RC_TAG` is `v${VERSION}-rc.${RC}`. +- `RELEASE_COMMIT`: the merged release pull request commit bound to the candidate. +- `RELEASE_DIR`: an absolute working directory outside the repository for artifacts, verification, and SVN checkouts; reuse it while continuing the same candidate. +- Candidate tag and artifact location, checksum/signature results, relevant CI runs, PPMC/IPMC vote threads and results, and completed publication steps. + +Report completed work with evidence, the next useful step, and any input still needed. Distinguish pending, failed, and unverified steps. Keep handoff notes in the conversation unless the user requests a file. + +## Choose the current phase + +| Current work | Read | +| -------------------------------------------------- | ------------------------------------------------ | +| Signing keys, ASF directories, registry setup | [Release setup](references/setup.md) | +| Version/changelog PR, RC, artifacts, or staging | [Candidate preparation](references/candidate.md) | +| Voting, approved publication, follow-up, or retry | [Publication](references/publication.md) | +| Licensing review of the checkout or supplied files | [License audit](../license-audit/SKILL.md) | + +The phase guides are the maintained release procedure for both people and agents. `RELEASE.md` is only a discovery link. Repository paths and Git/Cargo commands refer to the repository or release-worktree root; Markdown links are relative to their containing file. Read `cargo x --help` and the relevant subcommand help before running repository checks. + +## Candidate and publication continuity + +The signed source archive approved by the Apache Incubator PMC and published through ASF distribution is the official Apache release. Its name is `apache-asyncband-${VERSION}-incubating-src.tar.gz`. The crates.io package is a convenience distribution from the same approved commit; keep its Cargo-generated name and layout. + +Keep the RC tag, commit, artifacts, and vote tied together. A later `main` commit does not invalidate an existing candidate. Reuse an existing signed tag and staged bytes when retrying a transient failure. If candidate content changes or the community rejects it, agree on the replacement candidate and increment `RC`; preserve existing tags rather than rewriting them. + +After both vote results record approval, promote the exact voted source artifacts. The signed final `v${VERSION}` tag uses the approved RC commit and starts the crates.io publication workflow, subject to the configured `release` environment review. Successful CI alone does not establish vote approval. Confirm each external action's result before reporting completion or retrying it. + +Use the shared [license-audit skill](../license-audit/SKILL.md) to examine the relevant checkout or artifact contents. In Codex, the configured `license_auditor` can perform a delegated review; another agent can follow the same skill directly. Provide the candidate revision and actual artifact paths, then discuss the review's evidence and suggestions with the release manager. + +Follow the current [ASF Release Policy](https://www.apache.org/legal/release-policy.html), [Release Distribution Policy](https://infra.apache.org/release-distribution), [Release Creation Process](https://infra.apache.org/release-publishing.html), and [Incubator release guidance](https://incubator.apache.org/guides/releasemanagement.html). Explain any relevant ambiguity with its source and practical options instead of treating incomplete evidence as a project defect. diff --git a/.agents/skills/release/references/candidate.md b/.agents/skills/release/references/candidate.md new file mode 100644 index 0000000..e2736b8 --- /dev/null +++ b/.agents/skills/release/references/candidate.md @@ -0,0 +1,133 @@ + + +# Prepare and stage a release candidate + +## Prepare the release pull request + +For a new release, start from current `main` and choose `VERSION` from the changes since the latest crates.io release. If the release pull request or candidate already exists, resume its recorded version and commit. + +1. Change `version` in `asyncband/Cargo.toml` and refresh `Cargo.lock` with Cargo. +2. Move the entries under `Unreleased` in `CHANGELOG.md` into an undated `v${VERSION}` section immediately below it, then restore an empty `Unreleased` section. Keep user-impacting sections ordered as breaking changes, new features, bug fixes, and improvements; add the actual release date only after publication. +3. Review `LICENSE`, `NOTICE`, `DISCLAIMER`, source headers, and bundled dependencies. Agents can use the shared [license-audit skill](../../license-audit/SKILL.md); Codex can delegate to the project's [`license_auditor`](../../../../.codex/agents/license_auditor.toml) subagent. Ask: "Help review this checkout for release licensing. Explain what the existing arrangements cover, any material concerns with supporting evidence, and practical suggestions or open questions. Keep the review read-only." Use its evidence and suggestions to decide what follow-up is needed during release preparation. +4. Run the release checks: + +```shell +cargo x lint +cargo x check +cargo x test --no-capture +RUSTUP_TOOLCHAIN=1.86.0 cargo x test --no-capture +cargo x semver --release-version "${VERSION}" +cargo publish --package asyncband --locked --dry-run +``` + +For a semver-major release, including a pre-1.0 minor release such as `0.7.0`, the semver command uses minor compatibility rules to report breaking API changes. When it reports expected changes, record and review them in `CHANGELOG.md`, then rerun: + +```shell +cargo x semver --release-version "${VERSION}" --acknowledge-breaking-changes +``` + +Merge the release pull request and record its merge commit as `RELEASE_COMMIT`. Every candidate artifact, the final tag, and the crates.io package use this exact commit. + +## Create and validate a release candidate + +For a new candidate, create a release directory outside the repository and a detached worktree at `RELEASE_COMMIT`. When resuming, reuse the recorded `RELEASE_DIR`, worktree, and RC tag. Run later Git and Cargo commands from that worktree root. + +```shell +RELEASE_DIR="$(mktemp -d "${TMPDIR:-/tmp}/asyncband-release.XXXXXX")" +RC_TAG="v${VERSION}-rc.${RC}" +git fetch https://github.com/apache/asyncband.git main +git worktree add --detach "${RELEASE_DIR}/checkout" "${RELEASE_COMMIT}" +cd "${RELEASE_DIR}/checkout" +git grep -F "version = \"${VERSION}\"" -- asyncband/Cargo.toml Cargo.lock +git grep -Fx "## v${VERSION}" -- CHANGELOG.md +test -z "$(git status --porcelain)" +git tag --sign "${RC_TAG}" \ + --message "Apache Asyncband ${VERSION} release candidate ${RC}" \ + "${RELEASE_COMMIT}" +git push https://github.com/apache/asyncband.git "${RC_TAG}" +``` + +Wait for the `Release` GitHub Actions workflow to pass. The workflow validates the RC tag and runs `cargo publish --dry-run` against the unchanged `${VERSION}` package; it skips the crates.io publish job for RC tags. A candidate that needs a code change gets a new release pull request, merge commit, RC number, and signed tag. + +## Build and verify the source archive + +For a new candidate, build the source archive from the verified RC tag. Reuse existing signed artifacts for a retry of the same candidate. The `incubating` marker is required in the filename, and `gzip -n` keeps the gzip header independent of the local build time. + +```shell +RC_TAG="v${VERSION}-rc.${RC}" +SOURCE_DIR="apache-asyncband-${VERSION}-incubating-src" +ARTIFACT_DIR="${RELEASE_DIR}/dist" +mkdir -p "${ARTIFACT_DIR}" +git verify-tag "${RC_TAG}" +git archive --format=tar --prefix="${SOURCE_DIR}/" "${RC_TAG}" \ + | gzip -n -9 > "${ARTIFACT_DIR}/${SOURCE_DIR}.tar.gz" +( + cd "${ARTIFACT_DIR}" + shasum -a 512 "${SOURCE_DIR}.tar.gz" > "${SOURCE_DIR}.tar.gz.sha512" + gpg --armor --detach-sign --local-user "${ASF_GPG_FINGERPRINT}" \ + "${SOURCE_DIR}.tar.gz" +) +``` + +Verify the artifacts in a fresh temporary directory. The archive test uses Cargo's `--locked` mode to check the shipped lockfile; `cargo x test` does not expose that option: + +```shell +VERIFY_DIR="$(mktemp -d "${RELEASE_DIR}/verify.XXXXXX")" +( + cd "${ARTIFACT_DIR}" + shasum -a 512 --check "${SOURCE_DIR}.tar.gz.sha512" + gpg --verify "${SOURCE_DIR}.tar.gz.asc" "${SOURCE_DIR}.tar.gz" + tar --extract --gzip --file "${SOURCE_DIR}.tar.gz" --directory "${VERIFY_DIR}" +) +( + cd "${VERIFY_DIR}/${SOURCE_DIR}" + cargo test --workspace --all-features --locked + cargo publish --package asyncband --locked --dry-run +) +``` + +Inspect the archive for unexpected binary files and compare its contents with the RC tag. Read `LICENSE` and `NOTICE` against the bundled and derived third-party works and their source-file notices, using automated header checks as supporting evidence. When using the license-audit skill directly or through a subagent, provide `${ARTIFACT_DIR}/${SOURCE_DIR}.tar.gz`, the extracted `${VERIFY_DIR}/${SOURCE_DIR}`, and `${VERIFY_DIR}/${SOURCE_DIR}/target/package/asyncband-${VERSION}.crate`, together with `RELEASE_COMMIT`, so the review covers the actual contents and packaging conventions of each distribution. Discuss any material concerns and open questions with the release manager; the review informs the project's release process and ASF release vote. + +After completing the artifact review, remove the temporary directory: + +```shell +rm -rf "${VERIFY_DIR}" +``` + +## Stage the candidate on ASF infrastructure + +Check whether this candidate is already staged. For a new staging operation, check out a working copy under `RELEASE_DIR`, add the three candidate files, and commit them: + +```shell +svn checkout --depth=empty \ + https://dist.apache.org/repos/dist/dev/incubator/asyncband "${RELEASE_DIR}/svn-dev" +mkdir "${RELEASE_DIR}/svn-dev/${VERSION}-rc.${RC}" +cp \ + "${ARTIFACT_DIR}/${SOURCE_DIR}.tar.gz" \ + "${ARTIFACT_DIR}/${SOURCE_DIR}.tar.gz.asc" \ + "${ARTIFACT_DIR}/${SOURCE_DIR}.tar.gz.sha512" \ + "${RELEASE_DIR}/svn-dev/${VERSION}-rc.${RC}/" +svn add "${RELEASE_DIR}/svn-dev/${VERSION}-rc.${RC}" +svn status "${RELEASE_DIR}/svn-dev" +svn commit "${RELEASE_DIR}/svn-dev" \ + -m "Stage Apache Asyncband ${VERSION} release candidate ${RC}" +``` + +Confirm the candidate at `https://dist.apache.org/repos/dist/dev/incubator/asyncband/${VERSION}-rc.${RC}/` and verify every link prepared for the vote email. diff --git a/.agents/skills/release/references/publication.md b/.agents/skills/release/references/publication.md new file mode 100644 index 0000000..d850c6b --- /dev/null +++ b/.agents/skills/release/references/publication.md @@ -0,0 +1,89 @@ + + +# Vote, publish, and follow up + +Resume from the recorded candidate and vote results. Check which publication steps already succeeded before running commands again. + +## Hold the two-phase vote + +Incubating releases use the [Incubator two-phase vote](https://incubator.apache.org/cookbook/#two-phase-vote-on-podling-releases). Each vote remains open for at least 72 hours. + +When the staged candidate and supporting links have been verified, send `[VOTE] Release Apache Asyncband (Incubating) ${VERSION} RC${RC}` to `dev@asyncband.apache.org`. Include: + +- the staged source URL; +- the `KEYS` URL and signing-key fingerprint; +- the signed RC tag and commit hash; +- the changelog or comparison with the previous release; +- verification commands or a checklist for signatures, checksums, licensing, unexpected binaries, and the build; +- a closing time at least 72 hours after the vote starts. + +The PPMC vote passes with at least three PPMC `+1` votes and more PPMC `+1` votes than `-1` votes. Publish a result email that identifies the voters and links the archived vote thread. + +Then send the proposal to `general@incubator.apache.org` with the PPMC result and archive link. The IPMC vote passes with at least three binding IPMC `+1` votes and more binding `+1` votes than `-1` votes. Publish its result email and record the archive link. + +Begin publication after the IPMC result records a passing vote. + +## Promote and publish the approved release + +Promote the exact voted artifacts from the development distribution area: + +```shell +svn move \ + "https://dist.apache.org/repos/dist/dev/incubator/asyncband/${VERSION}-rc.${RC}" \ + "https://dist.apache.org/repos/dist/release/incubator/asyncband/${VERSION}" \ + -m "Release Apache Asyncband ${VERSION}" +``` + +If the final tag already exists, verify that it points to the approved RC commit and continue with its workflow state. Otherwise, create the signed final tag from the verified RC tag and push it: + +```shell +RC_TAG="v${VERSION}-rc.${RC}" +git verify-tag "${RC_TAG}" +git tag --sign "v${VERSION}" \ + --message "Apache Asyncband ${VERSION}" \ + "${RC_TAG}^{commit}" +git push https://github.com/apache/asyncband.git "v${VERSION}" +``` + +The final tag starts the crates.io publishing job. A configured reviewer compares the final tag with the approved RC, confirms the IPMC vote result, and approves the `release` environment deployment. The workflow verifies the package version and publishes with a short-lived crates.io token. + +After publication: + +1. Verify the version and metadata on crates.io and docs.rs. +2. After ASF distribution syncs, verify the source archive, checksum, and signature under `https://downloads.apache.org/incubator/asyncband/${VERSION}/` and the project `KEYS` file at `https://downloads.apache.org/incubator/asyncband/KEYS`. +3. Submit a post-release pull request that adds the actual publication date to the `v${VERSION}` changelog heading. +4. Announce the release on `dev@asyncband.apache.org` and other appropriate channels as Apache Asyncband (Incubating). +5. Remove superseded releases from `dist/release`; ASF retains them in the archive. + +## Recover from failures + +A transient CI, staging, or registry error can be retried against the same candidate after checking what already succeeded. + +If the community rejects a candidate or its content changes, coordinate a new candidate with an incremented `RC`. Remove the rejected candidate from the development distribution area: + +```shell +svn delete \ + "https://dist.apache.org/repos/dist/dev/incubator/asyncband/${VERSION}-rc.${RC}" \ + -m "Remove rejected Apache Asyncband ${VERSION} release candidate ${RC}" +``` + +For a failed final crates.io job, first check whether the version exists on crates.io. If it exists and its contents and metadata match the approved release, continue post-publication verification and follow-up; the upload may have succeeded before the job lost its response. If the version is absent, rerun the same final-tag workflow for a transient or publishing-infrastructure failure. A source or package change uses a new version and the full ASF vote process. A published version is immutable; if it has a confirmed problem, discuss any yank and follow-up release on the development list. + +Once release follow-up is complete and the release manager no longer needs the local artifacts, remove the detached worktree with `git worktree remove "${RELEASE_DIR}/checkout"` and clean up the recorded release directory. Retain it while there are unresolved verification or recovery questions. diff --git a/.agents/skills/release/references/setup.md b/.agents/skills/release/references/setup.md new file mode 100644 index 0000000..26bc326 --- /dev/null +++ b/.agents/skills/release/references/setup.md @@ -0,0 +1,60 @@ + + +# Release setup + +Check existing signing, distribution, and registry settings before making changes. Use this guide when preparing the first release or resolving a setup question. + +## Signing and ASF distribution + +The release manager needs an ASF-associated GPG key in the project `KEYS` file. Follow the [ASF release signing guide](https://infra.apache.org/release-signing.html), publish the public key, and verify its fingerprint through an independent channel. + +Create the project distribution directories before the first release: + +```shell +svn mkdir --parents https://dist.apache.org/repos/dist/dev/incubator/asyncband \ + -m "Initialize Apache Asyncband development distribution area" +svn mkdir --parents https://dist.apache.org/repos/dist/release/incubator/asyncband \ + -m "Initialize Apache Asyncband release distribution area" +``` + +Initialize `KEYS` with the first release manager's public key: + +```shell +KEYS_FILE="$(mktemp)" +gpg --armor --export "${ASF_GPG_FINGERPRINT}" > "${KEYS_FILE}" +svn import "${KEYS_FILE}" https://dist.apache.org/repos/dist/release/incubator/asyncband/KEYS \ + -m "Add Apache Asyncband release keys" +rm "${KEYS_FILE}" +``` + +Add each later release manager's public key to the existing `KEYS` file through the release distribution repository before staging their first candidate. The public verification URL is . + +## crates.io Trusted Publishing + +A crate owner configures [crates.io Trusted Publishing](https://crates.io/docs/trusted-publishing) for `asyncband` with these values: + +| Setting | Value | +| ----------------- | ------------- | +| Repository owner | `apache` | +| Repository name | `asyncband` | +| Workflow filename | `release.yml` | +| Environment | `release` | + +The `release` environment in `.asf.yaml` limits deployments to version tags and requires a configured reviewer. After validating the first OIDC publication, enable **Require trusted publishing for all new versions** in the crate settings. diff --git a/AGENTS.md b/AGENTS.md index 93c2b02..4333442 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,6 +23,8 @@ under the License. Use `cargo x` as the source of truth for repository workflows. Read `cargo x --help` and the relevant subcommand's `--help` before running build, test, lint, or formatting commands. +Use the shared [release skill](.agents/skills/release/SKILL.md) for release preparation, status checks, publication, and recovery. Its phase guides are the maintained release procedure; resume from the established candidate and completed steps. + Use the shared [license-audit skill](.agents/skills/license-audit/SKILL.md) for license audits and release licensing checks. For a delegated Codex review, use the [`license_auditor`](.codex/agents/license_auditor.toml) agent, which reads the same skill. Other agents can follow the skill directly. ## Rust Style diff --git a/RELEASE.md b/RELEASE.md index 85d33eb..eaa02e8 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -19,226 +19,4 @@ under the License. # Releasing Apache Asyncband (Incubating) -This runbook is for release managers. Follow the current [ASF Release Policy](https://www.apache.org/legal/release-policy.html), [ASF Release Distribution Policy](https://infra.apache.org/release-distribution), [ASF Release Creation Process](https://infra.apache.org/release-publishing.html), and [Incubator release guidance](https://incubator.apache.org/guides/releasemanagement.html); the current ASF policies are authoritative. - -The signed source archive approved by the Apache Incubator PMC and published through ASF distribution is the official Apache release. The crates.io package is a convenience distribution from the same approved commit. A signed `vX.Y.Z-rc.N` tag identifies the candidate; after the PPMC and IPMC votes pass, the voted artifacts move to the release distribution area and a signed `vX.Y.Z` tag on the same commit triggers crates.io publication. - -## Conventions - -- `VERSION` is the proposed final version, for example `0.7.2`. -- `RC` is the positive candidate number, for example `1`. -- `RELEASE_COMMIT` is the merged release pull request commit used for every candidate artifact and release tag. -- The source archive is `apache-asyncband-${VERSION}-incubating-src.tar.gz`; the RC number appears in the staging directory and tag. - -## One-time setup - -### Signing and ASF distribution - -The release manager needs an ASF-associated GPG key in the project `KEYS` file. Follow the [ASF release signing guide](https://infra.apache.org/release-signing.html), publish the public key, and verify its fingerprint through an independent channel. - -Create the project distribution directories before the first release: - -```shell -svn mkdir --parents https://dist.apache.org/repos/dist/dev/incubator/asyncband \ - -m "Initialize Apache Asyncband development distribution area" -svn mkdir --parents https://dist.apache.org/repos/dist/release/incubator/asyncband \ - -m "Initialize Apache Asyncband release distribution area" -``` - -Initialize `KEYS` with the first release manager's public key: - -```shell -KEYS_FILE="$(mktemp)" -gpg --armor --export "${ASF_GPG_FINGERPRINT}" > "${KEYS_FILE}" -svn import "${KEYS_FILE}" https://dist.apache.org/repos/dist/release/incubator/asyncband/KEYS \ - -m "Add Apache Asyncband release keys" -rm "${KEYS_FILE}" -``` - -Add each later release manager's public key to the existing `KEYS` file through the release distribution repository before staging their first candidate. The public verification URL is . - -### crates.io Trusted Publishing - -A crate owner configures [crates.io Trusted Publishing](https://crates.io/docs/trusted-publishing) for `asyncband` with these values: - -| Setting | Value | -| ----------------- | ------------- | -| Repository owner | `apache` | -| Repository name | `asyncband` | -| Workflow filename | `release.yml` | -| Environment | `release` | - -The `release` environment in `.asf.yaml` limits deployments to version tags and requires a configured reviewer. After validating the first OIDC publication, enable **Require trusted publishing for all new versions** in the crate settings. - -## 1. Prepare the release pull request - -Start from current `main` and choose `VERSION` from the changes since the latest crates.io release. - -1. Change `version` in `asyncband/Cargo.toml` and refresh `Cargo.lock` with Cargo. -2. Move the entries under `Unreleased` in `CHANGELOG.md` into an undated `v${VERSION}` section immediately below it, then restore an empty `Unreleased` section. Keep user-impacting sections ordered as breaking changes, new features, bug fixes, and improvements; add the actual release date only after publication. -3. Review `LICENSE`, `NOTICE`, `DISCLAIMER`, source headers, and bundled dependencies. Agents can use the shared [license-audit skill](.agents/skills/license-audit/SKILL.md); Codex can delegate to the project's [`license_auditor`](.codex/agents/license_auditor.toml) subagent. Ask: "Help review this checkout for release licensing. Explain what the existing arrangements cover, any material concerns with supporting evidence, and practical suggestions or open questions. Keep the review read-only." Use its evidence and suggestions to decide what follow-up is needed during release preparation. -4. Run the release checks: - -```shell -cargo x lint -cargo x check -cargo x test --no-capture -RUSTUP_TOOLCHAIN=1.86.0 cargo x test --no-capture -cargo x semver --release-version "${VERSION}" -cargo publish --package asyncband --locked --dry-run -``` - -For a semver-major release, including a pre-1.0 minor release such as `0.7.0`, the semver command uses minor compatibility rules to report breaking API changes. When it reports expected changes, record and review them in `CHANGELOG.md`, then rerun: - -```shell -cargo x semver --release-version "${VERSION}" --acknowledge-breaking-changes -``` - -Merge the release pull request and record its merge commit as `RELEASE_COMMIT`. Every candidate artifact, the final tag, and the crates.io package use this exact commit. - -## 2. Create and validate a release candidate - -Fetch `RELEASE_COMMIT`, inspect the detached worktree, and create a signed annotated RC tag: - -```shell -RC_TAG="v${VERSION}-rc.${RC}" -git fetch https://github.com/apache/asyncband.git main -git switch --detach "${RELEASE_COMMIT}" -git grep -F "version = \"${VERSION}\"" -- asyncband/Cargo.toml Cargo.lock -git grep -Fx "## v${VERSION}" -- CHANGELOG.md -test -z "$(git status --porcelain)" -git tag --sign "${RC_TAG}" \ - --message "Apache Asyncband ${VERSION} release candidate ${RC}" \ - "${RELEASE_COMMIT}" -git push https://github.com/apache/asyncband.git "${RC_TAG}" -``` - -Wait for the `Release` GitHub Actions workflow to pass. The workflow validates the RC tag and runs `cargo publish --dry-run` against the unchanged `${VERSION}` package; it skips the crates.io publish job for RC tags. A candidate that needs a code change gets a new release pull request, merge commit, RC number, and signed tag. - -## 3. Build and verify the source archive - -Build the source archive from the verified RC tag. The `incubating` marker is required in the filename, and `gzip -n` keeps the gzip header independent of the local build time. - -```shell -RC_TAG="v${VERSION}-rc.${RC}" -SOURCE_DIR="apache-asyncband-${VERSION}-incubating-src" -mkdir -p dist -git verify-tag "${RC_TAG}" -git archive --format=tar --prefix="${SOURCE_DIR}/" "${RC_TAG}" \ - | gzip -n -9 > "dist/${SOURCE_DIR}.tar.gz" -( - cd dist - shasum -a 512 "${SOURCE_DIR}.tar.gz" > "${SOURCE_DIR}.tar.gz.sha512" - gpg --armor --detach-sign --local-user "${ASF_GPG_FINGERPRINT}" \ - "${SOURCE_DIR}.tar.gz" -) -``` - -Verify the artifacts in a fresh temporary directory: - -```shell -VERIFY_DIR="$(mktemp -d)" -( - cd dist - shasum -a 512 --check "${SOURCE_DIR}.tar.gz.sha512" - gpg --verify "${SOURCE_DIR}.tar.gz.asc" "${SOURCE_DIR}.tar.gz" - tar --extract --gzip --file "${SOURCE_DIR}.tar.gz" --directory "${VERIFY_DIR}" -) -( - cd "${VERIFY_DIR}/${SOURCE_DIR}" - cargo test --workspace --all-features --locked - cargo publish --package asyncband --locked --dry-run -) -``` - -Inspect the archive for unexpected binary files and compare its contents with the RC tag. Read `LICENSE` and `NOTICE` against the bundled and derived third-party works and their source-file notices, using automated header checks as supporting evidence. When using the license-audit skill directly or through a subagent, provide `dist/${SOURCE_DIR}.tar.gz`, the extracted `${VERIFY_DIR}/${SOURCE_DIR}`, and `${VERIFY_DIR}/${SOURCE_DIR}/target/package/asyncband-${VERSION}.crate`, together with `RELEASE_COMMIT`, so the review covers the actual contents and packaging conventions of each distribution. Discuss any material concerns and open questions with the release manager; the review informs the project's release process and ASF release vote. - -After completing the artifact review, remove the temporary directory: - -```shell -rm -rf "${VERIFY_DIR}" -``` - -## 4. Stage the candidate on ASF infrastructure - -Check out an empty working copy, add the three candidate files under the RC directory, and commit them: - -```shell -svn checkout --depth=empty \ - https://dist.apache.org/repos/dist/dev/incubator/asyncband asyncband-dist-dev -mkdir "asyncband-dist-dev/${VERSION}-rc.${RC}" -cp \ - "dist/${SOURCE_DIR}.tar.gz" \ - "dist/${SOURCE_DIR}.tar.gz.asc" \ - "dist/${SOURCE_DIR}.tar.gz.sha512" \ - "asyncband-dist-dev/${VERSION}-rc.${RC}/" -svn add "asyncband-dist-dev/${VERSION}-rc.${RC}" -svn status asyncband-dist-dev -svn commit asyncband-dist-dev \ - -m "Stage Apache Asyncband ${VERSION} release candidate ${RC}" -``` - -Confirm the candidate at `https://dist.apache.org/repos/dist/dev/incubator/asyncband/${VERSION}-rc.${RC}/` and verify every link prepared for the vote email. - -## 5. Hold the two-phase vote - -Incubating releases use the [Incubator two-phase vote](https://incubator.apache.org/cookbook/#two-phase-vote-on-podling-releases). Each vote remains open for at least 72 hours. - -First, send `[VOTE] Release Apache Asyncband (Incubating) ${VERSION} RC${RC}` to `dev@asyncband.apache.org`. Include: - -- the staged source URL; -- the `KEYS` URL and signing-key fingerprint; -- the signed RC tag and commit hash; -- the changelog or comparison with the previous release; -- verification commands or a checklist for signatures, checksums, licensing, unexpected binaries, and the build; -- a closing time at least 72 hours after the vote starts. - -The PPMC vote passes with at least three PPMC `+1` votes and more PPMC `+1` votes than `-1` votes. Publish a result email that identifies the voters and links the archived vote thread. - -Then send the proposal to `general@incubator.apache.org` with the PPMC result and archive link. The IPMC vote passes with at least three binding IPMC `+1` votes and more binding `+1` votes than `-1` votes. Publish its result email and record the archive link. - -Begin publication after the IPMC result records a passing vote. - -## 6. Promote and publish the approved release - -Promote the exact voted artifacts from the development distribution area: - -```shell -svn move \ - "https://dist.apache.org/repos/dist/dev/incubator/asyncband/${VERSION}-rc.${RC}" \ - "https://dist.apache.org/repos/dist/release/incubator/asyncband/${VERSION}" \ - -m "Release Apache Asyncband ${VERSION}" -``` - -Create the signed final tag from the verified RC tag and push it: - -```shell -RC_TAG="v${VERSION}-rc.${RC}" -git verify-tag "${RC_TAG}" -git tag --sign "v${VERSION}" \ - --message "Apache Asyncband ${VERSION}" \ - "${RC_TAG}^{commit}" -git push https://github.com/apache/asyncband.git "v${VERSION}" -``` - -The final tag starts the crates.io publishing job. A configured reviewer compares the final tag with the approved RC, confirms the IPMC vote result, and approves the `release` environment deployment. The workflow verifies the package version and publishes with a short-lived crates.io token. - -After publication: - -1. Verify the version and metadata on crates.io and docs.rs. -2. After ASF distribution syncs, verify the source archive, checksum, and signature under `https://downloads.apache.org/incubator/asyncband/${VERSION}/` and the project `KEYS` file at `https://downloads.apache.org/incubator/asyncband/KEYS`. -3. Submit a post-release pull request that adds the actual publication date to the `v${VERSION}` changelog heading. -4. Announce the release on `dev@asyncband.apache.org` and other appropriate channels as Apache Asyncband (Incubating). -5. Remove superseded releases from `dist/release`; ASF retains them in the archive. - -## Recover from failures - -A failed vote or changed candidate content starts a new candidate with an incremented `RC`. Remove the rejected candidate from the development distribution area: - -```shell -svn delete \ - "https://dist.apache.org/repos/dist/dev/incubator/asyncband/${VERSION}-rc.${RC}" \ - -m "Remove rejected Apache Asyncband ${VERSION} release candidate ${RC}" -``` - -For a failed final crates.io job, first check whether the version exists on crates.io. Rerun the same workflow for a transient or publishing-infrastructure failure when the version is absent. A source or package change uses a new version and the full ASF vote process. A version present on crates.io is immutable; discuss any yank and follow-up release on the development list. +The maintained release procedure is the [release skill](.agents/skills/release/SKILL.md), including its phase guides for setup, candidate preparation, voting, and publication. Release managers can read it directly; coding agents can use it to prepare or resume the requested release work. diff --git a/licenserc.toml b/licenserc.toml index e3aabef..7cc575c 100644 --- a/licenserc.toml +++ b/licenserc.toml @@ -23,6 +23,7 @@ excludes = [ # Skill discovery requires YAML frontmatter first. Its ASF header follows the frontmatter, # which HawkEye currently cannot skip when checking or inserting headers. ".agents/skills/license-audit/SKILL.md", + ".agents/skills/release/SKILL.md", # These third-party-derived files retain the applicable upstream license and copyright notices. "asyncband/src/blocking/executor.rs", "asyncband/src/blocking/parker.rs", From b0093b607f4ef036456538c9fe38674ca5d6c860 Mon Sep 17 00:00:00 2001 From: tison Date: Fri, 11 Sep 2026 18:15:31 +0800 Subject: [PATCH 2/3] chore: add scoped release candidate verification --- .agents/skills/release/SKILL.md | 27 ++++++--- .../skills/release/references/candidate.md | 27 +-------- .../release/references/infrastructure.md | 34 +++++++++++ .agents/skills/release/references/setup.md | 60 ------------------- .../skills/release/references/verification.md | 55 +++++++++++++++++ .codex/agents/release_verifier.toml | 23 +++++++ AGENTS.md | 4 +- RELEASE.md | 2 +- 8 files changed, 136 insertions(+), 96 deletions(-) create mode 100644 .agents/skills/release/references/infrastructure.md delete mode 100644 .agents/skills/release/references/setup.md create mode 100644 .agents/skills/release/references/verification.md create mode 100644 .codex/agents/release_verifier.toml diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md index 58317fe..8731fcc 100644 --- a/.agents/skills/release/SKILL.md +++ b/.agents/skills/release/SKILL.md @@ -24,7 +24,7 @@ under the License. # Release Apache Asyncband -Help the release manager carry out the requested release work, explain the current state, and propose practical next steps. Keep coordination in the main conversation; use the shared license-audit skill for the licensing review. The release manager and project community make release decisions. +Help the release manager carry out the requested release work, explain the current state, and propose practical next steps. Keep release coordination in the main conversation. Delegate substantial candidate verification when it can run independently, and use the shared license-audit skill for the licensing review. The release manager and project community make release decisions. ## Resume the requested work @@ -44,14 +44,23 @@ Report completed work with evidence, the next useful step, and any input still n ## Choose the current phase -| Current work | Read | -| -------------------------------------------------- | ------------------------------------------------ | -| Signing keys, ASF directories, registry setup | [Release setup](references/setup.md) | -| Version/changelog PR, RC, artifacts, or staging | [Candidate preparation](references/candidate.md) | -| Voting, approved publication, follow-up, or retry | [Publication](references/publication.md) | -| Licensing review of the checkout or supplied files | [License audit](../license-audit/SKILL.md) | +| Current work | Read | +| ------------------------------------------------- | ---------------------------------------------------- | +| Version/changelog PR, RC, artifacts, or staging | [Candidate preparation](references/candidate.md) | +| Checking an existing candidate's artifacts | [Candidate verification](references/verification.md) | +| Voting, approved publication, follow-up, or retry | [Publication](references/publication.md) | -The phase guides are the maintained release procedure for both people and agents. `RELEASE.md` is only a discovery link. Repository paths and Git/Cargo commands refer to the repository or release-worktree root; Markdown links are relative to their containing file. Read `cargo x --help` and the relevant subcommand help before running repository checks. +The phase guides are the maintained release procedure for both people and agents. `RELEASE.md` is only a discovery link. Existing infrastructure is described in [Infrastructure](references/infrastructure.md); read it only for configuration changes, a new release manager's signing key, or infrastructure troubleshooting. + +Links within this skill resolve from the containing document and stay within this skill's files. Repository paths such as `.github/workflows/release.yml` resolve from the caller's Asyncband repository root, which may differ from the current working directory. Locate the `license-audit` skill and configured agents by name; if skill discovery is unavailable, read `.agents/skills/license-audit/SKILL.md` from that repository root. Do not infer repository locations by walking upward from this skill's installation directory. + +Read `cargo x --help` and the relevant subcommand help before running repository checks. + +## Delegate candidate verification + +Use the `release_verifier` Codex agent for a substantial check of an existing candidate when the main agent can continue independent work, such as preparing vote materials. Other coding agents can delegate the same candidate-verification guide to a worker or follow it directly. Keep a small status query in the main conversation. + +Give the verifier the repository root, candidate commit and tag, version, absolute artifact paths, expected signing fingerprint and its provenance, requested checks, and a scratch directory outside the checkout. It returns the checked revision and artifacts, observed results, and remaining gaps. Preserve the original artifacts for a separate `license-audit` review; the verifier does not duplicate that audit. Collect the results before staging or publishing the candidate. ## Candidate and publication continuity @@ -61,6 +70,6 @@ Keep the RC tag, commit, artifacts, and vote tied together. A later `main` commi After both vote results record approval, promote the exact voted source artifacts. The signed final `v${VERSION}` tag uses the approved RC commit and starts the crates.io publication workflow, subject to the configured `release` environment review. Successful CI alone does not establish vote approval. Confirm each external action's result before reporting completion or retrying it. -Use the shared [license-audit skill](../license-audit/SKILL.md) to examine the relevant checkout or artifact contents. In Codex, the configured `license_auditor` can perform a delegated review; another agent can follow the same skill directly. Provide the candidate revision and actual artifact paths, then discuss the review's evidence and suggestions with the release manager. +Use the shared `license-audit` skill to examine the relevant checkout or artifact contents. In Codex, the configured `license_auditor` can perform a delegated review; another agent can follow the same skill directly. Provide the candidate revision and actual artifact paths, then discuss the review's evidence and suggestions with the release manager. Follow the current [ASF Release Policy](https://www.apache.org/legal/release-policy.html), [Release Distribution Policy](https://infra.apache.org/release-distribution), [Release Creation Process](https://infra.apache.org/release-publishing.html), and [Incubator release guidance](https://incubator.apache.org/guides/releasemanagement.html). Explain any relevant ambiguity with its source and practical options instead of treating incomplete evidence as a project defect. diff --git a/.agents/skills/release/references/candidate.md b/.agents/skills/release/references/candidate.md index e2736b8..7dbd2b7 100644 --- a/.agents/skills/release/references/candidate.md +++ b/.agents/skills/release/references/candidate.md @@ -25,7 +25,7 @@ For a new release, start from current `main` and choose `VERSION` from the chang 1. Change `version` in `asyncband/Cargo.toml` and refresh `Cargo.lock` with Cargo. 2. Move the entries under `Unreleased` in `CHANGELOG.md` into an undated `v${VERSION}` section immediately below it, then restore an empty `Unreleased` section. Keep user-impacting sections ordered as breaking changes, new features, bug fixes, and improvements; add the actual release date only after publication. -3. Review `LICENSE`, `NOTICE`, `DISCLAIMER`, source headers, and bundled dependencies. Agents can use the shared [license-audit skill](../../license-audit/SKILL.md); Codex can delegate to the project's [`license_auditor`](../../../../.codex/agents/license_auditor.toml) subagent. Ask: "Help review this checkout for release licensing. Explain what the existing arrangements cover, any material concerns with supporting evidence, and practical suggestions or open questions. Keep the review read-only." Use its evidence and suggestions to decide what follow-up is needed during release preparation. +3. Review `LICENSE`, `NOTICE`, `DISCLAIMER`, source headers, and bundled dependencies using the `license-audit` skill. Codex can delegate that review to `license_auditor`; provide the repository root and requested revision. Use its evidence and suggestions to decide what follow-up is needed during release preparation. 4. Run the release checks: ```shell @@ -86,30 +86,9 @@ git archive --format=tar --prefix="${SOURCE_DIR}/" "${RC_TAG}" \ ) ``` -Verify the artifacts in a fresh temporary directory. The archive test uses Cargo's `--locked` mode to check the shipped lockfile; `cargo x test` does not expose that option: +Verify the existing artifacts with the [candidate-verification guide](verification.md), directly or through `release_verifier`. Supply the candidate identity, signing-key fingerprint, repository root, and absolute artifact paths. Keep the signed archive unchanged throughout verification. -```shell -VERIFY_DIR="$(mktemp -d "${RELEASE_DIR}/verify.XXXXXX")" -( - cd "${ARTIFACT_DIR}" - shasum -a 512 --check "${SOURCE_DIR}.tar.gz.sha512" - gpg --verify "${SOURCE_DIR}.tar.gz.asc" "${SOURCE_DIR}.tar.gz" - tar --extract --gzip --file "${SOURCE_DIR}.tar.gz" --directory "${VERIFY_DIR}" -) -( - cd "${VERIFY_DIR}/${SOURCE_DIR}" - cargo test --workspace --all-features --locked - cargo publish --package asyncband --locked --dry-run -) -``` - -Inspect the archive for unexpected binary files and compare its contents with the RC tag. Read `LICENSE` and `NOTICE` against the bundled and derived third-party works and their source-file notices, using automated header checks as supporting evidence. When using the license-audit skill directly or through a subagent, provide `${ARTIFACT_DIR}/${SOURCE_DIR}.tar.gz`, the extracted `${VERIFY_DIR}/${SOURCE_DIR}`, and `${VERIFY_DIR}/${SOURCE_DIR}/target/package/asyncband-${VERSION}.crate`, together with `RELEASE_COMMIT`, so the review covers the actual contents and packaging conventions of each distribution. Discuss any material concerns and open questions with the release manager; the review informs the project's release process and ASF release vote. - -After completing the artifact review, remove the temporary directory: - -```shell -rm -rf "${VERIFY_DIR}" -``` +For the separate `license-audit` review, provide the original source archive, the extracted source, and the Cargo package produced by verification, together with `RELEASE_COMMIT`. Discuss its evidence and suggestions with the release manager. Keep the verification directory available until both reviews finish; then remove that disposable directory. ## Stage the candidate on ASF infrastructure diff --git a/.agents/skills/release/references/infrastructure.md b/.agents/skills/release/references/infrastructure.md new file mode 100644 index 0000000..69a078a --- /dev/null +++ b/.agents/skills/release/references/infrastructure.md @@ -0,0 +1,34 @@ + + +# Release infrastructure + +This is a reference for the existing design, not a recurring release checklist. Consult it when changing configuration, troubleshooting publication, or arranging a new release manager's signing key. + +## crates.io Trusted Publishing + +Trusted Publishing is already configured for `asyncband`: repository `apache/asyncband`, workflow `release.yml`, and environment `release`. Routine releases reuse this configuration. + +`.github/workflows/release.yml` obtains a short-lived crates.io token through GitHub OIDC. Only a final `v${VERSION}` tag can enter the publish job; RC tags run package checks. `.asf.yaml` configures version-tag deployments and required reviewers for the `release` environment. Consult those repository files and the live crate settings when diagnosing a mismatch. See the [crates.io Trusted Publishing documentation](https://crates.io/docs/trusted-publishing) for changes to this setup. + +## Signing and ASF distribution + +Candidates are staged under `https://dist.apache.org/repos/dist/dev/incubator/asyncband/`; approved releases are promoted to `https://dist.apache.org/repos/dist/release/incubator/asyncband/`. The public verification key list is `https://downloads.apache.org/incubator/asyncband/KEYS`. + +The release manager uses an ASF-associated signing key published in the existing project `KEYS` file. For a new signing key, follow the [ASF release signing guide](https://infra.apache.org/release-signing.html), verify the fingerprint through an independent channel, and add the public key while preserving existing keys. Reuse established distribution areas and signing configuration; investigate a reported access or verification failure before proposing infrastructure changes. diff --git a/.agents/skills/release/references/setup.md b/.agents/skills/release/references/setup.md deleted file mode 100644 index 26bc326..0000000 --- a/.agents/skills/release/references/setup.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Release setup - -Check existing signing, distribution, and registry settings before making changes. Use this guide when preparing the first release or resolving a setup question. - -## Signing and ASF distribution - -The release manager needs an ASF-associated GPG key in the project `KEYS` file. Follow the [ASF release signing guide](https://infra.apache.org/release-signing.html), publish the public key, and verify its fingerprint through an independent channel. - -Create the project distribution directories before the first release: - -```shell -svn mkdir --parents https://dist.apache.org/repos/dist/dev/incubator/asyncband \ - -m "Initialize Apache Asyncband development distribution area" -svn mkdir --parents https://dist.apache.org/repos/dist/release/incubator/asyncband \ - -m "Initialize Apache Asyncband release distribution area" -``` - -Initialize `KEYS` with the first release manager's public key: - -```shell -KEYS_FILE="$(mktemp)" -gpg --armor --export "${ASF_GPG_FINGERPRINT}" > "${KEYS_FILE}" -svn import "${KEYS_FILE}" https://dist.apache.org/repos/dist/release/incubator/asyncband/KEYS \ - -m "Add Apache Asyncband release keys" -rm "${KEYS_FILE}" -``` - -Add each later release manager's public key to the existing `KEYS` file through the release distribution repository before staging their first candidate. The public verification URL is . - -## crates.io Trusted Publishing - -A crate owner configures [crates.io Trusted Publishing](https://crates.io/docs/trusted-publishing) for `asyncband` with these values: - -| Setting | Value | -| ----------------- | ------------- | -| Repository owner | `apache` | -| Repository name | `asyncband` | -| Workflow filename | `release.yml` | -| Environment | `release` | - -The `release` environment in `.asf.yaml` limits deployments to version tags and requires a configured reviewer. After validating the first OIDC publication, enable **Require trusted publishing for all new versions** in the crate settings. diff --git a/.agents/skills/release/references/verification.md b/.agents/skills/release/references/verification.md new file mode 100644 index 0000000..e915013 --- /dev/null +++ b/.agents/skills/release/references/verification.md @@ -0,0 +1,55 @@ + + +# Verify an existing release candidate + +Perform the requested checks against the supplied candidate and return evidence to the caller. This is a bounded technical check: preserve the supplied repository and artifacts, and create extraction or build outputs only in the caller's scratch directory or a new temporary directory outside the checkout. Do not change tags, sign replacement artifacts, stage, publish, send messages, or perform a separate license audit. + +## Inputs and scope + +Use the caller's repository root, `VERSION`, `RC_TAG`, `RELEASE_COMMIT`, absolute archive/signature/checksum paths, expected signing fingerprint and its provenance, and requested verification scope. The caller may supply an existing Cargo package as well. Resolve repository files from that explicit root; this guide's location does not identify the audited checkout. + +Establish which checks are requested and which inputs are available. Continue independent checks when an input is missing and report the resulting gap. A key bundled with an archive is not independent evidence of signer identity. Use a temporary GPG home when importing supplied verification keys so the user's keyring stays unchanged. + +## Verify identity and source contents + +1. Record the resolved commit and artifact paths. Check the supplied RC tag's commit and signature against `RELEASE_COMMIT` and the expected signing fingerprint. Keep an existing candidate tied to that commit even if `main` has advanced. +2. Verify the SHA-512 checksum and detached archive signature on the original bytes. Record signature validity separately from whether the signer matches the expected identity; a checksum or signature alone does not establish agreement with the candidate commit. +3. Inspect the archive member list before extracting. Check the expected `apache-asyncband-${VERSION}-incubating-src/` root, reject paths that escape the extraction directory, and inspect symlinks without following them outside the extracted tree. +4. Compare the archived source inventory, file contents, executable bits, and symlink targets with `git archive` of the resolved candidate commit, using a separate temporary extraction. Compare logical entries rather than compressed bytes or timestamps. Report missing, added, or changed entries with concrete paths. Check the package version in the extracted manifest against `VERSION`. + +For example, use `git -C "${REPO_ROOT}" rev-parse "${RC_TAG}^{commit}"` to resolve a candidate and `git -C "${REPO_ROOT}" verify-tag "${RC_TAG}"` to inspect its signature. Run `shasum -a 512 --check` from the artifact directory and `gpg --verify` with the explicitly supplied signature and archive. Inspect checksum filenames before using the checksum file so it checks the intended artifact. + +## Verify the build and Cargo package + +Run these checks when the caller requests build and packaging verification. Read `cargo x --help` and the relevant subcommand help in the extracted source first. The archive test uses Cargo's `--locked` mode to check the shipped lockfile; `cargo x test` does not expose that option. + +```shell +cd "${EXTRACTED_SOURCE}" +cargo test --workspace --all-features --locked +cargo publish --package asyncband --locked --dry-run +``` + +Use the resulting `target/package/asyncband-${VERSION}.crate` for packaging verification and the caller's license review. If a package is supplied separately, inspect its actual contents and compare it with the package generated from the candidate when available. Check the package name, version, packaged source, and Cargo provenance metadata where present. Account for Cargo-generated manifests and repository metadata when comparing; an absent commit field in a package built outside a Git checkout is not itself a mismatch. + +Preserve the original archive inventory when builds add files to the extracted directory. Report build or dependency-fetch failures as observed failures; do not change the candidate to make verification pass. + +## Return the result + +Return a concise account of the checked candidate, signature/checksum and source-comparison results, requested build/package results, concrete discrepancies, and checks not completed. Include commands and exit results when they matter. Give the caller the extracted source and package paths for `license-audit`; retain these scratch outputs until the caller has finished with them. Do not create a report file unless requested. diff --git a/.codex/agents/release_verifier.toml b/.codex/agents/release_verifier.toml new file mode 100644 index 0000000..33ddcd2 --- /dev/null +++ b/.codex/agents/release_verifier.toml @@ -0,0 +1,23 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +description = "Verify a supplied Asyncband release candidate's signatures, source identity, build, and Cargo package, then return evidence to the caller." +developer_instructions = ''' +Locate the release skill in the available skill catalog, or at .agents/skills/release/SKILL.md under the caller's Asyncband repository root. Read its references/verification.md and perform the caller's requested checks yourself. Preserve the supplied checkout and artifacts; use a separate scratch directory for extraction and builds. Return the evidence and remaining gaps to the caller without delegating or performing release actions. +''' +name = "release_verifier" +sandbox_mode = "workspace-write" diff --git a/AGENTS.md b/AGENTS.md index 4333442..0aaf02d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ under the License. Use `cargo x` as the source of truth for repository workflows. Read `cargo x --help` and the relevant subcommand's `--help` before running build, test, lint, or formatting commands. -Use the shared [release skill](.agents/skills/release/SKILL.md) for release preparation, status checks, publication, and recovery. Its phase guides are the maintained release procedure; resume from the established candidate and completed steps. +Use the shared [release skill](.agents/skills/release/SKILL.md) for release preparation, status checks, publication, and recovery. Its phase guides are the maintained release procedure; resume from the established candidate and completed steps. For an independent candidate check, use the [`release_verifier`](.codex/agents/release_verifier.toml) agent or follow the same verification guide directly. Use the shared [license-audit skill](.agents/skills/license-audit/SKILL.md) for license audits and release licensing checks. For a delegated Codex review, use the [`license_auditor`](.codex/agents/license_auditor.toml) agent, which reads the same skill. Other agents can follow the skill directly. @@ -41,7 +41,7 @@ Decision: [#257](https://github.com/apache/asyncband/pull/257). ## Documentation -Keep each Markdown prose paragraph and list item on one source line. Format Markdown tables so their columns and separators align in the source. +Keep each Markdown prose paragraph and list item on one source line. Format Markdown tables so their columns and separators align in the source. Keep skill resource links within the skill directory; reference other skills or agents by name and resolve repository paths from the supplied repository root. ## Changelog diff --git a/RELEASE.md b/RELEASE.md index eaa02e8..973cc04 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -19,4 +19,4 @@ under the License. # Releasing Apache Asyncband (Incubating) -The maintained release procedure is the [release skill](.agents/skills/release/SKILL.md), including its phase guides for setup, candidate preparation, voting, and publication. Release managers can read it directly; coding agents can use it to prepare or resume the requested release work. +The maintained release procedure is the [release skill](.agents/skills/release/SKILL.md), including its phase guides for candidate preparation, verification, voting, and publication. Release managers can read it directly; coding agents can use it to prepare or resume the requested release work. From ed606d342a43a7d162e747e166379379f9c5ccc0 Mon Sep 17 00:00:00 2001 From: tison Date: Fri, 11 Sep 2026 22:03:39 +0800 Subject: [PATCH 3/3] docs: remove the redundant release entry point --- .agents/skills/release/SKILL.md | 2 +- RELEASE.md | 22 ---------------------- 2 files changed, 1 insertion(+), 23 deletions(-) delete mode 100644 RELEASE.md diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md index 8731fcc..1e6643a 100644 --- a/.agents/skills/release/SKILL.md +++ b/.agents/skills/release/SKILL.md @@ -50,7 +50,7 @@ Report completed work with evidence, the next useful step, and any input still n | Checking an existing candidate's artifacts | [Candidate verification](references/verification.md) | | Voting, approved publication, follow-up, or retry | [Publication](references/publication.md) | -The phase guides are the maintained release procedure for both people and agents. `RELEASE.md` is only a discovery link. Existing infrastructure is described in [Infrastructure](references/infrastructure.md); read it only for configuration changes, a new release manager's signing key, or infrastructure troubleshooting. +The phase guides are the maintained release procedure for both people and agents. Existing infrastructure is described in [Infrastructure](references/infrastructure.md); read it only for configuration changes, a new release manager's signing key, or infrastructure troubleshooting. Links within this skill resolve from the containing document and stay within this skill's files. Repository paths such as `.github/workflows/release.yml` resolve from the caller's Asyncband repository root, which may differ from the current working directory. Locate the `license-audit` skill and configured agents by name; if skill discovery is unavailable, read `.agents/skills/license-audit/SKILL.md` from that repository root. Do not infer repository locations by walking upward from this skill's installation directory. diff --git a/RELEASE.md b/RELEASE.md deleted file mode 100644 index 973cc04..0000000 --- a/RELEASE.md +++ /dev/null @@ -1,22 +0,0 @@ - - -# Releasing Apache Asyncband (Incubating) - -The maintained release procedure is the [release skill](.agents/skills/release/SKILL.md), including its phase guides for candidate preparation, verification, voting, and publication. Release managers can read it directly; coding agents can use it to prepare or resume the requested release work.