Procedural items

[erget]

This issue supersedes #172 and is implemented by #256.

The larger changes to the CF governance process discussed at length in #172 have been pursued in a separate activity. I would like to capture the procedural changes affecting how we use GitHub that were discussed (and, I believe, mostly agreed) here.

People who have expressed interest in the original issue:
@castelao @davidhassell @JonathanGregory @ethanrd @dblodgett-usgs @martinjuckes @DocOtak @kevin-obrien @marqh @zklaus

People who expressed explicit support in their comments on that issue:
@DocOtak @ngalbraith

Summary of changes in PR

Implementation in GitHub / procedural stuff

• **Do we use semver?**Yes, but we shouldn't get hung up on it. Now we say we're "inspired by semver".
• Checklist before merges? Yes. Edit history.adoc, update authors, etc. in PR template.
• How do we ensure that issues are dealt with in a timely fashion? Attach the release frequency to the meeting so that changes actually come in. Note explicitly that pre-annual meeting 3 week feature freeze is a feature freeze. Tag stuff for milestones, that's motivating, and it summarises upcoming changes.
• Who sets tags and when? Secretary, 6 weeks after annual meeting.
• When do we delete branches? Whenever we want as long as they're not protected. Normally after merging.

Questions that in the #172 were considered interesting but are not addressed here:

• Who owns docs from the website?
• Align descriptive language in CONTRIBUTING.md with GH roles?

[JonathanGregory]

Thanks for summarising the issue(s), @erget. The constitutional aspect is now in cf-convention/cf-convention.github.io#88. We will have to wait for the website-building process to be fixed before proceeding further. I put that issue in the cf-convention.github.io repository, rather than in this one, because it's not specifically about the conventions, but about the governance of CF as a whole, and the governance documents belong in the website. On the other hand, this issue belongs here because it's specific to the management of the conventions document.

[erget]

Thanks @JonathanGregory for providing some context.

