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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
