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:27 UTC
(tooling-trusted-releases) 05/12: #1437 - typos and nav fixes
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 d7ed681eafa657a793d2d6ee42ff0435b2834bd4
Author: Alastair McFarlane <ar...@apache.org>
AuthorDate: Tue Sep 29 10:10:50 2026 +0100
#1437 - typos and nav fixes
---
atr/docs/checks.md | 2 +-
atr/docs/compose-phase.md | 12 +++++++-----
atr/docs/developer-guide.md | 2 +-
atr/docs/finish-phase.md | 9 ++++-----
atr/docs/getting-started.md | 20 ++++++++++----------
atr/docs/overview-of-the-code.md | 2 +-
atr/docs/project-configuration.md | 4 ++--
atr/docs/projects.md | 10 +++++-----
atr/docs/promoting-to-release.md | 4 ++--
atr/docs/release-catalog.md | 2 +-
atr/docs/release-manager-setup.md | 6 +++---
atr/docs/release-process-description.md | 8 ++++----
atr/docs/sbom-workflows.md | 2 +-
atr/docs/scope.md | 4 ++--
atr/docs/signing-artifacts.md | 2 +-
atr/docs/staging-and-voting.md | 4 ++--
atr/docs/trusted-publishing.md | 2 +-
atr/docs/vote-phase.md | 12 ++++++------
scripts/docs_build.py | 14 +++-----------
19 files changed, 57 insertions(+), 64 deletions(-)
diff --git a/atr/docs/checks.md b/atr/docs/checks.md
index 00dfe459..04dd4673 100644
--- a/atr/docs/checks.md
+++ b/atr/docs/checks.md
@@ -2,7 +2,7 @@
**Up**: `5.1.` [Compose phase](compose-phase)
-**Prev**: (none)
+**Prev**: `5.1.` [Compose phase](compose-phase)
**Next**: `5.1.2.` [License checks](license-checks)
diff --git a/atr/docs/compose-phase.md b/atr/docs/compose-phase.md
index 1c323e18..cba53561 100644
--- a/atr/docs/compose-phase.md
+++ b/atr/docs/compose-phase.md
@@ -2,9 +2,9 @@
**Up**: `5.` [Making releases](release-process-description)
-**Prev**: `4.2.` [Trusted Publishing](trusted-publishing)
+**Prev**: `5.` [Making releases](release-process-description)
-**Next**: `5.2.` [Vote phase](vote-phase)
+**Next**: `5.1.1.` [Checks](checks)
**Pages**:
@@ -24,7 +24,7 @@ The ***compose*** phase is where a ***Release Candidate*** is built up from its
***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
+vote. The candidate is held in ATR throughout, and nothing is committed to the Apache
distribution servers until the [finish phase](finish-phase).
## Responsibilities
@@ -50,5 +50,7 @@ software bill of materials where one is provided:
* [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.
+Most check results are there to help you produce a candidate that the PMC can vote on with
+confidence, and you can keep iterating whatever they report. A ***blocker***, though, means that a
+mandatory policy condition has been violated, and the candidate cannot proceed to a vote until it
+is resolved.
diff --git a/atr/docs/developer-guide.md b/atr/docs/developer-guide.md
index 83a87f91..cb765fd5 100644
--- a/atr/docs/developer-guide.md
+++ b/atr/docs/developer-guide.md
@@ -4,7 +4,7 @@
**Prev**: `6.` [Release catalog](release-catalog)
-**Next**: (none)
+**Next**: `7.1.` [Overview of the code](overview-of-the-code)
**Pages**:
diff --git a/atr/docs/finish-phase.md b/atr/docs/finish-phase.md
index f8fb37c1..51d7db9f 100644
--- a/atr/docs/finish-phase.md
+++ b/atr/docs/finish-phase.md
@@ -2,9 +2,9 @@
**Up**: `5.` [Making releases](release-process-description)
-**Prev**: `5.2.` [Vote phase](vote-phase)
+**Prev**: `5.2.1.` [Staging and voting](staging-and-voting)
-**Next**: `7.1.` [Overview of the code](overview-of-the-code)
+**Next**: `5.3.1.` [Promoting to release](promoting-to-release)
**Pages**:
@@ -31,9 +31,8 @@ available and the announcement has been sent, the release is published to the
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.
+* Announce the release through ATR. ATR checks that the artifacts have reached the download
+ servers first, and if they have not finished propagating it asks you to try again later.
## Publishing and announcing
diff --git a/atr/docs/getting-started.md b/atr/docs/getting-started.md
index 7f972155..a3791a7b 100644
--- a/atr/docs/getting-started.md
+++ b/atr/docs/getting-started.md
@@ -12,23 +12,23 @@
## Getting started with ATR
-There are prepatory steps you need to consider prior to starting your first ATR release as a Release Manager.
+There are some preparatory steps to take before you start your first ATR release as a Release Manager.
If your PMC is new to using ATR you will want to make sure that the project you are releasing a new version for is properly configured.
-In ATR you move your release candidate's artifacts into the system using one or more of several methods while traditionally you would commit
-them to `svn:dist:dev`.
+Traditionally you would commit your release candidate's artifacts to `svn:dist:dev`, whereas in ATR you move them into the system using
+one or more of several methods.
-1. ATR uses the ASF's MFA at mfa.apache.org. Make sure that you are registered first.
+1. ATR uses the ASF's multi-factor authentication at [mfa.apache.org](https://mfa.apache.org/). Make sure that you are registered first.
2. If you are a Release Manager who is not a PMC member then you will need a PMC member to "designate" you as one from the Committee page.
This is a change from legacy policy.
-3. You need to make sure that ATR has your [OpenPGP public key](/keys) is linked to your PMC. If your key is already in your project's
+3. Make sure that ATR has your [OpenPGP public key](/keys) linked to your PMC. If your key is already in your project's
`KEYS` file on `svn:dist:release` then you are ready. If not then ATR allows you to manage your [OpenPGP public keys](/keys).
-4. Depending on how you choose to upload your release candidate artifacts you may need to create a [Parsonal Access Token](/tokens) or
+4. Depending on how you choose to upload your release candidate artifacts you may need to create a [Personal Access Token](/tokens) or
upload a [public `SSH` key](/keys).
-5. Check your PMC's [release catalog](https://release-catalog.apache.org) to assure that the list of projects is correct. Reach out to the
+5. Check your PMC's [release catalog](https://release-catalog.apache.org) to make sure that the list of projects is correct. Reach out to the
tooling team to work on any corrections.
-6. When you login to ATR your [home page](/) shows you a list of your projects as an index and scroll down to
+6. When you log in to ATR your [home page](/) shows an index of your projects. Scroll down to a project to:
* Check the project's configuration through the "About this project" link.
- * See any release candidates that are in process.
+ * See any release candidates that are in progress.
* Start a new release candidate.
- * See any finished releases including current and archived made through ATR and also as found on https://downloads.apache.org/ and
+ * See any finished releases, current and archived, whether made through ATR or found on https://downloads.apache.org/ and
https://archive.apache.org/
diff --git a/atr/docs/overview-of-the-code.md b/atr/docs/overview-of-the-code.md
index 30b69e43..18d148a1 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.3.` [Finish phase](finish-phase)
+**Prev**: `7.` [Developer guide](developer-guide)
**Next**: `7.2.` [How to contribute](how-to-contribute)
diff --git a/atr/docs/project-configuration.md b/atr/docs/project-configuration.md
index 942048a0..fba8ad18 100644
--- a/atr/docs/project-configuration.md
+++ b/atr/docs/project-configuration.md
@@ -2,9 +2,9 @@
**Up**: `3.` [Projects](projects)
-**Prev**: (none)
+**Prev**: `3.` [Projects](projects)
-**Next**: `4.1.` [Signing artifacts](signing-artifacts)
+**Next**: `4.` [Release managers](release-manager-setup)
**Sections**:
diff --git a/atr/docs/projects.md b/atr/docs/projects.md
index 2b69c05d..fb9cc64b 100644
--- a/atr/docs/projects.md
+++ b/atr/docs/projects.md
@@ -4,7 +4,7 @@
**Prev**: `2.` [Getting started](getting-started)
-**Next**: `4.` [Release managers](release-manager-setup)
+**Next**: `3.1.` [Project configuration](project-configuration)
**Pages**:
@@ -24,13 +24,13 @@
## Introduction
-The Apache Trusted Releases (***ATR***) provides a standard and easy way for a Project Management Committee (***PMC***) or incubating project (***PPMC***)
+The Apache Trusted Releases (***ATR***) platform provides a standard and easy way for a Project Management Committee (***PMC***) or incubating project (***PPMC***)
to manage their releases in order to easily follow the Apache Way of governance. Most ASF documentation and systems use the following
-interchangable terms for PMCs: "Projects", Top Level Project (TLP), and "Podlings". For the ATR we felt it was important to make a distinction
+interchangeable terms for PMCs: "Projects", Top Level Project (TLP), and "Podlings". For the ATR we felt it was important to make a distinction
between the people involved in the PMC and the software produced. The platform provides a way for a committee to manage their project's software
releases.
-ATR models several kinds of component that correspond to organisational resources at the ASF, with some refinements of our own. We studied the
+ATR models several kinds of component that correspond to organizational resources at the ASF, with some refinements of our own. We studied the
release patterns of PMCs with unusually demanding release models - Airflow, Maven, Commons, Sling, and others - before designing this system. The
sections below define the major terminology as it is used in ATR.
@@ -45,7 +45,7 @@ for PPMCs.
* Committees in ATR have one or more ***Projects***.
* The ***Roster*** shows the committers and PMC Members of the committee, and allows for designation of committers as Release Managers.
* ***Permissions*** shows whether the committee is allowed to build release artifacts in ***CI***.
-* Each committee has a list of ***Signing Keys*** - the members' ***GPG public keys*** - which may be used to sign artifacts.
+* Each committee has a list of ***Signing Keys*** - the members' ***OpenPGP public keys*** - which may be used to sign artifacts.
## Project
diff --git a/atr/docs/promoting-to-release.md b/atr/docs/promoting-to-release.md
index 4d4af7c5..75d30ca4 100644
--- a/atr/docs/promoting-to-release.md
+++ b/atr/docs/promoting-to-release.md
@@ -2,9 +2,9 @@
**Up**: `5.3.` [Finish phase](finish-phase)
-**Prev**: `5.2.1.` [Staging and voting](staging-and-voting)
+**Prev**: `5.3.` [Finish phase](finish-phase)
-**Next**: (none)
+**Next**: `6.` [Release catalog](release-catalog)
**Sections**:
diff --git a/atr/docs/release-catalog.md b/atr/docs/release-catalog.md
index fae457a5..97451b6f 100644
--- a/atr/docs/release-catalog.md
+++ b/atr/docs/release-catalog.md
@@ -2,7 +2,7 @@
**Up**: [Documentation](.)
-**Prev**: `5.` [Making releases](release-process-description)
+**Prev**: `5.3.1.` [Promoting to release](promoting-to-release)
**Next**: `7.` [Developer guide](developer-guide)
diff --git a/atr/docs/release-manager-setup.md b/atr/docs/release-manager-setup.md
index f8a58596..a256665f 100644
--- a/atr/docs/release-manager-setup.md
+++ b/atr/docs/release-manager-setup.md
@@ -2,9 +2,9 @@
**Up**: [Documentation](.)
-**Prev**: `3.` [Projects](projects)
+**Prev**: `3.1.` [Project configuration](project-configuration)
-**Next**: `5.` [Making releases](release-process-description)
+**Next**: `4.1.` [Signing artifacts](signing-artifacts)
**Pages**:
@@ -52,7 +52,7 @@ Some upload methods authenticate you over ***SSH*** rather than by token. For th
### Personal access tokens
-A ***Personal Access Token*** (***PAT***) is a long-lived credential that identifies you to ATR's API and command-line tooling. Create one on the [tokens page](/tokens). ATR stores only a hash of the token and never the token itself, so make a note of it when it is first shown to you. You can optionally bind a token to a single IP address or range. Treat a PAT like a password, and revoke it from the same page if it is ever exposed.
+A ***Personal Access Token*** (***PAT***) is a credential that identifies you to ATR's API and command-line tooling. Create one on the [tokens page](/tokens). A PAT expires 180 days after it is created, after which you need to create a new one. ATR stores only a hash of the token and never the token itself, so make a note of it when it is first shown to you. Treat a PAT like a password, and revoke it from the same page if it is ever exposed.
### JSON Web Tokens
diff --git a/atr/docs/release-process-description.md b/atr/docs/release-process-description.md
index 1666a153..7d66f727 100644
--- a/atr/docs/release-process-description.md
+++ b/atr/docs/release-process-description.md
@@ -2,9 +2,9 @@
**Up**: [Documentation](.)
-**Prev**: `4.` [Release managers](release-manager-setup)
+**Prev**: `4.2.` [Trusted Publishing](trusted-publishing)
-**Next**: `6.` [Release catalog](release-catalog)
+**Next**: `5.1.` [Compose phase](compose-phase)
**Pages**:
@@ -28,6 +28,6 @@ The ASF releases open source software. The ATR platform helps PMCs release their
* ***Finish***. In this phase the Release Artifacts are committed to the Apache distribution SVN repository and announcement is deferred until the artifacts have made it
onto the download servers. The announcement is sent and the artifacts published to the Release Catalog. The commit goes directly to `svn:dist:release`,
as described in [Promoting to release](promoting-to-release).
-2. ***Released***. Releases that are released are active and cataloged and available via both a standard catalog api and at the proper urls using the CDN and download servers.
- Releases that use the current legacy methods skipping the ATR are also cataloged,
+2. ***Released***. Published releases are active and cataloged, and available both via a standard catalog API and at the proper URLs on the CDN and download servers.
+ Releases made through the legacy methods that bypass ATR are also cataloged.
3. ***Archived***. All cataloged releases may be archived using the ATR platform or by direct removal from `svn:dist:release`.
diff --git a/atr/docs/sbom-workflows.md b/atr/docs/sbom-workflows.md
index 48651f8f..f75fd4bc 100644
--- a/atr/docs/sbom-workflows.md
+++ b/atr/docs/sbom-workflows.md
@@ -4,7 +4,7 @@
**Prev**: `5.1.2.` [License checks](license-checks)
-**Next**: `5.2.1.` [Staging and voting](staging-and-voting)
+**Next**: `5.2.` [Vote phase](vote-phase)
**Sections**:
diff --git a/atr/docs/scope.md b/atr/docs/scope.md
index bca77f2c..d69164e3 100644
--- a/atr/docs/scope.md
+++ b/atr/docs/scope.md
@@ -16,7 +16,7 @@
## What is ATR?
ATR is the Apache Trusted Releases platform. The Project Management Committees (PMCs) of
-[The Apache Software Foundation](https://www.apache.org/)(ASF) make official ASF software releases. These official ASF releases are endorsed as an
+[The Apache Software Foundation](https://www.apache.org/) (ASF) make official ASF software releases. These official ASF releases are endorsed as an
"[act of the Foundation](https://www.apache.org/legal/release-policy.html#release-definition)". It is important that the foundation -
its board, members, committees, and contributors - and the general public have confidence in these software releases.
@@ -44,7 +44,7 @@ When a Software Bill of Materials (SBOM) is provided dependency risks are also a
## Who are ATR users?
-There are two kinds of ATR user: our participants from our PMCs who use ATR to publish software, and ASF software end users who use ATR to
+There are two kinds of ATR user: our participants from our PMCs who use ATR to publish software, and ASF software end users who use ATR to
obtain that software. This guide is primarily written for the former, our participants who are publishing their software. Skilled end users
may be interested in reading this guide for the purpose of learning the purported security claims that we make, reviewing the implementation
strategies that we picked to achieve them, and ascertaining the likelihood that those claims were achieved.
diff --git a/atr/docs/signing-artifacts.md b/atr/docs/signing-artifacts.md
index 0504f02c..2e20d593 100644
--- a/atr/docs/signing-artifacts.md
+++ b/atr/docs/signing-artifacts.md
@@ -2,7 +2,7 @@
**Up**: `4.` [Release managers](release-manager-setup)
-**Prev**: `3.1.` [Project configuration](project-configuration)
+**Prev**: `4.` [Release managers](release-manager-setup)
**Next**: `4.2.` [Trusted Publishing](trusted-publishing)
diff --git a/atr/docs/staging-and-voting.md b/atr/docs/staging-and-voting.md
index 92782948..47a2a933 100644
--- a/atr/docs/staging-and-voting.md
+++ b/atr/docs/staging-and-voting.md
@@ -2,9 +2,9 @@
**Up**: `5.2.` [Vote phase](vote-phase)
-**Prev**: `5.1.3.` [SBOM workflows](sbom-workflows)
+**Prev**: `5.2.` [Vote phase](vote-phase)
-**Next**: `5.3.1.` [Promoting to release](promoting-to-release)
+**Next**: `5.3.` [Finish phase](finish-phase)
**Sections**:
diff --git a/atr/docs/trusted-publishing.md b/atr/docs/trusted-publishing.md
index 899a14e9..9e8c33d0 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.` [Compose phase](compose-phase)
+**Next**: `5.` [Making releases](release-process-description)
**Sections**:
diff --git a/atr/docs/vote-phase.md b/atr/docs/vote-phase.md
index cc15cea9..0eba0c7e 100644
--- a/atr/docs/vote-phase.md
+++ b/atr/docs/vote-phase.md
@@ -2,9 +2,9 @@
**Up**: `5.` [Making releases](release-process-description)
-**Prev**: `5.1.` [Compose phase](compose-phase)
+**Prev**: `5.1.3.` [SBOM workflows](sbom-workflows)
-**Next**: `5.3.` [Finish phase](finish-phase)
+**Next**: `5.2.1.` [Staging and voting](staging-and-voting)
**Pages**:
@@ -31,13 +31,13 @@ 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.
+* PMC members review the candidate and cast their votes on the vote thread. Whose votes are
+ binding is a matter of ASF policy.
## 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
+ATR keeps the candidate and its artifacts staged for the whole of the vote, and tallies the votes
+from the vote thread on the mailing list. 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.
diff --git a/scripts/docs_build.py b/scripts/docs_build.py
index c0047cb0..a0d62a02 100755
--- a/scripts/docs_build.py
+++ b/scripts/docs_build.py
@@ -107,17 +107,9 @@ def build_navigation(entries: list[TocEntry]) -> dict[str, Navigation]:
parent_entry = next(e for e in entries if e.number.rstrip(".") == entry.parent)
up = (f"{parent_entry.number} {parent_entry.title}", parent_entry.path)
- prev_entry = None
- for j in range(i - 1, -1, -1):
- if entries[j].level == entry.level:
- prev_entry = entries[j]
- break
-
- next_entry = None
- for j in range(i + 1, len(entries)):
- if entries[j].level == entry.level:
- next_entry = entries[j]
- break
+ # Prev and next follow the reading order of the TOC, i.e. depth first
+ prev_entry = entries[i - 1] if (i > 0) else None
+ next_entry = entries[i + 1] if (i + 1 < len(entries)) else None
if prev_entry:
prev = (prev_entry.number, prev_entry.title, prev_entry.path)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org