AGENT SKILL

fory-release

Stage or verify an Apache Fory release candidate and prepare GitHub release notes. Use GitHub Actions by default for ATR source staging and Nexus JVM staging; use the retained local manual workflow only when the user explicitly requests manual publishing.

License 许可
Apache-2.0
所属仓库
apache/fory
最近更新
2026-11-14
Stars
★ 4.6k
Forks
471

01 前言 Front Matter

name
fory-release
description
Stage or verify an Apache Fory release candidate and prepare GitHub release notes. Use GitHub Actions by default for ATR source staging and Nexus JVM staging; use the retained local manual workflow only when the user explicitly requests manual publishing.

02 资源文件 5

03 SKILL.md 正文

Apache Fory Release

Use .github/workflows/stage-release-candidate.yml for source and JVM staging unless the user explicitly asks for a manual release. The workflow uses ci/release.py; do not reproduce its source-build, JVM-publication, Nexus closure, or artifact-verification logic in shell commands. Do not add unrelated test runs.

Release automation, CI, and artifact-compliance fixes belong in PRs targeting apache/main. Merge those fixes before preparing the candidate. Keep the version-preparation branch local and push only the immutable RC tag; do not push a releases-* branch or target it with repair PRs unless the release manager explicitly requests that separate branch workflow.

CI signing and staging prerequisites

The workflow runs only in apache/fory and uses these Infra-provisioned GitHub Actions secrets:

Secret Purpose
FORY_GPG_SECRET_KEY Import the Infra-managed CI signing key in each signing job
NEXUS_STAGE_DEPLOYER_USER Authenticate Java/Kotlin and Scala Nexus staging
NEXUS_STAGE_DEPLOYER_PW Authenticate Java/Kotlin and Scala Nexus staging

Source staging uses ATR with GitHub OIDC, not SVN credentials. Do not add a personal signing key, a GPG passphrase secret, or SVN credentials to this flow.

Source packaging requires Syft 1.57.0. CI installs this pinned version; install the same version on the trusted verification machine and put syft on PATH (or set SYFT to its executable path). The build emits a signed CycloneDX 1.6 SBOM beside the source archive, with its own SHA-512 checksum. It inventories the manifests and lock files included in the archive; it is not a complete resolved dependency inventory for every runtime's binaries. Dependency enrichment is disabled and the source commit supplies the timestamp so the SBOM can be compared byte-for-byte during verification.

The source archive includes .rat-excludes for machine-readable metadata, bundled license texts, and specifically attributed third-party files. Keep third-party notices intact. The matching lightweight-check exclusions are in .asf.yaml under project.policy.source_excludes_lightweight. ASF synchronizes that policy from the default branch. After merging policy changes to apache/main, confirm the exact patterns are active in ATR before staging. Do not disable either license check or add broad source-directory exclusions.

The Nexus account must have staging access to the org.apache.fory profile. Provisioning the shared CI credentials alone does not grant access to this project. stage_jvm checks profile access before building or uploading artifacts; if it is missing, ask Infra to grant Fory staging access to the provisioned CI account. Do not replace the CI credentials with a personal account.

Before the first CI release, or after a signing-key rotation:

  • Obtain the CI public key and its full primary fingerprint from Infra's message to the project's private mailing list. Confirm that this public key is present in the published Fory KEYS. If it is absent, arrange publication of the public key before staging a candidate. Keep private key material and revocation certificates out of the repository.
  • Set gpg_fingerprint to that independently confirmed CI key fingerprint for local verification and the vote email. Do not reuse a personal signing fingerprint from an earlier manual release or trust a CI log alone.
  • Merge the staging workflow to the default branch before dispatching it, and create the RC from a commit that contains the workflow. Do not move an old RC tag to make the workflow available.

Secret provisioning and ordinary PR checks do not prove that signing, ATR upload, or Nexus staging works. The first authorized CI staging run must succeed, and its artifacts must pass the trusted-hardware verification below before voting.

Required Inputs

Collect these values before starting:

  • release_version: final version without v or an RC suffix, such as 1.7.0.
  • rc: RC suffix, such as rc3.
  • previous_version: previous release tag version, such as 1.6.1.
  • Release discussion URL, if already known. If it is not supplied, find the exact release thread in the Fory development-list archive as described below.

Derive the release values:

release_branch="releases-${release_version}"
rc_tag="v${release_version}-${rc}"
release_candidate_url="https://releases.apache.org/download/path/fory/${release_version}"

Find the release discussion

If the release discussion URL was not supplied, search the Fory development-list archive for the exact release version and a [DISCUSS] subject. Use the deterministic helper, which accepts exactly one root discussion thread:

discussion_url="$(
  python3 .agents/skills/fory-release/scripts/find_discussion.py \
    "$release_version"
)"

Open the resulting URL and verify that its subject and body discuss the exact release_version. If the automated search finds zero or multiple roots, use the archive UI to search the same exact version and [DISCUSS]; ask the release manager only if the result remains absent or ambiguous. When a URL is supplied, open and verify it instead of assuming it matches this release.

Default CI Workflow

1. Create a clean local release branch

Run from the repository root. Clean means no staged, modified, or untracked files.

test -z "$(git status --porcelain)"
test "$(git remote get-url apache)" = "git@github.com:apache/fory.git"
git fetch apache main --tags
git switch -c "$release_branch" apache/main
test -z "$(git status --porcelain)"

For a new release branch, stop if the branch already exists or either cleanliness check fails. To resume an existing candidate, follow Release retries instead of recreating its branch or tag. Do not remove or hide user files to make the check pass.

2. Bump the version

python3 ci/release.py bump_version -version "$release_version" -l all
git diff --check
git status --short

Review the version diff. Use this command directly; do not substitute another version-bump workflow.

3. Commit the release version

git add -u
git commit -m "prepare release for ${release_version}"
test -z "$(git status --porcelain)"
release_commit="$(git rev-parse HEAD)"

Stage only the version changes produced by the release script. Keep this version-preparation commit local until the RC tag is pushed in the next step.

4. Create and push the RC tag

Before creating a new RC tag, confirm that neither the local nor remote tag already exists. Never move, delete, or overwrite a published RC tag. Retrying a workflow for its existing tag does not create a new candidate; follow Release retries.

test -z "$(git tag --list "$rc_tag")"
test -z "$(git ls-remote --tags apache "refs/tags/${rc_tag}")"
test "$(git rev-parse HEAD)" = "$release_commit"
git tag "$rc_tag" && git push apache "$rc_tag"
test "$(git rev-parse "${rc_tag}^{commit}")" = "$release_commit"

The tag starts the ecosystem package-release workflows. A later infrastructure failure does not by itself change the candidate; diagnose it using Release retries.

5. Stage source and JVM artifacts in CI

Dispatch the staging workflow on the immutable RC tag:

gh workflow run stage-release-candidate.yml \
  --repo apache/fory \
  --ref "$rc_tag" \
  -f source=true \
  -f jvm=true

Record the exact workflow run ID and URL and wait for it with gh run watch --exit-status. Do not select a run only by commit SHA because a main-branch run can share the same commit. The workflow stages the signed source archive to Apache Trusted Release through OIDC, publishes the JVM artifacts, and closes the Java/Kotlin and Scala Nexus repositories. It does not use SVN.

From the successful run summary, record and open both distinct Nexus staging repository IDs and the ATR candidate URL. Also record the reported Java runtime version and vendor for the independent rebuild:

java_kotlin_staging_id="orgapachefory-..."
scala_staging_id="orgapachefory-..."
java_runtime_version="..." # Complete java.runtime.version from JVM staging
java_vendor="..." # Exact java.vendor from JVM staging
test -n "$java_kotlin_staging_id"
test -n "$scala_staging_id"
test "$java_kotlin_staging_id" != "$scala_staging_id"

Keep both repositories closed during the vote. Do not promote them until the vote passes.

6. Check the tag-triggered workflows

Inspect every workflow triggered by the tag. Filter by the tag rather than only by commit SHA so main-branch runs at the same commit are not mixed into the result. By default, wait for every run and require successful conclusions:

python3 .agents/skills/fory-release/scripts/check_tag_workflows.py \
  --repo apache/fory \
  --tag "$rc_tag" \
  --commit "$release_commit" \
  --watch

The helper re-queries by tag after waiting to catch later-created runs. A failed run requires diagnosis, not an automatic RC increment. For a transient failure, rerun only the failed jobs with gh run rerun <run-id> --repo apache/fory --failed, then run the helper again for the same tag and commit.

If the release manager explicitly waives workflow monitoring for a particular RC, run the same command with --allow-incomplete instead of --watch, and record the snapshot IDs, states, and reason. Do not cancel the remote workflows or report incomplete runs as successful.

7. Verify all CI artifacts on trusted hardware

Do not run this comparison in GitHub Actions. Use the independently confirmed Infra-managed CI key fingerprint from the prerequisites. Install the same JDK distribution and complete runtime version recorded by JVM staging, including the build suffix, and set JAVA_HOME and PATH to it. Then run the repository verifier on a machine controlled by the release manager:

: "${gpg_fingerprint:?missing CI signing-key fingerprint}"
python3 ci/release.py verify_ci_artifacts \
  -v "$release_version" \
  --rc-tag "$rc_tag" \
  --java-kotlin-id "$java_kotlin_staging_id" \
  --scala-id "$scala_staging_id" \
  --gpg-fingerprint "$gpg_fingerprint" \
  --java-runtime-version "$java_runtime_version" \
  --java-vendor "$java_vendor" \
  --source-url "$release_candidate_url"

