SPDX Cryptographic Algorithm List release policy

[toscalix]

Background

• Check the SPDX License List release-process.md file
• This task is part of the publishing of the SPDX Cryptographic Algorithm List process, described in Add the SPDX Cryptographic Algorithm List to the SPDX website #51

Rationale

The SPDX Cryptographic Algorithm List should have an analogous structure than the SPDX License List, adapted to its on peculiarities. One of those analogies is the need for a release policy, adapted to the nature and lice cycle stage of this list. Such policy will be developed across several documents:

• release-process.md
• RELEASE-HISTORY.md
• RELEASE-NOTES.md

SPDX-tech group will validate the release policy, including the release process

Description

This task describes the

• creation
• discussion
• approval
• validation
• publishing

of the SPDX Cryptographic Algorithm release policy, structured in several documents to be included on the List like

• release-process.md
• RELEASE-HISTORY.md
• RELEASE-NOTES.md

Actions

• Create as a comment in this ticket a draft of what will become the release-process.md , including the List's release policy and process
• Discuss it at the SPDX Cryptography Group meeting
• Present it at the SPDX tech meeting
• Create a PR including release-process.md file for the SPDX Cryptographic Algorithm List.
• Send a mail to the spdx-tech mailing list with the link to the PR

DoD

• Link to draft:
• Link to the communication with SPDX tech:
• Link to the PR:
• Link to the corresponding communication to SPDX tech:
• Link to release-process.md:

[toscalix]

SPDX Cryptographic Algorithm List Release Policy document how to

1. Introduction
2. Purpose & Scope
3. Release Cadence & Versioning
4. Roles and Responsibilities
5. Pre-Release Preparation
6. Criteria for Inclusion and Deprecation
7. Release Workflow
8. Tagging & Versioning Protocol
9. Change Log & Release Notes
10. Post-Release Actions
11. Communication & Announcement
12. Release Artifacts & Distribution
13. Review and Maintenance of the Process
14. Glossary and References

---

1. Introduction

What to Include

• A brief summary of the purpose of the file.
• Project context (the SPDX Cryptographic Algorithm List and its analogy to the SPDX License List) — reference the idea of the SPDX License List being a curated list of identifiers. (license-list-XML)

Why Include It

• Helps readers immediately understand what the document is for and its relationship to the project.

2. Purpose & Scope

What to Include

Define the goals and boundaries of the release process (what the process covers, what it does not cover).

• A short statement of what the release process document covers: releasing new versions of the SPDX Cryptographic Algorithm List (CAL), not the tooling around it.
• Goals: consistency, traceability, review requirements, expected outputs (YAML list, JSON, site data, etc.).
• Scope boundaries: what is in (algorithm entries, schemas, generated artifacts, documentation) and what is out (downstream tool releases, external SCA tools, etc.).

Why Include It

• Clarifies and aligns expectations of users and maintainers, and ensures consistent application.
• Avoids scope creep (e.g., someone trying to define tool release policy in this doc).
• Gives new maintainers a clear mental model of what "a CAL release" means.

3. Release Cadence & Versioning

What to Include

• Target cadence (e.g., "quarterly, roughly aligned with SPDX License List releases, or as needed when significant changes accumulate").
• Versioning scheme for the list (e.g., v0.1, v1.0, semantic-ish rules for when you bump major/minor/patch).
• Rules for out-of-band releases (e.g., urgent security-related algorithm status changes).
• Cut-off period for pull requests or issues.
• Link to where versions are tagged (Git tags, GitHub Releases).

Why Include It

• Establishes clarity for contributors and consumers on update timing and stability.
• Helps downstream users plan integration and updates.
• Reduces debate each time about whether "this change" justifies a release.
• Aligns with SPDX ecosystem expectations (e.g., License List cadence).

4. Roles and Responsibilities

What to Include

Who can approve releases, merge changes, tag versions, update documentation, perform QA, etc.

• Defined roles: Release Manager, Reviewer(s) (crypto experts, legal/security reviewers if any), Maintainers with merge rights, Automation/Bot maintainers.
• Responsibilities per role: who cuts branches/tags, who runs validation scripts, who signs off on algorithm additions or status changes.
• How a Release Manager is selected or rotated.

Why Include It

• Avoids confusion around decision-making at release time ("who is allowed to cut the release?").
• Improves accountability and continuity if one person is unavailable.
• Makes it easier for new maintainers to step into the role.

