Definition Revisions Approval Process


#1

I think would be useful to formalize and document the Open Definition Revision Approval process (even the title may need revising). I’ve started a new document on GitHub to contain the working version of this document and have put my first attempt there. Please feel free to comment, discuss, edit, submit PRs etc.

Thanks,
Herb


Open Definition Advisory Council category?
#2

Thanks @herb_lainchbury,
Could you provide a link so people can find it easily? Not everyone here is familiar with GitHub.


#3

Haven’t read it yet but the link is almost certainly https://github.com/okfn/opendefinition/blob/gh-pages/source/open-definition-revision-process-dev.markdown


#4

I like this overall.

  • Do we want to say this forum instead of mailing lists? I vote yes on that
  • I propose we formalize the concept of “draft that has consensus” as a “release candidate” in a better way that is more formal with a number. If issues are brought up and we go back to edit, then we get to release candidate 2 or release candidate 3…
  • In step 5, “ready for voting, establishing a release candidate, and informing
    contributors that only typo corrections will be accepted from this point
    forward.” is unclear.
    • I think it’s more that we need to clarify that if the proposed release candidate has a successful vote, then only typo corrections will be accepted.

Overall, I still see lack of clarity about the meaning of only accepting typo fixes. I think I’d prefer something that distinguishes between real content changes vs rewordings. I see things like splitting up a run-on sentence or fixing a word to be more clear is in a different category from real policy changes. I would like to see a stage that says “we’re not going to discuss policy issues any further (unless strong objections like a hard-block/veto level are raised)” that still allows us to accept the scope and policy but still fine-tune the wordings.

Personally, my issue is that I really wanted to get through the debates about policy and concepts, see a draft that includes 100% of the proposed policy issues addressed, but still be able to make minor wording improvements. I saw the current situation as being asked to vote already on the first draft I read that included 100% of the policy proposals. I want to be able to say “yes, this captures all the policy proposals adequately, but I want to still fix up the precise writing before it’s final”. And in that case, I’d accept a rejection of any wording fixes that anyone sees as having policy impacts — in other words, I can accept the idea that we’ve agreed not to adjust the policy from here, but I don’t like that meaning that the wording is final. Sometimes, a wording change is easy enough, is completely an improvement, and doesn’t affect the policy.

By the way, thanks Herb for your proactive work on everything. Much appreciated, and thanks for being considerate of my concerns.


#5

I like the suggestions @wolftune - especially using this forum more :wink:

I think more clarity is needed on what happens where e.g. Raising issues on GitHub and then where they are discussed.

There is some nice integration between this forum and GitHub we should explore. E.g.


#6

Sorry, was unable to reply from my phone. (still figuring out how this system works)


#7

You may also like to use the polling feature to vote on release candidates.


#8

I am disappointed that minor positive fixes that could have easily been in 2.1 got excluded because of the poor clarity and process, but happy that we are working out a better process moving forward.

I suggest one new point for the process:

  • The process of determining whether to make something a release candidate should be required to include a list of any outstanding known issues being excluded. In other words, if there are questions unanswered, pull requests not yet merged, outstanding tickets… any of that should be mentioned. I don’t want people to be accepting consensus on a release candidate under a false impression that all outstanding items have been addressed.

Another detail to clarify:

  • The concept of the release-candidate phase is that even if something gets to be a release candidate, there is still a stage for people to express concerns, even if minor, and for others to choose to reject the release candidate per final vote specifically in order to update and get a release candidate 2. In other words, I don’t want to see a situation where a minor concern is brought up, nearly everyone agrees it makes sense to address, but it isn’t allowed in the already set release candidate, so we go forward on the main vote and then most people think “oh, this is still definitely improvement, I’ll vote yes” which I what I think happens now. So I want it to be explicitly clear that voting “no” on a final release isn’t a total “back to the drawing board, the initiative failed” sort of thing. It needs to be expressed that we can vote no on a final release specifically to just go incorporate some minor updates and make a release-candidate 2.

Hope that’s all clear. My main concern is that after important work is done we just rush the release rather than having adequate clean up and polish before the release.