Is 'CF-<vn>-draft' a conformant possibility for the Conventions attribute?

[sadielbartholomew]

Question

Under '2.6.1. Identification of Conventions' in the working i.e. draft main and Conformance documents, there is the statement (this from the former, but saying similar but with different wording for the latter):

Files that follow this version of the CF Conventions must indicate this by setting the NUG defined global attribute Conventions to a string value that contains 'CF-1.12-draft'

which follows the sentence in published versions where 'CF-1.12-draft' is replaced by the relevant version e.g. 'CF-1.11' (where it makes perfect sense).

My question: is this suggesting that 'CF-<vn>-draft' for some version number corresponding to an upcoming release, notably with the '-draft' suffix end, is a valid, compliant component value for the Conventions attribute, that should and can be expected to be be used in practice, or is this is a facet of the draft nature of the documents where the version has been set at 'CF-<vn>-draft' until the point of release when the '-draft' component gets dropped to indicate an official release?

I raise this firstly because it is unclear to me the answer to the above, but also that I think we should clarify this respect in one of the following ways, depending on the answer to the question:

• If 'CF-<vn>-draft' is indeed a conformant possibility, follow-on questions arise and I think we should provide clarification on these, for example:
  • Is it safe/wise and therefore advisable for software which processes the value set for the Conventions attribute to a specific version to set the upcoming version '<vn>' as the actual version in the case 'CF-<vn>-draft' is set, or should it be ignored? I think it could be unwise to do so because reference to a draft version could refer to any point in the drafting process where things will be added and amended or even rescinded, so the compliance state would be ambiguous.
  • What if anything is it advised a dataset manager/owner does when the version is released and hence no longer in draft form - ideally they should update from 'CF-<vn>-draft' to CF-<vn>'?
• ...and if it is not conformant, then the statements as above in the draft document are a source of potential confusion and I think we should amend or clarify, e.g. we could change the statement in the documents to not include '-draft' to avoid the confusion, because though the documents are in draft, the suggested attribute value won't have the '-draft' suffix in.

[sethmcg]

My feeling is that -draft is not conformant. People shouldn't be trying to conform to a draft version of the spec, and it shouldn't be regarded as valid in a Conventions attribute. (Gut reaction; I could be persuaded otherwise.)

However, the question then is, how much automation surrounds version numbers in the draft document, and would dropping the -draft in that context mess it up? Do we need some convention for indicating "this text will only appear in the draft, and will be replaced on release"?

[sadielbartholomew]

Thanks Seth, I agree with your sentiments and good further question. I'll wait to see who else might respond to get a feeling for whether folk agree and then we can go forward with considering that new question if they do.

[ethanrd]

I agree that -draft should not be included in the Conventions attribute CF version string.

[JonathanGregory]

I agree with Seth and Ethan that CF-vn-draft should not be valid for the Conventions attribute. Since it's a draft, it might possibly be changed before being released. We don't have an established process for doing that, and I don't recall it happening, but it seems conceivable. Therefore it's unsafe to use a draft as a reference. Thanks for raising the issue, @sadielbartholomew.

[sadielbartholomew]

Thanks for your thoughts Jonathan. I believe we now have three agreements that it is not valid, which is sufficient to my liking, though of course further thought is welcome from anyone.

Perhaps with the Information Management Team at the upcoming meeting (or a future one, if there's not time there) we can discuss the feasibility of amending the build or similar so this isn't a source of confusion, as per my related comments for this case of:

if it is not conformant, then the statements as above in the draft document are a source of potential confusion and I think we should amend or clarify, e.g. we could change the statement in the documents to not include '-draft' to avoid the confusion, because though the documents are in draft, the suggested attribute value won't have the '-draft' suffix in

and the questions, from Seth, of:

how much automation surrounds version numbers in the draft document, and would dropping the -draft in that context mess it up? Do we need some convention for indicating "this text will only appear in the draft, and will be replaced on release"?

[ethanrd]

I have added this to the agenda for the next meeting.

[sadielbartholomew]

Brill, thanks Ethan.

[JonathanGregory]

I've changed the category of this discussion, because it's not a question about how to use CF.

[ethanrd]

This came up briefly at the recent CF Info Management team meeting but we didn't make any decisions. Perhaps we can make some progress here and then during the CF Workshop.

It seems pretty well agreed that a string of the form CF-<vn>-draft is not a valid value for the "Conventions" attribute. The next steps are probably

1. deciding what text should be used in draft CF Conventions documents
2. figuring out how to make those changes in the GH Action that builds the document.

There are currently two places that specify how CF is specified in the "Conventions" attribute. The first is in CF 1.4 "Overview" where the second paragraph is this single sentence:

• Files using this version of the CF Conventions must set the NUG defined attribute Conventions to contain the string value "CF-1.12-draft" to identify datasets that conform to these conventions.

The second is in CF 2.6.1 "Identification of Conventions" where the first sentence of the first paragraph says

• Files that follow this version of the CF Conventions must indicate this by setting the NUG defined global attribute Conventions to a string value that contains "CF-1.12-draft".

We could replace these sentences all together with a version explaining that draft documents are not safe to use when constructing a dataset.

Perhaps we should (maybe a separate issue) also look at tweaking both of the current sentences so they are identical. Or even consider whether CF needs to spell this out in two locations.

[taylor13]

Perhaps the sentences could be reworded such that the draft version number isn't mentioned. Maybe something like

• For files conforming to the CF conventions, the NUG-defined global attribute Conventions should be of the form CF-<version number> where the version number must be one of the versions listed under "Revision History". The Conventions attribute should not refer to a draft version.

[JonathanGregory]

As @sethmcg mentioned, this is due to the automation. The "code" of the document actually has CF-{current-version-as-attribute} in both places. I suspect that we can fix this in version.adoc, whose contents are

// Set version
:version: 1.12

////
Normally, a draft is produced, unless the `final` attribute is defined.
Define the `final` attribute by uncommenting the following line
or with the commandline switch `-a final`.
////
// :final:

// No changes needed beyond this line
ifdef::final[]
:current-version: {version}
:current-version-as-attribute: {version}
endif::[]
ifndef::final[]
:current-version: {version} draft
:current-version-as-attribute: {version}-draft
endif::[]

Perhaps we just need to put :current-version-as-attribute: {version} for the draft as well as the final version. Then the Conventions string would currently be prescribed as CF-1.12. The current-version can remain as CF 1.12 draft. This string appears at the top of the rendered document, produced by cf-conventions.adoc. It would be nice also to insert somewhere in the text a statement that changes included since the last release are not really CF-conformant yet.

[DocOtak]

Would it be worth "watermarking" the page with draft as well? Something like https://www.w3.org/People/Schepers/unoffical_template.html but maybe not as aggressive.

[larsbarring]

This should be doable in Asciidoctor, see https://docs.asciidoctor.org/pdf-converter/latest/background-images/