diff --git a/.asf.yaml b/.asf.yaml index 22306e6..c1b0348 100644 --- a/.asf.yaml +++ b/.asf.yaml @@ -1,5 +1,5 @@ staging: - profile: + profile: ~ autostage: preview/* pelican: diff --git a/.github/workflows/build-pelican.yml b/.github/workflows/build-pelican.yml index 073af8d..0d6413c 100644 --- a/.github/workflows/build-pelican.yml +++ b/.github/workflows/build-pelican.yml @@ -16,7 +16,7 @@ jobs: permissions: contents: write # because we push to asf-site steps: - - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: true ref: ${{ github.ref || 'main' }} diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml index 69463f0..03f8a92 100644 --- a/.github/workflows/pre-commit.yml +++ b/.github/workflows/pre-commit.yml @@ -12,7 +12,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout code - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Install @@ -21,7 +21,7 @@ jobs: pip install pre-commit - name: Set PY run: echo "PY=$(python -VV | sha256sum | cut -d' ' -f1)" >> "$GITHUB_ENV" - - uses: actions/cache@v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.0.1 with: path: ~/.cache/pre-commit key: pre-commit|${{ env.PY }}|${{ hashFiles('.pre-commit-config.yaml') }} diff --git a/content/pages/atr-design-doc.md b/content/pages/atr-design-doc.md new file mode 100644 index 0000000..6f95208 --- /dev/null +++ b/content/pages/atr-design-doc.md @@ -0,0 +1,86 @@ +Title: Apache Trusted Releases design +license: https://www.apache.org/licenses/LICENSE-2.0 + +The main project is the Apache Trusted Releases platform. This is the initial design document. + +Repositories: + +- https://github.com/apache/tooling-trusted-releases +- https://github.com/apache/tooling-releases-client + +## 1. Automate the Release Process + + - Minimize human interaction. + - Community participation on **Release Votes** remains via email. + - Record all of the key events and metrics for tracking operations and performance. + - PMCs can quickly benefit. + - Infra costs and management complexity are decreased. + +## 2. Community + + - Work with a selection of **Apache** PMCs, **Incubator PPMCs(podlings)**, and **Infra** for **User Acceptance Testing (UAT)**. + - Co-ordinate with **Infra** on migration and operation. + - Contribute to Infra's **asfquart** and **asfpy** frameworks. + - Provide openings for volunteers to help so long as the contributions are adequate and timely. + - Assure that the **ATR platform** follows industry best practices especially regarding **SBOMs**, + **Certificate Management**, and **Digital Signatures**. + - Help lead the industry to better practices. + - Work within the **ASF** on **Release Policy** improvements. + +## 3. Apache Trusted Release Platform (ATR) + + - Incorporate all PMC Releases. + - Download page. + - Release Candidate page. + - Archived download page. + - Every PMC has a management interface. + - Current manual release practice is viewable. + - Automated release status. + - **KEYS** file management including revoking keys. + - Trigger release phases. + - Tracking performance. + - Platform includes a RESTful API. + - Serve release artifacts efficiently. + - Make switching from current manual release process to a minimal ATR process very simple. + - System Admins (Infra) have a management interface. + - Provide operational status to help Infra monitor ATR operations through the Infra Reporting Dashboard (IRD). + - Develop the platform with consideration about reusability outside of the ASF ecosystem, where feasible with regards to development costs. + + See [Platform Services](platform.html) for detailed requirements for the **ATR**. + +## 4. Automate Release Process around Compliance + + - Meet Release Policy + - Legal Policy + - Infra Policy + - Security Policy + - SBOMs and Attestations + - Include dependency and license compliance. + - Provide clear attribution and information about Release Votes. + - Certificate and Credential Management + - Manage the signing keys needed for automation. + - Download Page including available SBOM and verification instructions. + - Announcement Email. + +## 5. Release Lifecycle Phases + + Here is a flow chart showing the [Release Lifecycle Phases](https://github.com/apache/tooling-docs/blob/main/apache-trusted-releases/lifecycle.md). + +## 6. Infrastructure Requirements + + - Run book for releases.apache.org + - Progress on the retirement path for `svn:dist`. See [Legacy Releases from SVN Dist](svn-dist.html) + for possible transitional states. For the beta test _transition 1B_ is preferred. + - Legacy urls for dist.apache.org, downloads.apache.org, dlcdn.apache.org, and archive.apache.org remain supported. + - Path schemes for downloads.apache.org, dlcdn.apache.org, and archive.apache.org remain. + +## 7. Future Requirements + + - Integrate with the [Security Advisory Process](https://github.com/apache/tooling-docs/blob/main/apache-trusted-releases/advisory-process.md) to make it easy to track applicable advisories on download pages. + - Expand support for [Evaluating Build Claims](https://github.com/apache/tooling-docs/blob/main/apache-trusted-releases/evaluate.md) to additional build tools. + - Expand automated support for additional [Distribution Channels](https://github.com/apache/tooling-docs/blob/main/apache-trusted-releases/distributions.md). + - Include a [Signing Candidates](https://github.com/apache/tooling-docs/blob/main/apache-trusted-releases/digital-signatures.md) phase during ATR processing. + + > There are policy implications to the automation of digital signatures. + > For now, creating digital signatures on certain artifact types must be done prior to GPG signing and + > prior to submission of the release candidate. diff --git a/content/pages/atr/maven/README.md b/content/pages/atr/maven/README.md deleted file mode 100644 index 8bc7861..0000000 --- a/content/pages/atr/maven/README.md +++ /dev/null @@ -1,4 +0,0 @@ -Title: README placeholder -license: https://www.apache.org/licenses/LICENSE-2.0 - -Add maven plugin documentation here where Pelican will provide the skin. diff --git a/content/pages/index.md b/content/pages/index.md index abe0ce5..486f1c2 100644 --- a/content/pages/index.md +++ b/content/pages/index.md @@ -22,25 +22,19 @@ developed by ASF Infrastructure. 2. Automate the Release Process for the benefit of PMCs while also reducing infrastructure costs and management complexity. -### Contribute to the Discussion - -- Repository: https://github.com/apache/tooling-docs -- ASF Slack Channels: [#tooling-discuss](https://the-asf.slack.com/archives/C086X8CKEMB) – [#apache-trusted-releases](https://the-asf.slack.com/archives/C049WADAAQG) -- Mailing List: dev@tooling.apache.org – [archives](https://lists.apache.org/list.html?dev@tooling.apache.org) -- Subscribe to Mailing List: dev-subscribe@tooling.apache.org - ### Apache Trusted Releases (ATR) platform -All ASF Projects may participate in our second Alpha testing the new automation framework. +All ASF PMCs and Incubating podlings may participate in Beta testing of our new [Trusted Releases](/trusted-releases.html) platform. #### ATR Website Login to the ATR using your ASF credentials and you will have access to your PMC's projects. Incubating projects are welcome to join. -1. ATR: https://release-test.apache.org/ -2. Open API: https://release-test.apache.org/api/docs -3. Comparison: https://release-test.apache.org/about +1. ATR: https://releases.apache.org +2. Docs: https://releases.apache.org/docs +3. Open API: https://releases.apache.org/api/docs +4. Catalog: https://release-catalog.apache.org #### Source code @@ -54,3 +48,10 @@ Here are the source code repositories. Please view the README.md files for instr ### Security Issues To report a new vulnerability you have discovered please follow the [ASF vulnerability reporting process](https://apache.org/security/#reporting-a-vulnerability). + +### Contribute to the Discussion + +- Repository: https://github.com/apache/tooling-docs +- ASF Slack Channels: [#tooling-discuss](https://the-asf.slack.com/archives/C086X8CKEMB) – [#apache-trusted-releases](https://the-asf.slack.com/archives/C049WADAAQG) +- Mailing List: dev@tooling.apache.org – [archives](https://lists.apache.org/list.html?dev@tooling.apache.org) +- Subscribe to Mailing List: dev-subscribe@tooling.apache.org diff --git a/content/pages/trusted-releases.md b/content/pages/trusted-releases.md index 5a32fc8..e290559 100644 --- a/content/pages/trusted-releases.md +++ b/content/pages/trusted-releases.md @@ -1,33 +1,121 @@ Title: Apache Trusted Releases platform license: https://www.apache.org/licenses/LICENSE-2.0 -The main project is the Apache Trusted Releases platform. +The main project for the Tooling Initiative is the Apache Trusted Releases (ATR) platform. -Repositories: +1. Websites: -- https://github.com/apache/tooling-trusted-releases -- https://github.com/apache/tooling-releases-client + - https://releases.apache.org - this is the ATR UX which is dynamic requiring ASF login credentials. + - https://release-catalog.apache.org - this is the full ASF release catalog in a static website hosted by httpd. -## 1. Automate the Release Process +2. Repositories: - - Minimize human interaction. - - Community participation on **Release Votes** remains via email. - - Record all of the key events and metrics for tracking operations and performance. - - PMCs can quickly benefit. - - Infra costs and management complexity are decreased. + - https://github.com/apache/tooling-trusted-releases - the ATR UX and API. + - https://github.com/apache/tooling-releases-client - a Python client for Release Managers. + - https://github.com/apache/tooling-actions - Github Actions for Trusted Publishing. -## 2. Community +## Beta platform features - - Work with a selection of **Apache** PMCs, **Incubator PPMCs(podlings)**, and **Infra** for **User Acceptance Testing (UAT)**. - - Co-ordinate with **Infra** on migration and operation. - - Contribute to Infra's **asfquart** and **asfpy** frameworks. - - Provide openings for volunteers to help so long as the contributions are adequate and timely. - - Assure that the **ATR platform** follows industry best practices especially regarding **SBOMs**, - **Certificate Management**, and **Digital Signatures**. - - Help lead the industry to better practices. - - Work within the **ASF** on **Release Policy** improvements. + - Minimize human interaction + - Easily follow release policy + - Require MFA for access + - Designate Release Managers and maintain their GPG public signing keys + - Confirm the derived release catalog and properly configure sub-projects + - Securely compose Release Candidates + - Enforce vote standards while continuing to include community + - Releases are still delivered to `svn:dist:release` + - Legacy release awareness in building a full release catalog. + - Expedited security releases are completely private + - Templated vote and announcement emails -## 3. Apache Trusted Release Platform (ATR) +## Configuration + +The Apache Trusted Releases (ATR) platform makes a distinction between the two parts of a Project Management Committee. +First the PMC is a management committee with associated committers. Second, the PMC manages one or more projects. +To start to use ATR for your releases there is PMC configuration to review and adjust. + +### Committee + +For the Committee ATR tracks Projects, Release Managers, and Signing Keys. +The committee consists of the PMC Members and includes project committers by reference. +All PMC Members are enabled to be Release Managers. A PMC Member can designate any committer as a Release Manager. + +The committee also has an associated set of GPG signing keys found in `svn:dist:release` by convention. +ATR can be configured to maintain the KEYS file for you. + +Committees that are approved for CI Release builds require special setup. Permissions are shown on the committee page. +Look into [Tooling actions](https://github.com/apache/tooling-actions) for Github Actions to use for +[Trusted Publishing](https://releases.apache.org/docs/trusted-publishing). + +### Projects + +Most PMCs have only their namesake project. There are many projects that have 2-8 subprojects and there are a few +that have dozens of subprojects. We've determined subprojects via two methods. First via an existing DOAP file +known to https://projects.apache.org, and second by analyzing all existing and archived releases. +This process was imperfect and we require PMCs with multiple projects to correct and confirm these. The best place to verify projects is +by reviewing the PMC's catalog page at https://release-catalog.apache.org/. Engage with the Tooling team +to make corrections. + +There are many different project settings. These are categorized according to their aspect. + +1. Releases - start a new release version and view the project's current releases. +2. Metadata - the project name, description, and other urls. Some of these are required. +3. Security - security emails and threat model urls. +4. Lifecycle - how the project handles versioning. `semver`, `calver`, or `simple`. +5. Trusted Publishing - what GitHub repositories, branch, and workflows to trust. +6. Compose - license checking and other composition settings. +7. Vote - voting options and email templates. +8. Finish - distribution subdirectory and announcement email templates. + +You can review these in the ATR website and then export a yaml fragment to save it in your project repository's `.asf.yaml` file. + +### Release Managers + +Each Release Manager should manage their access tokens and keys. At a minimum new Release Managers will need to save their GPG public key. +Depending on the method chosen to upload your release candidate artifacts PATs, JWTs, or SSH keys may be required. + +## Release Candidate Phases + +ATR has three phases for a Release Candidate. The Release Manager will guide the Release Candidate through these phases in order +to make a Release of a new Version of a Project. + +A Release Candidate can be started in several ways. + +1. The ATR UX provides a few places to start a release. If you are making a secret Expedited Release then the UX is the only place. +2. The Python client provides a command. You must provide a PAT created in the UX. +3. The ATR Maven Plugin will start a new version when you run the target. You must configure Maven with a PAT created in the UX. +4. If you have permission to build releases in CI then you can use a GitHub Action. + +### 1. Compose + +This phase starts when a new release version is created. Every uploaded artifact is checked in several ways. New revisions may be made. +If you cancel a Vote you can return to the Compose phase and replace your artifacts with new revisions. There are several ways to upload. + +1. The ATR UX provides a few methods + - Browser upload. This is best for small source only releases. + - SVN Dev directory. If you are still creating your release and checking in your artifacts in SVN then ATR can upload from there. + - Rsync. This is best when you have many convenience binary artifacts. You will need to provide you SSH public key to ATR. +2. The Python client provides a command. You must provide a PAT created in the UX. +3. The ATR Maven Plugin will start a new version when you run the target. You must configure Maven with a PAT created in the UX. +4. If you have permission to build releases in CI then you can use a GitHub Action. The UX provides instructions. + +After artifacts are uploaded they go through two steps. + +1. Quarantine. Here each artifact is checked for defects like zip bombs and path traversal issues. Problems you would not to give your + downstream users and ones we cannot allow on the ATR server. +2. Checks. Here we perform license, signature, and checksum checks. We make sure that you have included at least one source release + artifact. We validate and evaluate any SBOM artifact provided. Because our excludes checks are imperfect, we expect Release Managers + to exercise judgment about license exceptions. + +### 2. Vote + +This phase provides a supervised voting period and a public view of the candidate artifacts and check results. + +### 3. Finish + +This phase allows for the distribution of the release and ends with the announcement. + +## Release Catalog - Incorporate all PMC Releases. - Download page. @@ -48,39 +136,7 @@ Repositories: See [Platform Services](platform.html) for detailed requirements for the **ATR**. -## 4. Automate Release Process around Compliance - - - Meet Release Policy - - Legal Policy - - Infra Policy - - Security Policy - - SBOMs and Attestations - - Include dependency and license compliance. - - Provide clear attribution and information about Release Votes. - - Certificate and Credential Management - - Manage the signing keys needed for automation. - - Download Page including available SBOM and verification instructions. - - Announcement Email. - ## 5. Release Lifecycle Phases Here is a flow chart showing the [Release Lifecycle Phases](https://github.com/apache/tooling-docs/blob/main/apache-trusted-releases/lifecycle.md). - -## 6. Infrastructure Requirements - - - Run book for releases.apache.org - - Progress on the retirement path for `svn:dist`. See [Legacy Releases from SVN Dist](svn-dist.html) - for possible transitional states. For the beta test _transition 1B_ is preferred. - - Legacy urls for dist.apache.org, downloads.apache.org, dlcdn.apache.org, and archive.apache.org remain supported. - - Path schemes for downloads.apache.org, dlcdn.apache.org, and archive.apache.org remain. - -## 7. Future Requirements - - - Integrate with the [Security Advisory Process](https://github.com/apache/tooling-docs/blob/main/apache-trusted-releases/advisory-process.md) to make it easy to track applicable advisories on download pages. - - Expand support for [Evaluating Build Claims](https://github.com/apache/tooling-docs/blob/main/apache-trusted-releases/evaluate.md) to additional build tools. - - Expand automated support for additional [Distribution Channels](https://github.com/apache/tooling-docs/blob/main/apache-trusted-releases/distributions.md). - - Include a [Signing Candidates](https://github.com/apache/tooling-docs/blob/main/apache-trusted-releases/digital-signatures.md) phase during ATR processing. - - > There are policy implications to the automation of digital signatures. - > For now, creating digital signatures on certain artifact types must be done prior to GPG signing and - > prior to submission of the release candidate. + diff --git a/content/pages/volunteer.md b/content/pages/volunteer.md index 5bb9340..1669f8c 100644 --- a/content/pages/volunteer.md +++ b/content/pages/volunteer.md @@ -12,5 +12,10 @@ There are some basic things you could do if you're going to help out with the AS - Work on documentation. - Discuss policy clarifications and other difficult issues including moving questions and proposals to the appropriate place. +We also have some tools under development that are volunteer led. + + - A Maven plugin to help with starting an ATR release. This is a Java project from several Maven PMC Members. + - A Responsible AI service for distributing and metering LLM use. Called **LLM-A-O**. + **Come talk to us on [Slack](https://the-asf.slack.com/) in the [#tooling-discuss](https://the-asf.slack.com/archives/C086X8CKEMB) channel!** diff --git a/content/theme/templates/menu.html b/content/theme/templates/menu.html index d5bb6ec..9c5d5d7 100644 --- a/content/theme/templates/menu.html +++ b/content/theme/templates/menu.html @@ -26,16 +26,19 @@