Skip to content

Build toolchain and tests#622

Open
cofinoa wants to merge 12 commits intocf-convention:mainfrom
cofinoa:build-toolchain-and-tests
Open

Build toolchain and tests#622
cofinoa wants to merge 12 commits intocf-convention:mainfrom
cofinoa:build-toolchain-and-tests

Conversation

@cofinoa
Copy link
Contributor

@cofinoa cofinoa commented Dec 24, 2025

No issue associated: this PR contains incremental tooling and documentation build improvements. There are no changes to the CF specification content.

Summary of changes

This PR improves the documentation build workflow and metadata plumbing:

  • Refactors the Makefile to make tool invocation more robust and overridable.
  • Adds explicit tool checks with clear error messages.
  • Introduces an optional environment.yml for reproducible Conda/Mamba builds.
  • Adds a basic link checker (make test-links) using lychee.
  • Updates README.md to document the build workflow.
  • Centralises release metadata in version.adoc, which now acts as the single source of truth for:
    • CF version number
    • canonical ISO release date
    • DOI (no yet defined)
  • Wires this metadata into the build system so that DRAFT and FINAL builds are explicit and reproducible.

All changes are optional and backward-compatible. System packages (apt) and RubyGems remain supported.
No changes are made to the normative text.


Current behaviour

  • A normal make build produces a DRAFT document.
  • A FINAL build may be produced using:
DOC_STATUS=FINAL make

In FINAL mode:

  • the visible release date is derived from the canonical release-date-iso
  • the citation year is fixed from the canonical release date
  • draft-only metadata is suppressed

This ensures that FINAL releases are fully reproducible.


Out of scope for this PR

This PR does not yet define:

  • the complete CF release workflow (DRAFT to RC to FINAL)
  • branch or tag conventions
  • formal release governance

The intention is to keep this PR focused on safe, incremental build improvements.

A separate Discussion will be opened with the Information Management Team in order to agree collaboratively on:

  • the editorial states to support
  • the Git branching and tagging model
  • a shared release checklist

Once there is consensus, a follow-up PR can implement the agreed workflow.


Release checklist

[NA] history.adoc up to date?
[NA] Conformance document up to date?

For maintainers

After merge:

  • delete the source branch when convenient
  • tags are set at the conclusion of the annual meeting
  • main continues to represent a working draft for the next version

@cofinoa cofinoa force-pushed the build-toolchain-and-tests branch from 5bf0212 to 48c8032 Compare December 29, 2025 20:51
@cofinoa
Copy link
Contributor Author

cofinoa commented Jan 3, 2026

From my side this PR is ready to merge. I would appreciate a review and confirmation from another team member of @cf-convention/info-mgmt before proceeding, since this touches the documentation build system (but not the normative content).

@JonathanGregory
Copy link
Contributor

Thank you for doing this, @cofinoa. Although it's not a change to the conventions, it is a substantial change in this repo, and I think it should be given greater visibility and discussed as a conventions enhancement issue (with GitHub label). Please could you open an issue for it and link this PR? The text you've already written in this PR would be fine for the issue.

Very soon (I hope) I'll have time to revive the issues in which we are discussing various procedures about changes to conventions, concerning the rules and CONTRIBUTING document. In that context we should discuss the process to agree technical changes like this. Although I've expressed my own view here, that we should have an issue for each non-trivial change, I expect that others have different views.

@cofinoa cofinoa added enhancement Proposals to add new capabilities, improve existing ones in the conventions, improve style or format GitHub Improvement to how we use GitHub for this repository governance Changes to the rules for modifying the conventions documents labels Jan 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement Proposals to add new capabilities, improve existing ones in the conventions, improve style or format GitHub Improvement to how we use GitHub for this repository governance Changes to the rules for modifying the conventions documents

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants