CF Conventions
CF Conventions editorial release workflow: introducing the Release Candidate stage #449
Replies: 4 comments 1 reply
-
|
Following up on this discussion, I think the recent CF-1.13 publication experience provides a concrete example of why it would be useful to make the RC -> FINAL editorial workflow more explicit. During the preparation of the CF-1.13 Zenodo record, @lhmarsden and @larsbarring raised an issue related to the DOI not being resolvable at the time it was referenced. In parallel, @sadielbartholomew raised an issue (cf-convention/cf-conventions#629) about the missing DOI URL. In this particular case, the delay was caused by a small set of minor editorial fixes that had to be applied to the final documents before they could be built and uploaded to the Zenodo draft for review. These were purely editorial corrections (for example, author metadata such as affiliation and ORCID), but they affected the timing of the final publication steps. None of these are scientific or normative issues, but they do expose a gap in how the editorial publication phase of a release is currently handled and communicated, in particular:
In practice, we already treat the period between an editorially complete text and formal publication as a Release Candidate phase, but this is not currently made explicit or documented as such. The CF-1.13 experience reinforces the motivation for this discussion: not to change governance or scientific review, but to make the editorial workflow clearer, reproducible, and easier to reason about, especially around DOI reservation, artefact consistency, and final publication. |
Beta Was this translation helpful? Give feedback.
-
|
At present, there are three separate locations where the final release artefacts produced locally are deposited, each playing a distinct role in the publication process:
While all artefacts originate from the same local build, the deposition process differs across these repositories. As a concrete example, for the CF-1.13 release the artefacts produced locally by the A. These artefacts were deposited in the Source Release Repository (GitHub release assets) as: A. In the Website Publication Repository, the artefacts are not served directly from the main branch. Instead, GitHub Actions is used to copy the relevant files to the corresponding In the Website Publication Repository (GitHub Pages), the artefacts were published as: A. In the Archival Repository (DOI) on Zenodo, the deposited artefacts were: B. This illustrates that, although all artefacts originate from the same local build, differences in naming conventions, directory layout, selection of artefacts, and publication mechanisms across repositories require careful coordination during the final publication phase. |
Beta Was this translation helpful? Give feedback.
-
|
@cofinoa just wanted to say that this sounds really useful, appreciate the careful work here. This sounds like this would make things clearer and simpler from my perspective. |
Beta Was this translation helpful? Give feedback.
-
|
I agree - was about to comment along the very same lines, so I will add my support to your comment Daniel (thanks). |
Beta Was this translation helpful? Give feedback.
-
|
I too appreciate your setting out the process clearly and thoroughly. It would be good to see it documented in the GitHub repo and linked to the website. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
Topic for discussion
Hi all,
While working recently on the documentation build tooling, it became clear to me that we do not yet have a fully written description of the editorial role of a Release Candidate (RC) in the CF release workflow, even though we more or less follow the same practice already.
I thought it would therefore be useful to open this discussion so that we can describe and agree the workflow together, and then decide how much of it should be documented or reflected in tooling.
What follows is just a starting point for discussion and feedback is very welcome.
Purpose of this discussion
The aim of this discussion is to establish a shared understanding of the editorial workflow for CF Conventions releases, from development (DRAFT) through to publication (FINAL), and in particular to introduce and formalise the Release Candidate (RC) stage within this workflow.
This is not about redefining CF versioning or scientific review. The intention is simply to make explicit how the editorial process works, so that it can be clearly documented and, if useful, later reflected in tooling (e.g. GitHub Actions).
Revisiting: cooling-off period for content acceptance
As a reminder, for a change to be included in a CF release it must complete a cooling-off period. A proposal must first be agreed as complete and accepted, and then remain free of any substantive objections for a minimum period (for example, three weeks). Editorial corrections remain acceptable during this time.
Once all accepted changes for a given release have completed this period, the normative content of that release is considered final.
Role of the Release Candidate and the release branch
As part of the editorial workflow, a dedicated release branch is created from the development branch (
main):This branch represents the specification text that is expected to become the next published CF release, and it is used to manage the transition from accepted content to publication. Release Candidate and FINAL tags are created from commits on this branch:
The RC and FINAL releases share the same metadata (version, canonical release date, reserved DOI). Additional RCs are created only if updates are required.
Summary of editorial states
For clarity, the editorial workflow may be viewed in terms of three stages:
DRAFT
Active development on
main, where content may continue to evolve.Release Candidate (RC)
Editorially complete text on the
release/vX.Y.0branch, during the acceptance period leading to publication.FINAL
The accepted RC is formally published and archived (i.e. Zenodo deposit).
Relationship with the
mainbranchOnce a release branch such as
has been created, the
mainbranch returns to representing ongoing development for the next CF release. In practice this means that metadata onmain(such as the version identifier and editorial status) reflects the next DRAFT release, while therelease/v1.14.0branch remains the editorial home for the upcoming publication.Synchronisation back to
mainOccasionally, minor editorial updates may be made on the
release/vX.Y.0branch during the RC and publication process (for example, documentation clarifications or small corrections). When the FINAL release is declared, these updates should be merged back intomainso that the development branch continues from the published text.Practical editorial steps (for reference)
Typical steps in the workflow include:
release/vX.Y.0branch frommainmaincontinues as the development branch for the next CF releasevX.Y.0-rc1,vX.Y.0-rc2, …)main, so that future development continues from the published textGovernance note
Progression from RC to FINAL is confirmed by the Information Management Team. Any normative changes after publication require a new CF release.
Related discussions and references
This topic relates to a number of previous CF PRs and discussions, including:
Build toolchain and tests
Build toolchain and tests cf-conventions#622
Release process
New version release procedure cf-conventions#588
Create a release procedure. cf-conventions#498
Website publication workflow and infrastructure guide
Add an Infrastructure Guide cf-convention.github.io#548
WIP: Add Infrastructure Guide cf-convention.github.io#106
CF-1.13 release timetable and cooling-off period
https://github.com/orgs/cf-convention/discussions/445
Comments and refinements are very welcome. Once there is agreement, this workflow can be documented for future releases.
Beta Was this translation helpful? Give feedback.
All reactions