Add CONTRIBUTING.md

[erget]

Point of order: I've updated this summary to capture discussion strewn throughout comments below and hidden those comments as I felt relevant. They're still there but they clutter less visually now that they're only shown in minimised form. Unresolved ones are left standing.

@JonathanGregory @davidhassell @ethanrd this is probably of interest to you.

This issue is sharded off of #102. I have moved the relevant commit via cherry-pick and rebased the original PR in order to keep things focused. The goal is to add CONTRIBUTING.md to this repository, which is the source for the CF website. It is implemented by #121.

I've tried to capture the relevant outstanding discussion on the topic of CONTRIBUTING.md from #102 to here. Of course, this is abridged now and I'm adding my own opinions, which is why I've pinged you for transparency. Based on the discussion from #102 (comment) ff. I plan to add the following labels to round out the associated PR:

• Governance: requiring oversight from the governance pannel
• Update/defect: to correct mistakes or update decisions, to be merged by a member of the Committees or Governance Panel as they correct / clarify decisions they've already made
• Enhancement: improving website UX, oversight from IMS team or any Committee or Panel member
• GitHub problem: Correct technical problem with website build, etc.
• Typo: Correct a trivial mistake, oversight from anyone with merge rights

Changes from that proposed by @JonathanGregory (let me know what you think about this please):

• I think we can live without a "duplicate" label and am not proposing to create one
• I'm also proposing foregoing the 3-week rule for the website and instead only requiring oversight of the people listed next to each label so that we're able to modify the website faster if needed. IMO the 3-week rule makes sense for documentation like the Conventions, but the website has the intent of being an index and providing up-to-date information at all times, and in cases like that of the workshop week before last it was essential to be able to make frequent updates without overhead.

The gist of it is:

• CONTRIBUTING.md basically tells a contributor to use the appropriate issue type
• Each issue tells you what approval is necessary for merging when the issue is created
• I have not applied a waiting period to any merges, as I think it is good to be able to change the website rapidly if we need to
• Approvals are required from a single member of the bodies described above per issue type, with the exception of governance-related issues - for that, 2 approvals are needed (because this should be done very carefully!)

Note that I also haven't listed the GitHub handles of the members anywhere. I think it might make sense to use automatic assignment to facilitate finding moderators but this is an idea that should be pursued in a separate issue as noted back in #102.

[JonathanGregory]

Dear Daniel @erget

Regarding update, I feel that self-approval isn't an effective review. You need a different person to check for mistakes or misunderstandings. I think it would be logical to say

Updates to the website should reflect decisions that have already been made by the Governance Panel or the Conventions or Standard Names Committees. They must be approved by a member of the Committee which made the decision. They can be merged immediately after approval.

Regarding enhancement, I wrote, "they do need a waiting period for comments, to allow people to have time to think or to return from holidays, and it might as well be three weeks with no unsatisfied comment, as for conventions enhancements. I think approval by one person is OK ... provided you add that the proposer cannot give approval." You said this was fine by you, but I don't think you implemented those bits.

Best wishes

Jonathan

[erget]

Hi @JonathanGregory ,

Thanks for those comments! I am finally getting back to this issue now. To keep the conversation focused I hid all of the comments that were made above and that had resulted in agreement; I'm keeping your previous one unhidden and responding to it here.

There are 2 outstanding issues as far as I can tell:

Reviews of updates

Regarding update, I feel that self-approval isn't an effective review. You need a different person to check for mistakes or misunderstandings. I think it would be logical to say

Updates to the website should reflect decisions that have already been made by the Governance Panel or the Conventions or Standard Names Committees. They must be approved by a member of the Committee which made the decision. They can be merged immediately after approval.

I'm not sure where we disagree here. The text currently reads

Updates to the website must be approved by a member of the Conventions Committee and Standard Names Committee, the Governance Panel, or someone to whom they have delegated this responsibility.
Updates should reflect decisions that have already been made by the Governance Panel or one of the Committees.
They can be merged immediately after approval.
Furthermore, if they are proposed by someone who has the authority to merge such an update, that person can self-approve the update.

So self-approval is only possible in the case that the person making the update is "a member of the Conventions Committee and Standard Names Committee, the Governance Panel, or someone to whom they have delegated this responsibility" of making the update. This person will have been carefully chosen and the body who delegates the task of making the update will only choose them if they are sure that the person in question will do everything in their power to ensure that the all necessary checks have been done before publishing something.

The reason I have worded things that way is that I believe that this is flexible - i.e. it only allows certain people to make certain changes, as delegation is limited to a specific scope. As an example, the organising committee of the annual workshop might use this authority to make updates within minutes in order to ensure that the workshop runs smoothly. After the workshop is closed out, the authority to make these updates expires. And I don't believe that there is a real danger that people will make updates unilaterally - updates can only be made if they have already been agreed with everybody who needs consulting. Asking somebody else to proofread those updates only adds an additional layer of approval, without generating benefit.

