Workflow?

[ChrisBarker-NOAA]

In #130, we discussed and developed a CONTRIBUTING.md doc.

But that Doc was aimed at contributors -- and a number of issues came up in the discussion about the workflow that weren't decided, and also not about things we should be putting in a doc designed for outside contributors. But I don't hink we ever did nail down those issues, or at least I dont see it documented anywhere.

So I also propose we start a new discussion and document for the workflow: how we are going to use branches, etc.

I also propose that we create the concept of an "CF enhancement proposal" (CEP) where we document the pros and cons and final decision about a significant CF change. The Workflow doc could be the first of these.

This idea was inspired by the long discussion in #148, and by other projects use of Enhancement proposals, at least in the Python community:

https://www.python.org/dev/peps/

https://www.numpy.org/neps/index.html

https://matplotlib.org/devel/MEP/index.html

The idea is that when there is a significant (and perhaps contentious) addition or change to CF, our primary goal is an update to the convention doc. The previous discussion in #130 captured a fair bit about that process. But, in fact, we also need:

• a better way to manage the discussion -- one central pace where the current proposal and pros and cons, etc are written out.

• a way to capture that discussion for the future, so that when folks re-visit it in the future, they will see not just the convention, but why it is the way it is.

So I propose that we create a new section in the docs in this repo for enhancement proposals -- we can start with an index and draft of a gitHub workflow doc. (and maybe one for #148, too.

[martinjuckes]

Hi @ChrisBarker-NOAA , one difficulty with the github discussion at #148 is that, because it is a lengthy discussion, it is becoming hard to track the latest favoured formulation of the proposal. In the trac system, as I understand it, the proposal is described at the top of the page and updated by the proposer as the discussion evolves. This means that you can usually get a good idea of the state of the discussion by looking at the top of the page and the last few comments. We could do something similar in github is we agreed that the first post in each issue should be a proposal and be updated by the proposer as he accepts suggestions in the discussion thread, and the proposer's explanations of his initial ideas should start in the 2nd post.

[dblodgett-usgs]

@ChrisBarker-NOAA I think the issue with #148 may be that the rules are not being followed. I just commented on that issue to see if we can get a moderator who can start to summarize the current state of the proposal.

I think it would be good practice to make updates to the original body of the proposal as the discussion evolves, but I don't think we should make that call without trying it out. Maybe someone would want to moderate that issue and see how it works? GitHub does track the history of changes to comments on issues (main description counts as a comment).

I also just got the issue template set up properly. You can see it here: https://github.com/cf-convention/cf-conventions/blob/master/.github/ISSUE_TEMPLATE/proposed-change-request.md and it is presented to anyone opening a new issue on this repository now. It wasn't set up right until now so #148 didn't get all the details that would have been needed to be in accordance with the cf rules.

Regarding your proposal,

1. I think that the "enhancement" tag and the rule to have a moderator is meant to satisfy the need you are describing regarding contentious discussion around cf enhancements -- I would prefer to let the existing rules be tried out for a while before making changes.

2. I don't disagree that we should think about how to use branching if at all and make sure we are using the github-flow appropriately. However, given that we are at such an early phase of utilizing the system, I would prefer to have a few proposals attempt to interpret and follow the contributing guidelines as they stand and see where there are gaps that need to be filled rather than getting (potentially overly) prescriptive in the near term.

My preference would be to close this issue and keep an eye on these concerns as we move forward.

Best,

• Dave

[ChrisBarker-NOAA]

"""
I think that the "enhancement" tag and the rule to have a moderator is meant to satisfy the need you are describing regarding contentious discussion around cf enhancements -- I would prefer to let the existing rules be tried out for a while before making changes.
"""

See See: #151 for an idea about slight modification of those rules.

But they key suggestion here is an addition -- that there be a "working document" that summarizes the proposal AND the discussion, and that that "working document" become a permanent fixture so that folks can see why decisions where made the way they were.

This wouldn't really change anything in teh current rules, just make it clear where the "summary" goes, and what form is should take.

[dblodgett-usgs]

This issue has been superseded by #172. I'm going to close it in favor of taking up a more focused debate.