diff --git a/conventions.md b/conventions.md index 2150f824..ced20eca 100755 --- a/conventions.md +++ b/conventions.md @@ -105,6 +105,12 @@ group: "navigation"
+ +

Rules for contributing to CF

+ +

Rules and guidelines for changes to the CF conventions + +

Rules for changing CF standard names and other controlled vocabulary

List of contributors to CF conventions

diff --git a/discussion.md b/discussion.md index 9c7f7089..22aabe57 100755 --- a/discussion.md +++ b/discussion.md @@ -20,11 +20,11 @@ Discussions by category: ❓ [Questions and answers about using CF][gi Proposals to change CF are made, debated and decided as [GitHub issues][github_issues] in three repositories: -* [Vocabulary issues][github_vocabularies], in the [vocabularies repository](https://github.com/cf-convention/vocabularies), for proposing additions or amendments to standard names, their definitions, or other CF controlled vocabulary (area types and standardized regions). [Open a new issue](https://github.com/cf-convention/vocabularies/issues/new/choose). See also [closed vocabulary issues][github_vocabularies_closed]. +* [Vocabulary issues][github_vocabularies], in the [vocabularies repository](https://github.com/cf-convention/vocabularies), for proposing additions or amendments to standard names, their definitions, or other CF controlled vocabulary (area types and standardized regions), according to the [rules for changes to CF vocabularies](https://cfconventions.org/standard_name_rules.html). [Open a new issue](https://github.com/cf-convention/vocabularies/issues/new/choose). See also [closed vocabulary issues][github_vocabularies_closed]. As well as in GitHub issues, the status of proposals about standard names is shown by the [CEDA vocabulary editor][vocab_editor]. To see a list of resolved proposals (accepted or rejected) for standard names from March 2011 onwards, click "Inactive" in the [CEDA vocabulary editor][vocab_editor]. -* [Conventions issues][github_conventions], in the [conventions repository](https://github.com/cf-convention/cf-conventions), for proposing enhancements and reporting defects in the CF conventions. [Open a new issue](https://github.com/cf-convention/cf-conventions/issues/new/choose). See also [closed conventions issues][github_conventions_closed], classified by reason for closure: [change agreed][github_conventions_change] • [agreement not to change][github_conventions_nochange] • [dormant][github_conventions_dormant]. "Dormant" means the discussion on a proposed change did not reach a conclusion. Dormant issues may be reopened if there is a new impetus or ideas that might help bring about an agreement. +* [Conventions issues][github_conventions], in the [conventions repository](https://github.com/cf-convention/cf-conventions), for proposing enhancements and reporting defects in the CF conventions, according to the rules and guidelines for [contributing to the CF conventions](https://github.com/cf-convention/cf-conventions?tab=contributing-ov-file#contributing-to-the-cf-conventions). [Open a new issue](https://github.com/cf-convention/cf-conventions/issues/new/choose). See also [closed conventions issues][github_conventions_closed], classified by reason for closure: [change agreed][github_conventions_change] • [agreement not to change][github_conventions_nochange] • [dormant][github_conventions_dormant]. "Dormant" means the discussion on a proposed change did not reach a conclusion. Dormant issues may be reopened if there is a new impetus or ideas that might help bring about an agreement. * [Website and governance issues][github_website], in the [website repository](https://github.com/cf-convention/cf-convention.github.io), for proposing changes and reporting defects in the [CF website][website] or CF governance. [Open a new issue](https://github.com/cf-convention/cf-convention.github.io/issues/new/choose). diff --git a/errors.md b/errors.md deleted file mode 100755 index 1b633543..00000000 --- a/errors.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -layout: default -title: Errors ---- - -# Rules for Correcting Errors in CF Documents - -These rules apply to the CF conventions document, the conformance document, the standard name table and its guidelines. - -Errors in these documents can be corrected under these rules if it is clear that the text as it stands isn't what was agreed, because of a typographical or some other error. -These rules can't be followed for making substantive changes. -Errors in the standard names can alternatively be pointed out on the CF email list, and implemented by the manager of CF standard names (Alison) as part of a regular update. - -If someone thinks there is an error in a document, they should open a github issue of type "defect" to point it out and to state what should be done to the text in order to correct the error. -A corresponding github pull request can also be submitted in addition to the issue. - -The correction is held to have been agreed if three weeks pass without anyone disagreeing with it. -After that period, the issue should be closed by the manager of the CF conventions or the manager of CF standard names, who will make the change and/or merge the pull request. -No moderator is needed because there cannot be any substantive discussion under these rules. - -If anyone disagrees that the correction should be made, because they think the document does have the intended meaning, then a correction cannot be made by these rules, the issue should be closed, and the change should be proposed as an enhancement instead, following the rules for making changes to the CF standard, if the proposer wants to pursue the issue. - -These rules were agreed under github [issue #130][130]. - -[130]: https://github.com/cf-convention/cf-conventions/issues/130 diff --git a/governance.md b/governance.md index 860250af..d70cc2d5 100755 --- a/governance.md +++ b/governance.md @@ -8,10 +8,6 @@ group: "navigation" ## Governance Documents -* [Rules for making changes to the CF Conventions][rules] - * Discussion about these rules can be found in the [CF mailing list archives][mail], in June and July, 2007. See messages with the subject line "proposed rules for changes to CF conventions". - * The rules were amended in January 2016 following [CF trac ticket 146][ticket146] -* [Rules for correcting errors in the CF documents][errors] * [CF constitution](constitution.md) * CF white paper (Lawrence et al., 2006) \[ [PDF][pdf], [HTML][html] \] diff --git a/index.md b/index.md index bf5f0a0b..43a1d968 100755 --- a/index.md +++ b/index.md @@ -57,7 +57,9 @@ markdown="1" signals that the text within the div is markdown, not HTML. --> See also the links in the navigation bar at the top of this page. -Proposals for changing CF (GitHub issues):
[vocabulary](https://github.com/cf-convention/vocabularies/issues) (including standard names), [conventions](https://github.com/cf-convention/cf-conventions/issues), [website and governance](https://github.com/cf-convention/cf-convention.github.io/issues) +Rules for contributing to CF: [vocabulary](https://cfconventions.org/standard_name_rules.html) (including standard names), [conventions](https://github.com/cf-convention/cf-conventions?tab=contributing-ov-file#contributing-to-the-cf-conventions) + +Proposals for changing CF: [vocabulary](https://github.com/cf-convention/vocabularies/issues), [conventions](https://github.com/cf-convention/cf-conventions/issues), [website and governance](https://github.com/cf-convention/cf-convention.github.io/issues) [CF GitHub organisation](https://github.com/cf-convention) @@ -97,4 +99,4 @@ The CF community embraces a philosophy of producing excellence by maintaining an
-
\ No newline at end of file +
diff --git a/rules.md b/rules.md deleted file mode 100755 index 3c3ef4dc..00000000 --- a/rules.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -layout: default -title: Rules ---- - -# Rules for CF Conventions Changes - -New proposals are to be made in GitHub issues using the template, including verbatim changes proposed to the text of standard document and the conformance document. - -A member of the conventions committee, or another suitably qualified person, volunteers to moderate the discussion. -If no-one volunteers, the chairman of the committee will ask someone to do it. - -The discussion takes place on GitHub issues and all may participate. - -The moderator periodically summarises discussion on github, keeps it moving forward and tries to achieve a consensus. -It is expected that everyone with an interest will contribute to the discussion and to achieving a consensus during this stage. -During the discussion, if an objection is raised, answered and not reasserted, the moderator will assume the objection has been dropped. -However, since consensus is the best outcome, it will be helpful if anyone who expresses an objection explicitly withdraws it on changing their mind or deciding to accept the majority view. - -The moderator is encouraged to organize conference calls and/or webex-type interactions if this might help resolve an issue more quickly. - -It will be helpful if a test netCDF file is provided as early as possible during the discussion. -However, several variants of the proposal may be discussed, and the proposer may not be able to provide test netCDF files for all of them. - -When three weeks have passed with no contributions being made, the moderator should attempt to move toward a decision on the proposal by summarising the discussion and indicating the outcome as consensus, near consensus, or not near consensus (see below) on making the proposed change. -Since several versions of the proposal might have been discussed, the summary should make clear which one, if any, would be adopted. -The moderator will then invite further comment on the proposal, as summarised. -If further comments are made i.e. the discussion restarts, this step is repeated. - -Once the summary has been made, if the test netCDF file does not yet exist, it must be created (unless the summary suggests the proposal should be rejected). -When three weeks have passed with no contributions following a summary, and providing a test file exists (if appropriate), a decision is reached in one of the following ways: - -Consensus: Accept the proposal if there is no outstanding objection, and at least three contributors have expressed support for it, including at least two members of the conventions committee. -If the moderator personally expresses support, he or she can be counted among the supporters. - -Near consensus: If the conditions for consensus are not met but the moderator's summary is that consensus has nearly been achieved, accept the proposal if all, or all but one, of the conventions committee vote in favour of it. -The moderator will call for votes and all members should vote. - -Not near consensus: No change to standard. - -The GitHub issue is then closed by the moderator stating the outcome. - -If the change is accepted, the standard document should be updated, the CF convention version number incremented, and the conformance document updated. - -The author of the proposal should be added to the list of contributing authors of the CF convention. - -If the change, once implemented in the conventions, subsequently turns out to be materially flawed, meaning that data written following the convention could be somehow erroneous or ambiguous, a github issue should urgently be opened to discuss whether to revoke the change. -If this is agreed by a majority of the committee, a new version of the conventions will be prepared immediately, with the second digit of the version number incremented, and will be recommended to be used instead of the flawed version. -The flawed version will be deprecated by a statement in the standard document and the conformance document. -However, any data written with the flawed version will not be invalidated, although it may be problematic for users. -Errors or lack of clarity in wording, when the convention itself is not at fault, can be corrected by defect tickets on the usual schedule. - -All versions of the standard and conformance document should be kept available online, with their github issues and a history of changes. - -## Additional rules relating to the CF data model - -The CF data model will guide the development of CF by providing a framework for ensuring that proposed changes fit into CF in a logical way, rather than just a pragmatic one. - -All new proposals will be assessed to see if the new features defined in the proposal map onto the CF data model. - -The assessment will be carried out by a member of the conventions committee or another suitably qualified person. -If no-one volunteers, the chairman of the committee will ask someone to do it. - -If the proposal maps onto the existing CF data model then no modifications to the data model are required. - -Otherwise an attempt must be made to modify the proposal so that its new features do map onto the CF data model, and in such a way that the proposal's intent is not compromised. - -If the proposal cannot be acceptably modified to conform to the existing data model, then the data model will need to be modified to accommodate the new features. -If the data model may be extended or generalised in some way that allows the new features but does not affect its existing constructs and relationships, the proposal is considered backwards compatible. -This is the preferred solution. - -Any changes to the data model must be described verbatim as part of the proposal discussion, including any modified or new data model diagrams. -However, to facilitate the progress of a proposal that requires data model changes, it is sufficient for the general nature of the data model modifications to be identified, on the understanding that the data model text will be updated in detail at a later date, possibly after the proposal has been accepted. - -## Additional recommendations relating to UGRID - -CF incorporates named versions of the UGRID conventions without redefining them in the CF conventions document, i.e. CF formally refers to the UGRID conventions document for its description of mesh topologies. -UGRID has its own governance that is independent of the rules governing the CF conventions, and it is therefore the joint responsibility of the CF and UGRID communities to ensure that changes to one convention are mutually agreeable to the other. - -In the unlikely and highly undesirable event that a non-negotiable change to one convention is incompatible with the other convention then this may be resolved either by restricting which versions of UGRID are allowed in CF; or else (as a last resort) rewriting UGRID into the CF conventions document, including any required compatibility changes, thereby breaking the formal dependence on the external UGRID conventions. diff --git a/standard_name_rules.md b/standard_name_rules.md index ba8019bd..e3e0a78a 100644 --- a/standard_name_rules.md +++ b/standard_name_rules.md @@ -7,7 +7,7 @@ title: Vocabulary rules # Rules for Changes to CF Standard Names, Area Types and Standardized Region List Vocabularies **These rules apply only to changes in CF controlled vocabularies. -The rules for changes to the CF conventions themselves are given [here](http://cfconventions.org/rules.html).** +The rules for changes to the CF conventions themselves are given [here](https://github.com/cf-convention/cf-conventions?tab=contributing-ov-file#contributing-to-the-cf-conventions).** New proposals are made by opening a new issue in the cf-convention/vocabularies github repository. The 'Standard Names' template should be used, even if the proposal relates to one of the other vocabularies.