5. Pre-Release Preparation

What to Include

• How changes that may go into a release are collected: issues labeled "crypto-list: candidate", PR labels, milestones (e.g., milestone: CAL v0.2).
• Process for triaging: who reviews issues/PRs, how to move them in or out of the milestone.
• Update of documentation, test plan, schema validation.
• Release process life cycle:
  • Release process stages
  • Actions and Notifications on each stage
  • PR merge deadline

Why Include It

• Ensures releases are intentional, not just "whatever was merged lately".
• Ensures the release artifact is complete and verified.
• Makes it easier to produce accurate release notes (you know which PRs were "in scope").
• Helps manage backlog vs. release-blocking issues.

6. Criteria for Inclusion and Deprecation

What to Include

• What qualifies algorithm submissions for a release.
• Criteria for inclusion in the upcoming release:
  • new algorithms
  • property changes
  • deprecations
  • metadata fixes
  • labeling criteria for "next release"
• Schema or content validation.
  • Compatibility rules: what kinds of schema changes are allowed in minor releases vs. major releases.
  • Policy for deprecating properties and introducing new ones (e.g., deprecation period, migration guidance).
• Documentation requirements.
• Policy on backporting fixes to older versions, if applicable.
• Alignment with the SPDX spec or crypto rules.
• Policies for:
  • Marking algorithms as deprecated (e.g., insecure algorithms) vs. removing them.
  • How long deprecated items remain in the list, and how they are flagged (properties or metadata).
  • Handling changes that break downstream tools (e.g., renaming IDs, changing key type semantics).
  • Guidance for downstream users on handling deprecation (e.g., check "status" property).

Why Include It

• Controls quality and consistency (similar to license submission validation), since downstream tools depend on the stability of the List schema and property semantics.
• Clear rules reduce the risk of breaking consumers unexpectedly.
• Encourages maintainers to think about migration when evolving the data model.
• Crypto algorithms evolve; you must capture status without harming reproducibility (old software still uses deprecated algorithms).
• Downstream tools need predictability around when identifiers or properties may disappear or change meaning.

7. Release Workflow

What to Include

• Step-by-step sequence from branch creation → tests → tagging → publishing.
• Criteria for approving a release: all required checks passed, release notes drafted, issues in the milestone closed or moved, schema changes reviewed.
• Formal approval process
  • List of mandatory checks before cutting a release and how these checks are run
  • Policy for what happens if a check fails (release is blocked, who can override).

Why Include It

Makes the governance around releases explicit and transparent

• Creates a reliable, repeatable process.
• Guarantees a minimum quality level for every release, since it ensures community and expert review before data is considered "official"
• Makes releases repeatable and reduces regressions.
• Reduces the risk of unilateral or rushed releases
• Provides confidence for downstream users that the list is internally consistent.

8. Tagging & Versioning Protocol

What to Include

• Branching strategy and model.
• Branching model for releases.
• Tag naming convention

Why Include It

Essential for traceability and projection of release history.

• Ensures consistent repo history and discoverable releases.
• Helps downstream tools know which tag/map to use.
• Avoids ambiguity in how artifacts map to Git history.

9. Change Log & Release Notes

What to Include

• How to summarise changes for release.
• Required content for each release’s notes:
  • New algorithms added (with IDs).
  • Changes to properties of existing algorithms (e.g., cryptoClass change, key size corrections).
  • Deprecated or removed algorithms or properties.
  • Schema changes and migration notes.
  • Known issues.
• Templates or automation suggestions.
• Process description: from change suggestion/request to merged change description to release notes entry
• Where release notes live

Why Include It

• Communicates what’s changed to users and downstream tools in a concise way to understand impact
• Supports traceability from release to discussion/PR history.
• Encourages consistent documentation across releases.
• Enables marketers to connect contributors' work with users

10. Post-Release Actions

What to Include

• Updating default branch to dev or next milestone branch.
• Closing associated issues/milestones.
• Roll-back and hot fixes policy
  • How to handle critical fixes post-release.
  • What happens when the release goes wrong and roll-back is the sane option
• Monitor user feedback or reported issues related to the new release.

Why Include It

• Keeps things tidy and prepares for next cycle.
• Stay prepared for the unpredictable: ensures a reliable process for urgent issues.
• Helps capture lessons and feed them back into the process.
• Avoids outdated docs and stale milestones.

11. Communication & Announcement

