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 ba2e914 Add an introduction to ATR to the manual
ba2e914 is described below
commit ba2e914820fd5c5baa4ff7d1204df77ceaaed509
Author: Sean B. Palmer <[email protected]>
AuthorDate: Tue Oct 7 16:46:53 2025 +0100
Add an introduction to ATR to the manual
---
atr/manual/contribution.html | 2 ++
atr/manual/contribution.md | 3 +++
atr/manual/index.html | 23 ++++++++++++++++++++---
atr/manual/index.md | 40 +++++++++++++++++++++++++++++++++++++---
4 files changed, 62 insertions(+), 6 deletions(-)
diff --git a/atr/manual/contribution.html b/atr/manual/contribution.html
new file mode 100644
index 0000000..45715f0
--- /dev/null
+++ b/atr/manual/contribution.html
@@ -0,0 +1,2 @@
+<h1>Contribution guide</h1>
+<p>TODO</p>
diff --git a/atr/manual/contribution.md b/atr/manual/contribution.md
new file mode 100644
index 0000000..2521839
--- /dev/null
+++ b/atr/manual/contribution.md
@@ -0,0 +1,3 @@
+# Contribution guide
+
+TODO
diff --git a/atr/manual/index.html b/atr/manual/index.html
index 1adef07..c58a90b 100644
--- a/atr/manual/index.html
+++ b/atr/manual/index.html
@@ -1,3 +1,20 @@
-<h1>Apache Trusted Releases user manual</h1>
-<p>Welcome to the user manual for the <strong>Apache Trusted Releases</strong>
(ATR) platform.</p>
-<p>This user manual is a work in progress.</p>
+<h1>Apache Trusted Releases (ATR) manual</h1>
+<p>Welcome to the user and developer manuals for the <strong>Apache Trusted
Releases</strong> (ATR) platform.</p>
+<p>NOTE: This user manual is a work in progress.</p>
+<h2>Introduction to ATR</h2>
+<h3>What is ATR?</h3>
+<p>ATR is a platform through which committees of <a
href="https://www.apache.org/";>Apache Software Foundation</a> (ASF) projects
can make official ASF software releases. Official ASF releases are endorsed as
an "<a
href="https://www.apache.org/legal/release-policy.html#release-definition";>act
of the Foundation</a>". It is therefore important that the foundation -
its board, members, committees, and contributors - and the general public can
have confidence in the releases.</p>
+<p>What sort of confidence in releases is required? All parties need to be
certain that the software available for download is exactly that which was
intended to be published by the applicable project management committee (PMC),
and by the foundation. This may seem trivial, but software distribution
platforms such as ATR now operate in extremely adversarial environments. In the
years before ATR was launched, <a
href="https://en.wikipedia.org/wiki/Supply_chain_attack";>supply chain attacks
[...]
+<p>The end goal of supply chain attacks is almost always to cause harm to
users. Harms are wide-ranging and can include unwanted features, the extraction
of money from the user, surveillance and exfiltration of data, and material
damage. The exact methods of supply chain attacks vary, but the general
principle is to modify some legitimate software between the time that it was
written and the time that it was received by the end user, without the
modification being noticed. If software is [...]
+<p><strong>The goal of ATR is to deter and minimize the risk of supply chain
attacks.</strong> ATR does not ensure the quality of software received
legitimately from PMCs. The foundation as a whole, of course, has the goal of
establishing the highest quality of software to be produced, but that is not
the responsibility of ATR as a platform. The responsibility of ATR is to ensure
that the software it distributes to end users is the legitimate submission of
each of our constituent PMCs. I [...]
+<h3>Who are ATR users?</h3>
+<p>There are two kinds of ATR user: our participants who use ATR to publish
their 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 th [...]
+<p>It is important to remember that security is a complex and rapidly evolving
field, as the parties are involved in an ongoing game of cat and mouse.
Software producers are often under tight budget and time constraints, forced to
prioritize properties other than security, working in environments known to be
insecure, using practices known to be suboptimal, and deploying to
architectures with known vulnerabilities. Attackers race to find mistakes
before producers, and use them to their o [...]
+<p>In this guide, we document how ATR is situated in this complex security
landscape. But we also document the day-to-day operation of ATR: which forms to
use, which buttons to press, how to make the release process simple,
convenient, and well understood, but always with the goal of producing software
as it was intended to be.</p>
+<h3>What is ATR like to use?</h3>
+<p>Security of ASF release processes is the primary goal of ATR, but
outstanding usability is also necessary to achieve this goal. The ASF has been
in operation since 1999, and has needed release procedures from the very start.
ATR is the next step in the evolution of those procedures, but the release
managers (RMs) responsible for releasing ASF software are accustomed to the
existing procedures. Convenience is a visceral property with a disproportionate
effect. If ATR were secure but le [...]
+<p>As such, we offer a choice of interfaces when using ATR. We have a
web-based interface, a JSON API, and a command-line interface (CLI). We try to
make functionality as available as possible across all three interfaces. We
also plan to add a text user interface (TUI), which is a kind of hybrid of the
web-based interface and the CLI. The intention of having so many interfaces is
that users can choose the ones which are most convenient for them at each
step.</p>
+<p>Speaking of steps, what are the steps to release software on ATR? We have
kept this as simple as possible. First, the project's participants compose a
candidate release from existing files. Second, as per ASF policy, the PMC votes
on that candidate release. Third, if the vote passes, the PMC officially
publishes and announces the erstwhile candidate release as a finished, official
release. That's the whole process for the majority of PMCs, but of course there
are many details and cons [...]
+<h3>Who develops ATR?</h3>
+<p>ATR is developed by ASF Tooling, an ASF initiative launched in 2025, and
responsible for streamlining development, automating repetitive tasks, reducing
technical debt, and enhancing collaboration throughout the ASF. The source code
of ATR is developed in public as open source code, and ASF Tooling welcomes
high quality contributions to the codebase from external contributors, whether
from existing ASF contributors or members of the public. Because of the
stringent security and usabil [...]
+<p>This manual is an integral part of ATR, and contributions to this manual
are therefore treated like any of the rest of the code. We welcome all types of
contribution, whether that be writing entire pages or correcting small
typographical errors. The easiest path to contribution is to <a
href="https://github.com/apache/tooling-trusted-release/compare";>create a pull
request</a> on <a href="https://github.com/apache/tooling-trusted-release";>our
GitHub repository</a>. You can also <a href [...]
diff --git a/atr/manual/index.md b/atr/manual/index.md
index b4039cb..785ecaf 100644
--- a/atr/manual/index.md
+++ b/atr/manual/index.md
@@ -1,5 +1,39 @@
-# Apache Trusted Releases user manual
+# Apache Trusted Releases (ATR) manual
-Welcome to the user manual for the **Apache Trusted Releases** (ATR) platform.
+Welcome to the user and developer manuals for the **Apache Trusted Releases**
(ATR) platform.
-This user manual is a work in progress.
+NOTE: This user manual is a work in progress.
+
+## Introduction to ATR
+
+### What is ATR?
+
+ATR is a platform through which committees of [Apache Software
Foundation](https://www.apache.org/) (ASF) projects can make official ASF
software releases. Official ASF releases are endorsed as an "[act of the
Foundation](https://www.apache.org/legal/release-policy.html#release-definition)".
It is therefore important that the foundation - its board, members,
committees, and contributors - and the general public can have confidence in
the releases.
+
+What sort of confidence in releases is required? All parties need to be
certain that the software available for download is exactly that which was
intended to be published by the applicable project management committee (PMC),
and by the foundation. This may seem trivial, but software distribution
platforms such as ATR now operate in extremely adversarial environments. In the
years before ATR was launched, [supply chain
attacks](https://en.wikipedia.org/wiki/Supply_chain_attack) on open s [...]
+
+The end goal of supply chain attacks is almost always to cause harm to users.
Harms are wide-ranging and can include unwanted features, the extraction of
money from the user, surveillance and exfiltration of data, and material
damage. The exact methods of supply chain attacks vary, but the general
principle is to modify some legitimate software between the time that it was
written and the time that it was received by the end user, without the
modification being noticed. If software is di [...]
+
+**The goal of ATR is to deter and minimize the risk of supply chain attacks.**
ATR does not ensure the quality of software received legitimately from PMCs.
The foundation as a whole, of course, has the goal of establishing the highest
quality of software to be produced, but that is not the responsibility of ATR
as a platform. The responsibility of ATR is to ensure that the software it
distributes to end users is the legitimate submission of each of our
constituent PMCs. In other words, f [...]
+
+### Who are ATR users?
+
+There are two kinds of ATR user: our participants who use ATR to publish their
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 [...]
+
+It is important to remember that security is a complex and rapidly evolving
field, as the parties are involved in an ongoing game of cat and mouse.
Software producers are often under tight budget and time constraints, forced to
prioritize properties other than security, working in environments known to be
insecure, using practices known to be suboptimal, and deploying to
architectures with known vulnerabilities. Attackers race to find mistakes
before producers, and use them to their own [...]
+
+In this guide, we document how ATR is situated in this complex security
landscape. But we also document the day-to-day operation of ATR: which forms to
use, which buttons to press, how to make the release process simple,
convenient, and well understood, but always with the goal of producing software
as it was intended to be.
+
+### What is ATR like to use?
+
+Security of ASF release processes is the primary goal of ATR, but outstanding
usability is also necessary to achieve this goal. The ASF has been in operation
since 1999, and has needed release procedures from the very start. ATR is the
next step in the evolution of those procedures, but the release managers (RMs)
responsible for releasing ASF software are accustomed to the existing
procedures. Convenience is a visceral property with a disproportionate effect.
If ATR were secure but less [...]
+
+As such, we offer a choice of interfaces when using ATR. We have a web-based
interface, a JSON API, and a command-line interface (CLI). We try to make
functionality as available as possible across all three interfaces. We also
plan to add a text user interface (TUI), which is a kind of hybrid of the
web-based interface and the CLI. The intention of having so many interfaces is
that users can choose the ones which are most convenient for them at each step.
+
+Speaking of steps, what are the steps to release software on ATR? We have kept
this as simple as possible. First, the project's participants compose a
candidate release from existing files. Second, as per ASF policy, the PMC votes
on that candidate release. Third, if the vote passes, the PMC officially
publishes and announces the erstwhile candidate release as a finished, official
release. That's the whole process for the majority of PMCs, but of course there
are many details and conside [...]
+
+### Who develops ATR?
+
+ATR is developed by ASF Tooling, an ASF initiative launched in 2025, and
responsible for streamlining development, automating repetitive tasks, reducing
technical debt, and enhancing collaboration throughout the ASF. The source code
of ATR is developed in public as open source code, and ASF Tooling welcomes
high quality contributions to the codebase from external contributors, whether
from existing ASF contributors or members of the public. Because of the
stringent security and usability [...]
+
+This manual is an integral part of ATR, and contributions to this manual are
therefore treated like any of the rest of the code. We welcome all types of
contribution, whether that be writing entire pages or correcting small
typographical errors. The easiest path to contribution is to [create a pull
request](https://github.com/apache/tooling-trusted-release/compare) on [our
GitHub repository](https://github.com/apache/tooling-trusted-release). You can
also [email patches](https://lists.ap [...]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
