MAINTAINERS_GUIDE|CONTRIBUTING: Make generic enough for all OCI Projects #20

wking · 2016-09-09T07:08:48Z

With opencontainers/tob#18 landing and runtime-tools and image-tools getting seeded with project-template content, it would be nice to make more of this repository generic enough to apply to all OCI Projects. This PR addresses that (see also #4).

There are a number of commits here, and I've tried to keep them fairly atomic and independent. If it makes review easier, I'm happy to split them out into separate PRs. Detailed motivation for all changes is in the respective commit message.

This could be batched with #18 and #19 for an all-maintainers vote, but:

It's touching very different stuff, so there's less maintainer-bandwidth savings by batching.
It's a lot bigger, so it probably needs more editing before it settles enough to be worth voting on.

I recommend interested parties review this here, and once it settles down (likely long after #18 and #19 have been decided ;) we put it to a separate all-maintainer vote.

…late into merge-project-template To fulfill the TOB's [1]: Both of the proposed projects would incorporate the Governance and Releases processes from the OCI project template: https://github.com/opencontainers/project-template. which was approved with this vote [2]. Generated with: $ git pull git://github.com/opencontainers/project-template.git master $ git checkout --ours .pullapprove.yml README.md $ git checkout --theirs CONTRIBUTING.md LICENSE MAINTAINERS_GUIDE.md $ git add .pullapprove.yml CONTRIBUTING.md LICENSE MAINTAINERS_GUIDE.md README.md $ git commit I think there are a few improvements we could make to these template docs [3,4,5], but the TOB vote happened before I'd floated those. If/when they land, we can pull the updated versions into this repository via a follow-up merge. * 'master' of git://github.com/opencontainers/project-template: (33 commits) .pullapprove.yml: Reset on push, ignore authors, and require sign-offs GOVERNANCE.md: fix typo GOVERNANCE and RELEASES: split the files project-governance: Make voting more generic proposals: release approval process explain security@ email proposal: fix a typo proposals: release-approval-process fix a grammar thing release-approval: Add non-spec unanimous quorum reduction release-approval: Shuffle to make more DRY proposals: release-approval-process: fixup additional typos proposals: release approval process: improve REJECT feedback proposals: release approval process: add information to projects proposals: release approval process: add language about mailing list proposals: release approval process: add quorum language proposals: release-approval-process: add voting members language proposals: release approval process: clarify utility of GitHub proposals: release approval process: use consistent language for rejects proposals: release approval process: one month pre-releases proposals: release approval process 3 rcs required proposals: release approval process to one week for apps ... Conflicts: .pullapprove.yml CONTRIBUTING.md LICENSE MAINTAINERS_GUIDE.md README.md [1]: https://github.com/opencontainers/tob/blob/8997b1aa221b3b61d4305bede41c257b879bdeeb/proposals/tools.md#governance-and-releases [2]: https://groups.google.com/a/opencontainers.org/forum/#!topic/tob/rZ4luMa-pxY Subject: VOTE Required: approve new projects: image-tools, runtime-tools Date: Wed, 07 Sep 2016 22:37:32 +0000 Message-ID: <CAD2oYtMLMFQouEVU7HTO-EKnW6vKu82dGT+0mziXZzCyqngj=A@mail.gmail.com> [3]: opencontainers/project-template#18 Subject: GOVERNANCE: Proposing a motion is a LGTM by default [4]: opencontainers/project-template#19 Subject: GOVERNANCE: Drop the co-sponsor requirement [5]: opencontainers/project-template#20 Subject: MAINTAINERS_GUIDE|CONTRIBUTING: Make generic enough for all OCI Projects

…late into merge-project-template To fulfill the TOB's [1]: Both of the proposed projects would incorporate the Governance and Releases processes from the OCI project template: https://github.com/opencontainers/project-template. which was approved with this vote [2]. Generated with: $ git pull git://github.com/opencontainers/project-template.git master $ git checkout --ours .pullapprove.yml README.md $ git checkout --theirs CONTRIBUTING.md LICENSE MAINTAINERS_GUIDE.md $ git add .pullapprove.yml CONTRIBUTING.md LICENSE MAINTAINERS_GUIDE.md README.md $ git commit I think there are a few improvements we could make to these template docs [3,4,5], but the TOB vote happened before I'd floated those. If/when they land, we can pull the updated versions into this repository via a follow-up merge. * 'master' of git://github.com/opencontainers/project-template: (33 commits) .pullapprove.yml: Reset on push, ignore authors, and require sign-offs GOVERNANCE.md: fix typo GOVERNANCE and RELEASES: split the files project-governance: Make voting more generic proposals: release approval process explain security@ email proposal: fix a typo proposals: release-approval-process fix a grammar thing release-approval: Add non-spec unanimous quorum reduction release-approval: Shuffle to make more DRY proposals: release-approval-process: fixup additional typos proposals: release approval process: improve REJECT feedback proposals: release approval process: add information to projects proposals: release approval process: add language about mailing list proposals: release approval process: add quorum language proposals: release-approval-process: add voting members language proposals: release approval process: clarify utility of GitHub proposals: release approval process: use consistent language for rejects proposals: release approval process: one month pre-releases proposals: release approval process 3 rcs required proposals: release approval process to one week for apps ... Conflicts: .pullapprove.yml CONTRIBUTING.md LICENSE MAINTAINERS_GUIDE.md README.md [1]: https://github.com/opencontainers/tob/blob/8997b1aa221b3b61d4305bede41c257b879bdeeb/proposals/tools.md#governance-and-releases [2]: https://groups.google.com/a/opencontainers.org/forum/#!topic/tob/rZ4luMa-pxY Subject: VOTE Required: approve new projects: image-tools, runtime-tools Date: Wed, 07 Sep 2016 22:37:32 +0000 Message-ID: <CAD2oYtMLMFQouEVU7HTO-EKnW6vKu82dGT+0mziXZzCyqngj=A@mail.gmail.com> [3]: opencontainers/project-template#18 Subject: GOVERNANCE: Proposing a motion is a LGTM by default [4]: opencontainers/project-template#19 Subject: GOVERNANCE: Drop the co-sponsor requirement [5]: opencontainers/project-template#20 Subject: MAINTAINERS_GUIDE|CONTRIBUTING: Make generic enough for all OCI Projects Signed-off-by: W. Trevor King <wking@tremily.us>

jonboulle · 2017-01-09T12:52:40Z

MAINTAINERS_GUIDE.md

+   Anyone can do this.
+4. Endorse (`LGTM`) or oppose (`Rejected`) the pull request.
+   The relevant maintainers do this (see below [Who decides what?](#who-decides-what)).
+   Changes that effect project management (changing policy, cutting releases, etc.) are [proposed and voted on the mailing list](GOVERNANCE.md).


Thanks. Fixed with 0787a41 → 9597f27.

jonboulle · 2017-01-10T12:40:36Z

CONTRIBUTING.md

-Small changes or changes that have been discussed on the project mailing list
-may be submitted without a leader issue, in which case you are free to name
-your branch however you like.
+Small changes or changes that have been discussed on the


nit, this file is now inconsistently wrapped, grumble grumble

I've been trying to transition to the one-sentence-per-line approach used by runtime-spec when I'd need to re-wrap anything. I've updated this hunk to follow that with 9597f27 → d3f0172. But the file as a whole still mixes manually wrapped lines (at 79 chars?) with the sentence wrapped lines I've touched. Should I add a re-wrapping commit that applies sentence wrapping to everything else in the file? Should I reroll my changes to stick with 79-char wrapping (and if so, should we document that wrapping width somewhere)?

jonboulle · 2017-01-10T12:40:42Z

lgtm

stevvooe · 2017-01-10T20:47:20Z

MAINTAINERS_GUIDE.md

-in the best interests of the project.  Sometimes maintainers can disagree and
-this is part of a healthy project to represent the point of views of various people.
-In the case where maintainers cannot find agreement on a specific change the
-role of a Chief Maintainer comes into play.


Is the intent to remove the concept of a chief maintainer?

Yes. See the d3f0172 commit message for more motivation around this specific pivot.

Which proposal removed the concept of Chief maintainer? That sounds like a necessary decider to keep things moving.

None of the changes in this PR have been voted on by any OCI maintainers. As I said in the topic post

I recommend interested parties review this here, and once it settles down (likely long after #18 and #19 have been decided ;) we put it to a separate all-maintainer vote.

If any portions of this PR are considered more contentious than others, I'm also happy to pull those commits off into a separate PR for a separate all-maintainer vote.

Currently the OCI seems to have one repository per Project. A few repositories are not official projects; ocitools is just becoming official [1] and artwork [2] may never be a Project. But I expect that going forward, any opencontainers/ repos that have a MAINTAINERS file will be official Projects, so the union rule here should be both correct and easy to maintain. The file is not Markdown, so I've gone with my usual reference-style link instead of a Markdown reference-style link. [1]: opencontainers/tob#18 Subject: Create runtime-tools and image-tools projects [2]: https://github.com/opencontainers/artwork Signed-off-by: W. Trevor King <wking@tremily.us>

Use links, which gives us a bit more space to discuss the content while still making the filename discoverable. Signed-off-by: W. Trevor King <wking@tremily.us>

The other headers only have a single blank line before them. Signed-off-by: W. Trevor King <wking@tremily.us>

So we'll have room for some non-Git contributing advice as well. Signed-off-by: W. Trevor King <wking@tremily.us>

wking · 2017-08-21T20:03:22Z

Rebased around #27 with d3f0172 → 14a58e0.

RobDolinMS · 2017-08-21T21:15:23Z

CONTRIBUTING.md

+
+## Weekly Call
+
+The contributors and maintainers of all OCI projects have a weekly meeting Wednesdays at 2:00 PM (USA Pacific).


Should this now be a monthly meeting?

Should this now be a monthly meeting?

Good point. Done in 14a58e0 → dc9715d, although that means that new spec projects (if we get any) will need their own supplemental meetings to satisfy this SHOULD.

So far dev@ volume has been low enough that we haven't needed per-project lists [1], so we can add it in this central location. In the event that we do split lists later, the reference-style link makes it easy for projects to update the target without touching the line with the link text. The meetings and IRC channel are in the same boat (not enought traffic to be worth splitting). The content I'm adding here is adapted from [2,3]. As long as the meeting is shared, linking the runtime-spec maintained meeting.ics seemed easier than keeping a parallel copy here. The CoC titles itself "OpenContainers Code of Conduct", but [4] has: Connecting with the Open Container Initiative community And I feel like I've been seeing the singular, spaced form more frequently. While we're adding reference-style links, convert the DCO link as well to make the text easier to read. [1]: https://groups.google.com/a/opencontainers.org/d/msg/dev/Ctw-fcO1IuA/7vrr4YiyDgAJ Subject: Re: splitting this list into image-spec-dev, runtime-spec-dev, etc Date: Wed, 20 Apr 2016 14:45:55 -0400 Message-ID: <CAEXjzRug6uL_1eLHyxUzN+3AchXq6KVtV6KmgxRj0Gu+krfAcg@mail.gmail.com> [2]: https://github.com/opencontainers/runtime-spec/blob/7a36e7ed86ee3b4c6dbcdbd02052ec1ef6787c3c/README.md#contributing [3]: https://github.com/opencontainers/runtime-spec/blob/1077f05ae7b05ce79159e66c25f8ff80f58ffedb/README.md#meetings [4]: https://www.opencontainers.org/community Signed-off-by: W. Trevor King <wking@tremily.us>

Not all OCI Projects are primarily Go, and filling in off-topic formatting advice doesn't seem useful. One approach to this would be to require projects to support 'make fmt' to handle any auto-formatting. But an easier approach is to keep the document generic in this repository [1], and allow downstream projects to add their own project-specific content as they see fit. I don't expect a lot of churn in this document, so there shouldn't be many conflicts between those downstream changes and further project-template development. [1]: opencontainers#4 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

Current ocitools docs are the man pages under man/. No docs for building them yet beyond the Makefile rule, and that may be all we need ;). Because there is no downstream consensus on doc locations, remove the reference. Downstream repositories can add it (or similar content) back in as they see fit [1]. I don't expect a lot of churn in this document, so there shouldn't be many conflicts between those downstream changes and further project-template development. [1]: opencontainers#4 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

The old wording did not mention email discussion before working up changes, which we often recommend [1,2] to avoid contributors sinking a lot of work into a pull request that ends up being rejected because of a fundamental design issue. The new wording mentions that and also: * Removes the overly compact short answer to avoid confusion [3]. The section is not so long that it needs a one-line summary. * Distinguishes between in-PR votes (LGTM/Rejected) and merging/closing the PR. * Mentions GOVERNANCE for management changes. * Uses an enumerated list instead of "Step N" text. * Uses the README's recommended one line per sentence. [1]: CONTRIBUTING.md#conventions [2]: opencontainers/runtime-spec#420 (comment) [3]: opencontainers/runtime-spec#420 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

If we wanted to enumerate these we should use Markdown's enumerated list. But these aren't ordered, so remove the old enumerations. Also adjust to the README's recommended one line per sentence. Signed-off-by: W. Trevor King <wking@tremily.us>

"are" is for plurals. Signed-off-by: W. Trevor King <wking@tremily.us>

This information was already covered more explicitly in the earlier "What are a maintainer's responsibilities?" section. Signed-off-by: W. Trevor King <wking@tremily.us>

wking · 2018-03-07T23:42:15Z

I've dropped the commit removing the Chief Maintainer because that landed via #42. Can I do anything to move the rest of these changes forward as well? Should I continue to split them off into single-commit PRs?

caniszczyk · 2018-03-08T18:31:50Z

@wking if you can close this and break changes up and do it one PR a a time, that would be great, totally appreciate you cleaning this up

wking · 2018-03-08T19:02:20Z

Split up into #43 through #52, so closing this one.

wking force-pushed the generic-docs branch 3 times, most recently from 26f54e2 to 0787a41 Compare September 9, 2016 07:29

wking mentioned this pull request Sep 9, 2016

Rename repo from ocitools to runtime-tools opencontainers/runtime-tools#205

Closed

wking mentioned this pull request Nov 17, 2016

Merge branch 'master' of git://github.com/opencontainers/project-template into merge-project-template opencontainers/runtime-tools#274

Closed

This was referenced Jan 6, 2017

*: Pull opencontainers/project-template opencontainers/go-digest#20

Closed

CONTRIBUTING: Remove branch-naming suggestions #27

Merged

jonboulle reviewed Jan 9, 2017

View reviewed changes

wking force-pushed the generic-docs branch from 0787a41 to 9597f27 Compare January 9, 2017 19:42

jonboulle reviewed Jan 10, 2017

View reviewed changes

wking force-pushed the generic-docs branch from 9597f27 to d3f0172 Compare January 10, 2017 14:29

stevvooe reviewed Jan 10, 2017

View reviewed changes

wking added 4 commits August 21, 2017 13:00

README: Update list of content

5c732a5

Use links, which gives us a bit more space to discuss the content while still making the filename discoverable. Signed-off-by: W. Trevor King <wking@tremily.us>

CONTRIBUTING: Remove extra blank line before "Conventions"

c73cecd

The other headers only have a single blank line before them. Signed-off-by: W. Trevor King <wking@tremily.us>

CONTRIBUTING: Push existing content down into a Git subsection

3ac2cce

So we'll have room for some non-Git contributing advice as well. Signed-off-by: W. Trevor King <wking@tremily.us>

wking force-pushed the generic-docs branch from d3f0172 to 14a58e0 Compare August 21, 2017 20:03

RobDolinMS reviewed Aug 21, 2017

View reviewed changes

wking added 6 commits August 21, 2017 14:46

MAINTAINERS_GUIDE: Replace "are ... responsibility?" with "...ties?"

08aacb2

"are" is for plurals. Signed-off-by: W. Trevor King <wking@tremily.us>

wking force-pushed the generic-docs branch from 14a58e0 to dc9715d Compare August 21, 2017 21:46

wking mentioned this pull request Feb 1, 2018

Add distribution spec project proposal opencontainers/tob#35

Merged

wking mentioned this pull request Mar 7, 2018

MAINTAINERS_GUIDE: Replace Chief Maintainer with GOVERNANCE #42

Merged

wking force-pushed the generic-docs branch from dc9715d to f7f7fd0 Compare March 7, 2018 23:40

MAINTAINERS_GUIDE: Remove duplicate maintainer expectations

f7f7fd0

This information was already covered more explicitly in the earlier "What are a maintainer's responsibilities?" section. Signed-off-by: W. Trevor King <wking@tremily.us>

wking closed this Mar 8, 2018

wking mentioned this pull request Apr 6, 2018

*: Move closer to project-template's current status opencontainers/runtime-spec#966

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MAINTAINERS_GUIDE|CONTRIBUTING: Make generic enough for all OCI Projects #20

MAINTAINERS_GUIDE|CONTRIBUTING: Make generic enough for all OCI Projects #20

wking commented Sep 9, 2016 •

edited

Loading

jonboulle Jan 9, 2017

wking Jan 9, 2017

jonboulle Jan 10, 2017

wking Jan 10, 2017

jonboulle commented Jan 10, 2017

stevvooe Jan 10, 2017

wking Jan 10, 2017

stevvooe Jan 10, 2017

wking Jan 10, 2017

wking commented Aug 21, 2017

RobDolinMS Aug 21, 2017

wking Aug 21, 2017

wking commented Mar 7, 2018

caniszczyk commented Mar 8, 2018

wking commented Mar 8, 2018


		## Weekly Call

		The contributors and maintainers of all OCI projects have a weekly meeting Wednesdays at 2:00 PM (USA Pacific).

MAINTAINERS_GUIDE|CONTRIBUTING: Make generic enough for all OCI Projects #20

MAINTAINERS_GUIDE|CONTRIBUTING: Make generic enough for all OCI Projects #20

Conversation

wking commented Sep 9, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonboulle commented Jan 10, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wking commented Aug 21, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wking commented Mar 7, 2018

caniszczyk commented Mar 8, 2018

wking commented Mar 8, 2018

wking commented Sep 9, 2016 •

edited

Loading