You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@asyncband.apache.org by ti...@apache.org on 2026/08/29 09:48:24 UTC

(asyncband) branch main updated: docs: streamline repository guidance (#238)

This is an automated email from the ASF dual-hosted git repository.

tisonkun pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/asyncband.git


The following commit(s) were added to refs/heads/main by this push:
     new f9dc126  docs: streamline repository guidance (#238)
f9dc126 is described below

commit f9dc12698b1fa999d895cc4f2097cac9eb390b1f
Author: tison <wa...@gmail.com>
AuthorDate: Sat Aug 29 17:48:20 2026 +0800

    docs: streamline repository guidance (#238)
---
 .github/semantic.yml |   2 +-
 AGENTS.md            |  21 ++++-----
 MIGRATE.md           |   2 +-
 RELEASE.md           | 124 +++++++++++++++++++++++++--------------------------
 4 files changed, 73 insertions(+), 76 deletions(-)

diff --git a/.github/semantic.yml b/.github/semantic.yml
index 68ed8e1..62e3934 100644
--- a/.github/semantic.yml
+++ b/.github/semantic.yml
@@ -42,4 +42,4 @@ types:
   - chore
   - revert
 
-targetUrl: https://github.com/fast/asyncband/blob/main/.github/semantic.yml
+targetUrl: https://github.com/apache/asyncband/blob/main/.github/semantic.yml
diff --git a/AGENTS.md b/AGENTS.md
index 78d5903..8cae64f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,20 +1,17 @@
-# Agent Instructions
+# Repository Guidelines
 
-## Cargo XTask
+## Workflows
 
-Use `cargo x` as the source of truth for repository workflows.
+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.
 
-- Run `cargo x --help` before choosing build, test, lint, or formatting commands.
-- Run `cargo x <command> --help` for command-specific behavior.
+## Rust Style
 
-## Code Style
+Declare restricted visibility at the module boundary and use `pub` for items in that module's API.
 
-- Express visibility at the module boundary. Inside a restricted module, use `pub` for its module API instead of repeating `pub(crate)`.
+## Documentation
 
-## Commits and Pull Requests
+Keep each Markdown prose paragraph and list item on one source line.
 
-Follow the semantic definition at `.github/semantic.yml`.
+## Pull Requests
 
-- Keep title descriptions short.
-- Simple PR descriptions should only include a `Summary` section.
-- Complex PR descriptions may also include a `Design Notes` section.
+Format pull request titles according to `.github/semantic.yml` and keep the description concise. Use a `Summary` section for routine changes and add `Design Notes` only when the design needs explanation.
diff --git a/MIGRATE.md b/MIGRATE.md
index 1038357..6486778 100644
--- a/MIGRATE.md
+++ b/MIGRATE.md
@@ -20,6 +20,6 @@ asyncband = "0.6.7"
 
 Asyncband 0.6.7 is the compatibility point for the rename, so the dependency name and Rust paths are the only changes expected in this step. No compatibility package or re-export keeps the `mea` crate name available; downstream crates must update those names directly.
 
-Once the project builds with Asyncband 0.6.7, upgrade through later Asyncband releases separately. Follow the [Asyncband changelog](CHANGELOG.md) and apply the migration notes for each release instead of combining later breaking changes with the rename.
+Once the project builds with Asyncband 0.6.7, follow the [Asyncband changelog](CHANGELOG.md) when upgrading to later releases.
 
 For the background to the rename, see the [Asyncband proposal discussion](https://lists.apache.org/thread/f31qd3jm3odomjwy3lqkk21coyqsr9xs).
diff --git a/RELEASE.md b/RELEASE.md
index 012152d..61773d0 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,28 +1,23 @@
 # Releasing Apache Asyncband (Incubating)
 
-This document is a runbook for release managers. Publishing software has legal consequences, so follow the current [ASF Release Policy](https://www.apache.org/legal/release-policy.html), [ASF Release Distribution Policy](https://infra.apache.org/release-distribution), and [Incubator release guidance](https://incubator.apache.org/guides/releasemanagement.html) if they differ from this document.
+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.
 
-> [!IMPORTANT]
->
-> The signed source archive approved by the Apache Incubator PMC is the official Apache release. The crates.io package is a convenience distribution built from the same approved commit; it must not be published before the Incubator vote passes.
+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.
 
-The process deliberately separates release candidates from publication. A signed `vX.Y.Z-rc.N` tag identifies the exact source candidate and only performs a crates.io dry run. After both votes pass, a signed `vX.Y.Z` tag is added to the same commit and triggers the protected crates.io publishing job.
-
-## Terminology
+## Conventions
 
 - `VERSION` is the proposed final version, for example `0.7.0`.
-- `RC` is the positive release candidate number, for example `1`.
-- `CANDIDATE` is `${VERSION}-rc.${RC}`, for example `0.7.0-rc.1`.
-- `RC_TAG` is `v${CANDIDATE}` and `FINAL_TAG` is `v${VERSION}`.
-- The official source archive is `apache-asyncband-${VERSION}-incubating-src.tar.gz`. The RC number belongs to the staging directory and tag, not the artifact filename.
+- `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
 
-### GPG and ASF distribution directories
+### Signing and ASF distribution
 
-The release manager needs an ASF-associated GPG key whose public key is available from 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.
+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.
 
-Before the first release, create the project directories if they do not exist:
+Create the project distribution directories before the first release:
 
 ```shell
 svn mkdir --parents https://dist.apache.org/repos/dist/dev/incubator/asyncband \
@@ -31,19 +26,21 @@ svn mkdir --parents https://dist.apache.org/repos/dist/release/incubator/asyncba
   -m "Initialize Apache Asyncband release distribution area"
 ```
 
-Export all current release-manager public keys into `KEYS`, review the file, and commit it to the release distribution directory. Append new keys instead of replacing existing valid keys.
+Initialize `KEYS` with the first release manager's public key:
 
 ```shell
-gpg --armor --export "${ASF_GPG_FINGERPRINT}" > KEYS
-svn import KEYS https://dist.apache.org/repos/dist/release/incubator/asyncband/KEYS \
+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}"
 ```
 
-The public verification URL is <https://downloads.apache.org/incubator/asyncband/KEYS>. Update `KEYS` before staging a candidate whenever the signing keys change.
+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 <https://downloads.apache.org/incubator/asyncband/KEYS>.
 
 ### crates.io Trusted Publishing
 
-The `asyncband` crate already exists, so a crate owner can configure [crates.io Trusted Publishing](https://crates.io/docs/trusted-publishing) without a bootstrap publication. In the crate's **Settings → Trusted Publishing** page, add a GitHub Actions publisher with these exact values:
+A crate owner configures [crates.io Trusted Publishing](https://crates.io/docs/trusted-publishing) for `asyncband` with these values:
 
 | Setting           | Value         |
 | ----------------- | ------------- |
@@ -52,61 +49,54 @@ The `asyncband` crate already exists, so a crate owner can configure [crates.io
 | Workflow filename | `release.yml` |
 | Environment       | `release`     |
 
-The workflow obtains a short-lived OIDC token and keeps no long-lived crates.io token in GitHub. The `release` GitHub environment is managed by `.asf.yaml`: it accepts version tags and requires approval from one of the configured project committers. The person who pushed the tag may approve the deployment.
-
-After one successful Trusted Publishing release, remove any legacy `CARGO_REGISTRY_TOKEN` repository or environment secret and enable **Require trusted publishing for all new versions** in the crate settings. Keep at least two active crate owners so that the publisher configuration can be recovered without depending on one person.
+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` according to the changes since the latest crates.io release.
+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 a dated `VERSION` section, then restore an empty `Unreleased` section. Keep user-impacting sections ordered as breaking changes, new features, bug fixes, and improvements.
-3. Confirm that `LICENSE`, `NOTICE`, and `DISCLAIMER` are correct and that all source files have the required license headers.
-4. Run the normal validation and the semver check:
+3. Verify `LICENSE`, `NOTICE`, `DISCLAIMER`, source headers, and bundled dependencies.
+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
-audits with minor compatibility rules so that breaking API changes remain visible. Review every
-reported change against `CHANGELOG.md` and `MIGRATE.md`, then explicitly acknowledge the reviewed
-inventory:
+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
 ```
 
-Do not use `--acknowledge-breaking-changes` for a semver-minor or semver-patch release.
-
-Open and merge a normal pull request. Do not push the version change directly to `main`; the final release is identified by tags, so the release process does not require a direct branch push.
-
-Record the merge commit as `RELEASE_COMMIT`. All candidate artifacts, the final tag, and the crates.io package must come from this exact commit.
+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 the merged commit, verify it, and create a signed annotated RC tag:
+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 status --short
-git tag --sign "v${VERSION}-rc.${RC}" \
+git tag --sign "${RC_TAG}" \
   --message "Apache Asyncband ${VERSION} release candidate ${RC}" \
   "${RELEASE_COMMIT}"
-git push https://github.com/apache/asyncband.git "v${VERSION}-rc.${RC}"
+git push https://github.com/apache/asyncband.git "${RC_TAG}"
 ```
 
-Wait for the `Release` GitHub Actions workflow to pass. An RC tag runs package validation but cannot enter the crates.io publishing job. If validation requires a code change, abandon this candidate, merge a new release PR, increment `RC`, and use a new tag; never move or reuse an existing tag.
+Wait for the `Release` GitHub Actions workflow to pass. An RC tag runs package validation and skips the crates.io publishing job. A candidate that needs a code change gets a new release pull request, merge commit, RC number, and signed tag.
 
-## 3. Build the official source archive
+## 3. Build and verify the source archive
 
-Build the candidate from the RC tag in a clean clone. The `incubating` marker is mandatory in the filename, and `gzip -n` avoids embedding the local build time.
+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}"
@@ -123,42 +113,50 @@ git archive --format=tar --prefix="${SOURCE_DIR}/" "${RC_TAG}" \
 )
 ```
 
-Verify the artifacts before uploading them:
+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"
-  cd "${SOURCE_DIR}"
+  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
 )
+rm -rf "${VERIFY_DIR}"
 ```
 
-Also inspect the archive for unexpected binary files, verify `LICENSE`, `NOTICE`, and `DISCLAIMER`, and check that its contents correspond to the RC tag.
+Inspect the archive for unexpected binary files, verify `LICENSE`, `NOTICE`, and `DISCLAIMER`, and compare its contents with the RC tag.
 
 ## 4. Stage the candidate on ASF infrastructure
 
-Check out an empty working copy so old candidates are not copied accidentally, add the three files, and commit them under the candidate directory:
+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"* "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 that the candidate is visible at `https://dist.apache.org/repos/dist/dev/incubator/asyncband/${VERSION}-rc.${RC}/` and that every link in the vote email works.
+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 require the [two-phase vote described by the Incubator](https://incubator.apache.org/cookbook/).
+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:
 
@@ -166,14 +164,14 @@ First, send `[VOTE] Release Apache Asyncband (Incubating) ${VERSION} RC${RC}` to
 - the `KEYS` URL and signing-key fingerprint;
 - the signed RC tag and commit hash;
 - the changelog or comparison with the previous release;
-- commands or a checklist for verifying signatures, checksums, licensing, absence of unexpected binaries, and the build;
-- a statement that the vote remains open for at least 72 hours.
+- 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 podling vote passes with at least three `+1` votes from PPMC members, more PPMC `+1` votes than `-1` votes, and at least 72 hours elapsed. Send a result email that identifies voters and links the archived vote thread.
+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 same proposal to `general@incubator.apache.org`, including the podling vote result and archive link. This vote also remains open for at least 72 hours and requires at least three binding `+1` votes from Incubator PMC members with a majority in favor. Send a result email after it closes.
+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.
 
-Do not create the final tag, publish to crates.io, or announce a release until the Incubator vote passes.
+Begin publication after the IPMC result records a passing vote.
 
 ## 6. Promote and publish the approved release
 
@@ -186,27 +184,29 @@ svn move \
   -m "Release Apache Asyncband ${VERSION}"
 ```
 
-Wait for the files to appear at `https://downloads.apache.org/incubator/asyncband/${VERSION}/`. Then add a signed final tag to the exact RC commit and push only that tag:
+Create the signed final tag from the verified RC tag and push it:
 
 ```shell
-RC_COMMIT="$(git rev-list --max-count=1 "v${VERSION}-rc.${RC}")"
+RC_TAG="v${VERSION}-rc.${RC}"
+git verify-tag "${RC_TAG}"
 git tag --sign "v${VERSION}" \
   --message "Apache Asyncband ${VERSION}" \
-  "${RC_COMMIT}"
+  "${RC_TAG}^{commit}"
 git push https://github.com/apache/asyncband.git "v${VERSION}"
 ```
 
-The final tag starts the crates.io publishing job. Before approving the `release` environment deployment, a configured project committer must compare the final tag with the approved RC and confirm that the Incubator vote passed. The person who pushed the tag may perform this approval. The workflow verifies that the tag exactly matches the package version and publishes with a short-lived crates.io token.
+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. Announce the release on `dev@asyncband.apache.org` and other appropriate channels, identifying it as Apache Asyncband (Incubating).
-3. Remove superseded releases from `dist/release`; they remain available from the ASF archive.
+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. Announce the release on `dev@asyncband.apache.org` and other appropriate channels as Apache Asyncband (Incubating).
+4. Remove superseded releases from `dist/release`; ASF retains them in the archive.
 
-## Failed candidates and publication failures
+## Recover from failures
 
-If either vote fails or any candidate content changes, remove the staged candidate, increment `RC`, and restart from a new signed RC tag. Never replace an artifact, checksum, signature, or tag under an existing candidate name.
+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 \
@@ -214,4 +214,4 @@ svn delete \
   -m "Remove rejected Apache Asyncband ${VERSION} release candidate ${RC}"
 ```
 
-If the final crates.io job fails before publication, fix only the publishing infrastructure and rerun the same workflow. If the version reached crates.io, it is immutable: do not overwrite it or move tags. Yank it only when necessary, discuss the incident on the development list, and prepare a new version through the full ASF vote when source changes are required.
+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.


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@asyncband.apache.org
For additional commands, e-mail: commits-help@asyncband.apache.org