From 3d42587de2b6588a679e366db6066e70b041223a Mon Sep 17 00:00:00 2001 From: David Blodgett Date: Mon, 21 May 2018 14:17:44 -0500 Subject: [PATCH 1/8] draft github CONTRIBUTING guidelines --- .github/CONTRIBUTING.md | 73 ++++++++++++++++++++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 8 +++- CODE_OF_CONDUCT.md | 25 +++++++++++ 3 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 .github/CONTRIBUTING.md create mode 100644 CODE_OF_CONDUCT.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..4a90cb01 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,73 @@ +# 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. + +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. + +As of the creation of this version of these guidelines, contributions can also be +made through the [cf-trac](https://cf-trac.llnl.gov/trac/) infrastructure. +[Procedures for using trac](http://cfconventions.org/rules.html) are not covered +here and it is expected that the trac system will be deprecated once the +community is comfortable using github for the purpose. + +## General Guidelines + +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 that it's easy to trace the discussion which led to a +given agreed proposal. + +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. 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. 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. + +## Issues and Pull Requests + +The following cases describe potential patterns of use for Issues. + +1. **Typo Fix** If the change is a non-controversial fix such as a typo, +no issue is required. A pull request with the fix can be submitted directly. +Contributors not familiar with github are encouraged to 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. 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 if the reporter is familiar with git and github. Discussion of +the proposal should take place in one issue. Once accepted, a pull request could +be submitted implementing the suggested change. 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 patter described 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. Some proposals have +been developed in google docs and contributed as a pull request after general +consensus has been reached, but the specific tools used for development of +significant changes is up to those contributing and reviewing it. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 1441f946..57114603 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,7 +1,13 @@ -See http://cf-trac.llnl.gov/trac/ticket/XXX +_If trac was used for review of contribution:_ +See http://cf-trac.llnl.gov/trac/ticket/XXX - [ ] Added link from trac ticket to this PR? > Applied via ​https://github.com/cf-convention/cf-conventions/pull/XXX - [ ] Updated "Revision History"? (Use the date you applied the changes.) + +_If github issues were used for review:_ +See issue #XXX + + - [ ] Updated "Revision History"? (Use the date you applied the changes.) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..af36991f --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,25 @@ +# Contributor Code of Conduct + +As contributors and maintainers of this project, we pledge to respect all people who +contribute through reporting issues, posting feature requests, updating +documentation, submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free experience for +everyone, regardless of level of experience, gender, gender identity and expression, +sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion. + +Examples of unacceptable behavior by participants include the use of sexual language or +imagery, derogatory comments or personal attacks, trolling, public or private harassment, +insults, or other unprofessional conduct. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, +commits, code, wiki edits, issues, and other contributions that are not aligned to this +Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed +from the project team. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by +opening an issue or contacting one or more of the project maintainers. + +This Code of Conduct is adapted from the Contributor Covenant +(http:contributor-covenant.org), version 1.0.0, available at +http://contributor-covenant.org/version/1/0/0/ From a5495b4dcc64f31c2f25cefa72695d7ac1f5f52b Mon Sep 17 00:00:00 2001 From: David Blodgett Date: Mon, 21 May 2018 19:55:11 -0500 Subject: [PATCH 2/8] minor changes per review --- .github/CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 4a90cb01..37371966 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -21,7 +21,7 @@ As of the creation of this version of these guidelines, contributions can also b made through the [cf-trac](https://cf-trac.llnl.gov/trac/) infrastructure. [Procedures for using trac](http://cfconventions.org/rules.html) are not covered here and it is expected that the trac system will be deprecated once the -community is comfortable using github for the purpose. +community is comfortable using github for this purpose. ## General Guidelines @@ -45,12 +45,12 @@ detailed review of the text may take place in a pull request. ## Issues and Pull Requests -The following cases describe potential patterns of use for Issues. +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. A pull request with the fix can be submitted directly. -Contributors not familiar with github are encouraged to submit issues for typos -and similar issues for others to fix. +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 From dd39d1505d576a12e881dfde87f155d94b876dc1 Mon Sep 17 00:00:00 2001 From: David Blodgett Date: Thu, 7 Jun 2018 07:27:27 -0500 Subject: [PATCH 3/8] labels --- .github/CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 37371966..0ecdbc4a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -43,6 +43,10 @@ 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. +4. **Use [labels](https://github.com/cf-convention/cf-conventions/labels) on issues +and pull requests.** Please attempt to present contributions as enhancements, +defects, or typos and label them accordingly. + ## Issues and Pull Requests The following cases describe potential patterns of use for issues and pull requests. From 63288ba885ea97dbc09321de8acafd3ff7b0e68b Mon Sep 17 00:00:00 2001 From: David Blodgett Date: Wed, 18 Jul 2018 20:35:42 -0500 Subject: [PATCH 4/8] reflow and edit contributing --- .github/CONTRIBUTING.md | 92 ++++++++++++++--------------------------- 1 file changed, 32 insertions(+), 60 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 0ecdbc4a..d7c6163a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,76 +2,48 @@ 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. +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. -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) +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. - -As of the creation of this version of these guidelines, contributions can also be -made through the [cf-trac](https://cf-trac.llnl.gov/trac/) infrastructure. -[Procedures for using trac](http://cfconventions.org/rules.html) are not covered -here and it is expected that the trac system will be deprecated once the -community is comfortable using github for this purpose. +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 -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 that it's easy to trace the discussion which led to a -given agreed proposal. +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 what led to a given agreed proposal. -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. Depending on the -length and nature of the proposal, this may require different approaches as -described below. +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. +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. 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. +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. +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. -4. **Use [labels](https://github.com/cf-convention/cf-conventions/labels) on issues -and pull requests.** Please attempt to present contributions as enhancements, -defects, or typos and label them accordingly. +4. **Use [labels](https://github.com/cf-convention/cf-conventions/labels) on issues and pull requests.** +Please attempt to present contributions as enhancements, defects, or typos and label them accordingly. ## Issues and Pull Requests 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. 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. 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 if the reporter is familiar with git and github. Discussion of -the proposal should take place in one issue. Once accepted, a pull request could -be submitted implementing the suggested change. 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 patter described 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. Some proposals have -been developed in google docs and contributed as a pull request after general -consensus has been reached, but the specific tools used for development of -significant changes is up to those contributing and reviewing it. +1. **Typo Fix** If the change is a non-controversial fix such as a typo, no issue is required. +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 patter 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. From d17c4bab8d69ec027146686b9e4631e2d2e179f6 Mon Sep 17 00:00:00 2001 From: David Blodgett Date: Mon, 23 Jul 2018 14:48:46 -0500 Subject: [PATCH 5/8] some review changes from @JonathanGregory --- .github/CONTRIBUTING.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index d7c6163a..76f5f63f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -13,9 +13,8 @@ The CF community takes great pride in respectful and collegial discourse. Any di ## General Guidelines -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 what led to a given agreed proposal. +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 tha led to a given agreed proposal. 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. @@ -24,15 +23,16 @@ Depending on the length and nature of the proposal, this may require different a 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. 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.** -Please attempt to present contributions as enhancements, defects, or typos and label them accordingly. +Contributions must be presented as enhancements, defects, or typos and labeled accordingly. ## Issues and Pull Requests 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. +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. @@ -43,7 +43,8 @@ If the modification is non-controversial, a pull request could be opened simulta 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 patter described in Single Section Change. +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. +Tools used for development of significant changes are up to those contributing and reviewing it. +Note that their is a rendered "rich-diff" view of a pull request that can be helpful for review of large contributions. From 36b797c524528b158854a511000ff191fe20881f Mon Sep 17 00:00:00 2001 From: David Blodgett Date: Sat, 11 Aug 2018 19:31:47 -0500 Subject: [PATCH 6/8] template updates --- .github/ISSUE_TEMPLATE/issue_template.md | 9 +++++++++ .github/PULL_REQUEST_TEMPLATE.md | 14 +------------- 2 files changed, 10 insertions(+), 13 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/issue_template.md diff --git a/.github/ISSUE_TEMPLATE/issue_template.md b/.github/ISSUE_TEMPLATE/issue_template.md new file mode 100644 index 00000000..eeef3e3e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/issue_template.md @@ -0,0 +1,9 @@ +Change proposals should include the following information as applicable. + +**Title:** Short and descriptive. +**Moderator:** @user +**Requirement Summary:** A few sentence functional summary +**Technical Proposal Summary:** Brief proposal overview +**Benefits:** Who or what will benefit from this proposal? +**Status Quo:** Discussion of the current state CF and other standards. +**Detailed Proposal:** Complete proposal \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 57114603..9117eddc 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,13 +1 @@ -_If trac was used for review of contribution:_ -See http://cf-trac.llnl.gov/trac/ticket/XXX - - - [ ] Added link from trac ticket to this PR? - - > Applied via ​https://github.com/cf-convention/cf-conventions/pull/XXX - - - [ ] Updated "Revision History"? (Use the date you applied the changes.) - -_If github issues were used for review:_ -See issue #XXX - - - [ ] Updated "Revision History"? (Use the date you applied the changes.) +See issue #XXX for discussion of these changes. \ No newline at end of file From 23c0db289c3422b2fbf5a618f987f836577b490d Mon Sep 17 00:00:00 2001 From: David Blodgett Date: Wed, 15 Aug 2018 13:23:30 -0500 Subject: [PATCH 7/8] minor contributing update --- .github/CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 76f5f63f..ae7ef606 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -30,6 +30,9 @@ Contributions must be presented as enhancements, defects, or typos and labeled a ## Issues and Pull Requests +Issues should attempt to follow the guidelines here and in the issue template as much as possible. +All new pull requests should be submitted to the master branch and will be merged or closed as soon as agreement has been reached. +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. From 241c20721824a5fc7c5cd6829fbb64104a33cce1 Mon Sep 17 00:00:00 2001 From: David Blodgett Date: Sat, 25 Aug 2018 10:58:19 -0500 Subject: [PATCH 8/8] typos --- .github/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ae7ef606..8e6e5714 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -14,7 +14,7 @@ The CF community takes great pride in respectful and collegial discourse. Any di ## General Guidelines 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 tha led to a given agreed proposal. +This is so it is easy to trace the discussion that led to a given agreed proposal. 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. @@ -50,4 +50,4 @@ Final review should take place in the pull request and the issue closed when the 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 their is a rendered "rich-diff" view of a pull request that can be helpful for review of large contributions. +Note that there is a rendered "rich-diff" view of a pull request that can be helpful for review of large contributions.