The command checks out the exact RC commit in a temporary clone, rebuilds the source archive, source SBOM, and complete JVM publication without signing or upload credentials, verifies the staged signatures with the public key, and compares every source, JAR, POM, source JAR, documentation JAR, and distribution file byte-for-byte. Each JVM ecosystem is built once and may reuse the machine's normal dependency caches; only source and build outputs are clean. It writes a Markdown report under dist/. Any mismatch or missing artifact blocks the vote. Before downloading or rebuilding, the verifier requires an OpenJDK 25 runtime whose java.runtime.version and java.vendor exactly match the supplied staging values. Matching only the Java major version is insufficient. The verifier also requires the expected public key in KEYS; local personal keyrings are not used to satisfy this check. Failed verification retains the local rebuild and downloaded artifacts beside the report for diagnosis; successful verification removes these temporary files. After a download failure, retry with --rebuild-dir <retained-directory> to reuse the completed unsigned build on the same machine without recompiling. The completed rebuild must have a matching JDK record; a missing or different record requires a fresh build. The checkout must still match the RC commit and remain unchanged. Downloads, signature checks, and every byte comparison run again; retained files are not deleted in this mode. Source packaging uses a direct git archive of the RC tag without rewriting LICENSE, creating commits, or moving refs. Benchmark-specific attribution stays in benchmarks/LICENSE and benchmarks/NOTICE with the excluded benchmark sources.

8. Draft the vote email

Load only the release-manager identity from .local/fory-release.env when drafting the email. Never commit this ignored file or store release secrets in it.

release_config="$(git rev-parse --show-toplevel)/.local/fory-release.env"
test -f "$release_config"
. "$release_config"
release_manager_name="${FORY_RELEASE_MANAGER_NAME:?missing release manager name}"

Read the vote email template and produce a complete, copyable email. Fill every placeholder from verified output, attach the trusted-hardware report or link an existing public copy, and state that the vote remains open for at least 72 hours without specifying a closing date or time. Do not send the email unless requested.

Explicit Manual Workflow

Only when the user explicitly requests manual publishing, read and follow the manual release workflow. Do not fall back to it automatically after a CI failure.

Verification-Only Requests

For an existing candidate, do not create another tag or staging repository. Confirm the exact tag, commit, source URL (ATR or manual SVN), both Nexus repository IDs, and signing-key fingerprint from the vote. Check the tag workflows and run step 7 against those artifacts. Rebuild the unmodified RC checkout, not the verifier's branch; never copy newer POMs or sources into the RC to force a match. Report any mismatch against the original candidate.

GitHub Release Title and Notes

When authorized to create the final GitHub Release after the vote passes:

  • Set the title to the version tag alone, such as v1.7.6, not Apache Fory 1.7.6. Use --title "v${release_version}" when creating it with gh release create.
  • Put important features in a ## Highlights section before the full change list. Give each important feature its own named ### subsection rather than leaving it only as an entry in the change list. Explain what users can do with it and include a concise example or documentation link where useful.
  • Describe only features included in that release; preserve the complete change list after the highlights.

Release retries

An RC identifies the release content under review, not a CI attempt. Inspect the failed step and its logs before deciding how to recover. Network timeouts, dependency-download failures, runner failures, and interrupted status checks do not by themselves invalidate an unchanged candidate.

Without a substantive release change, keep the same release commit and RC tag and resume only the failed or incomplete steps. Preserve verified Maven staging repositories and source artifacts; do not rebuild or republish successful artifacts merely because an unrelated CI job failed. Before retrying a push, upload, Nexus action, or SVN commit, inspect remote state because an interrupted request may already have succeeded. Use the Nexus reference's --verify-only path for repositories that are already closed.

Create a higher RC only when a substantive fix changes the release content, such as source, dependencies, build inputs, or packaging. Commit the actual fix before tagging the replacement; do not create an empty commit or a second RC at the same unchanged release commit just to retry infrastructure. Keep the previous tag immutable and verify the replacement artifacts through the release workflow. An unresolved code or artifact defect still blocks the vote.

Stop Conditions

Before creating a new tag, stop if the Git tree is dirty, the tag already exists, or its target would differ from the release commit. A failed workflow, staging operation, or artifact check pauses the dependent step until it is diagnosed and recovered under Release retries; failure alone does not require a higher RC. Before sending the vote, require the selected source candidate URL (ATR or manual SVN) and both closed Nexus repositories to be public, the trusted-hardware report to show a complete byte-for-byte match, and tag workflows to be successful unless the release manager explicitly waived monitoring.

References

04 同仓库更多 Skills