What to Include

• Channels where CAL releases are announced: SPDX mailing lists, GitHub Discussions, social media, or website posts.
• Template or outline of announcement: version, high-level changes, compatibility notes, links to release notes and artifacts.
• Who is responsible for announcements, and when they should happen relative to tagging.

Why Include It

Ensures adopters and contributors know about it.

• Ensures users and integrators discover new releases promptly.
• Avoids silent breaking changes for downstream users.
• Encourages community engagement and feedback on releases.

12. Release Artifacts & Distribution

What to Include

• Source-of-truth repo state at tag.
• Generated output formats, and where they are published
• Where unreleased builds are staged.
• List of scripts and tools used for releases
• Policy for maintaining these tools
• How automation is integrated in CI

Why Include It

• Defines what consumers should expect from releases.
• Encourages repeatable, low-error releases.
• Makes it easier for new maintainers to run the same process by supporting automated compliance of the release.
• Aligns with SPDX License List’s pattern of generating stable output formats from a source repo.

13. Review and Maintenance of the Process

What to Include

• How changes to the release process itself are proposed, discussed, and approved.
• Where this document fits into SPDX-wide governance (e.g., requires approval from SPDX technical steering, legal team, or a dedicated CAL working group).
• Versioning of the release process doc

Why Include It

• Ensures the process evolves but remains properly documented.
• Ensures that process changes have similar transparency to data changes.
• Makes it clear that this document is authoritative but not immutable.

14. Glossary and References

What to Include

• Define terms
• Links to information, procedures and guidelines that might help to better understand this policy

Why Include It

• Helps readers unfamiliar with release terminology.
• It provides a better context to those approaching the release policy for the very first time

release-process-howto.md

[toscalix]

SPDX Cryptographic Algorithm List Release Policy document how to

1. Introduction
2. Purpose, Scope and Repository Structure
3. Release Cadence
4. Roles and Responsibilities
5. Pre-Release Preparation
6. Inclusion and Removal of Cryptographic Algorithms
7. Release Workflow
8. Tagging & Versioning Protocol
9. Change Log & Release Notes
10. Post-Release Actions
11. Communication & Announcement
12. Release Artifacts & Distribution
13. Review and Maintenance of the Process
14. Glossary and References

---

1. Introduction

1.1 What This Document Is

This document defines the release policy for the SPDX Cryptographic Algorithm List (SPDX CryptAlg): a standardized, community-curated list of cryptographic algorithms maintained by the SPDX Cryptography Group.

It describes how new versions of the list are prepared, approved, published, and communicated, with the goal of ensuring that every release is consistent, traceable, and the result of an adequate review — so that downstream tools and SPDX profiles that depend on the list can rely on it with confidence. It is intended for contributors, maintainers, and anyone who consumes the list in their tools or workflows.

---

1.2 What the SPDX Cryptographic Algorithm List Is

The SPDX Cryptographic Algorithm List is modeled after the SPDX License List: a curated set of identifiers that give the software community a shared, unambiguous vocabulary for referencing a specific class of technical objects — in this case, cryptographic algorithms.

---

1.3 Relationship to SPDX Profiles

The SPDX Cryptographic Algorithm List is a shared resource used by different SPDX profiles — such as the Security profile and the Operations profile — as a reference for identifying cryptographic algorithms in SBOM documents. This means the list does not exist in isolation: other parts of the SPDX standard depend on it.

Because of these dependencies, not all changes to the list carry the same weight. Changes that affect the structure of the list or its property descriptions require a more careful review than algorithm entries, given their potential impact on the profiles that depend on SPDX CryptAlg. This distinction is a guiding principle throughout this release policy.

---

2. Purpose, Scope and Repository Structure

2.1 Goals

The release process is designed to achieve three goals:

Consistency. Every release follows the same process, regardless of the volume or nature of the changes it contains. This ensures that the list remains reliable and that downstream consumers can integrate updates without surprises.

Traceability. Every change included in a release can be traced back to the issue where it was discussed and the pull request where it was reviewed. Nothing reaches a release without a record of how it got there.

Adequate review. Not all changes require the same level of scrutiny. Algorithm entries and corrections can move through the process relatively quickly. Changes that affect the structure of the list or property descriptions require broader consultation, given their potential impact on the SPDX profiles that depend on SPDX CryptAlg.

---

2.2 What This Process Covers

This release policy applies to the following:

