DOC: adds Archive versions 7.0 and 7.1 (#157)

Author: lizgehret

book/back-matter/glossary.md

@@ -5,6 +5,10 @@ Action
   A generic term to describe a {term}`Method`, {term}`Visualizer`, or {term}`Pipeline`.
   Actions accept parameters and/or {term}`Artifacts <Artifact>` and/or {term}`Metadata`) as input, and generate one or more {term}`Results <Result>` as output.
 
+Annotation
+  Additional information that can be attached to a QIIME 2 {term}`Result`, such as a text file or cryptographic signature.
+  See {term}`Note` and {term}`Signature` for more information on the respective {term}`Annotation` types that have been implemented, and what they can contain.
+
 Archive
   The directory structure of a QIIME 2 {term}`Result`.
   Contains *at least* a root directory (named by {term}`UUID`) and a ``VERSION`` file within that directory.
@@ -24,7 +28,7 @@ Collection
   These can be used as {term}`Input`, {term}`Parameter`, and {term}`Output` {term}`Types <Type>`.
 
 Conda metapackage
-  A metapackage is a package  with no  files,  only  metadata.
+  A metapackage is a package with no files, only metadata.
   They are typically used to collect several packages together into a single package via dependencies.
   ([source](https://docs.conda.io/projects/conda-build/en/stable/resources/commands/conda-metapackage.html))
 
@@ -78,6 +82,10 @@ Metadata
 Method
   A method accepts some combination of QIIME 2 {term}`artifacts <Artifact>` and {term}`parameters <Parameter>` as {term}`input`, and produces one or more QIIME 2 artifacts as {term}`output`.
 
+Note
+  A type of {term}`Annotation` that can be added to a QIIME 2 {term}`Result`.
+  This type of {term}`Annotation` can accept inline text or a path to a file whose contents will be written to the associated {term}`Result`, with a limit of 10 MiB.
+
 Output
   Objects returned by an {term}`action`. Can be {term}`artifact(s) <Artifact>` or {term}`visualization(s) <Visualization>`.
 
@@ -127,6 +135,11 @@ Semantic Type
   When associated with a {term}`directory format`, the combination defines an {term}`artifact class`.
   These types may be extended by {term}`plugins<Plugin>`.
 
+Signature
+  A type of {term}`Annotation` that can be added to a QIIME 2 {term}`Result`.
+  This {term}`Annotation` contains a cryptographic signature, providing support to 'self-sign' QIIME 2 {term}`Results <Result>`.
+  This allows for identity confirmation for who created a particular {term}`Result`.
+
 Single-Use Plugin (SUP)
   A plugin that is intended for one specific use case, such as generating figures for a single manuscript, as opposed to a plugin that is intended for general widespread usage.
 

book/framework/references/archive-versions.md

@@ -238,5 +238,126 @@ action:
     - <index of this element in the collection out of total elements in the collection e.g. 1/100 for the first element in a collection of 100>
 ```
 
+(archive-version-7)=
 ## Archive Version 7
-Archive Version 7 development is [currently being planned](https://github.com/qiime2/qiime2/issues/747).
+Starting with QIIME 2 version [2025.4](https://github.com/qiime2/qiime2/releases/tag/2025.4.0), QIIME 2 {term}`Archive` versions 7+ utilize semantic versioning.
+What this means is each new QIIME 2 {term}`Archive` version is broken up into a major version and a minor version.
+Major version updates (i.e. version 6.x -> 7.x) include a significantly different internal structure, such as new files within the zip archive.
+Backward compatibility across major versions is not guaranteed (such that a version 7.0 archive will not be compatible with older software versions that didn't yet know about that version).
+Minor version updates (i.e. 7.n -> 7.n+1) include minor differing internal structure and/or features/capabilities.
+These will be backwards compatible to the nearest major version (such that a version 7.1 or 7.2 archive will be compatible with other software versions as long as they knew about 7.0).
+
+### Archive Version 7.0
+Released in QIIME 2 version [2025.4](https://github.com/qiime2/qiime2/releases/tag/2025.4.0) ([changelog](https://forum.qiime2.org/t/qiime-2-2025-4-is-now-available/33088)) [commit `0d2c8ec`](https://github.com/qiime2/qiime2/commit/0d2c8ec7d0cb6e3b81c4ab621e78bd0df74c11a0), this version adds:
+ - support for creation of {term}`Annotations <Annotation>` (of sub-type {term}`Note`) to a QIIME 2 {term}`Result`;
+ - an all-new `conda-env.yaml` file containing all environment dependencies a {term}`Result` was created from;
+ - updated checksum calculations from `md5` to `sha512`;
+ - and total file size calculation for all files within the `data` directory as a new entry under the top level/provenance level `metadata.yaml` files.
+All of the new additions to the {term}`Archive` file structure are outlined below.
+
+{term}`Annotations <Annotation>` are a way of attaching additional information to a QIIME 2 {term}`Result`.
+In version 7.0, {term}`Note` has been added as a supported {term}`Annotation` sub-type.
+{term}`Notes <Note>` can either contain inline text or a filepath whose contents will be written to the {term}`Note`.
+
+The updated structure of a QIIME 2 {term}`Result` includes a new top-level `annotations` directory, where all {term}`Annotations <Annotation>` will be written.
+Each {term}`Note` that is created and written to this directory will have the following structure:
+
+```yaml
+annotations/
+    8b1ddcc2-b4e7-4c9f-9338-a7785a47862e/
+        checksums.sha512
+        metadata.yaml
+        note.txt
+    217d5eb4-febf-48e8-83ac-1a4dbebe8cf5/
+        checksums.sha512
+        metadata.yaml
+        note.txt
+```
+
+Each sub-directory underneath the `annotations` directory corresponds to the UUID associated with each {term}`Note` {term}`Annotation` that was added to the {term}`Result`.
+In each UUID's subdirectory, a {term}`Note` will contain the following files:
+ - A `note.txt` file that contains either the inline text or the contents of the filepath provided upon creation of the {term}`Note`.
+ - A `metadata.yaml` file that contains specific details about the {term}`Annotation` (which will be laid out in detail below).
+ - A `checksums.sha512` file with the sha512 calculated checksum for each file within the directory (`metadata.yaml` and `note.txt`).
+
+The contents of the `metadata.yaml` file are as follows:
+
+```yaml
+id: 8b1ddcc2-b4e7-4c9f-9338-a7785a47862e
+name: <note-name>
+type: Note
+created_at: <yyyy-mm-ddThh:mm:ss.ms>
+root_result_uuid: d594e658-65fd-4658-8de1-88097ce43abd
+referenced_result_uuid: d594e658-65fd-4658-8de1-88097ce43abd
+```
+
+`id` corresponds to the {term}`Annotation's <Annotation>` UUID, the `root_result_uuid` corresponds to the UUID of the {term}`Result` the {term}`Annotation` is attached to, and the `referenced_result_uuid` corresponds to the UUID of the {term}`Result` the {term}`Annotation` is in reference to.
+Note that the current implementation of {term}`Annotations <Annotation>` doesn't support referencing a {term}`Result` separate from the one the {term}`Annotation` is attached to, but these separate fields have been created to allow for this functionality to be supported in future {term}`Archive` versions.
+
+In addition to {term}`Annotations <Annotation>`, a new `conda-env.yaml` file (located under the `provenance` directory) has been added within the {term}`Archive` structure.
+This file contains all of the dependencies present in the conda environment where the {term}`Result` in question was created from.
+The contents of this file are as follows (with this example showing a very minimal environment):
+
+```yaml
+dependencies:
+    - numpy=1.26.4=py310h4bfa8fc_0
+    - pandas=2.2.2=py310hbf2a7f0_1
+    - python=3.10.14=h00d2728_0_cpython
+    - q2-metadata=2025.10.0.dev0+1.g61b847b=py310hd4cd7ad_0
+    - q2-mystery-stew=2025.10.0.dev0+1.g25270e3=py310h3cfa9b4_0
+    - q2-types=2025.10.0.dev0+5.g4a8aaa7=py310h974e487_0
+    - q2cli=2025.10.0.dev0+2.g2976552=py310h68e8629_0
+    - q2galaxy=2025.10.0.dev0=py310hac6da46_0
+    - q2templates=2025.10.0.dev0+1.g695609d=py310h88e6d8d_0
+    - qiime2=2025.10.0.dev0+6.g65a1488=py310hf606c39_0
+```
+
+Each entry matches the pattern: `<package-name>=<package-version>=<build-number>`.
+
+### Archive Version 7.1
+Released in QIIME 2 version [2025.10](https://github.com/qiime2/qiime2/releases/tag/2025.10.1) ([changelog](https://forum.qiime2.org/t/qiime-2-2025-10-is-now-available/33760))
+[commit `7d2a9b1`](https://github.com/qiime2/qiime2/commit/7d2a9b12d98666200b370de89e9e633b33e9acb8), this version adds {term}`Signatures <Signature>`, a new {term}`Annotation` sub-type that provides support for cryptographically signing a QIIME 2 {term}`Result`.
+
+A new {term}`Signature` is created by using the fingerprint of an existing GnuPG keypair to cryptographically sign a {term}`Result`, thus providing a verifiable identity associated with that {term}`Result`.
+
+The structure of a {term}`Signature` {term}`Annotation` within a {term}`Result` is as follows:
+
+```yaml
+annotations/
+    217d5eb4-febf-48e8-83ac-1a4dbebe8cf5/
+        checksums.sha512
+        metadata.yaml
+        signature.gpg
+```
+
+Each {term}`Signature` (separated by their associated UUID sub-directories) contains the following files:
+- A `signature.gpg` file that contains the cryptographic signature created with the provided GnuPG keypair.
+- A `metadata.yaml` file that contains specific details about the {term}`Signature` (laid out in detail below).
+- A `checksums.sha512` file with the sha512 calculated checksum for each file within the directory (`metadata.yaml` and `signature.gpg`).
+
+The contents of the `metadata.yaml` file are as follows:
+
+```yaml
+id: 217d5eb4-febf-48e8-83ac-1a4dbebe8cf5
+name: <signature-name>
+type: Signature
+created_at: <yyyy-mm-ddThh:mm:ss.ms>
+root_result_uuid: 046a982d-dbfa-41d1-8596-f767c71f4673
+referenced_result_uuid: 046a982d-dbfa-41d1-8596-f767c71f4673
+algorithm: <GnuPG keypair algorithm>
+checksum_digest: <sha512sum>
+signer_name: <signer-name>
+signer_email: <signer-email>
+fingerprint: <GnuPG keypair fingerprint>
+```
+
+The {term}`Signature`-specific fields are defined as follows:
+- `algorithm` refers to the encryption algorithm used when generating the GnuPG keypair used for creating the {term}`Signature`.
+- `checksum_digest` refers to the calculated `sha512` sum of the root-level `checksums.sha512` file, used for {term}`Signature` verification.
+- `signer_name` and `signer_email` refer to the GnuPG uid credentials associated with the keypair used for creating the {term}`Signature`.
+- `fingerprint` refers to the fingerprint associated with the GnuPG keypair used for creating the {term}`Signature`.
+
+More details on {term}`Signature` creation and verification, along with information on installing and using GnuPG for this purpose, can be found in [How to sign and verify Results](https://use.qiime2.org/en/latest/how-to-guides/sign-and-verify-artifacts.html).
+
+### Archive Version 7.2
+Archive Version 7.2 development is currently being planned.