-
Notifications
You must be signed in to change notification settings - Fork 46
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #256 from erget/procedural-items
This pull request implements #257 on procedural (GitHub) items for the conventions repo.
- Loading branch information
Showing
9 changed files
with
65 additions
and
51 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,11 @@ | ||
| See issue #XXX for discussion of these changes. | ||
| See issue #XXX for discussion of these changes. | ||
|
|
||
| # Release checklist | ||
| - [ ] Authors updated in `cf-conventions.adoc`? | ||
| - [ ] Next version in `cf-conventions.adoc` up to date? Versioning inspired by [SemVer](https://semver.org). | ||
| - [ ] `history.adoc` up to date? | ||
| - [ ] Conformance document up-to-date? | ||
|
|
||
| # For maintainers | ||
| After the merge remember to delete the source branch. | ||
| Tags are set at the conclusion of the annual meeting; until then `master` always is a draft for the next version. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,67 +1,53 @@ | ||
| # Contributing to the NetCDF-CF conventions | ||
| # Contributing to the netCDF-CF Conventions | ||
|
|
||
| Dear CF community member, | ||
|
|
||
| Thank you for taking the time to consider making a contribution to the [cf-conventions](http://cfconventions.org/). | ||
| The NetCDF Climate and Forecasting conventions are a product by and for a broad community and your contribution is the key to their usefulness. | ||
| The netCDF Climate and Forecasting conventions are a product by and for a broad community and your contribution is the key to their usefulness. | ||
|
|
||
| This set of guidelines provides a brief overview of the practices and procedures that should be used in fixing, updating, or adding to the conventions. | ||
| This set of guidelines provides a brief overview of the practices and procedures that should be used in fixing, updating, or adding to the conventions. | ||
| It builds on the [rules for CF Convention changes.](http://cfconventions.org/rules.html) | ||
|
|
||
| As a prerequisite to this guide, please review the community's code of [conduct.](https://github.com/cf-convention/cf-conventions/blob/master/CODE_OF_CONDUCT.md) | ||
| The CF community takes great pride in respectful and collegial discourse. Any disrespectful or otherwise derogatory communication will not be tolerated. | ||
|
|
||
| ## General Guidelines | ||
| These contribution guidelines are designed to make it easy to contribute to the | ||
| CF Conventions and are tailored to the platform where they are hosted, GitHub. | ||
| They are intended to support your work and not to constrict you; if at any time | ||
| you find them difficult to follow, ask for help. | ||
| Your contribution is valuable and the community will be happy to give a hand. | ||
|
|
||
| 1. **A given proposal should be discussed as one issue.** It shouldn't fork or be superseded by another one, unless that reflects what has happened to the proposal. | ||
| This is so it is easy to trace the discussion that led to a given agreed proposal. | ||
| ## General guidelines for using GitHub to change the CF Conventions | ||
|
|
||
| 2. **A proposal should convey the reasoning and effect on all relevant sections of the specification.** | ||
| An overview of all actual changes and the impact the changes have on the specification should be clear. | ||
| 1. **A given proposal should be discussed as one issue.** It shouldn't fork or be superseded by another one, unless that reflects what has happened to the proposal. | ||
| This is so it is easy to trace the discussion that led to a given agreed proposal. | ||
| 1. **A proposal should convey the reasoning and effect on all relevant sections of the specification.** | ||
| An overview of all actual changes and the impact the changes have on the specification should be clear. | ||
| Depending on the length and nature of the proposal, this may require different approaches as described below. | ||
|
|
||
| 3. **In general, issues should be used for discussion of proposed changes and pull requests should be used for review of agreed upon changes.** | ||
| In other words, if the content or concept of what is being proposed needs to be vetted by the community it should be vetted in an issue. | ||
| 1. **In general, issues should be used for discussion of proposed changes and pull requests should be used for review of agreed upon changes.** | ||
| In other words, if the content or concept of what is being proposed needs to be vetted by the community it should be vetted in an issue. | ||
| If the proposal is non-controversial (such as a typo correction) or has been agreed to in concept in an issue, then detailed review of the text may take place in a pull request. | ||
| Practically all changes should be documented and discussed in an issue fixed in a related pull request. | ||
|
|
||
| 4. **Use [labels](https://github.com/cf-convention/cf-conventions/labels) on issues and pull requests.** | ||
| 1. **Use [labels](https://github.com/cf-convention/cf-conventions/labels) on issues and pull requests.** | ||
| Currently this is achieved by using an appropriate issue template when creating a [new issue](https://github.com/cf-convention/cf-conventions/issues/new/choose). | ||
| 1. **Comments in pull requests.** These should be avoided, unless discussing changes to the wording of a proposal that do not impact on the agreed meaning. This is so that the scientific development of the proposal is easily found in one place, i.e. the GitHub issue. | ||
|
|
||
| 5. **Comments in pull requests.** These should be avoided, unless discussing changes to the wording of a proposal that do not impact on the agreed meaning. This is so that the scientific development of the proposal is easily found in one place, i.e. the GitHub issue. | ||
|
|
||
| ## Issues and Pull Requests | ||
| ## Issues and pull requests | ||
| Note that it takes a minimum of three weeks for a change to the content of the CF Conventions to be merged into the Convention's next version. | ||
| As the Conventions are published once a year, this means that the de facto "feature freeze" for a given version of the CF Conventions is three weeks before that year's annual meeting. | ||
|
|
||
| Issues should attempt to follow the guidelines here and in the issue template as much as possible. | ||
| Issues should attempt to follow the guidelines in the issue template as much as possible. | ||
| All new pull requests should be submitted to the master branch of this repository. | ||
| It is recommended that pull requests are created on a branch of a personal fork of this repository. | ||
| Use of other branches is at the discretion of the repository administrators. | ||
| The following cases describe potential patterns of use for issues and pull requests. | ||
|
|
||
| 1. **Typo Fix** If the change is a non-controversial fix such as a typo, no issue is required as these changes do not appear in the convention history. | ||
| A pull request with the fix can be submitted directly. | ||
| Contributors not familiar with github can submit issues for typos and similar issues for others to fix. | ||
|
|
||
| 2. **Single Section Change** In the case of a change concerning one to a few paragraphs, an issue should be opened that describes the problem and proposed fix. | ||
| If important to the issue, the problem text should be pasted in the body of the issue and proposed fix included. | ||
| A link to the line where the problem exists could also be included. | ||
| If the modification is non-controversial, a pull request could be opened simultaneously. | ||
| Discussion of the proposal should take place in one issue. | ||
| Final review should take place in the pull request and the issue closed when the pull request is merged. | ||
|
|
||
| 3. **Changes Spanning Multiple Sections** If reasonable, changes concerning multiple sections should follow the pattern described in Single Section Change. | ||
| If explicitly listing proposed changes is not practical, general guideline 2 should be followed to document the proposal. | ||
| Depending on the nature of the proposal, interested community members can decide what the most effective tool is for development and review of specification changes. | ||
| Tools used for development of significant changes are up to those contributing and reviewing it. | ||
| Note that there is a rendered "rich-diff" view of a pull request that can be helpful for review of large contributions. | ||
|
|
||
| ## Merging of pull requests, and closing and reopening of issues | ||
|
|
||
| When an issue and accompanying pull request concludes with an agreed change to the conventions, then the pull request will be merged into the master branch after a further 3 weeks has elapsed, assuming that no more discussion occurs. This is as described by the rules for conventions changes at http://cfconventions.org/rules.html. If further substantive comments are raised during this period, then the final 3 week period will restart after a new conclusion is agreed. | ||
|
|
||
| The pull request will be merged by a member of the governance panel or the CF conventions and standard names committee. | ||
| When an issue and accompanying pull request concludes with an agreed change to the conventions, the pull request is merged into the master branch according to the [Rules for CF Convention Changes](http://cfconventions.org/rules.html). | ||
|
|
||
| The person who merges the pull request should also close the issue, leaving a comment that the issue was concluded with no further comment during the subsequent 3 weeks. | ||
| The pull request is merged by a member of the Governance Panel or the CF Conventions and Standard Names Committee. | ||
| The person who merges the pull request also closes the issue. | ||
|
|
||
| If subsequent discussion is required after the pull request has been merged then a new issue should be raised, rather than reopening the closed issue. | ||
| An issue may be closed without the merging of a pull request if the change was not accepted by the community. In this case the issue may be reopened for further discussion at a later date. | ||
| An issue may be closed without the merging of a pull request if the change was not accepted by the community. | ||
| In this case the issue may be reopened for further discussion at a later date. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters