From abab707b6c67f002af5f57b4260a5c10c74d8eda Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 6 Apr 2018 13:04:07 -0700 Subject: [PATCH] *: Move closer to project-template's current status Generated with: $ git remote add project-template git://github.com/opencontainers/project-template.git $ git fetch project-template $ git show --oneline project-template/master 61d73a3 (project-template/master) Merge pull request #40 from wking/minor-patch-bullet $ git merge --squash --allow-unrelated-histories project-template/master $ git checkout HEAD -- .pullapprove.yml MAINTAINERS README.md RELEASES.md $ git checkout project-template/master -- GOVERNANCE.md LICENSE $ emacs README.md CONTRIBUTING.md # unify around project-template's CONTRIBUTING.md approach $ emacs meeting.ics # update link to point at CONTRIBUTING.md#meetings $ git commit -sv I personally prefer non-squash merges to preserve history and ease future updates, but that approach has not been popular within the OCI [1,2], so I'm going with a squash-merge here. I'm sticking with the local RELEASES.md, because it uses four-space indents. I've filed [3] to upstream that change. I've also filed [4] upstreaming our local wording change from 70ba4e6d (meeting: Bump January meeting from the 3rd to the 10th, 2017-12-07, #943). I've also fixed the GOVERNANCE.md security link in flight with [5]. I've left the other in-flight project-template changes alone [6]. I've wrapped the URL in meetings.ics to avoid [7]: Line length should not be longer than 75 characters near line #33 Reference: RFC 5545 3.1. Content Lines [1]: https://github.com/opencontainers/go-digest/pull/20#issuecomment-273344526 [2]: https://github.com/opencontainers/runtime-tools/pull/274#issuecomment-312595923 [3]: https://github.com/opencontainers/project-template/pull/54 [4]: https://github.com/opencontainers/project-template/pull/55 [5]: https://github.com/opencontainers/project-template/pull/34 [6]: https://github.com/opencontainers/project-template/pulls [7]: https://icalendar.org/validator.html Signed-off-by: W. Trevor King --- CONTRIBUTING.md | 150 +++++++++++++++++++++++++++++++++++++++++++ GOVERNANCE.md | 13 +--- LICENSE | 14 +++- MAINTAINERS_GUIDE.md | 92 ++++++++++++++++++++++++++ README.md | 114 +------------------------------- meeting.ics | 5 +- 6 files changed, 262 insertions(+), 126 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 MAINTAINERS_GUIDE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..52e67703e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,150 @@ +# 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, which are usually 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 are posted to the [mailing list](#mailing-list) and minutes from past calls are archived [here][minutes], with minutes from especially old meetings (September 2015 and earlier) archived [here][runtime-wiki]. + +## 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 + +If you are reporting a security issue, do not create an issue or file a pull +request on GitHub. Instead, disclose the issue responsibly by sending an email +to security@opencontainers.org (which is inhabited only by the maintainers of +the various OCI projects). + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +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. +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](#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 +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. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Commit messages must start with a capitalized and short summary +written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite (if any) should be passing. Include documentation changes +in the same commit so that a revert would remove all traces of the feature or +fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +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][]): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +1 Letterman Drive +Suite D4700 +San Francisco, CA, 94129 + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +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]: meeting.ics +[minutes]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/ +[runtime-wiki]: https://github.com/opencontainers/runtime-spec/wiki +[UberConference]: https://www.uberconference.com/opencontainers diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 92c860949..e64738174 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -8,11 +8,11 @@ This section describes generic rules and procedures for fulfilling that mandate. ## Proposing a motion -A maintainer SHOULD propose a motion on the dev@opencontainers.org mailing list (except [security issues](#security-issues)) with another maintainer as a co-sponsor. +A maintainer SHOULD propose a motion on the dev@opencontainers.org mailing list (except [security issues](CONTRIBUTING.md#security-issues)) with another maintainer as a co-sponsor. ## Voting -Voting on a proposed motion SHOULD happen on the dev@opencontainers.org mailing list (except [security issues](#security-issues)) with maintainers posting LGTM or REJECT. +Voting on a proposed motion SHOULD happen on the dev@opencontainers.org mailing list (except [security issues](CONTRIBUTING.md#security-issues)) with maintainers posting LGTM or REJECT. Maintainers MAY also explicitly not vote by posting ABSTAIN (which is useful to revert a previous vote). Maintainers MAY post multiple times (e.g. as they revise their position based on feedback), but only their final post counts in the tally. A proposed motion is adopted if two-thirds of votes cast, a quorum having voted, are in favor of the release. @@ -31,17 +31,10 @@ A quorum is established when at least two-thirds of maintainers have voted. For projects that are not specifications, a [motion to release](#release-approval) MAY be adopted if the tally is at least three LGTMs and no REJECTs, even if three votes does not meet the usual two-thirds quorum. -## Security issues - -Motions with sensitive security implications MUST be proposed on the security@opencontainers.org mailing list instead of dev@opencontainers.org, but should otherwise follow the standard [proposal](#proposing-a-motion) process. -The security@opencontainers.org mailing list includes all members of the TOB. -The TOB will contact the project maintainers and provide a channel for discussing and voting on the motion, but voting will otherwise follow the standard [voting](#voting) and [quorum](#quorum) rules. -The TOB and project maintainers will work together to notify affected parties before making an adopted motion public. - ## Amendments The [project governance](#project-governance) rules and procedures MAY be amended or replaced using the procedures themselves. -The MAINTAINERS of this project governance document is the total set of MAINTAINERS from all Open Containers projects (runC, runtime-spec, and image-spec). +The MAINTAINERS of this project governance document is the total set of MAINTAINERS from all Open Containers projects (go-digest, image-spec, image-tools, runC, runtime-spec, runtime-tools, and selinux). ## Subject templates diff --git a/LICENSE b/LICENSE index bdc403653..8dada3eda 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,3 @@ - Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ @@ -176,7 +175,18 @@ END OF TERMS AND CONDITIONS - Copyright 2015 The Linux Foundation. + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "{}" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright {yyyy} {name of copyright owner} Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/MAINTAINERS_GUIDE.md b/MAINTAINERS_GUIDE.md new file mode 100644 index 000000000..8e9691747 --- /dev/null +++ b/MAINTAINERS_GUIDE.md @@ -0,0 +1,92 @@ +## Introduction + +Dear maintainer. Thank you for investing the time and energy to help +make this project as useful as possible. Maintaining a project is difficult, +sometimes unrewarding work. Sure, you will get to contribute cool +features to the project. But most of your time will be spent reviewing, +cleaning up, documenting, answering questions, justifying design +decisions - while everyone has all the fun! But remember - the quality +of the maintainers work is what distinguishes the good projects from the +great. So please be proud of your work, even the unglamourous parts, +and encourage a culture of appreciation and respect for *every* aspect +of improving the project - not just the hot new features. + +This document is a manual for maintainers old and new. It explains what +is expected of maintainers, how they should work, and what tools are +available to them. + +This is a living document - if you see something out of date or missing, +speak up! + +## What are a maintainer's responsibilities? + +It is every maintainer's responsibility to: + +* 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? + +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 +part of the project, it's in the repo. It's in the repo, it's part of +the project.* + +As a result, all decisions can be expressed as changes to the +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 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? + +Yes. Nobody should ever push to master directly. All changes should be +made through a pull request. + +## Who decides what? + +All decisions are pull requests, and the relevant maintainers make +decisions by accepting or refusing the pull request. Review and acceptance +by anyone is denoted by adding a comment in the pull request: `LGTM`. +However, only currently listed `MAINTAINERS` are counted towards the required +two LGTMs. In addition, if a maintainer has created a pull request, they cannot +count toward the two LGTM rule (to ensure equal amounts of review for every pull +request, no matter who wrote it). + +Overall the maintainer system works because of mutual respect. +The maintainers trust one another to act in the best interests of the project. +Sometimes maintainers can disagree and this is part of a healthy project to represent the points of view of various people. +In the case where maintainers cannot find agreement on a specific change, maintainers should use the [governance procedure](GOVERNANCE.md) to attempt to reach a consensus. + +### How are maintainers added? + +The best maintainers have a vested interest in the project. Maintainers +are first and foremost contributors that have shown they are committed to +the long term success of the project. Contributors wanting to become +maintainers are expected to be deeply involved in contributing code, +pull request review, and triage of issues in the project for more than two months. + +Just contributing does not make you a maintainer, it is about building trust with the current maintainers of the project and being a person that they can depend on to act in the best interest of the project. +The final vote to add a new maintainer should be approved by the [governance procedure](GOVERNANCE.md). + +### How are maintainers removed? + +When a maintainer is unable to perform the [required duties](#what-are-a-maintainers-responsibilities) they can be removed by the [governance procedure](GOVERNANCE.md). +Issues related to a maintainer's performance should be discussed with them among the other maintainers so that they are not surprised by a pull request removing them. diff --git a/README.md b/README.md index b40dba17d..eabb40fc2 100644 --- a/README.md +++ b/README.md @@ -36,118 +36,8 @@ Runtime developers can build runtime implementations that run OCI-compliant bund ## Contributing -Development happens on GitHub for the spec. -Issues are used for bugs and actionable items and longer discussions can happen on the [mailing list](#mailing-list). - -The specification and code is licensed under the Apache 2.0 license found in the [LICENSE](./LICENSE) file. - -### Discuss your design - -The project welcomes submissions, but please let everyone know what you are working on. - -Before undertaking a nontrivial change to this specification, send mail to the [mailing list](#mailing-list) to discuss what you plan to do. -This gives everyone a chance to validate the design, helps prevent duplication of effort, and ensures that the idea fits. -It also guarantees that the design is sound before code is written; a GitHub pull-request is not the place for high-level discussions. - -Typos and grammatical errors can go straight to a pull-request. -When in doubt, start on the [mailing-list](#mailing-list). - -### Meetings - -The contributors and maintainers of all OCI projects have monthly meetings, which are usually 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 are posted to the [mailing list](#mailing-list) and minutes from past calls are archived [here][minutes], with minutes from especially old meetings (September 2015 and earlier) archived [here][runtime-wiki]. - -### Mailing List - -You can subscribe and join the mailing list on [Google Groups][dev-list]. - -### IRC - -OCI discussion happens on #opencontainers on Freenode ([logs][irc-logs]). - -### Git commit - -#### Sign your work - -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 http://developercertificate.org): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -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`. - -#### Commit Style - -Simple house-keeping for clean git history. -Read more on [How to Write a Git Commit Message][how-to-git-commit] or the Discussion section of [git-commit(1)][git-commit.1]. - -1. Separate the subject from body with a blank line -2. Limit the subject line to 50 characters -3. Capitalize the subject line -4. Do not end the subject line with a period -5. Use the imperative mood in the subject line -6. Wrap the body at 72 characters -7. Use the body to explain what and why vs. how - * If there was important/useful/essential conversation or information, copy or include a reference -8. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...") - +See [our contribution documentation](CONTRIBUTING.md). [charter]: https://www.opencontainers.org/about/governance -[code-of-conduct]: https://github.com/opencontainers/tob/blob/master/code-of-conduct.md -[dev-list]: https://groups.google.com/a/opencontainers.org/forum/#!forum/dev -[how-to-git-commit]: http://chris.beams.io/posts/git-commit -[irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/ -[iso-week]: https://en.wikipedia.org/wiki/ISO_week_date#Calculating_the_week_number_of_a_given_date -[minutes]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/ +[code-of-conduct]: https://github.com/opencontainers/tob/blob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md [oci]: https://www.opencontainers.org -[rfc5545]: https://tools.ietf.org/html/rfc5545 -[runtime-wiki]: https://github.com/opencontainers/runtime-spec/wiki -[uberconference]: https://www.uberconference.com/opencontainers - -[git-commit.1]: http://git-scm.com/docs/git-commit diff --git a/meeting.ics b/meeting.ics index 4a0cc03b5..ff1239048 100644 --- a/meeting.ics +++ b/meeting.ics @@ -21,7 +21,7 @@ END:DAYLIGHT END:VTIMEZONE BEGIN:VEVENT UID:tdc-meeting@opencontainers.org -DTSTAMP:20171207T173000Z +DTSTAMP:20180406T200000Z DTSTART;TZID=America/Los_Angeles:20170906T140000 RRULE:FREQ=MONTHLY;INTERVAL=1;BYDAY=1WE RDATE;TZID=America/Los_Angeles:20180110T140000 @@ -30,7 +30,8 @@ DURATION:PT1H SUMMARY:OCI TDC Meeting DESCRIPTION;ALTREP="https://github.com/opencontainers/runtime-spec# meetings":Open Containers Initiative Developer Meeting\n - https://github.com/opencontainers/runtime-spec#meetings\n + https://github.com/opencontainers/runtime-spec/blob/master + /CONTRIBUTING.md#meetings\n Web: https://www.uberconference.com/opencontainers\n Audio-only: +1 415 968 0849 (no PIN needed) LOCATION:https://www.uberconference.com/opencontainers