You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tooling.apache.org by ar...@apache.org on 2026/09/30 17:23:24 UTC

(tooling-trusted-releases) 02/12: #1437 - update phase docs

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

alitheg pushed a commit to branch 1437-docs
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git

commit 6d1e959b6de7ce366562123cd3de26a4cd3724ce
Author: Alastair McFarlane <ar...@apache.org>
AuthorDate: Mon Sep 28 17:07:15 2026 +0100

    #1437 - update phase docs
---
 atr/docs/checks.md                      |  8 ++---
 atr/docs/compose-phase.md               | 54 +++++++++++++++++++++++++++++++++
 atr/docs/finish-phase.md                | 45 +++++++++++++++++++++++++++
 atr/docs/index.md                       | 13 +++++---
 atr/docs/license-checks.md              |  8 ++---
 atr/docs/overview-of-the-code.md        |  2 +-
 atr/docs/promoting-to-release.md        |  8 ++---
 atr/docs/release-process-description.md |  8 ++---
 atr/docs/sbom-workflows.md              |  8 ++---
 atr/docs/staging-and-voting.md          |  8 ++---
 atr/docs/trusted-publishing.md          |  2 +-
 atr/docs/vote-phase.md                  | 43 ++++++++++++++++++++++++++
 12 files changed, 175 insertions(+), 32 deletions(-)

diff --git a/atr/docs/checks.md b/atr/docs/checks.md
index d2729a86..00dfe459 100644
--- a/atr/docs/checks.md
+++ b/atr/docs/checks.md
@@ -1,10 +1,10 @@
-# 5.1. Checks
+# 5.1.1. Checks
 
-**Up**: `5.` [Making releases](release-process-description)
+**Up**: `5.1.` [Compose phase](compose-phase)
 
-**Prev**: `4.2.` [Trusted Publishing](trusted-publishing)
+**Prev**: (none)
 
-**Next**: `5.2.` [License checks](license-checks)
+**Next**: `5.1.2.` [License checks](license-checks)
 
 **Sections**:
 
diff --git a/atr/docs/compose-phase.md b/atr/docs/compose-phase.md
new file mode 100644
index 00000000..1c323e18
--- /dev/null
+++ b/atr/docs/compose-phase.md
@@ -0,0 +1,54 @@
+# 5.1. Compose phase
+
+**Up**: `5.` [Making releases](release-process-description)
+
+**Prev**: `4.2.` [Trusted Publishing](trusted-publishing)
+
+**Next**: `5.2.` [Vote phase](vote-phase)
+
+**Pages**:
+
+* `5.1.1.` [Checks](checks)
+* `5.1.2.` [License checks](license-checks)
+* `5.1.3.` [SBOM workflows](sbom-workflows)
+
+**Sections**:
+
+* [Overview](#overview)
+* [Responsibilities](#responsibilities)
+* [Checks and compliance](#checks-and-compliance)
+
+## Overview
+
+The ***compose*** phase is where a ***Release Candidate*** is built up from its parts. The
+***Release Manager*** assembles the ***Release Artifacts***, uploads them to ATR, and runs the
+platform's checks against them. Composing is deliberately iterative: the Release Manager can add,
+replace, and remove artifacts, and re-run the checks, until the candidate is ready to put to a
+vote. Nothing composed in this phase is public, and nothing is committed to the Apache
+distribution servers until the [finish phase](finish-phase).
+
+## Responsibilities
+
+The compose phase is mostly the work of the Release Manager, on behalf of the PMC:
+
+* Assemble the release artifacts and upload them to the candidate.
+* Sign each artifact and register the corresponding key, so that ATR and, later, end users can
+  verify the signatures. See [Signing artifacts](signing-artifacts), and
+  [Release managers](release-manager-setup) for the keys and access methods available to you.
+* Run the checks and resolve anything they report before starting a vote.
+
+Other PMC members are not required to act during compose, but the candidate is visible to them,
+and it is good practice to review it before it goes to a vote.
+
+## Checks and compliance
+
+ATR runs a number of automated checks over the composed artifacts to catch problems early, while
+they are still cheap to fix. These cover the integrity of the artifacts, their licensing, and the
+software bill of materials where one is provided:
+
+* [Checks](checks) - the checks ATR runs and how to read their results.
+* [License checks](license-checks) - how ATR helps you follow ASF licensing policy.
+* [SBOM workflows](sbom-workflows) - generating and attaching a software bill of materials.
+
+The checks are advisory during compose - they are there to help you produce a candidate that the
+PMC can vote on with confidence, not to block you from iterating.
diff --git a/atr/docs/finish-phase.md b/atr/docs/finish-phase.md
new file mode 100644
index 00000000..f8fb37c1
--- /dev/null
+++ b/atr/docs/finish-phase.md
@@ -0,0 +1,45 @@
+# 5.3. Finish phase
+
+**Up**: `5.` [Making releases](release-process-description)
+
+**Prev**: `5.2.` [Vote phase](vote-phase)
+
+**Next**: `7.1.` [Overview of the code](overview-of-the-code)
+
+**Pages**:
+
+* `5.3.1.` [Promoting to release](promoting-to-release)
+
+**Sections**:
+
+* [Overview](#overview)
+* [Responsibilities](#responsibilities)
+* [Publishing and announcing](#publishing-and-announcing)
+
+## Overview
+
+The ***finish*** phase turns an approved ***Release Candidate*** into a published release. Once a
+vote has passed, the ***Release Artifacts*** are committed to the Apache distribution SVN
+repository, at `svn:dist:release`, and from there they propagate to the download servers and the
+CDN. The announcement is held back until the artifacts have actually reached the download servers,
+so that the links in the announcement work when readers follow them. Once the artifacts are
+available and the announcement has been sent, the release is published to the
+[Release catalog](release-catalog).
+
+## Responsibilities
+
+The finish phase is again mostly the work of the Release Manager:
+
+* Promote the approved candidate, which commits the artifacts to `svn:dist:release`.
+* Wait for the artifacts to reach the download servers before announcing, rather than announcing
+  as soon as the commit lands.
+* Send the announcement once the downloads are live.
+
+## Publishing and announcing
+
+ATR commits the artifacts directly to `svn:dist:release` and defers the announcement until they
+are available for download, so there is no window in which the announcement points at files that
+are not yet there. After publication the release is cataloged alongside every other current and
+archived ASF release. See [Promoting to release](promoting-to-release) for the mechanics of the
+commit and announcement, and [Release catalog](release-catalog) for where the finished release
+ends up.
diff --git a/atr/docs/index.md b/atr/docs/index.md
index e23b9e87..f54facd3 100644
--- a/atr/docs/index.md
+++ b/atr/docs/index.md
@@ -14,11 +14,14 @@ NOTE: This documentation is a work in progress.
   * `4.1.` [Signing artifacts](signing-artifacts)
   * `4.2.` [Trusted Publishing](trusted-publishing)
 * `5.` [Making releases](release-process-description)
-  * `5.1.` [Checks](checks)
-  * `5.2.` [License checks](license-checks)
-  * `5.3.` [SBOM workflows](sbom-workflows)
-  * `5.4.` [Staging and voting](staging-and-voting)
-  * `5.5.` [Promoting to release](promoting-to-release)
+  * `5.1.` [Compose phase](compose-phase)
+    * `5.1.1.` [Checks](checks)
+    * `5.1.2.` [License checks](license-checks)
+    * `5.1.3.` [SBOM workflows](sbom-workflows)
+  * `5.2.` [Vote phase](vote-phase)
+    * `5.2.1.` [Staging and voting](staging-and-voting)
+  * `5.3.` [Finish phase](finish-phase)
+    * `5.3.1.` [Promoting to release](promoting-to-release)
 * `6.` [Release catalog](release-catalog)
 * `7.` [Developer guide](developer-guide)
   * `7.1.` [Overview of the code](overview-of-the-code)
diff --git a/atr/docs/license-checks.md b/atr/docs/license-checks.md
index 2733dd28..30bef2cc 100644
--- a/atr/docs/license-checks.md
+++ b/atr/docs/license-checks.md
@@ -1,10 +1,10 @@
-# 5.2. License checks
+# 5.1.2. License checks
 
-**Up**: `5.` [Making releases](release-process-description)
+**Up**: `5.1.` [Compose phase](compose-phase)
 
-**Prev**: `5.1.` [Checks](checks)
+**Prev**: `5.1.1.` [Checks](checks)
 
-**Next**: `5.3.` [SBOM workflows](sbom-workflows)
+**Next**: `5.1.3.` [SBOM workflows](sbom-workflows)
 
 **Sections**:
 
diff --git a/atr/docs/overview-of-the-code.md b/atr/docs/overview-of-the-code.md
index 44d241a0..30b69e43 100644
--- a/atr/docs/overview-of-the-code.md
+++ b/atr/docs/overview-of-the-code.md
@@ -2,7 +2,7 @@
 
 **Up**: `7.` [Developer guide](developer-guide)
 
-**Prev**: `5.5.` [Promoting to release](promoting-to-release)
+**Prev**: `5.3.` [Finish phase](finish-phase)
 
 **Next**: `7.2.` [How to contribute](how-to-contribute)
 
diff --git a/atr/docs/promoting-to-release.md b/atr/docs/promoting-to-release.md
index 114ae2ce..4d4af7c5 100644
--- a/atr/docs/promoting-to-release.md
+++ b/atr/docs/promoting-to-release.md
@@ -1,10 +1,10 @@
-# 5.5. Promoting to release
+# 5.3.1. Promoting to release
 
-**Up**: `5.` [Making releases](release-process-description)
+**Up**: `5.3.` [Finish phase](finish-phase)
 
-**Prev**: `5.4.` [Staging and voting](staging-and-voting)
+**Prev**: `5.2.1.` [Staging and voting](staging-and-voting)
 
-**Next**: `7.1.` [Overview of the code](overview-of-the-code)
+**Next**: (none)
 
 **Sections**:
 
diff --git a/atr/docs/release-process-description.md b/atr/docs/release-process-description.md
index e9f68b57..1666a153 100644
--- a/atr/docs/release-process-description.md
+++ b/atr/docs/release-process-description.md
@@ -8,11 +8,9 @@
 
 **Pages**:
 
-* `5.1.` [Checks](checks)
-* `5.2.` [License checks](license-checks)
-* `5.3.` [SBOM workflows](sbom-workflows)
-* `5.4.` [Staging and voting](staging-and-voting)
-* `5.5.` [Promoting to release](promoting-to-release)
+* `5.1.` [Compose phase](compose-phase)
+* `5.2.` [Vote phase](vote-phase)
+* `5.3.` [Finish phase](finish-phase)
 
 **Sections**:
 
diff --git a/atr/docs/sbom-workflows.md b/atr/docs/sbom-workflows.md
index 18e4b776..48651f8f 100644
--- a/atr/docs/sbom-workflows.md
+++ b/atr/docs/sbom-workflows.md
@@ -1,10 +1,10 @@
-# 5.3. SBOM workflows
+# 5.1.3. SBOM workflows
 
-**Up**: `5.` [Making releases](release-process-description)
+**Up**: `5.1.` [Compose phase](compose-phase)
 
-**Prev**: `5.2.` [License checks](license-checks)
+**Prev**: `5.1.2.` [License checks](license-checks)
 
-**Next**: `5.4.` [Staging and voting](staging-and-voting)
+**Next**: `5.2.1.` [Staging and voting](staging-and-voting)
 
 **Sections**:
 
diff --git a/atr/docs/staging-and-voting.md b/atr/docs/staging-and-voting.md
index b32098d5..92782948 100644
--- a/atr/docs/staging-and-voting.md
+++ b/atr/docs/staging-and-voting.md
@@ -1,10 +1,10 @@
-# 5.4. Staging and voting
+# 5.2.1. Staging and voting
 
-**Up**: `5.` [Making releases](release-process-description)
+**Up**: `5.2.` [Vote phase](vote-phase)
 
-**Prev**: `5.3.` [SBOM workflows](sbom-workflows)
+**Prev**: `5.1.3.` [SBOM workflows](sbom-workflows)
 
-**Next**: `5.5.` [Promoting to release](promoting-to-release)
+**Next**: `5.3.1.` [Promoting to release](promoting-to-release)
 
 **Sections**:
 
diff --git a/atr/docs/trusted-publishing.md b/atr/docs/trusted-publishing.md
index e3d23d13..899a14e9 100644
--- a/atr/docs/trusted-publishing.md
+++ b/atr/docs/trusted-publishing.md
@@ -4,7 +4,7 @@
 
 **Prev**: `4.1.` [Signing artifacts](signing-artifacts)
 
-**Next**: `5.1.` [Checks](checks)
+**Next**: `5.1.` [Compose phase](compose-phase)
 
 **Sections**:
 
diff --git a/atr/docs/vote-phase.md b/atr/docs/vote-phase.md
new file mode 100644
index 00000000..cc15cea9
--- /dev/null
+++ b/atr/docs/vote-phase.md
@@ -0,0 +1,43 @@
+# 5.2. Vote phase
+
+**Up**: `5.` [Making releases](release-process-description)
+
+**Prev**: `5.1.` [Compose phase](compose-phase)
+
+**Next**: `5.3.` [Finish phase](finish-phase)
+
+**Pages**:
+
+* `5.2.1.` [Staging and voting](staging-and-voting)
+
+**Sections**:
+
+* [Overview](#overview)
+* [Responsibilities](#responsibilities)
+* [Casting and resolving the vote](#casting-and-resolving-the-vote)
+
+## Overview
+
+The ***vote*** phase is where the PMC decides, as an act of the Foundation, whether the
+***Release Candidate*** should become a release. Once the Release Manager is satisfied with the
+composed candidate they start a vote, and the PMC votes to approve it or not. The artifacts being
+voted on stay in ATR for the duration of the vote, so the vote email can link to them directly and
+every voter reviews the same thing. A vote may be canceled and restarted if a problem comes to
+light. Once a vote passes, the candidate is ready to publish in the [finish phase](finish-phase).
+
+## Responsibilities
+
+Both the Release Manager and the wider PMC have a part to play in this phase:
+
+* The ***Release Manager*** starts the vote, links to the artifacts under vote, and, when the
+  vote is over, tallies the result and resolves it.
+* PMC members review the candidate and cast their votes. Whose votes are binding is a matter of
+  ASF policy, and ATR records each vote against the candidate.
+
+## Casting and resolving the vote
+
+ATR keeps the candidate and its artifacts staged for the whole of the vote, and records the votes
+as they are cast. When the vote is complete the Release Manager resolves it: a passing vote moves
+the candidate on to the finish phase, and a failed or canceled vote returns it to compose so that
+it can be revised. See [Staging and voting](staging-and-voting) for how staging, vote emails, and
+resolution work in ATR.


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