From bc2b4405fbf9c68cb352531a850f27f8a20a5f73 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 8 Sep 2016 22:19:05 -0700 Subject: [PATCH 01/11] MAINTAINERS: Explain the format and reference other projects 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]: https://github.com/opencontainers/tob/pull/18 Subject: Create runtime-tools and image-tools projects [2]: https://github.com/opencontainers/artwork Signed-off-by: W. Trevor King --- MAINTAINERS | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 MAINTAINERS diff --git a/MAINTAINERS b/MAINTAINERS new file mode 100644 index 0000000..9bee195 --- /dev/null +++ b/MAINTAINERS @@ -0,0 +1,8 @@ +This meta-project is maintained by the union of MAINTAINERS for all OCI Projects [1]. + +Other OCI Projects should list one maintainer per line, with a name, email address, and GitHub username: + +Random J Developer (@RandomJDeveloperExample) +A. U. Thor (@AUThorExample) + +[1]: https://github.com/opencontainers/ From 5c732a537761d55fd8ed9884153b0091314629bf Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 8 Sep 2016 22:26:24 -0700 Subject: [PATCH 02/11] README: Update list of content 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 --- README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2a80b08..a8187da 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,11 @@ # OCI Project Template -All OCI projects should have: -* LICENSE -* CONTRIBUTING.md -* MAINTAINERS.md -* MAINTAINERS_GUIDE.md -* README +Useful boilerplate and organizational information for all OCI projects. + +* README (this file) +* [The Apache License, Version 2.0](LICENSE) +* [A list of maintainers](MAINTAINERS) +* [Maintainer guidelines](MAINTAINERS_GUIDE.md) +* [Contributor guidelines](CONTRIBUTING.md) +* [Project governance](GOVERNANCE.md) +* [Release procedures](RELEASES.md) From c73cecd8a848c19bd8d2f1efff5444ad81da1505 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 8 Sep 2016 22:29:52 -0700 Subject: [PATCH 03/11] CONTRIBUTING: Remove extra blank line before "Conventions" The other headers only have a single blank line before them. Signed-off-by: W. Trevor King --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7abbd2b..5457924 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,6 @@ We're trying very hard to keep the project lean and focused. We don't want it to do everything for everybody. This means that we might decide against incorporating a new feature. - ### Conventions Fork the repo and make changes on your fork in a feature branch. From 3ac2cceda0979ba69b8824010492236e830ffbed Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 8 Sep 2016 22:46:00 -0700 Subject: [PATCH 04/11] CONTRIBUTING: Push existing content down into a Git subsection So we'll have room for some non-Git contributing advice as well. Signed-off-by: W. Trevor King --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5457924..2573841 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,6 @@ -## Contribution Guidelines +# Contribution Guidelines + +## Git ### Security issues From 7a6fc8f5c70d27fe5123fa69a0d569118957694f Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 8 Sep 2016 22:31:37 -0700 Subject: [PATCH 05/11] CONTRIBUTING: Code of conduct, meetings, mailing list, and IRC 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: [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 --- CONTRIBUTING.md | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2573841..cabbe10 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,30 @@ # Contribution Guidelines +Development happens on GitHub. +Issues are used for bugs and actionable items and longer discussions can happen on the [mailing list](#mailing-list). + +The content of this repository is licensed under the [Apache License, Version 2.0](LICENSE). + +## Code of Conduct + +Participation in the Open Container community is governed by [Open Container Code of Conduct][code-of-conduct]. + +## Meetings + +The contributors and maintainers of all OCI projects have monthly meetings at 2:00 PM (USA Pacific) on the first Wednesday of every month. +There is an [iCalendar][rfc5545] format for the meetings [here][meeting.ics]. +Everyone is welcome to participate via [UberConference web][UberConference] or audio-only: +1 415 968 0849 (no PIN needed). +An initial agenda will be posted to the [mailing list](#mailing-list) in the week before each meeting, and everyone is welcome to propose additional topics or suggest other agenda alterations there. +Minutes from past meetings are archived [here][minutes]. + +## Mailing list + +You can subscribe and browse the mailing list on [Google Groups][mailing-list]. + +## IRC + +OCI discussion happens on #opencontainers on [Freenode][] ([logs][irc-logs]). + ## Git ### Security issues @@ -27,7 +52,7 @@ incorporating a new feature. Fork the repo and make changes on your fork in a feature branch. For larger bugs and enhancements, consider filing a leader issue or mailing-list thread for discussion that is independent of the implementation. -Small changes or changes that have been discussed on the project mailing list may be submitted without a leader issue. +Small changes or changes that have been discussed on the [project mailing list](#mailing-list) may be submitted without a leader issue. If the project has a test suite, submit unit tests for your changes. Take a look at existing tests for inspiration. Run the full test suite on your branch @@ -69,8 +94,7 @@ or `Fixes #XXX`, which will automatically close the issue when merged. The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): +can certify the below (from [developercertificate.org][]): ``` Developer Certificate of Origin @@ -119,3 +143,12 @@ then you just add a line to every git commit message: using your real name (sorry, no pseudonyms or anonymous contributions.) You can add the sign off when creating the git commit via `git commit -s`. + +[code-of-conduct]: https://github.com/opencontainers/tob/blob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md +[developercertificate.org]: http://developercertificate.org/ +[Freenode]: https://freenode.net/ +[irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/ +[mailing-list]: https://groups.google.com/a/opencontainers.org/forum/#!forum/dev +[meeting.ics]: https://github.com/opencontainers/runtime-spec/blob/master/meeting.ics +[minutes]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/ +[UberConference]: https://www.uberconference.com/opencontainers From 3ad8a618be11e0a9cda60b2982b8fa69fdf84396 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 8 Sep 2016 22:55:46 -0700 Subject: [PATCH 06/11] CONTRIBUTING: Remove gofmt advice 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]: https://github.com/opencontainers/project-template/issues/4#issuecomment-221081999 Signed-off-by: W. Trevor King --- CONTRIBUTING.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cabbe10..c353ad1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,10 +63,6 @@ your documentation changes for clarity, concision, and correctness, as well as a clean documentation build. See ``docs/README.md`` for more information on building the docs and how docs get released. -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - Pull requests descriptions should be as clear as possible and include a reference to all the issues that they address. From ec9dc072356af1a315c1121cfa3b3d35e5f8ecf1 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 8 Sep 2016 23:58:14 -0700 Subject: [PATCH 07/11] CONTRIBUTING: Remove docs/README.md reference 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]: https://github.com/opencontainers/project-template/issues/4#issuecomment-221081999 Signed-off-by: W. Trevor King --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c353ad1..4e104bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,8 +60,7 @@ before submitting a pull request. Update the documentation when creating or modifying features. Test your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. +well as a clean documentation build. Pull requests descriptions should be as clear as possible and include a reference to all the issues that they address. From 676a2ea9e3e8cb36352908564a4f641dc7ed5c36 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 8 Sep 2016 23:19:28 -0700 Subject: [PATCH 08/11] MAINTAINERS_GUIDE: Mention email in "How are decisions made?" 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]: https://github.com/opencontainers/runtime-spec/pull/420#discussion_r61972422 [3]: https://github.com/opencontainers/runtime-spec/pull/420#discussion_r61973030 Signed-off-by: W. Trevor King --- MAINTAINERS_GUIDE.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/MAINTAINERS_GUIDE.md b/MAINTAINERS_GUIDE.md index 8f6f129..82ad791 100644 --- a/MAINTAINERS_GUIDE.md +++ b/MAINTAINERS_GUIDE.md @@ -31,8 +31,6 @@ It is every maintainer's responsibility to: ## How are decisions made? -Short answer: with pull requests to the project repository. - This project is an open-source project with an open design philosophy. This means that the repository is the source of truth for EVERY aspect of the project, including its philosophy, design, roadmap and APIs. *If it's @@ -44,14 +42,19 @@ repository. An implementation change is a change to the source code. An API change is a change to the API specification. A philosophy change is a change to the philosophy manifesto. And so on. -All decisions affecting this project, big and small, follow the same 3 steps: - -* Step 1: Open a pull request. Anyone can do this. - -* Step 2: Discuss the pull request. Anyone can do this. - -* Step 3: Accept (`LGTM`) or refuse a pull request. The relevant maintainers do -this (see below "Who decides what?") +All decisions affecting this project, big and small, follow the same procedure: + +1. Discuss a proposal on the [mailing list](CONTRIBUTING.md#mailing-list). + Anyone can do this. +2. Open a pull request. + Anyone can do this. +3. Discuss the pull request. + 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 affect project management (changing policy, cutting releases, etc.) are [proposed and voted on the mailing list](GOVERNANCE.md). +5. Merge or close the pull request. + The relevant maintainers do this. ### I'm a maintainer, should I make pull requests too? From 815ae22962c90a5fe9d9395d650beab50ca7e2ee Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 8 Sep 2016 23:28:20 -0700 Subject: [PATCH 09/11] MAINTAINERS_GUIDE: Remove enumeratations for responsibilities 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 --- MAINTAINERS_GUIDE.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/MAINTAINERS_GUIDE.md b/MAINTAINERS_GUIDE.md index 82ad791..3800d03 100644 --- a/MAINTAINERS_GUIDE.md +++ b/MAINTAINERS_GUIDE.md @@ -22,12 +22,11 @@ speak up! It is every maintainer's responsibility to: -* 1) Expose a clear roadmap for improving their component. -* 2) Deliver prompt feedback and decisions on pull requests. -* 3) Be available to anyone with questions, bug reports, criticism etc. - on their component. This includes IRC and GitHub issues and pull requests. -* 4) Make sure their component respects the philosophy, design and - roadmap of the project. +* Expose a clear roadmap for improving their component. +* Deliver prompt feedback and decisions on pull requests. +* Be available to anyone with questions, bug reports, criticism etc. on their component. + This includes IRC and GitHub issues and pull requests. +* Make sure their component respects the philosophy, design and roadmap of the project. ## How are decisions made? From 08aacb22e02186f52b7ace138a7d1ed7f0a83e34 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 9 Sep 2016 00:18:16 -0700 Subject: [PATCH 10/11] MAINTAINERS_GUIDE: Replace "are ... responsibility?" with "...ties?" "are" is for plurals. Signed-off-by: W. Trevor King --- MAINTAINERS_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MAINTAINERS_GUIDE.md b/MAINTAINERS_GUIDE.md index 3800d03..60eb266 100644 --- a/MAINTAINERS_GUIDE.md +++ b/MAINTAINERS_GUIDE.md @@ -18,7 +18,7 @@ available to them. This is a living document - if you see something out of date or missing, speak up! -## What are a maintainer's responsibility? +## What are a maintainer's responsibilities? It is every maintainer's responsibility to: From f7f7fd044c9e6a2453370d06d81ef82dde97ef93 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 9 Sep 2016 00:16:59 -0700 Subject: [PATCH 11/11] MAINTAINERS_GUIDE: Remove duplicate maintainer expectations This information was already covered more explicitly in the earlier "What are a maintainer's responsibilities?" section. Signed-off-by: W. Trevor King --- MAINTAINERS_GUIDE.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/MAINTAINERS_GUIDE.md b/MAINTAINERS_GUIDE.md index 60eb266..cbd121d 100644 --- a/MAINTAINERS_GUIDE.md +++ b/MAINTAINERS_GUIDE.md @@ -107,13 +107,7 @@ conflict resolution rules expressed above apply. The voting period is five business days on the Pull Request to add the new maintainer. -### What is expected of maintainers? - -Part of a healthy project is to have active maintainers to support the community -in contributions and perform tasks to keep the project running. Maintainers are -expected to be able to respond in a timely manner if their help is required on specific -issues where they are pinged. Being a maintainer is a time consuming commitment and should -not be taken lightly. +### How are maintainers removed? When a maintainer is unable to perform the required duties they can be removed with a vote by 66% of the current maintainers with the chief maintainer having veto power.