This is an automated email from the ASF dual-hosted git repository.
wave pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 23fbca3 Nomenclature updates (#6)
23fbca3 is described below
commit 23fbca37c5d5eb85622f155ad119f4bffba8d413
Author: Dave Fisher <[email protected]>
AuthorDate: Sun Feb 2 13:40:58 2025 -0800
Nomenclature updates (#6)
* Use Phase instead of State/Activity/Task
* Lifecycle is Phases of Stages
* Data Model Updates
* Update distributions.md
* Update test-distributions.md
* Update for lifecycle phases
* Remove overengineering
* Update README.md
---
README.md | 2 +-
apache-trusted-release/data-model.md | 12 +++---
apache-trusted-release/distributions.md | 2 +-
apache-trusted-release/lifecycle.md | 18 +++++++--
apache-trusted-release/platform.md | 59 ++++++----------------------
apache-trusted-release/requirements.md | 49 ++---------------------
apache-trusted-release/test-distributions.md | 2 +-
7 files changed, 39 insertions(+), 105 deletions(-)
diff --git a/README.md b/README.md
index 5ebeebd..04d41bd 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ The team's website source will be developed here as well.
- [Requirements](apache-trusted-release/requirements.md)
- [Platform Services](apache-trusted-release/platform.md)
-- [Release Lifecycle](apache-trusted-release/lifecycle.md)
+- [Release Lifecycle Phases](apache-trusted-release/lifecycle.md)
- [Test Distributions](apache-trusted-release/test-distributions.md)
- [Distributions](apache-trusted-release/distributions.md)
diff --git a/apache-trusted-release/data-model.md
b/apache-trusted-release/data-model.md
index 1c28c2f..46c635c 100644
--- a/apache-trusted-release/data-model.md
+++ b/apache-trusted-release/data-model.md
@@ -2,7 +2,7 @@
Here is an introduction to the ATR's data model.
-> The following needs some work, but I wanted to have nomenclature for
discussion.
+> The view here is descriptive of a json model, but the implementation will be
a combination of filesytem files and subdirs along with an SQLite database
schema.
## Projects
@@ -70,15 +70,17 @@ CVEs are can be stored by id and are associated to other
objects through lists.
## Releases
-Releases are related groups of packages. Candidate releases go through stages
and states as tasks are completed until the release is ready.
-Currrent releases need little activity aside from acknowledging CVEs and
revoking a no longer supported release.
+Releases are related groups of packages. Candidate releases go through stages
and these have phases.
+When approved to be released the stage is moved to current.
+Currrent releases have initial phases to distribute and announce the release.
1. Storage key
2. Stage
-3. State - Performing a Task is a state.
+3. Phase
+3. Version String
4. CVEs
3. Packages - List of triples of file, signature, and checksum that are the
downloadable components of a release.
-6. SBOMs - in an acceptable SBOM format and maintained in Tasks using standard
python libraries.
+6. SBOMs - in an acceptable SBOM format and maintained in Phases using
standard python libraries.
5. Votes
- Pass or Fail
- Summary
diff --git a/apache-trusted-release/distributions.md
b/apache-trusted-release/distributions.md
index c2a58c4..c84b6ab 100644
--- a/apache-trusted-release/distributions.md
+++ b/apache-trusted-release/distributions.md
@@ -1,4 +1,4 @@
-# Third Party Distributions
+# Distributions Phase
Support will be added to the ATR for distribution of release packages to third
parties in a priority order.
diff --git a/apache-trusted-release/lifecycle.md
b/apache-trusted-release/lifecycle.md
index 6d8df4b..b0bdf37 100644
--- a/apache-trusted-release/lifecycle.md
+++ b/apache-trusted-release/lifecycle.md
@@ -1,5 +1,13 @@
# Release Lifecycle
+A Release will go through a lifecycle of **stages** and **phases**.
+
+Stages include **Build**, **Candidate**, **Current**, and **Revoked**.
+The ATR does not manage build stage releases. It takes over on the transition
from the build to the cnadidate stage.
+Stages control where on the **ATR** Website a release can be found.
+
+Phases are states or activities during a Release's life cycle.
+
```mermaid
flowchart TD
subgraph Apache Trusted Release
@@ -8,7 +16,7 @@ flowchart TD
C@{ shape: docs, label: "Release Candidate" }
A -->|automatically triggered| C
B -->|manually triggered| C
- subgraph Release Candidate
+ subgraph Release Candidate Stage
D@{ shape: processes, label: "Evaluate Candidate" }
C --> D
DD@{ shape: process, label: "Sign Candidate" }
@@ -24,7 +32,7 @@ flowchart TD
DD --> GG
GG --> E
end
- subgraph Release
+ subgraph Current Release Stage
JJ@{ shape: docs, label: "Release" }
JJJ --> JJ
G@{ shape: processes, label: "Distribute" }
@@ -49,10 +57,12 @@ flowchart TD
end
```
-## Definitions
+## Phases
**Announce CVEs**
-: At some moment after a release happens a project may announce CVEs that
either impact or are solved by a release. The security team and PMC manage CVEs
including announcements and publishing via cveprocess.apache.org The ATR will
update SBOMs with new CVEs.
+: At some moment as or after a release happens a project may announce CVEs
that either impact or are solved by a release. The security team and PMC manage
CVEs including announcements and publishing via cveprocess.apache.org The ATR
will update SBOMs with new CVEs.
+
+> Note where this is an explicit phase or not depends on integration
discussions with the security team.
**Announce Release**
: Send a compliant announcement of the release. This template will include
release metadata.
diff --git a/apache-trusted-release/platform.md
b/apache-trusted-release/platform.md
index 18c94d2..d953452 100644
--- a/apache-trusted-release/platform.md
+++ b/apache-trusted-release/platform.md
@@ -1,16 +1,13 @@
-# Platform Services
+# Platform Service
-1. Datastore: https://releases.apache.org
-2. Task Runner: https://artifacts.apache.org
-
-> Monitoring the service stack will indicate if the stack split is indicated.
Let's make sure that such a split is relatively quick.
+https://releases.apache.org
## Datastore
1. Release Storage. A large filesystem with folders for each release's files.
The release folder path is immutable.
2. Metadata Database. An sql database on the server with the metadata schema.
-### Web Service
+## Web Service
1. `asfquart` based asynchronous python web service.
2. Fronted by `httpd`.
@@ -18,7 +15,7 @@
4. Fronted by a CDN. The caching policies need to properly defined.
5. Avoid long running processes.
-### Release Metadata and Files
+### Release Stages
1. Current Releases
2. Candidate Releases
@@ -31,7 +28,7 @@
1. Collate Keys by Committer
2. Link Committer Keys to Project, Signed Releases
-### Release CVE Store
+### Release CVEs
1. CVE metadata
3. Affected releases
@@ -68,16 +65,14 @@ The co-ordinates make up the external path to objects. The
metadata database pro
- SBOMs - Special files stored in the release folder.
- CVEs - CVE metadata and release linkage.
-3. POST Actions - Transitions with a Task
- - Analyze
- - Vote Monitor
- - Distribute - Push to Package Repositories
- - Push / Pull with dist.apache.org
- - others?
+3. POST Phases - Transitions, Activities, and Communication
+ - Transition into Phase.
+ - Perform Phase activity.
+ - Optionally email phase status.
- See [Release Lifecycle](./lifecycle.md) for how Actions are chained
together to perform a Release.
+ See [Release Lifecycle](./lifecycle.md) for how phases are chained together
to perform a Release.
-4. POST Templated Release Emails
+4. POST Templated Emails
- Announcements
- Votes
- Status
@@ -110,36 +105,4 @@ The co-ordinates make up the external path to objects. The
metadata database pro
- Responsive with Header(Hamburger)/Content/Footer.
- Include Search in Header(Hamburger)
-## Task Runner
-
-1. Runner for processes taking more than a few seconds.
-2. Manages an array of concurrent tasks.
-3. Provides operational status.
-4. Monitor load to avoid saturation and find true limits.
-
-### Web Service
-
-1. `asfquart` based asynchronous python web service.
-2. Fronted by `httpd`.
-3. Limit web access to ATR Datastore, other Runners, and IRD.
-
-### Restful API
-
-See [Release Lifecycle](./lifecycle.md) for how Action Tasks are chained
together to perform tasks related to a Release.
-
-1. GET
- - Status
- - Task
-
-2. CRUD on
- - Task
-
-3. Task Types
- - Analyze
- - Test Distribution
- - Vote Monitor
- - Distribution
- - Monitor Manual Distribution
- - Push / Pull with dist.apache.org
- - others?
diff --git a/apache-trusted-release/requirements.md
b/apache-trusted-release/requirements.md
index 2d6f844..b4bd76f 100644
--- a/apache-trusted-release/requirements.md
+++ b/apache-trusted-release/requirements.md
@@ -33,6 +33,7 @@ While reading consider these Notes:
- Manual triggers.
- Tracking performance.
- Platform includes a RESTful API.
+ - Work with Security Team about integration of CVE information.
- Make switching from current manual release process to a minimal ATR
process very simple.
- Provide operational status to help Infra monitor ATR operations through
the IRD.
@@ -47,55 +48,13 @@ While reading consider these Notes:
- SBOMs and Attestations
- Include dependency and license compliance.
- Provide clear attribution and information about Release Votes.
+ - CVEs
- Certificate and Credential Management
- Manage the signing keys needed for automation.
- Download Page including available SBOM and verification instructions.
- Announcement Email.
-## 5. Automated Actions
+## 5. Release Lifecycle Phases
- These requirements are by category and are not necessarily ordered. Here is
a flow chart showing the
- [Release Lifecycle](lifecycle.md).
+ Here is a flow chart showing the [Release Lifecycle Phases](lifecycle.md).
- - Triggers:
- - Initiation by GH Action and/or GitBox Event.
- - Initiation by metadata commit to the Dist Repository.
- - Manual for steps that may require manual work first.
- - Procedures:
- - Maintain the SBOM.
- - Check compliance:
- - Security Policy.
- - Legal Policy (to the extent possible).
- - Distribution Policy is built into the **ATR**
- - Signing Certificates.
- - Optional Digital Signatures:
- - Windows.
- - macOS.
- - (others TBD).
- - Voting:
- - Perform the Release Vote on the project dev list.
- - PMC votes through ATR, but emails are sent for each.
- (Use a hosted release candidate page that looks like the Download page)
- - Failure:
- - Non-compliance
- - Failed Votes
- - Email status to dev list
- - Distribution:
- - Release to the required Dist Repository.
- - Release to selected optional repositories. (Prioritized list)
- - Maven Central
- - PyPi
- - Node
- - DockerHub
- - Artifactory
- - (others TDB)
- - Candidates:
- - Some release candidates may be distributed to test repositories.
- - Apache staging repository
- - Test PyPi
- - (others TDB)
- - Developers may want to test those artifacts while voting.
- - Release Summary Email.
- - Include instructions about any optional repositories not automated.
- - Once any manual steps are completed, manually trigger the next step.
- - Announce Release via Email.
diff --git a/apache-trusted-release/test-distributions.md
b/apache-trusted-release/test-distributions.md
index 1bd4aad..df4a119 100644
--- a/apache-trusted-release/test-distributions.md
+++ b/apache-trusted-release/test-distributions.md
@@ -1,4 +1,4 @@
-# Test Distributions
+# Test Distributions Phase
Support will be added to the ATR for distribution of release candidate
packages in a priority order.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
