erget commented 2 years ago

Some discussion with @JonathanGregory on minting 1.10 brought us to this issue. I've volunteered to look at this at the upcoming workshop and won't fill this with too much details, but here's some context so I'll remember what it's about:

Do you think that rules.md is the right place to document these? It sounds to me more like modalities of working with GitHub, in which case CONTRIBUTING.md might be a better home for these guidelines.

...These two documents [rules.md and CONTRIBUTING.md] overlap somewhat in purpose. Could we merge them? In order to do that, we would have to put the rules for making enhancements and rules for correcting defects into the same file, along with the contents of CONTRIBUTING.

JonathanGregory commented 2 weeks ago

Background

Daniel @erget began this issue two years ago. I'm reviving it now in an attempt to bring it to a conclusion, following discussions in the last two CF committee meetings. As Daniel wrote above, he and I had discussed merging CONTRIBUTING in this (conventions) repo and rules in the website repo, because both of them are about how to change the conventions. Since moderation of proposals and use of labels are both aspects of the process to be documented, the discussion in the open issues #151 on moderation of proposals and #440 on labels will inform this issue as well.

I believe that this issue should supersede website issue #102 on "refactoring the rules". Issue 102 is in the website repo because the rules for changing the conventions were originally part of the governance arrangements. These days, the conventions are only one of three things which we change (conventions, vocabulary and website/governance), each with its own repo. Therefore I think it's logical to discuss those rules in this repo and issue. Daniel drafted some changes in his website PR #103. That PR was merged by accident, which Daniel undid with some git enchantment, so those changes have not been implemented. I propose that we should continue with the discussion of Daniel's draft text in this issue, as well as the subsequent additions in #102 that aren't in his PR #103.

Website issue #102 includes a diagram of the process as well. For simplicity, I propose that we should not talk about the diagram in this issue, because the later website issue #217 is a good place to do that.

As you see, part of my aim with this issue is to tidy up and provide an overview of this set of unfinished issues. To summarise:

369 (this issue). Merge `CONTRIBUTING` and `Rules`. If we agree to do that, we can continue in this issue (or start a new one), on the text of that unified document. The text will be informed by the following five items:

website issue #102 and associated PR on clarifying the rules.

151 on moderation of proposals for conventions changes.

328 on the rules for deprecating content

440 on labels in the conventions repository

Discussion #349, which I have just begun with a couple of questions about the change process.

325 on updating the checklist in the conventions PR template. That must be consistent with the description of the change process.

website issue #217 on a diagram of the change process.

Proposal

I propose that we

Delete the links to rules for making changes to the CF Conventions and rules for correcting errors in the CF documents from the governance page, leaving just the links to the CF constitution and the 2006 white paper which preceded it.
Delete rules.html and errors.html from the website repo.
Revise the CONTRIBUTING document by combining the two sets of rules, including the short revision history of the rules which currently appears on the governance page, with the current text of CONTRIBUTING.
Make a link to the new document on the conventions page. This would be parallel to the link to the instructions for proposing changes to vocabulary which appears on the vocabularies page.
Make links to both the new CONTRIBUTING and the vocabulary rules on the discussion page, and as quick links from the CF home page.

This means that, whether you look at the website or the repo, you will always be directed to the same CONTRIBUTING file for instructions on proposing changes to the conventions, which will be in this (conventions) repo, the relevant one. (Among others, @mwengren has argued for arrangements like this.)

What are your opinions?

larsbarring commented 2 weeks ago

Excellent, I agree that this is a good way forward. Thanks for initiating this! In particular I like unifying the rules in the web pages and the github repos.

cf-convention / cf-conventions

Merge `CONTRIBUTING` and `rules` #369

Background

369 (this issue). Merge `CONTRIBUTING` and `Rules`. If we agree to do that, we can continue in this issue (or start a new one), on the text of that unified document. The text will be informed by the following five items:

151 on moderation of proposals for conventions changes.

328 on the rules for deprecating content

440 on labels in the conventions repository

325 on updating the checklist in the conventions PR template. That must be consistent with the description of the change process.

Proposal

cf-convention / cf-conventions

Merge `CONTRIBUTING` and `rules` #369

Background

369 (this issue). Merge CONTRIBUTING and Rules. If we agree to do that, we can continue in this issue (or start a new one), on the text of that unified document. The text will be informed by the following five items:

151 on moderation of proposals for conventions changes.

328 on the rules for deprecating content

440 on labels in the conventions repository

325 on updating the checklist in the conventions PR template. That must be consistent with the description of the change process.

Proposal

369 (this issue). Merge `CONTRIBUTING` and `Rules`. If we agree to do that, we can continue in this issue (or start a new one), on the text of that unified document. The text will be informed by the following five items: