Feedback Request: Improving Document Versioning and Colophon Details

[cofinoa]

Issue Description:
To improve traceability and provide clearer context for both draft and final versions of our documents, I’ve been working on dynamically generating a more detailed revnumber and Colophon section. The aim is to capture relevant metadata for every build, making it easier to track the source, version, and status of the document.

Current Approach:

1. Dynamic revnumber (for both Drafts and Final Builds)

The revnumber will be automatically generated and include the following components:

• Last tag (e.g., v1.12.0)
• Number of commits since the tag (e.g., 24)
• Dirty state (if there are uncommitted changes)
• Last commit date
• Last commit ID (short hash)
• Build date
• Remote repo URL (cf-convention/cf-conventions)
• Branch name

Example (Draft):
1.12.0-24-gb724218-dirty, 18 December, 2024 18:15:00 UTC, build 11 December, 2024 18:30:45 UTC, repo: cofinoa/cf-conventions, branch: new-revnumber-colophon

---

2. Colophon Section (Separate for Drafts and Final Builds)

The Colophon will appear after document title and authors, and just before ToC . This approach provides complete metadata for both draft and final builds, offering greater visibility into the origin and history of the document.

Example Colophon for a Draft Build

---

Colophon (Draft Version)

Climate and Forecast Conventions version 1.12-draft has no DOI yet: 10.5281/zenodo.FFFFFF

[CC0 LOGO HERE] This document is dedicated to the public domain following the Creative Commons Zero v1.0 Universal Deed.

The Climate and Forecasting Conventions website https://cfconventions.org/ contains additional resources and provides further information.

DON’T use the following reference to cite this version of the document, as it is only shown as a draft:
Eaton, B., Gregory, J., Drach, B., Taylor, K., Hankin, S. et al. (2024). NetCDF Climate and Forecast (CF) Metadata Conventions (1.12-draft). CF Community. https://doi.org/10.5281/zenodo.FFFFFF

Draft Information:

• Document Title: [Document Title]
• Draft Version: [Draft Version] (e.g., "Draft v1.13")
• Generated On: [Build Date & Time] (e.g., "11 December, 2024 18:30:45 UTC")
• Build Status: [Clean/Dirty] (e.g., "Dirty" if there are uncommitted changes)

Versioning Details (Dynamic Metadata):

• Last Git Tag: [v1.12.0]
• Commits Since Tag: [24]
• Last Commit ID: [Short Hash] (e.g., "b724218")
• Last Commit Date: [Commit Date] (e.g., "11 December, 2024 18:15:00 UTC")
• Current Branch: [Branch Name] (e.g., "main")
• Repository URL: [cf-convention/cf-conventions]

---

Colophon (Final Version)

Climate and Forecast Conventions version 1.12 DOI: 10.5281/zenodo.14275599

cc zero This document is dedicated to the public domain following the [Creative Commons Zero v1.0 Universal]> (https://creativecommons.org/publicdomain/zero/1.0/) Deed.

The Climate and Forecasting Conventions website https://cfconventions.org/ contains additional resources and provides further information.

Use the following reference to cite this version of the document:
Eaton, B., Gregory, J., Drach, B., Taylor, K., Hankin, S. et al. (2024). NetCDF Climate and Forecast (CF) Metadata Conventions (1.12). CF Community. https://doi.org/10.5281/zenodo.14275599

Publication Information:

• Document Title: [Document Title]
• Version: [Final Version] (e.g., "v1.13")
• Published On: [Publication Date & Time] (e.g., "15 December, 2024)
• Build Status: Clean

Versioning Details (Dynamic Metadata):

• Git Tag: [v1.13.0]
• Last Commit ID: [Short Hash] (e.g., "e6f7c9a")
• Last Commit Date: [Commit Date] (e.g., "15 December, 2024 13:45:00 UTC")
• Branch: [Branch Name] (e.g., "release")
• Repository URL: [cf-convention/cf-conventions]

---

How You Can Help

We’d like feedback on the following:

1. Does this approach make sense for you?

• Is it useful to have this level of metadata for both draft and final builds?
• Would you suggest any changes to the layout, terminology, or included metadata?

2. Should we simplify the metadata for the final version?

• For example, would it be better to avoid the commit and repo information for final builds, or are these details still useful for tracking purposes?

3. Do you prefer the revnumber to be in the document header, the colophon, or both?

• Currently, we have it included in both places for drafts, but we could simplify it for final versions.

4. Any other feedback or suggestions?

• Open to any thoughts on how to make this more user-friendly and clear.

Looking forward to your input!

[JonathanGregory]

Dear Antonio

Thanks for this. I think it would be useful to include the "versioning details" in the colophon of draft versions, since there are many of those and it can be useful to know which one you're looking at. I don't think we should have these versioning details in the colophon of the final released versions, which are well-defined. I'm not clear what extra the "publication information" adds which you might need to distinguish drafts. Please could you explain more? Regarding whether the revnumber should be in the document header, please could you point out which part of the document you mean, in your examples?

Best wishes

Jonathan

[cofinoa]

@JonathanGregory,

I agree with your suggestion to display versioning metadata details in the draft artifact within the colophon section, while removing most of them from the final artifact. As you noted, the main goal of this approach is to better distinguish between multiple drafts and ensure traceability, especially when several iterations exist.

The "revnumber" is an AsciiDoc attribute that appears after the title and author on the first page (the "document header").

• For draft builds, I initially included it in both the document header and colophon for better visibility. However, I now see that it may be sufficient to display it only in the colophon.
• For final builds, I agree it is unnecessary since the version, DOI, and publication date provide sufficient traceability.

Clarification on "Publication Information" vs. "Versioning Details"

• Revision Information: Tracks development progress and includes Git tag, commit count, last commit hash, branch, and repository URL.
• Publication Information: Represents the formal release and includes the official version, DOI, and publication date.

There is some overlap between "publication information" and the existing DOI/citation, which may be confusing. I will prepare an example to clarify the distinctions and refine the approach.

Best
Antonio