So, in this case, I think we're working with people whom we can trust, and making the process too onerous will only lead to it not being followed. Note that we currently have no CONTRIBUTING.md at all concerning the website and therefore no guidelines to refer to, and nonetheless I'm still discussing this until we reach consensus, rather than making the updates on my own. I believe that we can expect this behaviour from everyone to whom we've granted write access to the repository.

So I've spent all this time arguing a point that we might already be agreed on but I think it's worth it being extra clear here. Do you see this differently?

Comment period for enhancements

Regarding enhancement, I wrote, "they do need a waiting period for comments, to allow people to have time to think or to return from holidays, and it might as well be three weeks with no unsatisfied comment, as for conventions enhancements. I think approval by one person is OK ... provided you add that the proposer cannot give approval." You said this was fine by you, but I don't think you implemented those bits.

I'm sorry about this! It slipped past me but has now been implemented in 56f06a4.

What do you think?

Cheers,
Daniel

[JonathanGregory]

Dear Daniel @erget

Thanks for returning to this.

Regarding enhancement, I believe we should note that the proposer cannot approve the proposal.

Regarding update, I'm not concerned about abuse of the rules. I trust the people who might make updates. My concern is about mistakes. I believe it is a common procedure to seek review from someone else before updating a public document, and I don't see why it should introduce a big delay, since there are plenty of people who could do the review and approve the update. It may even save time overall by preventing mistakes which would have to be rectified. If my view on this point is out of line with the general view, I'll accept the majority decision.

Did we decide to have labels for each of these categories of issue? If so that could be mentioned in CONTRIBUTING. It's useful because it indicates which rules will apply.

Best wishes

Jonathan

[davidhassell]

Hi @erget and @JonathanGregory

Thanks for working on this.

In CONTIBUTING.md there is the line "Details are noted in the relevant issue template." - could you you expand on what this means? Is it just the details of which bodies are required to give approval? If so I don't think this line adds much to the previous few lines. If not, ...

Regarding update, I'm not sure that the possibility of a limited scope is that clear in the text, and I think that outside of such special events, I agree that approval should be sought. How about replacing the last line ("Furthermore ...") with "To more easily allow multiple updates relating to a particular topic (such as recording the minutes of the annual meeting), a member of the governance committee may temporarily nominate people to self-approve updates."?

Thanks,
David

[erget]

Hi @JonathanGregory, @davidhassell,

Addressing this:

Regarding enhancement, I believe we should note that the proposer cannot approve the proposal.

Done in a3af3a1.

Regarding update, I'm not concerned about abuse of the rules. I trust the people who might make updates. My concern is about mistakes. I believe it is a common procedure to seek review from someone else before updating a public document, and I don't see why it should introduce a big delay, since there are plenty of people who could do the review and approve the update. It may even save time overall by preventing mistakes which would have to be rectified. If my view on this point is out of line with the general view, I'll accept the majority decision.

I now understand your concern better, and @davidhassell has also proposed some improvements to the wording, so I'll address that below.

Did we decide to have labels for each of these categories of issue? If so that could be mentioned in CONTRIBUTING. It's useful because it indicates which rules will apply.

Yes, labels are applied automatically depending on the template chosen. I've explained this in 3d92bcd.

Addressing this:

In CONTIBUTING.md there is the line "Details are noted in the relevant issue template." - could you you expand on what this means? Is it just the details of which bodies are required to give approval? If so I don't think this line adds much to the previous few lines. If not, ...

I agree, that is what I meant and I think that 3d92bcd now explains this. I've removed the line in 0e0400f.

Regarding update, I'm not sure that the possibility of a limited scope is that clear in the text, and I think that outside of such special events, I agree that approval should be sought. How about replacing the last line ("Furthermore ...") with "To more easily allow multiple updates relating to a particular topic (such as recording the minutes of the annual meeting), a member of the governance committee may temporarily nominate people to self-approve updates."?

I agree with you both here. What do you think about the text I've proposed in 52180c1?

As always thanks for your input and a pleasant weekend unto all,
Daniel

[JonathanGregory]

Dear Daniel @erget
That looks fine to me now, thanks, except for the unnecessary "both" in "A proposer cannot both approve their own enhancement." Happy weekend
Jonathan

[erget]

Hi @JonathanGregory
Corrected in fc6303d. Good eye.

I propose handling this as an enhancement, i.e. I'm the proposer, and you as a member of the Governance Panel have now approved the proposed enhancement. This means that I'll merge this proposal after 3 weeks on 2020-11-16 barring any objections.

A happy weekend to you as well,
Daniel

[davidhassell]

Hi @erget - looks good to me, thanks.
Happy weekends all round,
David

[JonathanGregory]

Yes, that is fine. Thanks.