The .adp.yaml metadata file

Artifacts may have a metadata file associated with them ending in .adp.yaml. The filename convention is $artifact-filename.adp.yaml (for instance, httpd-2.4.54.tar.bz2.adp.yaml), and the file resides in the same directory as the artifact. The file contains data about the release and its promotion history, and may contain (but is not limited to nor requires) the following items:

• The date and time the artifact was uploaded for testing/voting.
• The committer who uploaded the artifact.
• A link to the email thread (on lists.apache.org) summarizing any vote to promote the artifact to an official release, and its result.
• The date and time the artifact was promoted to an official release (if released).
• Any additional release notes or announcements the project wishes to associate with the artifact.

The file provides the provenance of an artifact for internal purposes and helps downstream users with verification of the artifact, and can be modified by anyone on the project up to the point of promoting the artifact to an official release. ADP automatically creates the file when a new artifact is uploaded as a release candidate, and transfers it to the release directory upon promoting the artifact. Likewise, removing a release candidate removes the file (as well as any .asc and .shaNNN files associated with the artifact).

Keywords (WIP)

The table below describes the currently planned keywords for the .adp.yaml metadata file and their intended purposes:

keyword	data type	description
uploaded*	string	The time and date (ISO 8601) the artifact was uploaded for review/voting
uploaded_by*	string	The ASF committer that uploaded the artifact for review/voting
released*	string	The time and date (ISO 8601) the artifact was promoted to an official release
released_by*	string	The ASF committer that promoted the artifact to official release
links	dict	Any links that may provide additional information about the release process for this artifact, in the form of URL: "description", e.g: https://lists.apache.org/thread/f0vgqkxpzsgxzl9c67c3w7nbyp1h4vps: Official release vote for httpd 2.4.55. This field should contain links to vote threads, external README/INSTALL documents etc.
description	string	The description, or common name, of this artifact, such as Apache HTTPd 2.4.55 or Apache Tomcat 11.0.0-M1`, etc.
notes	string	Any release or otherwise informational notes the project wishes to attach to this release in the public ADP directory listing, in markdown format (no HTML allowed).
known_risks	dict	A dictionary that may contain links to or descriptions of known risks, such as CVEs, that apply to this artifact. This field can be updated after-the-fact for releases, once a CVE or other risk has been published.

Please note: Certain keywords, marked with an asterisk above, (specifically uploaded, uploaded_by, released, and released_by) will automatically be filled in by ADP, and must not be modified by release managers or other committers. Changes to the metadata after promoting an artifact to release is possible for certain fields, and will cause an audit email to be sent to the project's PMC mailing list for provenance.

An example metadata file for Apache Tomcat 11.0.0-M1 could look like:

# apache-tomcat-11.0.0-M1-deployer.tar.gz.adp.yaml
uploaded: 2022-12-01T12:58:42Z
uploaded_by: markt
released: 2022-12-05T16:25:31Z
released_by: markt
links:
  https://lists.apache.org/thread/dydxj28f000dj3n0byjwnm52tvpfh5m3: Apache Tomcat 11.0.0-M1 release vote
  https://lists.apache.org/thread/nw39v9brmk700scxxtr4mtf8tngd18gj: Release Announcement email
  https://tomcat.apache.org/tomcat-11.0-doc/changelog.html: Changelog for 11.0.0-M1
description: Apache Tomcat 11.0.0-M1
notes: >
  Users of Tomcat 11 onwards should be aware that, as a result of the move from Java EE to Jakarta EE as part of the transfer of Java EE 
  to the Eclipse Foundation, the primary package for all implemented APIs has changed from javax.* to jakarta.*. This will almost certainly 
  require code changes to enable applications to migrate from Tomcat 9 and earlier to Tomcat 11 and later. 
  A [migration tool](https://github.com/apache/tomcat-jakartaee-migration) has been developed to aid this process.
known_risks:
  CVE-2023-12345: Gnomes may get eaten by a lion.