• Algorithm entries in the working repository, including new additions, corrections, and removals.
• Property descriptions and any changes to the structure of the list.
• The JSON output published in the data repository at each release.
• The documentation that accompanies the list, such as the contributing guide and the properties description file.

---

2.3 What This Process Does Not Cover

This release policy does not govern:

• The release of downstream tools that consume SPDX CryptAlg, including SCA scanners or SBOM generators.
• The release process of the SPDX specification or any of its profiles.
• The release process of the SPDX License List or any other SPDX-maintained list.

Those are independent processes managed by their respective communities. Where coordination is needed — for example, when a structural change to SPDX CryptAlg may affect a profile — that coordination is handled through the relevant SPDX working groups, but the decisions and timelines remain separate.

---

2.4 The Two-Repository Model

SPDX CryptAlg uses a two-repository model, following the same approach as the SPDX License List (license-list-XML and license-list-data). Understanding this model for the License List is essential to understanding how SPDX Cryptographic Algorithm List releases and deployments work.

Working repository: cryptographic-algorithm-list

This is where all authoring and community work happens. We sometimes refer to it as "input repo". New algorithm entries, changes to existing ones, and updates to property descriptions are first discussed and shaped in GitHub issues. Pull requests are only opened once the content is considered mature enough for formal review. Every pull request, review, and group decision lands here. This repository is the source of truth for the content of the list. Each algorithm is described in a dedicated .yaml file, one per algorithm, stored in the yaml/ folder of this repository.

This repository does not produce releases directly. It is an input, not a distribution channel.

Data repository: cryptographic-algorithm-list-data

This is the repository where the released version of the Cryptographic Algorithm List is deployed. We often refer to ir as the "output repo". At each release, the content of the working repository is processed and a set of output files is generated and published here. This is the repository that downstream tools and consumers should point to.

The output format is JSON, following the JSON schema used across the SPDX ecosystem. JSON Schema is a standard way of describing the structure and constraints of JSON data: it specifies what fields are expected, what types they hold, and what values are valid. Using the SPDX JSON schema ensures that SPDX CryptAlg outputs are consistent with other SPDX data and can be consumed directly by tools that already support the SPDX format, without requiring those tools to learn a new data structure. No other output formats — such as HTML or XML — are produced at this stage.

Each version published in the data repository corresponds to a tagged state of the working repository. The data repository contains only generated outputs; it is never edited by hand.

This separation keeps the authoring workflow clean and gives consumers a stable, predictable place to find versioned data, independently of the ongoing activity in the working repository.

2.5 — The Website

The SPDX Cryptographic Algorithm List is published as a human-readable website at:

https://spdx.github.io/cryptographic-algorithm-list

