search

cf-convention / cf-conventions

AsciiDoc Source
http://cfconventions.org/cf-conventions/cf-conventions
Creative Commons Zero v1.0 Universal
85 stars 45 forks source link

Proposal on enhancing governance process #172

Closed erget closed 4 years ago

erget commented 5 years ago

Title: Enhancing governance process Moderator: @dblodgett-usgs Moderator Status Review [last updated: YY/MM/DD]: Brief comment on current status, update periodically Requirement Summary: The community has discussed at numerous occasions the possibility of improving the CF Governance Process. This discussion is aimed at producing an update that will benefit the community. Technical Proposal Summary: The proposal also contains minor changes to GitHub metafiles that would aid contributors. Benefits: The beneficiaries of this proposal are those interested in contributing to the Conventions and users of the Conventions who need changes implemented or need to understand how these are implemented. Status Quo: The proposed text is contained in #173 and is based on a draft that was circulated to the CF Governance Panel and the community at large before the 2019 annual meeting. It has been refined subsequently based on inputs from the community at the meeting and in telephone conferences that took place thereafter. Detailed Proposal: The proposal is described fully in the summary below. The PR itself is structured as a set of "larger questions" in bold. If these have been answered, they are checked off and an answer is provided summarising the stance the proposed text takes on the relevant question. This is followed by a link to the commit within the PR that implements that logic. Therefore the text as a whole can be read in its current state by looking at the PR's "files changed" view or by looking at the individual commits. As the CF Conventions have never had a Constitution as such, but only a section of a white paper on the Conventions describing the "constitution" (lower case) of the various committees, the proposed document is new. Although it is based heavily off the original document, it has a different intent and the author @erget is not of the opinion that it makes sense to attempt to implement these changes as a revision of that document; this document serves a purpose that no previous one had and will also have a different level of visibility.

Summary

This is to open discussion on enhancing the governance process surrounding the CF Conventions. It is based on this original proposal and supersedes that discussion. It is related to #150, #151, #194 and maybe others.

The proposal is being discussed in detail at the netCDF-CF Workshop taking place at ESIP 2019. I hope to use the time where so many members of the community are together in order to prioritize the work, collect feedback and put together a team with the mandate to prepare a full proposal to revise the governance process and propose a straightforward implementation in GitHub.

The corresponding pull request is not mature enough for adoption; it is simply there to make the discussion easier to trace at this time.

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

People who have expressed support in their comments below: @DocOtak @ngalbraith

Their contributions have led to improvements in the proposal; nonetheless the changes proposed in this issue's corresponding PR do not necessarily reflect their opinion.

This top comment will be used for presenting a summary so we don't have to dig through the history to understand stuff.

Open points identified for refinement at workshop

Governance (finalised at e94a72c)

CF Committee, Standard Name Committee, Governance Panel are all considered "bodies" in this context.

Implementation in GitHub / procedural stuff

Updated after telco on 2019-09-02 with @erget @DocOtak and after telco on 2019-09-10 with @zklaus @dblodgett-usgs @erget

To be tackled separately:

DocOtak commented 5 years ago

Here is a link to the Semantic Versioning 2.0.0 specification: https://semver.org/spec/v2.0.0.html

I support the adoption of this as policy for versioning the CF document. Perhaps there should be a section in the pull request/issue template to indicate which version part would need to be incremented.

martinjuckes commented 5 years ago

Hi @erget , I can see that some decisions appear to have been taken and items ticked off above, but I can't see where the discussion is happening or how the decisions are reached. Are these all points which were decided at the annual meeting?

erget commented 5 years ago

HI @martinjuckes no, those were open issues that were discussed at the meeting and that need to be addressed clearly in the proposal. I have collected as close to a concensus as I could while I was there, but we weren't able to reach a conclusion on every one of them. I am closing them piece by piece as I take a concrete stance on them in the proposal itself, but of course the proposal in its final form will still need to be discussed by the community and deliberated by the Governance Panel. My attempt currently is to create a proposal which makes it easier for people to do this in a concrete fashion.

erget commented 5 years ago

This also needs to be coordinated with #194 .

erget commented 5 years ago

@DocOtak I think this is about as far as I can take the proposal for the moment. You'd mentioned that you might have some time to work on e.g. CONTRIBUTING.md to align the language with GitHub-standard lingo. Do you want to tackle that before you go into Catch Me If You Can mode?

erget commented 5 years ago

Dear colleagues, and most particularly those who have expressed interest in changes to the CF governance processes (@castelao @davidhassell @JonathanGregory @ethanrd @dblodgett-usgs @martinjuckes @DocOtak @kevin-obrien @marqh @zklaus),

I've finalised the draft to update the governance process of CF. The major questions that the update tries to address are summarised in the top comment of this issue. Each question is in bold, followed by the conclusion that I have written into the proposal and a link to the specific commit where I have done that. This will make it easier to pick apart the text that I'm proposing, I hope. The full set of changes can be viewed in the pull request.

At this point there are still a few open questions concerning how to continue our work in GitHub, and I have left those in the summary, but if we agree on this set of changes I would leave them open here and address them in more focused, separate issues.

A telephone conference is planned for next Tuesday, at 2019-09-10T15:00Z to discuss GitHub related issues with the GitHub enthusiasts. If you're interested in joining please ping me and I'll send you the attendance details.

In the meantime I would be very interested to hear your input on this proposal and hope that we can move forward constructively and swiftly. My approach in the text has been to be opinionated but I am not married to these concepts so if you can improve these ideas, please do.

Best regards, Daniel

DocOtak commented 5 years ago

PR #195 looks ok to me, especially in the context of how people are used to doing things (legacy way?).

Re the issues vs pr closing, this is super useful: https://help.github.com/en/articles/closing-issues-using-keywords

It would require updates to the templates so people know to add them to their PR. Something like:

[ ] closes #172

When the PR is merged, github will close the referenced issue automatically and even put a little message of "closed in #somepr" see the bottom of https://github.com/pydata/xarray/issues/3056 for an example.

erget commented 5 years ago

@DocOtak agreed, I've added this to #173.

JonathanGregory commented 5 years ago

Dear Daniel

Thanks for your continuing useful work on this.

In the CONTRIBUTING.md, I think we ought to distinguish how one should proceed according to the labels attached. For labels of typo or style, it would be OK to use a pull request directly. It's very important that this route is only used for changes that definitely could not have any implication for the meaning of the CF standard document. For defects and enhancements, it is necessary to open an issue. A defect is something more than a spelling mistake; it is a proposal to alter the wording in order to clarify or correct the document. An issue is needed because sometimes it is debatable whether the proposed change is actually to correct a defect or whether it's a substantial change (i.e. an enhancement), depending on the interpretation you have of the existing text.

Concerning the constitution, as I have said before, we already have one of these, in the CF white paper. Certainly we can discuss changes that would improve it, but I think we ought to start from what we have. The existing constitution is in asciidoc form at http://www.met.rdg.ac.uk/~jonathan/CF_metadata/constitution_original.adoc and I also prepared a modified version at http://www.met.rdg.ac.uk/~jonathan/CF_metadata/constitution.adoc The latter version combines the two committees (as has been the case for a long time) and includes a couple of your proposed changes too. Rather than proposing an entire replacement document, could you take the existing constitution, and propose modifications? That would make it easier to focus on and discuss the changes you have in mind.

Best wishes

Jonathan

taylor13 commented 5 years ago

Dear all,

I would note that in addition to the ascii documents referred to by @JonathanGregory, there is the original CF white paper setting out governance and process at http://cfconventions.org/Data/cf-documents/cf-governance/cf2_whitepaper_final.html (also http://cfconventions.org/Data/cf-documents/cf-governance/cf2_whitepaper_final.pdf ) and additional rules for modifying the conventions linked from http://cfconventions.org/governance.html.

best regards, Karl

erget commented 5 years ago

Hi @JonathanGregory you're right of course, there had been so much discussion over such a long time and the text was in the making on multiple platforms, so that I simply forgot to follow that important part of the procedure. I am not in the office at the moment but will make sure to open an issue for the general discussion of this matter on Monday. It simply slipped my mind.

JonathanGregory commented 5 years ago

Just to clarify: the asciidoctor file which I created contains the text from Appendix 2 of the white paper that Karl refers to i.e. the constitution of the committees. Converting it was an exercise for me in adoc file, as well as trying to be useful for this debate. Cheers, J

JonathanGregory commented 5 years ago

I understand, Daniel - thanks very much. J

ngalbraith commented 5 years ago

The document above, Jonathan's modified version says that members of the committee

must retire after five years, but may be reappointed.

I'm not sure if we have a record of appointment dates, which makes it difficult to know if or when we have been or should be retired.

Other than that, it looks good to me.

erget commented 5 years ago

Hi all,

Thanks @ngalbraith for the input. I've noted you as one of the supporters in the issue's summary - please contradict me if that was not your intent.

@JonathanGregory , @taylor13 in my post above I naively assumed that I had, because I was in a hurry before going on leave, not provided the proper transparency to my proposal. I was pleased to find myself vindicated upon examining the issue - I'm simply so used to @JonathanGregory being correct that I had not checked ;)

So to clarify, I have indeed made an issue whose summary attempts to break down the gist of the proposal and describe the text I've submitted. Each point contains a pointer to a commit that attempted to address that specific point. The reason I've done this is that, as requested, I started from the original text and modified it granularly so that the history is transparent. Although this entails a large number of changes, this was the best way I found to avoid a "big bang" approach.

In the interest of brevity I won't repeat the summary here, but I hope that you will review it under the link I've provided and I believe that you at the very least will find it transparent enough so that if there are disagreements we can discuss them in a fairly isolated fashion.

I'll be grateful for any input - thanks for participating in this discussion.

Best regards, Daniel

JonathanGregory commented 5 years ago

Dear Daniel

Thanks for directing me to the pull request. I'll look at it again. As you mentioned (yesterday in person) I see that you have linked the pull request (173) in the first contribution to the issue. The lack of an automatic linkage between issues and pull requests (if I understand correctly) means that it's very good practice clearly to identify any relevant pull requests at the top of the issue. That's a good reason to keep the first contribution up to date. Have we mentioned in CONTRIBUTING.md that the issue should identify pull requests at the top? Even more useful is to say that they are pull requests in the text, I think, since this is not obvious from the in-text link (until you hover or click on it).

Best wishes

Jonathan

ethanrd commented 5 years ago

Hi @erget. Was there discussion about making the secretaries elected positions? They are currently, I believe, funded positions. (Perhaps @bnlawrence, @davidhassell , and/or @japamment could comment.)

Text about them being elected positions was added to constitution.adoc in committ 1ef2457. The text describing them as funded positions was removed in change 3e692f2.

ethanrd commented 5 years ago

@erget Just wondering if the consitution document should be in the web page repo rather than in the conventions document repo.

bnlawrence commented 5 years ago

@ethanrd Thanks for pinging me on this. I have made a comment on the relevant pull request (1ef2457), the gist of which is: I don't know how this would work by making them elected, so I am strongly against that change.

taylor13 commented 5 years ago

