You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tooling.apache.org by "asf-tooling (via GitHub)" <gi...@apache.org> on 2026/05/08 22:31:47 UTC
Re: [I] Document the scope of ATR (tooling-trusted-releases)
asf-tooling commented on issue #424:
URL: https://github.com/apache/tooling-trusted-releases/issues/424#issuecomment-4410338547
<!-- gofannon-issue-triage-bot v2 -->
**Automated triage** — analyzed at `main@2da7807a`
**Type:** `documentation` • **Classification:** `actionable` • **Confidence:** `high`
**Application domain(s):** `shared_infrastructure`
### Summary
Issue #424 requests documentation of ATR's scope: whether it's mandatory for all ASF releases, the timeline for policy changes, and whether ATR will provide release pages/metadata. @dave2wave committed to updating the README and tooling-docs with: (1) long-term timeline and conditions for ATR becoming mandatory, (2) note that policy discussions are in progress, and (3) clarification that release pages/data feeds will NOT override PMC-maintained DOWNLOAD pages. As of now, the user guide remains a stub ('work in progress') and the README's Status section doesn't address scope questions.
### Where new code would go
- `atr/docs/scope.md` — new file
A dedicated scope page in the user guide section would address the three points @dave2wave committed to documenting: timeline/conditions for ATR being mandatory, policy change status, and relationship to PMC download pages.
### Proposed approach
@dave2wave already committed to writing this documentation. The approach should follow their stated plan: (1) add a scope/adoption section to the user guide (or a new page linked from it) explaining the long-term timeline, the conditions under which ATR becomes mandatory, and the current state of policy discussions; (2) clarify that ATR will provide release pages and data feeds but will NOT override PMC-maintained DOWNLOAD pages; (3) add a brief summary or link in the README's Status section pointing to the full scope documentation.
The most natural location for the full scope explanation is a new page in `atr/docs/` (e.g., `scope.md`) linked from the user guide and table of contents. The README would then include a one-paragraph précis with a link. Since @dave2wave indicated they'd handle this and mentioned tooling-docs as well, the maintainer should confirm whether this is still planned or if a contributor should pick it up.
### Suggested patches
#### `atr/docs/user-guide.md`
Add a reference to a new Scope page and expand the introduction stub
````diff
--- a/atr/docs/user-guide.md
+++ b/atr/docs/user-guide.md
@@ -10,6 +10,7 @@
**Pages**:
+* `2.0.` [Scope and adoption](scope)
* `2.1.` [Components](components)
* `2.2.` [Signing artifacts](signing-artifacts)
* `2.3.` [Checks](checks)
@@ -19,6 +20,7 @@
**Sections**:
* [Introduction](#introduction)
## Introduction
-This is a work in progress. Meanwhile, you can read the [ATR tutorial](/tutorial).
+This is a work in progress. Meanwhile, you can read the [ATR tutorial](/tutorial).
+
+If you are new to ATR and want to understand whether and when it applies to your project, start with the [Scope and adoption](scope) page.
````
#### `atr/docs/scope.md`
New page documenting ATR scope per @dave2wave's commitments in the issue discussion
````diff
--- /dev/null
+++ b/atr/docs/scope.md
@@ -0,0 +1,49 @@
+# 2.0. Scope and adoption
+
+**Up**: `2.` [User guide](user-guide)
+
+**Prev**: (none)
+
+**Next**: `2.1.` [Components](components)
+
+**Sections**:
+
+* [Is ATR mandatory?](#is-atr-mandatory)
+* [Adoption timeline](#adoption-timeline)
+* [Release pages and data feeds](#release-pages-and-data-feeds)
+
+## Is ATR mandatory?
+
+<!-- TODO: confirm exact policy language with ASF board/tooling team -->
+As of this writing, ATR is **not mandatory** for ASF release processes. PMCs may
+continue to use their existing release workflows. ATR is available as an
+optional tool that strengthens supply chain security and automates compliance
+checks.
+
+The conditions under which ATR may become mandatory in the future are subject to
+ongoing policy discussions within the ASF. Any changes to release policy will be
+communicated through official ASF channels and mailing lists with adequate
+notice for PMCs to prepare.
+
+## Adoption timeline
+
+<!-- TODO: fill in concrete dates or milestones when policy decisions are made -->
+The expected long-term timeline for ATR adoption is still being determined.
+Policy discussions are in progress. When decisions are reached, this section
+will be updated with specific milestones and transition periods.
+
+PMCs interested in early adoption can begin using ATR immediately through the
+[alpha test deployment](https://release-test.apache.org/). Early feedback helps
+shape the platform before any policy changes take effect.
+
+## Release pages and data feeds
+
+ATR will provide release pages and structured data feeds for published releases.
+These pages serve as an additional view of release metadata and artifacts
+managed through ATR.
+
+**Important:** ATR release pages will **not** override or replace PMC-maintained
+DOWNLOAD pages. PMCs remain responsible for their own download pages and can
+continue to maintain them as they do today. ATR pages are complementary, not a
+replacement.
+
+<!-- TODO: document specific URLs and feed formats when available -->
````
#### `atr/docs/index.md`
Add the new Scope page to the documentation table of contents
````diff
--- a/atr/docs/index.md
+++ b/atr/docs/index.md
@@ -8,6 +8,7 @@
* `1.` [Introduction to ATR](introduction-to-atr)
* `2.` [User guide](user-guide)
+ * `2.0.` [Scope and adoption](scope)
* `2.1.` [Components](components)
* `2.2.` [Signing artifacts](signing-artifacts)
* `2.3.` [Checks](checks)
````
#### `README.md`
Add a brief scope statement in the Status section with link to full documentation
````diff
--- a/README.md
+++ b/README.md
@@ -35,6 +35,10 @@ Please review our [issue tracker](https://github.com/apache/tooling-trusted-rele
> It does not represent final technical or policy decisions for future ASF Tooling products.
> The code is provided without guarantees regarding stability, security, or backward compatibility.
+### Scope
+
+ATR is currently **optional** for ASF projects. It does not replace PMC-maintained download pages. When and under what conditions ATR may become mandatory is subject to ongoing policy discussions. See the [Scope and adoption](https://release-test.apache.org/docs/scope) documentation for details.
+
## Quick start
**Run with Docker Compose (recommended):**
````
### Open questions
- Has @dave2wave already started this work in tooling-docs or another repository? The comment mentions 'likely tooling-docs' which may be a separate documentation site.
- What are the actual policy decisions and timeline? The diffs use TODO placeholders since concrete policy hasn't been decided yet.
- Should the numbering be '2.0' (before Components) or should it be unnumbered/part of the user guide introduction instead of a separate page?
- Is there coordination needed with the ASF board or policy team before publishing scope documentation?
### Files examined
- `atr/docs/index.md`
- `README.md`
- `atr/docs/introduction-to-atr.md`
- `atr/docs/user-guide.md`
- `atr/docs/developer-guide.md`
- `atr/docs/components.md`
- `atr/docs/overview-of-the-code.md`
- `atr/docs/checks.md`
---
*Draft from a triage agent. A human reviewer should validate before merging any change. The agent did not run tests or verify diffs apply.*
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org