You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tooling.apache.org by sb...@apache.org on 2025/10/07 15:47:11 UTC
(tooling-trusted-releases) branch main updated: Add an introduction to ATR to the manual
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 <se...@miscoranda.com>
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: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org