asf-tooling commented on issue #527:
URL:
https://github.com/apache/tooling-trusted-releases/issues/527#issuecomment-4410165960
<!-- gofannon-issue-triage-bot v2 -->
**Automated triage** — analyzed at `main@2da7807a`
**Type:** `documentation` • **Classification:** `actionable` •
**Confidence:** `medium`
**Application domain(s):** `shared_infrastructure`
### Summary
This issue requests updating the Apache Incubator's release management guide
(hosted at incubator.apache.org) to include ATR as an option for podling
releases, with up-to-date ASF release policy links. The ATR codebase already
supports incubating projects (podling checks, PPMC committees), but the ATR
documentation lacks a dedicated incubator/podling user guide section explaining
how podlings should use ATR. The issue may also be tracking external
documentation work on the Incubator website itself, which is outside this
repository.
### Where new code would go
- `atr/docs/incubator-releases.md` — new file
A new documentation page specifically for incubator/podling release
managers explaining how to use ATR for podling releases, including PPMC vote
requirements, DISCLAIMER file expectations, 'incubating' naming requirements,
and links to current ASF release policy.
### Proposed approach
Create a new documentation page (e.g., `atr/docs/incubator-releases.md`)
that serves as a guide for podling release managers using ATR. This page should
cover: (1) how podling committees (PPMCs) are represented in ATR, (2) the
additional requirements ATR enforces for podlings (incubating in filenames,
DISCLAIMER files), (3) the two-phase vote process (PPMC vote then IPMC vote) if
applicable, (4) links to current ASF release policy and incubator release
policy, and (5) how ATR simplifies compliance with incubator release
requirements. The page should be added to the user guide TOC. Additionally, the
issue references updating the *external* incubator.apache.org guide, which
would require a separate PR to the apache/incubator repository—this ATR-side
doc would be the complement that the external guide can link to.
Note that the scope of the external documentation update
(incubator.apache.org) is outside this repository and would need to be tracked
separately or as a cross-repo effort.
### Suggested patches
#### `atr/docs/incubator-releases.md`
New documentation page for incubator podling release management with ATR
````diff
--- /dev/null
+++ b/atr/docs/incubator-releases.md
@@ -0,0 +1,67 @@
+# 2.7. Incubator release management
+
+**Up**: `2.` [User guide](user-guide)
+
+**Prev**: `2.6.` [Trusted Publishing](trusted-publishing)
+
+**Next**: (none)
+
+**Sections**:
+
+* [Introduction](#introduction)
+* [How podlings use ATR](#how-podlings-use-atr)
+* [Podling-specific requirements](#podling-specific-requirements)
+* [Voting process for podlings](#voting-process-for-podlings)
+* [Links to ASF release policy](#links-to-asf-release-policy)
+
+## Introduction
+
+This page is for release managers of [Apache
Incubator](https://incubator.apache.org/) podlings who want to use ATR to
manage their releases. ATR fully supports podling releases and automatically
enforces the additional requirements that the ASF places on incubating projects.
+
+## How podlings use ATR
+
+Podlings are represented in ATR as committees, specifically as PPMCs
(Podling Project Management Committees). When your podling is set up in ATR,
ATR automatically knows that it is an incubating project and applies the
appropriate checks.
+
+The general workflow for a podling release is the same as for a top-level
project:
+
+1. **Compose** a candidate release from your release artifacts.
+2. **Vote** on the candidate release (see [voting
process](#voting-process-for-podlings) below for podling-specific details).
+3. **Finish** and publish the release once the vote passes.
+
+## Podling-specific requirements
+
+ATR automatically enforces the following additional requirements for
podling releases:
+
+### Artifact naming
+
+All artifact filenames must include the word "incubating". ATR's [path and
naming checks](checks#path-and-naming-checks) will fail if this requirement is
not met.
+
+### DISCLAIMER file
+
+Each source archive must contain a `DISCLAIMER` or `DISCLAIMER-WIP` file at
the top level of the root directory, alongside `LICENSE` and `NOTICE`. ATR's
[license file checks](checks#license-files-in-archives) verify this
automatically.
+
+### Signing keys
+
+Podling release managers must have their signing keys registered with their
podling's committee in ATR. See [signing artifacts](signing-artifacts) for how
to create and upload keys.
+
+## Voting process for podlings
+
+<!-- TODO: Document whether ATR handles the two-phase PPMC + IPMC vote,
+ or whether IPMC voting is handled separately. -->
+
+Podling releases typically require a vote on the podling's dev mailing
list, followed by a vote on the incubator general mailing list. Consult the
[ASF Incubator release management
guide](https://incubator.apache.org/guides/releasemanagement.html) for the
current voting requirements.
+
+## Links to ASF release policy
+
+* [ASF Release Policy](https://www.apache.org/legal/release-policy.html)
+* [ASF Release Distribution
Policy](https://infra.apache.org/release-distribution.html)
+* [Incubator Release Management
Guide](https://incubator.apache.org/guides/releasemanagement.html)
+* [ASF Incubator IP Clearance](https://incubator.apache.org/ip-clearance/)
+* [Guide to Release Signing](https://infra.apache.org/release-signing.html)
````
#### `atr/docs/index.md`
Add the new incubator page to the documentation table of contents
````diff
--- a/atr/docs/index.md
+++ b/atr/docs/index.md
@@ -12,6 +12,7 @@
* `2.4.` [License checks](license-checks)
* `2.5.` [Check ignores](check-ignores)
* `2.6.` [Trusted Publishing](trusted-publishing)
+ * `2.7.` [Incubator release management](incubator-releases)
* `3.` [Developer guide](developer-guide)
* `3.1.` [Running the server](running-the-server)
* `3.2.` [Overview of the code](overview-of-the-code)
````
#### `atr/docs/user-guide.md`
Add the new incubator page to the user guide pages listing
````diff
--- a/atr/docs/user-guide.md
+++ b/atr/docs/user-guide.md
@@ -15,6 +15,7 @@
* `2.4.` [License checks](license-checks)
* `2.5.` [Check ignores](check-ignores)
* `2.6.` [Trusted Publishing](trusted-publishing)
+* `2.7.` [Incubator release management](incubator-releases)
**Sections**:
````
### Open questions
- Does this issue also intend for a PR to be filed against the
apache/incubator repository to update
incubator.apache.org/guides/releasemanagement.html?
- Does ATR currently support the two-phase voting process (PPMC vote + IPMC
vote) required for podling releases, or is only one vote tracked?
- Should this documentation also cover graduation from incubator (removing
'incubating' from names, removing DISCLAIMER)?
- Are there any podlings currently using ATR whose experience could inform
this documentation?
### Files examined
- `atr/docs/index.md`
- `atr/docs/introduction-to-atr.md`
- `atr/docs/user-guide.md`
- `atr/docs/components.md`
- `atr/docs/signing-artifacts.md`
- `atr/docs/checks.md`
- `atr/docs/license-checks.md`
- `atr/docs/check-ignores.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]
