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:01:58 UTC
Re: [I] Incubator documentation for release management (tooling-trusted-releases)
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: 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