Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Correct the wording in the conformance document section 2.3 "Naming Conventions" #226

Closed
davidhassell opened this issue Jan 13, 2020 · 6 comments
Labels
defect Conventions text meaning not as intended, misleading, unclear, has typos, format or language errors

Comments

@davidhassell
Copy link
Contributor

davidhassell commented Jan 13, 2020

Title: Correct the wording in the conformance document section 2.3 "Naming Conventions"

Moderator: @RosalynHatcher

Requirement Summary: The conventions say, in section 2.3, that "Variable, dimension, attribute and group names should begin with a letter, ...", but the conformance document says must instead of should for checking this. The Conventions document is correct (see also Trac Ticket 157 https://cfconventions.org/Data/Trac-tickets/157.html), so the conformance document needs changing.

Technical Proposal Summary: Change "must" to "should" in that part of the conformance document, and move the whole sentence to "recommendations" (from "requirements")

Benefits: Everyone, as the checker will better reflect the conventions

Status Quo: Compliant files may fail the checks.

Detailed Proposal: PR to follow

@davidhassell davidhassell added the defect Conventions text meaning not as intended, misleading, unclear, has typos, format or language errors label Jan 13, 2020
@RosalynHatcher
Copy link
Contributor

I agree with this and am happy with the PR.

@taylor13
Copy link

likewise, I think this correction should be made.

@DocOtak
Copy link
Member

DocOtak commented Jan 13, 2020

Should the CF conventions documentation adopt BCP 14 [RFC2119] [RFC8174]?

@erget
Copy link
Member

erget commented Jan 14, 2020

@DocOtak I love RFC2119 and fully support using it fastidiously. It's been a great help to me in numerous requirements documents.

I do believe that migrating the document to use those terms correctly and consistently would be a larger effort that, if desired, should be a separate "project" since it's so wide-reaching.

Maybe this would be an appropriate item for the backlog to be discussed e.g. at the annual meeting and implemented as its own issue?

@davidhassell
Copy link
Contributor Author

Using well-defined definitions for these terms sounds like a good idea, as well as, perhaps, reviewing the terms in the main conventions document. @erget's suggestions for discussing this in it's own right, as opposed to discussing it on this ticket, sounds like th right way forward, to me. Perhaps there are terms in the main conventions document that could/should be changed, too.

@davidhassell
Copy link
Contributor Author

Merging this so that it goes in to CF-1.8. Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
defect Conventions text meaning not as intended, misleading, unclear, has typos, format or language errors
Projects
None yet
Development

No branches or pull requests

5 participants