This site is the primary point of discovery for anyone looking to understand or browse the list. It is modeled after the SPDX License List website (https://spdx.org/licenses/) and the SPDX specification website (https://spdx.github.io/spdx-spec/), both of which publish structured technical content as static sites generated from source repositories.

The website is built with MkDocs using a theme provided by Read the Docs, and is deployed automatically via GitHub Actions on each release. It is generated from the content of the -data repository (output repo) at the time of each tagged release. The website is never edited by hand.

Structure of the website

The website contains the following pages:

• Home page — An introductory description of the SPDX Cryptographic Algorithm List and its purpose, including a browsable table of all algorithms showing their full name, short identifier (id), and cryptographic class (cryptoClass).
• Properties Description — An explanation of all properties used in the .yaml files, corresponding to the properties description document maintained in the working repository.
• Algorithm Inclusion Principles — The criteria the Cryptography Group uses to evaluate whether an algorithm is eligible for inclusion in the list.
• Contributing — Guidance for contributors on how to propose new algorithms, report errors, and participate in the review process.
• Individual algorithm pages — A dedicated page for each algorithm in the list, accessible at a predictable URL based on the algorithm identifier (e.g., https://spdx.github.io/cryptographic-algorithm-list/3des.htm). Each page presents the full set of properties for that algorithm.
• Links to the GitHub repositories — Direct links to both the working repository and the data repository, so that users can access the source files and machine-readable outputs.

2.6 The Parser

The parser — referred to as cryptalg-parser — is the tool that reads the .yaml algorithm files in the input repo and generates the output artifacts that are published at each release. It is hosted inside the input repo (cryptographic-algorithm-list), making it co-located with the source data it processes.

The cryptalg-parser is modeled after two tools used elsewhere in the SPDX ecosystem:

• The spec-parser, which reads the SPDX 3 model files (written in a constrained Markdown format, stored in spdx-3-model) and generates MkDocs input, PlantUML diagrams, JSON dumps, and other outputs used to publish the SPDX specification website.
• The LicenseListPublisher, which reads the XML source files in license-list-XML and generates the RDFa, HTML, text, and JSON output formats published in license-list-data and on the SPDX License List website.

For SPDX CryptAlg, the parser takes the .yaml files stored in the yaml/ folder of the working repository as its input, and produces two categories of output:

• JSON files, which are published in the -data repository (cryptographic-algorithm-list-data) and consumed directly by downstream tools and SBOM generators.
• Static web pages, which are used by MkDocs to generate the website described in section 2.5.

The parser runs as part of the automated release pipeline, triggered by GitHub Actions at release time. It is never run manually during normal operations; its execution is part of the release workflow defined in section 7.

Because the parser is hosted in the working repository, any changes to it — including bug fixes, new output formats, or schema validation improvements — are subject to the same review process as changes to the algorithm data itself. Modifications to the parser that affect the structure of the generated outputs are treated as structural changes and require the broader consultation described in section 2.1.

---

3. Release Cadence

3.1 Release Cadence

SPDX CryptAlg targets a monthly release cadence. The intention is to publish a new version once per month, on a scheduled basis, regardless of the volume of changes accumulated since the previous release. Every change merged into the working repository before the freeze date is expected to be included in that month's release.

This regular cadence gives downstream tools and consumers a predictable integration rhythm, and ensures that improvements — even minor ones — reach users quickly rather than accumulating for long periods. It also avoids the overhead of managing long release cycles while the list is still maturing.

At this early stage of the list's life cycle, some flexibility in the cadence and freeze dates may be needed. The monthly target should be treated as a commitment the group works toward, rather than a rigid constraint. Where circumstances require adjusting a release date, the decision will be documented and communicated through the usual channels. Skipping a release cycle is a no-action event: the Cryptography Group may decide to skip a release without any further process or communication required.

Hot Releases

An additional, unscheduled release (hot release) may be issued outside the monthly cadence in exceptional circumstances. These include, but are not limited to:

• A critical correction that would lead downstream tools to produce materially incorrect outputs if left until the next scheduled release.
• An urgent change driven by SPDX
• A relevant security event or standardization body decision

Hot releases follow the same versioning scheme as regular releases. The release notes(CHANGELOG.md) must explain why a hot release was necessary.

Data Freeze

To be included in a given monthly release, a pull request must be merged into the working repository no later than 7 calendar days before the scheduled release date. Changes merged after the freeze will be included in the following month's release. This period allows time for pre-release checks, release note drafting, and JSON output generation in the data repository.

Changes merged after that data freeze date will be included by default in the following month's release. In exceptional circumstances, the person appointed by the Cryptography Group for that release might add the changes to the coming release. Such cherry picking should be justified within the Cryptography Group and recorded in the release notes.

4. Roles and Responsibilities

Each release involves two roles: a Release Coordinator and the Reviewers. Both are filled by members of the Cryptography Group.

4.1 Release Coordinator

For each release, the Cryptography Group appoints one of its members as Release Coordinator. The appointment is made by consensus within the group. There is no permanent or standing Release Coordinator: the role is assigned on a per-release basis, allowing the responsibility to be shared across group members over time.

The Release Coordinator has all the rights necessary to carry out the release, including the ability to create and merge branches, tag versions in both repositories, trigger validation and generation scripts, publish the release in the data repository, and update the associated documentation. These rights are scoped to the release process and exercised in accordance with the conditions and actions described in the preceding sections of this policy.

The Release Coordinator is responsible for driving the release to completion: coordinating the pre-release checks, drafting or overseeing the release notes, cutting the tag, and ensuring the release is published and announced correctly.

4.2 Reviewers

The Reviewers are the remaining members of the Cryptography Group who are not acting as Release Coordinator for a given release. Their role is to support the Release Coordinator by reviewing the actions taken throughout the release process — checking that pre-release conditions are met, that the release notes are accurate and complete, and that the published output is consistent with the content of the working repository.

Reviewers do not block the release unilaterally, but their feedback must be addressed before a release is considered ready to publish. Any unresolved concern should be escalated to the full group for a decision.

---

5. Pre-Release Preparation

What to Include

• How changes that may go into a release are collected: issues labeled "crypto-list: candidate", PR labels, milestones (e.g., milestone: CryptAlg v0.2).
• Process for triaging: who reviews issues/PRs, how to move them in or out of the milestone.
• Update of documentation, test plan, schema validation.
• Release process life cycle:
  • Release process stages
  • Actions and Notifications on each stage
  • PR merge deadline

Why Include It

• Ensures releases are intentional, not just "whatever was merged lately".
• Ensures the release artifact is complete and verified.
• Makes it easier to produce accurate release notes (you know which PRs were "in scope").
• Helps manage backlog vs. release-blocking issues.

6. Inclusion and Removal of Cryptographic Algorithms

Determining whether a candidate algorithm should be included in SPDX CryptAlg requires the Cryptography Group to evaluate each submission on a case-by-case basis. The criteria below set out an order of priority for that evaluation. They are not exhaustive: the ultimate decision will be based on the totality of the factors and the goals of the list as described in section 1.

6.1 Criteria for Inclusion

This is a description of the criteria the Cryptography Group follows to include and deprecate algorithms on the SPDX Cryptographic Algorithm List:

Key factors — an algorithm that meets any of the following will be included:

A. The algorithm has been standardised by a recognised standardisation body, including but not limited to NIST, ISO/IEC, ETSI, IETF, IEEE, or national standards bodies. Both current standards and those that have been withdrawn or superseded are eligible, as withdrawn standards may still appear in existing software and systems.

B. The algorithm is or has been widely used in industry or commercial software, regardless of whether it was formally standardised. Demonstrated adoption across multiple products, ecosystems, or vendors is sufficient.

C. The algorithm has had or continues to have significant use in academic research or as a reference implementation in the cryptographic community, such that it is likely to appear in real-world software or SBOM data.

Additional factors — for algorithms that do not clearly meet one of the definitive factors above, the group will consider the following:

1. The algorithm has a stable, identifiable specification — whether a standards document, a peer-reviewed paper, or a well-established technical reference — such that its definition is unambiguous and unlikely to change.
2. The algorithm has actual, demonstrable use in software that is packaged, distributed, or analysed with SBOM tooling. Substantial use may be demonstrated through presence in multiple projects, or in one or a few significant ones.
3. The algorithm has a well-known identifier or name within the community it comes from, reducing the risk of ambiguity or duplication.
4. The algorithm is not already represented on the list under a different identifier. Submissions that duplicate an existing entry will not be accepted; a correction to an existing entry should be submitted as a property update rather than a new algorithm.

The Cryptography Group may also consider any additional information provided by the submitter or raised by the community during the review process.

6.2 Submission Requirements

A candidate algorithm must be submitted as a GitHub issue in the working repository before a pull request is opened. The issue is the place where the group evaluates whether the algorithm meets the inclusion criteria. A pull request should only be opened once the group has reached sufficient consensus that the algorithm is suitable for inclusion.

Each algorithm entry must be submitted as a .yaml file following the schema defined in the working repository. The file must include, at minimum, all mandatory properties as defined in the properties description file. We encourage all submitter to also include the information corresponding to optional properties. In general, submissions that do not conform to the schema will not be merged.

6.3 Removal Policy

Removal from the list — as opposed to deprecation — is reserved for cases where an entry was added in error: for example, a duplicate entry, a submission based on a non-existent algorithm, or an entry with a fundamental data quality problem that cannot be corrected in place. Removal in such cases requires explicit agreement from the Cryptography Group and must be documented in the release notes of the release in which it occurs, with guidance for any downstream tools that may have referenced the removed identifier.

An algorithm already on the list will not be removed simply because:

• A standardisation body has formally withdrawn, revoked, or replaced it.
• It is widely considered cryptographically broken or unsafe by the security community.
• It has fallen entirely out of use and is no longer encountered in real-world software or SBOM data.
• It is considered obsolete, or no longer recommended.

Removal would break downstream tools and undermine the traceability that SPDX CryptAlg is designed to provide.

---

7. Release Workflow

What to Include

• Step-by-step sequence from branch creation → tests → tagging → publishing.
• Criteria for approving a release: all required checks passed, release notes drafted, issues in the milestone closed or moved, schema changes reviewed.
• Formal approval process
  • List of mandatory checks before cutting a release and how these checks are run
  • Policy for what happens if a check fails (release is blocked, who can override).

Why Include It

Makes the governance around releases explicit and transparent

• Creates a reliable, repeatable process.
• Guarantees a minimum quality level for every release, since it ensures community and expert review before data is considered "official"
• Makes releases repeatable and reduces regressions.
• Reduces the risk of unilateral or rushed releases
• Provides confidence for downstream users that the list is internally consistent.

8. Tagging & Versioning Protocol

8.1 Versioning Scheme

Each release is identified by a version string with the following format:

<generation>.<YYYY>.<MM>.<DD>.<hh>.<mm>

Where:

• <generation> is a positive integer representing a major era of the list. It starts at 1 and is incremented only when a breaking change is introduced — that is, a change that would require downstream consumers or SPDX profiles to adapt their integration in a non-trivial way. Examples include a fundamental restructuring of the .yaml schema, a change in the semantics of a core property, or a renaming of algorithm identifiers at scale. As noted in section 1.3, such changes require broader consultation and explicit group agreement before they can be merged. Increments to the generation number are therefore expected to be rare.
• <YYYY>.<MM>.<DD> is the calendar date of the release, in ISO 8601 format.
• <hh>.<mm> is the time of the release in UTC, using a 24-hour clock. This component is part of the canonical version string but may be omitted in human-facing communications — announcements, changelogs, documentation — where the date alone is sufficient to identify the release unambiguously.

Examples:

Canonical version	Shortened form (for communications)
1.2025.10.01.14.00	1.2025.10.01
1.2026.02.05.09.30	1.2026.02.05
2.2026.06.01.10.00	2.2026.06.01 (generation increment)

The date-based versioning scheme makes the release history immediately readable — any consumer can tell at a glance when a version was produced — while the generation number provides a clear, unambiguous signal when breaking changes occur.

8.2 Tagging and Publication

Each release is tagged in both repositories:

• cryptographic-algorithm-list
• cryptographic-algorithm-list-data

using the canonical version string (e.g., 1.2026.02.05.09.30).

GitHub Releases are used to publish each version, with the release notes (CHANGELOG.md file) associated directly to the corresponding tag. The ultimate goal is that anyone can trace the correct release in both repositories, the corresponding data, the release notes, and the release history (RELEASE-HISTORY.md) files.

8.3 Branching Strategy

The Cryptography Group has agreed on avoiding feature and release branches as much as possible, practicing what is usually called trunk based development (TBD). So the branching strategy is no-branching

---

9. Change Log & Release History

Every release of SPDX CryptAlg produces a record of what changed. This record serves two purposes. For downstream consumers — tools, SBOM generators, integrators — it communicates what has changed and whether any action on their side is required. For contributors and the Cryptography Group itself, it creates a traceable history that connects each release to the issues and pull requests that shaped it.

This section defines how that record is maintained: what files are used, what content is required in each, and how the release notes are assembled during the release workflow.

The change log and release history are maintained in two separate files in the root of the working repository (cryptographic-algorithm-list):

CHANGELOG.md is the primary release documentation file. It contains the full release notes for every published version, in reverse chronological order — most recent release first. Each entry documents what changed in that release: new algorithm entries, corrections, deprecations, schema changes, and any other relevant information. This file grows with every release and is the canonical source of release notes for SPDX CryptAlg. It is this file that is linked from GitHub Releases and referred to in release announcements.

RELEASE-HISTORY.md is a compact table listing all published versions and their release dates, in reverse chronological order. It provides a quick reference for anyone who needs to identify when a specific version was published, without reading through the full changelog. It follows the same format as the RELEASE-HISTORY.md file of the SPDX License List.

Both files are stored in the root of the working repository and kept under version control. They are updated as part of the release workflow and committed before the release tag is cut.

---

9.1 Content Requirements for CHANGELOG.md Entries

Each release entry in CHANGELOG.md must begin with a level-two heading that identifies the release version and date, using the following format:

## <version> — <YYYY-MM-DD>

Where <version> is the shortened form of the canonical version string (e.g., 1.2026.03.01), as defined in section 8.1. The date uses ISO 8601 format.

The body of each entry must cover the following categories, as applicable. A category may be omitted if it has no content for a given release, with one exception: the Algorithm entries section is always present, even if no entries were added, corrected, or deprecated in that release.

Algorithm entries added. A numbered list of all new algorithm entries included in the release, identified by their SPDX CryptAlg identifier. Each entry should include a brief parenthetical note when the reason for addition is not self-evident — for example, when an algorithm was added in response to a specific standardisation body decision or a security event.

Algorithm entries corrected. A description of any corrections made to existing entries, including the identifier of the corrected algorithm and a plain-language explanation of what was changed and why. Corrections to a property value (for example, a cryptoClass correction or a key size fix) should name the property and describe the before/after change.

Algorithm entries deprecated. A list of any identifiers that have been deprecated in this release, with a brief explanation of the reason and — where applicable — the identifier of the superseding or related entry.

Algorithm entries removed. Removal is rare and reserved for the specific cases described in section 6.3 of this policy. When it occurs, the removed identifier must be listed explicitly, the reason must be stated, and guidance must be provided for downstream tools that may have referenced the removed identifier.

Schema changes. A description of any changes to the .yaml schema used in the working repository or to the JSON schema used in the data repository. Schema changes should clearly indicate whether the change is backwards-compatible or whether it may require adaptation by consumers. Migration notes should be included when a consumer action is needed.

Documentation and tooling changes. A brief description of any significant changes to documentation, the parser, CI scripts, or other tooling included in the release.

Known issues. Any issues known at the time of release that downstream consumers should be aware of, with links to the relevant GitHub issues.

Hot release rationale. If the release is a hot release issued outside the regular monthly cadence, the entry must include an explicit statement of why the hot release was necessary. This is required by section 3.1 of this policy.

Each changelog entry must also include a link to the milestone in the working repository listing all pull requests included in the release, and — where available — a link to the diff comparing the previous release to the current one. These links are the primary mechanism for tracing the release back to its constituent changes. Contributors are encouraged to draft changelog entries as they submit and merge pull requests, rather than writing the entire entry at release time: a brief note in the PR description describing the change in changelog-ready language reduces the burden on the Release Coordinator and improves the quality of the final notes.

---

9.2 RELEASE-HISTORY.md Format

RELEASE-HISTORY.md is a simple Markdown table listing all published releases in reverse chronological order. It uses the shortened version string and the release date, following this format:

# Release History of the SPDX Cryptographic Algorithm List

| Release | Date |
| ------- | ---- |
| 1.2026.03.01 | 2026-03-01 |
| 1.2026.02.05 | 2026-02-05 |

A new row is added to the top of the table for each release, including hot releases, at the time the release tag is cut. The shortened version string is used in the table; the canonical version string (including the time component) is available via the tag in the repository.

---

9.3 Process: From Issue and Pull Request to Changelog Entry

The changelog is not written in one sitting at release time. It is assembled progressively across the lifecycle of the release, drawing on the issues and pull requests that constitute it.

The recommended practice is as follows. When a pull request is submitted for review, the author includes a brief description of the change in changelog-ready language in the PR description — no more than one or two sentences for a typical algorithm entry. When the PR is merged, the Release Coordinator or the author adds a corresponding line to a working draft of the CHANGELOG.md entry for the upcoming release. This draft is maintained in the working repository between releases, either as an in-progress section at the top of CHANGELOG.md or as a dedicated issue or discussion thread used for drafting purposes.

In the pre-release phase, the Release Coordinator consolidates the working draft into the final changelog entry, ensures all merged PRs are accounted for, and verifies that the entry is complete and accurate before it is committed as part of the release. Reviewers are responsible for checking the accuracy and completeness of the changelog entry before the release tag is cut.

This incremental approach reduces the risk of incomplete or inaccurate release notes and ensures that the traceability goals of this policy — connecting every change to the issue and PR where it was discussed and reviewed — are met in practice.

---

9.4 Relationship to GitHub Releases

At the time of publication, the Release Coordinator creates a GitHub Release in the working repository associated with the release tag. The body of the GitHub Release is the changelog entry for that version, copied from CHANGELOG.md. This makes the release notes discoverable directly from the GitHub interface without requiring users to navigate to the file.

The data repository (cryptographic-algorithm-list-data) is tagged with the same canonical version string at the same time, as described in section 8.2. The GitHub Release in the data repository may reference the changelog entry in the working repository rather than duplicating it.

[toscalix]

Section 5 of the release policy will be completed when we do the first release, so we can accurately describe the release workflow and the corresponding actions.

It will be the same for several other sections of the policy

[toscalix]

Section 8 and 9 are new. They need to be reviewed