This PR is related solely to how we do things on GitHub. Currently we have no rules on how to accept such changes (I'd like to address that soon when taking a closer look at the "Rules" document on the website) and thus I propose that we treat it in the same way as we treat proposed changes to the Conventions themselves.

The proposed changes are summarised as follows:

• Refer to issue templates rather than describing them in CONTRIBUTING.md. This makes us more flexible.
• Offer help to those who are not familiar with GitHub if they have difficulties submitting proposals
• Note that the 3-week rule implicitly includes a "feature freeze" that submitters should be aware of
• Copyedit
• Augment pull request template to include procedures for making it easier to mint a release after any given merge
• Link to associated pull request in issue templates

Would anybody be willing to moderate the discussion surrounding these changes? I consider them to be of a minor nature.

[JonathanGregory]

This looks good to me and I support the changes. Thanks. I will also moderate the discussion, if there is any, unless someone who is more skilled with GitHub (i.e. practically anyone else) is willing to do it. These rules belong within the remit of the conventions committee, so I agree it's logical to apply the conventions rules to changing these rules, which means three weeks start today for disagreements and suggestions to be noted.

[JonathanGregory]

Looking at it again, I wonder whether what is happening to the text about single- and multiple-section changes in CONTRIBUTING.md - is it somewhere else? Thanks.

[erget]

Hi @JonathanGregory I considered it an enhancement to the guidelines to combine them into one and the same category - "Enhancement" - and describe that in the issue template. In my opinion it's better to simply say in CONTRIBUTING something along the lines of "Use an issue template that matches what you want to do" and then describe what to do in the issue itself.

Furthermore I think it makes more sense to differentiate the approach by the nature of the change proposed, rather than simply how many sections would be changed - either way there may be the necessity for changes to multiple sections that the original author may not notice at first blush, and so a full review should take place IMHO regardless of whether the change text is small or large.

What do you think?

[JonathanGregory]

Dear @erget

Yes, I agree with

It's better to simply say in CONTRIBUTING something along the lines of "Use an issue template that matches what you want to do" and then describe what to do in the issue itself

and thanks for implementing that approach. In order to follow the approach, the contributor needs guidance to decide which template to use - whether it's a defect, typo fix, github issue or enhancement. These categories should be related to the two categories in the rules documents (making changes, and correction of errors).

I also agree that single- and multiple-paragraph changes are the same kind of enhancement and the guidance doesn't have to be separated like that. However, some of this advice is useful, and it would be a pity to lose it:

• 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.
• 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.

You may have put some of this in general guidance. If not, could the reminder belong in the template for an enhancement? Similarly, we currently have this guidance for a typo issue, which could go in its template:

• 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.

Thanks for considering this.

Jonathan

[erget]

Hi Jonathan,

I agree that this guidance is useful and think it's best to put it in the appropriate issue templates.

• 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.

I've included both of these in the "Defect", template.

• If the modification is non-controversial, a pull request could be opened simultaneously.

I've included this in the "Enhancement".

• Discussion of the proposal should take place in one issue.

This is noted in CONTRIBUTING.

• Final review should take place in the pull request and the issue closed when the pull request is merged.

I believe CONTRIBUTING also sufficiently covers this in its final section.

• 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.

I would consider this implicit based on CONTRIBUTING lines 14-18:

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.

What do you think?

Cheers,
Daniel

[JonathanGregory]

I think that's fine, Daniel. Thanks for your thoroughness. Jonathan

[davidhassell]

Hi Daniel, this is all very good - thanks for putting it together. I support all of the changes/enhancements here, but I have one question: In .github/PULL_REQUEST_TEMPLATE.md you have:

For maintainers

After the merge remember to delete the source branch

I'm not sure what this means, as the source branch will typically not belong to a maintainer, rather a member of the CF community. Perhaps I've misunderstood the term "Maintainer"? (As an aside, I wonder why is it good practice to delete source branches after they've been merged? I'm sure it is, just curious.)

David

[erget]

Hi @davidhassell as in many things git-related, I don't feel that this is a best practice - it's more of a preference. I prefer a repository that feels tidy, and as branches are identifiers just like tags or commit IDs, having fewer of them makes for a more pristine autocomplete.

Under "Maintainer" I understand somebody who can perform a merge on the canonical repository - so probably the IM team in our case. My interpretation would be that if the source branch is on another repository, which will more often be the case, the proposer would do as they like with their branches.

[mwengren]

@erget and others, I have some ideas for how to improve handling contributions/associated processes and a few GitHub recommendations. Hopefully this is the right place to comment vs. opening a new issue.

This is from the perspective of a relative newcomer interested in making minor contributions to the convention docs. If similar suggestions have been made already somewhere I missed, please disregard.

Mostly, these have to do with the current version of the Rules for Contributions from the website and also CONTRIBUTING.md.

Suggestions:

• link directly from Rules page to this repo and/or discuss repo to make it obvious where to file an issue/proposal under which circumstances - cf-conventions repo for proposed changes to the conventions and discuss for standard names and other CF matters (as it is now the doc mentions GitHub and GitHub issues but isn't specific as to the repo and doesn't provide any links outside of the page itself, which is not very helpful). It sounds like this may be in the works here in part, so ignore if so. This would make the Rules page much more useful!

• update the README in both repos with a clear link back to the Rules page and/or CONTRIBUTING.md page(s). I didn't find any links to CONTRIBUTING.md outside of perhaps mentions in old issues, unless I missed them, and I think expecting new contributors (esp. those new to GitHub) to read that file is not reasonable. Both resources should be called out clearly in the cf-conventions README. The discuss README does this in part but it could also link back to the Rules page. The README in the cf-convetions repo is also mostly technical and could use more repo usage/intent information to make it more informative.

• add some means (such as an '@' team alias in GitHub) that allows contributors to directly communicate with the CF Governance Committee or some other appropriate governance team about dormant issues, and advertise this clearly in the Rules page, READMEs, CONTRIBUTING.md or elsewhere. At the moment, it's not clear to me as a contributor whom I should try to engage with about the status of my PR and/or issue. If an issue is created by someone and doesn't receive a moderator or discussion lags, what should the author do? It's not clear IMO. It would be helpful to describe where they can go for help or how to flag their issue for followup, and it might make the contribution process a better experience to newcomers and help grow the community. Teams could be created from the current membership in the groups from the Governance page as a suggestion.

[JonathanGregory]

Dear Micah @mwengren
I think this issue should be confined to CONTRIBUTING.md and the other GitHub files outlined at the start, but I believe Daniel already has in mind to make Rules point to CONTRIBUTING.md as a separate issue. Your third point is good as well, but probably the answer to this has first to be decided before it can be advertised i.e. who is actually responsible. This depends both on the nature of the issue (technical GitHub/website vs content) and which repo it is (governance on the website, conventions, or standard names in discuss). I'd say that is an issue to be raised separately from this one.
Jonathan

[mwengren]

@JonathanGregory thanks for your input. Understand about the scope. I will create a new issue to handle my third point regarding communication/feedback pathways for contributors. EDIT: further GitHub research indicates this isn't possible, @ mentions of teams can only be by members of the organization the team exists in, so I'll withdraw this. Might be a nice feature to use if GitHub supports public teams someday.

Regarding the other two suggestions I made, if additional linkages between the Rules page and CONTRIBUTING.md are in the works, that will help.

I would still suggest expanding the scope here to include some edits to README.md to address the process of making contributions, whether they be links back to the Rules page or to CONTRIBUTING.md. My recommendation would be just to add a header and paragraph titled 'Making Contributions to the CF Conventions' or something like that.

As is, the README still seems to be a little lacking as a front page about what the repo is and how users should interact with it. It is the first place everyone will look, after all.

[JonathanGregory]

@mwengren, thank you for your comments and your further research on GitHub teams. Nonetheless your point is a good one. We need to define who is responsible for making sure issues proceed to a conclusion. This is a governance issue. I've made a note of it (on my own to-do list).

@erget, would you consider Micah's suggestion to add text to README.md that points to CONTRIBUTING.md and the rules? That makes sense to me, since README could be a natural place to look if you come to the repository first, rather than the website.

[erget]

@mwengren @JonathanGregory thank you for your input. I've added some updates to README.md. I've proposed (surgical) changes to README.md accordingly (see #256 for details).

[JonathanGregory]

Thank you, @erget. I think that addresses @mwengren's point. Presuming he agrees with that, there are no outstanding matters. This enhancement (procedural items especially CONTRIBUTING.md) has sufficient support according to the rules and will be agreed on 23rd June if no further objections are raised.

[mwengren]

Looks good to me, thanks. I would still advocate for some clear process for contributors, in either issues or PRs, to ping the Governance Committee or other group of GitHub stewards about status of contributions, but as I said earlier, GitHub Teams don't currently support this, for better or worse.

Perhaps if they did someday or if @JonathanGregory or anyone else has good suggestions, this can be added in the Rules later on.

[erget]

@mwengren I agree that this would be good! I also however think that this is separate from the issue at hand. Do you plan on attending the upcoming Community Workshop? There will be a session where we discuss GitHub procedures on the first day and I think your input here would be very valuable to help us continue to improve our processes.

[JonathanGregory]

Michah @mwengren, perhaps you could comment on cf-convention/cf-convention.github.io#102, which is another issue from Daniel @erget. In that issue, I have proposed assigning particular labels, which would imply who was responsible for various classes of issue. I think that would help to solve the problem you identified in this issue. At least you would know who[m] to ping.

This issue (procedural items) is still on course to be agreed next Tuesday 23rd.

[JonathanGregory]

This issue has been approved, according to the rules, and I have merged the pull request. Thank you @erget for the proposal and to others for comments.