Dear All, As a next step toward the CF community using GitHub tools to discuss and refine the specification, we need contribution guidelines for this repository. For background and interesting reading, this issue follows #106 and #112 and is more or less governed by the CF community conversation in [Trac ticket 160.](https://cf-trac.llnl.gov/trac/ticket/160) The consensus in that ticket has lead us here.
The outcome of this issue should be an initial [CONTRIBUTING.md](https://help.github.com/articles/setting-guidelines-for-repository-contributors/) and modifications to the [pull request template](https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/) per the requirements described below. We should use this issue to discuss and evolve these requirements then I will submit a pull request with content according to the consensus. __Please review the use case and guidelines below. I will begin work on the CONTRIBUTIONS.md document in a few weeks based on the consensus we have sometime in May.__ __Top level use case:__ As a contributor to the CF specification, I need to know the rules and instructions for *how* GitHub should be used, so I know the right way to submit my suggested addition or changes. Guidelines: (derived from correspondence between @JonathanGregory, @dblodgett-usgs and others.) - Some simple instructions are needed so that anyone who does not use GitHub for any other purpose can follow them successfully. GitHub can be used in a variety of ways and we need clear guidance regarding how the CF community wants to use the tools. - 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, in the same way that we continue discussion under one trac ticket for a given proposal. This is so that it's easy to trace the discussion which led to a given agreed proposal. - It has to be easy to see what is being proposed in the context of the discussion. In Trac we say: I propose to do X, Y and Z, with the result that the text will read as follows in Section N _blah blah blah_ and as follows in Section M _rhubarb rhubarb_ Thus it's possible to see the reasoning and the effect on all the sections, all gathered together, and understand it. In GitHub, there is no relation between the argument and the modified text, unless the argument is put as annotations in the text, but in that case the bits of argument are all over the place. **Somehow you need to get an overview of the changes all together.** - In the case of short changes, I think that excerpting the existing spec in a GitHub issue with suggested new content in the body of a GitHub issue would work well. Once agreed to in the issue, the change can be implemented and submitted as a pull request referencing the issue. - In the case of long changes (i.e. where the body of an issue isn't long enough or changes are in many parts of the specification) the significant addition would likely come in the form of added content in a persons fork of the specification. They might register the contribution and their intent with the community in an issue for general feedback, work on the content in their fork, then submit a pull request when the consensus is that it's ready to be submitted. If the community finds utility in line by line comments in a pull request, that's great, but I don't think we need to force that issue. Line by line comments are really great for code. They can be a great for text, but they can also be very cumbersome. - Regarding "long changes" Maybe we could recommend that the discussion *begins* with proposed changes in the issue itself, but if the proposal involves changes in many places in the document, so it's awkward to spell them all out, it would be better to do this in a fork, but it's not worth doing that until it seems that the proposal is likely to be agreed. Moreover, if it does look like a proposal is going to be agreed, or when it has been, it would definitely be useful for the proposer to fork and update the documents, because otherwise someone else will have to do it later (as for trac tickets). So we should encourage that. However, to enable it, we need really simple instructions about how to do it! - Regarding a hybrid approach of GitHub and trac, it seems that part of that ship sailed when we started managing the text in GitHub. That said, I see no reason not to allow changes to be vetted in trac until we have enough success using GitHub to track modifications that the community is ready to leave trac behind. We are already referencing trac from GitHub. Opening the option to not use Trac seams like the next step to me. Best, Dave Blodgett -- You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub: https://github.com/cf-convention/cf-conventions/issues/130
