This is an automated email from the ASF dual-hosted git repository.
sbp pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git
The following commit(s) were added to refs/heads/main by this push:
new 406074a Add a new page about components to the user guide
406074a is described below
commit 406074ab9ba2fcf36b9452f249b489295f3ca533
Author: Sean B. Palmer <[email protected]>
AuthorDate: Wed Jan 14 14:24:39 2026 +0000
Add a new page about components to the user guide
---
atr/docs/components.md | 48 ++++++++++++++++++++++++++++++++++++++++++
atr/docs/index.md | 3 ++-
atr/docs/running-the-server.md | 2 +-
atr/docs/signing-artifacts.md | 4 ++--
atr/docs/user-guide.md | 3 ++-
5 files changed, 55 insertions(+), 5 deletions(-)
diff --git a/atr/docs/components.md b/atr/docs/components.md
new file mode 100644
index 0000000..f1e5940
--- /dev/null
+++ b/atr/docs/components.md
@@ -0,0 +1,48 @@
+# 2.1. Components
+
+**Up**: `2.` [User guide](user-guide)
+
+**Prev**: (none)
+
+**Next**: `2.2.` [Signing artifacts](signing-artifacts)
+
+**Sections**:
+
+* [Introduction](#introduction)
+* [Committee](#committee)
+* [Project](#project)
+* [Release](#release)
+* [Revision](#revision)
+* [Artifact](#artifact)
+
+## Introduction
+
+ATR knows about several kinds of components that correspond to organizational
resources at the ASF, but some of the components mean a slightly different
thing in ATR or are customized in some way. This page documents the major
things to know about, and what's special about them.
+
+## Committee
+
+A **committee** in ATR is a PMC (Project Management Committee), or a PPMC
(Podling Project Management Committee). The concept of a committee is important
in ATR because both its members and all release managers have elevated
permissions compared to non-member and non-release-manager committers.
+
+Committees in ATR have one or more projects.
+
+## Project
+
+A **project** in ATR produces software or bundle of software that a committee
votes on. This means that if your committee bundles several kinds of software
together for a vote, that still counts as only one project in ATR. You must
pick a version number for the "bundled" software in such a case, but of course
your constituent software still has its own individual version numbers and we
plan for ATR to be made aware of those too.
+
+Projects in ATR have one or more releases.
+
+## Release
+
+A **release** in ATR is a specific version of software or bundle of software
produced by a project. As mentioned in the project section above, bundled
software must have an overall version number that may be different from the
version numbers of the constituent software in the bundle. Also, we allow the
release of more than one release concurrently, and we allow the release of
prior versions (e.g. security patch level versions) after later versions.
+
+Releases in ATR have one or more revisions.
+
+## Revision
+
+A **revision** is a snapshot of a release during the process of it being
prepared by the release manager or release managers. There are two preparation
phases: before and after voting. The phase before voting is called the
_compose_ phase and the phase after voting is called the _finish_ phase. In
these phases it is possible, subject to certain constraints (many more after
voting than before), to add files, move files, edit files, and delete files,
and each such modification produces a n [...]
+
+Revisions in ATR have one or more artifacts.
+
+## Artifact
+
+An **artifact** is a file that has been uploaded by a release manager to a
revision, and will constitute part of the release to be voted on, distributed,
and officially announced. ATR will automatically check artifacts for adherence
to as many ASF policies as we can automate checking for. It provides them for
download during all phases before final release, and then will publish them
through official channels during final release. At the moment, in alpha phase
(as of January 2026), we do [...]
diff --git a/atr/docs/index.md b/atr/docs/index.md
index c180ff1..9a0a57f 100644
--- a/atr/docs/index.md
+++ b/atr/docs/index.md
@@ -8,7 +8,8 @@ NOTE: This documentation is a work in progress.
* `1.` [Introduction to ATR](introduction-to-atr)
* `2.` [User guide](user-guide)
- * `2.1.` [Signing artifacts](signing-artifacts)
+ * `2.1.` [Components](components)
+ * `2.2.` [Signing artifacts](signing-artifacts)
* `3.` [Developer guide](developer-guide)
* `3.1.` [Running the server](running-the-server)
* `3.2.` [Overview of the code](overview-of-the-code)
diff --git a/atr/docs/running-the-server.md b/atr/docs/running-the-server.md
index ed4f057..aef3687 100644
--- a/atr/docs/running-the-server.md
+++ b/atr/docs/running-the-server.md
@@ -2,7 +2,7 @@
**Up**: `3.` [Developer guide](developer-guide)
-**Prev**: `2.1.` [Signing artifacts](signing-artifacts)
+**Prev**: `2.2.` [Signing artifacts](signing-artifacts)
**Next**: `3.2.` [Overview of the code](overview-of-the-code)
diff --git a/atr/docs/signing-artifacts.md b/atr/docs/signing-artifacts.md
index 864760e..7f657cb 100644
--- a/atr/docs/signing-artifacts.md
+++ b/atr/docs/signing-artifacts.md
@@ -1,8 +1,8 @@
-# 2.1. Signing artifacts
+# 2.2. Signing artifacts
**Up**: `2.` [User guide](user-guide)
-**Prev**: (none)
+**Prev**: `2.1.` [Components](components)
**Next**: `3.1.` [Running the server](running-the-server)
diff --git a/atr/docs/user-guide.md b/atr/docs/user-guide.md
index 10dea15..8004289 100644
--- a/atr/docs/user-guide.md
+++ b/atr/docs/user-guide.md
@@ -8,7 +8,8 @@
**Pages**:
-* `2.1.` [Signing artifacts](signing-artifacts)
+* `2.1.` [Components](components)
+* `2.2.` [Signing artifacts](signing-artifacts)
**Sections**:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