I wholly agree with @bnlawrence (see https://github.com/cf-convention/cf-conventions/issues/172#issuecomment-533989404 and https://github.com/cf-convention/cf-conventions/commit/1ef2457b9bc7ec35eb2b21a0afdd46e01e260b7b ) that electing secretaries won't work under present support mechanisms. I suppose we could consider electing secretaries if more than one person has an interest and has funding to do the job, but I think even in this case, we would want to consider appointing co-secretaries.

erget commented 5 years ago

Hi everybody,

First of all my thanks for the participation here - I'm very glad to see more eyes looking at the document and appreciate your feedback very much.

@ethanrd - I think it would make sense to have the document in the website repo, but perhaps we could agree first using this issue, as it's already open, and then move the finalised document into there once we're done. Would you agree to this approach?

@JonathanGregory - Your idea of making sure that an associated pull requests are clearly marked in issues is good, I've implemented this in the issue templates for which that might apply in 0bc9499.

@ethanrd @bnlawrence @taylor13 - You bring up some valid concerns about electing secretaries that have convinced me. I've changed the issue summary and reverted that bit in e612409.

What is the general feeling in the group at the moment considering the other aspects of the proposal, and the proposal as a whole with the removal of the secretary's election?

Best regards, Daniel

JonathanGregory commented 4 years ago

Dear Daniel

I think that the part of your proposal which deals with making modifications is in good shape. This part doesn't belong in the constitution.

I continue to find the constitution hard to deal with, because it's a completely different document from the one we currently have. Without wishing to seem reactionary or to frustrate your concerns, I'd like to revert to the present document, and discuss minimal amendments to achieve whatever is necessary. So I have started again from the asciidoc I compiled from the white paper of 2006, and have made some insertions and strikethrough to propose changes, at http://www.met.rdg.ac.uk/~jonathan/CF_metadata/constitution_modified.html (or http://www.met.rdg.ac.uk/~jonathan/CF_metadata/constitution_modified.adoc for the source). These changes add some text and ideas from your version. The limit on the number of committee members is removed, but the terms and method of appointment are as at present. The out-of-date parts (transitional arrangements in 2006) are deleted. I have added one new bit, on how the panel is constituted, for which we have no current rules. Here I am proposing a mechanism whereby the panel must have itself confirmed annually from both "above and below".

You weren't inviting this, but I hope it helps.

Best wishes and thanks for your patience

Jonathan

JonathanGregory commented 4 years ago

Some further clarification:

I did not change the text with respect to the present rules, which state that "Members [of the committee] may choose to resign at any time and must retire after five years, but may be reappointed." Obviously we could choose a shorter term - that's something to debate.

Although this is no change on paper, in practice it would be. We have always had this rule but never implemented it. Some committee members have resigned or retired, but none have stood down because their time was up. I agree that it would be a good thing if we had this periodic renewal. Since reappointment is allowed, it doesn't mean we'd lose valuable members who were willing to remain. However it offers a way for people to step down automatically and gracefully, if for example they no longer have the time or interest to contribute but haven't got round to retiring.

As Nan pointed out, most of the committee members are beyond their terms, so we need to consider transitional arrangements. I suggest that we first of all find out which present committee members who have served for more than five years are willing to continue. Then I suggest we divide the superannuated members into groups, some to retire now, some in a year, etc.

graybeal commented 4 years ago

I encourage you to consider terms carefully. For some members, being on the committee is (a) an honor, and (b) of actual value, not just intrinsic value. Creating a process that nudges people off the committee has the potential to leave some people unhappy, and to reduce the number of visible eyes on the issues.

That said, I'm a little unclear about the relationship between committee membership and participation in CF Convention review processes, so consider this 'just a thought'.

JonathanGregory commented 4 years ago

Dear John

Thanks for your comment. I agree that it would very regrettable if introducing terms for committee members made them feel as though they were being pushed out. I also appreciate that being on the committee can be useful, on account of the recognition and appreciation implied. I hope that committee members feel encouraged by their membership to get involved in CF discussions. We definitely do not want fewer people involved. With most issues, there are too few people engaged.

What I meant is that, if someone's priorities and interests change (on the long term, not as a temporary variation), they may no longer be in a position to contribute. However they might not take the step of resigning, because that could feel like making a statement of dissociation from CF, or simply because they don't get round to it. Hence, periodically questioning us all whether we wish to carry on could be a useful prompt in that situation. It is a way to leave and be thanked for past contributions. Those who wish to be reappointed will also be thanked for making that ongoing commitment!

Everyone can participate in the review process. The only special role that the committee members have is that at least two of them must express positive support for a proposal before it can be approved. Since consensus is the aim, everyone's comments are of equal value.

Jonathan

martinjuckes commented 4 years ago

Hello @erget , this looks good .. a nice piece of work.

Some questions:

  1. In CODE_OF_CONDUCT.md, there is a line: "opening an issue or contacting one or more of the project maintainers." (a) Who are the project maintainers? Should this be the Governance Panel or Conventions Committee? (b) For avoidance of doubt, it should probably specify a cf-conventions issue, as opposed to an issue in one of the other relevant repos, such as the new one for standard name discussions.

  2. in CONTRIBUTING.md: will "non-controversial" changes submitted as pull-requests also be subject to a waiting period to give others (aside from the proposer) the opportunity to question the change? Or is it acceptable for someone who has authorization to submit a request and accept it immediately? I can see the attraction of this, but it does create a lack of transparency. We should try to avoid the situation that occurred recently when someone made a string of non-controversial changes, spent months trying to get someone to implement the changes by accepting a pull request, and then was eventually told that a committee member had made the changes independently in a parallel pull request. I would prefer to have all changes documented as issues, but allow that "non-controversial" changes can be immediately backed up by a pull-request. This would improve transparency, and I don't think the added work of creating an issue is too onerous.

  3. in CONTRIBUTING.md, line 41: "All new pull requests should be submitted to the master branch and will be merged or closed as soon as agreement has been reached." This appears to contradict the 3-week rule.

  4. Membership of the committee: the procedures governing membership are, from my perspective, totally opaque and this lack of transparency is something of a problem. Since that annual meeting is starting to function as an effective decision making forum, perhaps it would be useful to review the membership at that meeting? This would make it clear that it should be a community decision .. or should it be in the gift of the Governance Panel? A regular review would give a means of maintaining the authority of the committee without imposing an artificial time limit.

erget commented 4 years ago

Dear all who've been contributing to this discussion, my sincere thanks and apologies for being radio silent for so long - I was literally in the jungle and out of reach, but that does not diminish my interest in this issue and I'm happy to pick up the ball now I'm back in office.

Responded to curtly because I'm in a rush and in chronological order: @JonathanGregory I have some difficulties with terminology, as in my understanding the original document that we're working from isn't a constitution at all, but a section of a white paper devoted to describing the constitution of different bodies at the time the white paper was written. In my mind we're striving to produce a constitution as a kind of terms of reference at this time. I will be happy to review your text in the coming days. I may not agree with all points, as usual, but as always I'm happy for the engagement and the synthesis of our ideas will surely be better than what I produced in the vacuum at the end :)

Also @graybeal I agree that at the bare minimum we need to ensure that we track people's contributions to all parts of taking care of the Conventions, and what I've proposed here may not be enough. I agree that the goal should not be to nudge people off. My thought was that if the people currently serving are electing to do so there's less of a tendency to feel that change proposals end up in a vacuum chamber where nobody feels responsible. My thoughts are in line with @JonathanGregory here that periodically confirming people's membership would perhaps encourage their ongoing commitment.

@martinjuckes thank you for that feedback. Concerning (1) I agree. Concerning (2) I think we need at least 4 eyes on every change, even minor ones, but for the most minor ones I would argue the four-eye principal can suffice. Probably you're right about requiring issues always. Concerning (3) you're right, this also doesn't reflect my understanding. Concerning (4) I think using hte annual meeting would be a useful mechanism. There is some parallel discussion going on via email that I haven't been able to catch up with yet but will review and see what I can bring together. On all these points I'm happy to update the draft in all those aspects in the coming days.

JonathanGregory commented 4 years ago

Dear Martin and Daniel

Re Martin's points.

(2) We could define "non-controversial" as nothing more than spelling mistakes, formatting issues and typos. Maybe it would be OK to allow those to be corrected with just a pull request. However, on the whole I think it's easier to avoid that judgement, and to have an issue for all changes. Such minor changes would be defects, subject to the three-week rule requiring no dissent to be expressed. However the issue could just say e.g. "Fixed typos in section X". There is still a judgement to be made about whether a given change is a defect or an enhancement. The latter requires positive support to be expressed by three people, including two committee members, as well as there being no objections oustanding for three weeks.

(4) The committee is appointed by the governance panel. That is the case in the existing constitution and I haven't changed it in my modified version at http://www.met.rdg.ac.uk/~jonathan/CF_metadata/constitution_modified.html This is an important function of the governance panel. People who would like to serve on the committee are welcome to volunteer to the governance panel, who have the responsibility to make sure the committee has a membership with a range of relevant expertise. The only formal role of the committee is the one in supporting changes (see last paragraph). In my version I have suggested ways in which the governance panel should ensure it has the confidence of the community and the WGCM, which is the parent/guardian organisation for CF.

The appendix to the white paper is the current constitution. It hasn't been extracted and put separately on the website and labelled as such, but the white paper has always been on the website, for that reason. It is the rules we've been following, except that we haven't implemented the regular retirement of committee members.

Cheers

Jonathan

erget commented 4 years ago

Dear colleagues,

Thanks for the extensive discussion surrounding this proposal over a long period of time. This issue can now be cleanly superseded by #257 for the following reasons:

Therefore I am closing this issue in favour of the newer one (#257).

Cheers, Daniel