Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

proposals: add release-approval-process #15

Closed
wants to merge 18 commits into from
Closed

proposals: add release-approval-process #15

Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
bdfa70d
proposals: add release-approval-process
Jun 9, 2016
1e3b643
proposal: release-approval-process add some motivation
Jun 10, 2016
66fce91
proposals: release approval process to one week for apps
Jun 14, 2016
da906b9
proposals: release approval process 3 rcs required
Jun 14, 2016
b01dc6c
proposals: release approval process: one month pre-releases
Jun 14, 2016
ff453b6
proposals: release approval process: use consistent language for rejects
Jun 14, 2016
86a3255
proposals: release approval process: clarify utility of GitHub
Jun 14, 2016
d6a6dbe
proposals: release-approval-process: add voting members language
Jun 14, 2016
33d5a19
proposals: release approval process: add quorum language
Jun 15, 2016
78d6c1e
proposals: release approval process: add language about mailing list
Jun 15, 2016
4206adb
proposals: release approval process: add information to projects
Jun 15, 2016
abd3704
proposals: release approval process: improve REJECT feedback
Jun 15, 2016
fb003ff
proposals: release-approval-process: fixup additional typos
Jun 16, 2016
77305d8
release-approval: Shuffle to make more DRY
wking Jun 16, 2016
ebae4ac
release-approval: Add non-spec unanimous quorum reduction
wking Jun 17, 2016
7599a0f
proposals: release-approval-process fix a grammar thing
Jun 22, 2016
9553cfe
proposal: fix a typo
Jun 22, 2016
37088fb
proposals: release approval process explain security@ email
Jun 25, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions proposals/release-approval-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# OCI Project Release Approval Process v1.0

OCI projects need a standard process for making releases so the community of maintainers can consistently know when something can be tagged and released. This approval process hopes to encourage early consistent consensus building during project and specification development. The mechanisms used are regular community communication on the mailing list about progress, scheduled meetings for issue resolution and release triage, and regularly paced and communicated releases. An anti-pattern that we want to avoid is heavy development or discussions "late cycle" around major releases. We want to build a community that is involved and communicates consistently through all releases instead of relying on "silent periods" as a judge of stability.

## List-based voting

**Making a release:** Maintainers (listed in the repository's MAINTAINERS file) MUST announce intentions to release on the dev@opencontainers.org mailing list with another maintainer as a co-sponsor. Voting on proposed releases SHOULD happen on the dev@opencontainers.org mailing list (except [security fixes](#security-fixes)) 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 feeback), but only their final post counts in the final tally. A proposed release passes if two-thirds of votes cast, a quorum having voted, are in favor of the release. A quorum is established when at least two-thirds of maintainers have voted. Voting SHOULD remain open for a week, although under exceptional conditions (e.g. security fixes) non-major releases which reach quorum with unanimous support MAY be released earlier. For projects that are not specifications, a proposed release also passes if the final tally is at least three LGTMs and no REJECTs, even if three votes does not meet the usual two-thirds quorum.

**Rejecting a release:** A project maintainer MAY choose to reply with REJECT. A project maintainer posting a REJECT MUST include a list of concerns or links to written documentation for those concerns (e.g. GitHub issues or mailing-list threads). The project maintainers SHOULD try to resolve the concerns and wait for the rejecting maintainer to change their opinion to LGTM. However, a release MAY pass with REJECTs, as outlined in the previous paragraph.

## Security fixes

Security fix releases MUST use security@opencontainers.org instead of dev@opencontainers.org, but should otherwise follow the standard [list-based voting process](#list-based-voting). The security@opencontainers.org email includes all members of the TOB; the TOB will guide the security sensitive release with project maintainers.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to flesh this out a bit in philips#2, but I'm concerned about two things:

  • If you pull in the TOB, you have to explain how the TOB and maintainers will interact (i.e. what does “guide” mean in your sentence?). I'd rather just have {project}+security@ addresses (e.g. runtime-spec+security@opencontainers.org), and the maintainers can pull in the TOB as they see fit (like always).
  • Who gets advanced notification of security fixes? Do folks who want advanced access apply by mailing the security address? E.g. “please let us know before pushing security fixes so we can patch our system. We have $N users, and you can trust us not to leak/abuse the information because $REASONS”. Where is the list of approved early-contacts maintained (probably not in the public project repo)?


## Parallel proposals

A single repository MAY have several release proposals in parallel. However each proposed release after the first MUST be based on a previous release that has already landed.

For example, runtime-spec maintainers may propose a v1.0.0-rc2 on the 1st of the month and a v0.9.1 bugfix on the 2nd of the month. They may not propose a v1.0.0-rc3 until the v1.0.0-rc2 is accepted (on the 7th if the vote initiated on the 1st passes).

## Specifications

The OCI maintains three categories of projects: specifications, applications, and conformance-testing tools. However, specification releases have special restrictions in the [OCI charter][charter]:

* They are the target of backwards compatibility (§7.g), and
* They are subject to the OFWa patent grant (§8.d and e).

To avoid unfortunate side effects (onerous backwards compatibity requirements or Member resignations), the following additional procedures apply to specification releases:

**Planning a release:** Every OCI specification project SHOULD hold meetings that involves maintainers reviewing pull requests, debating outstanding issues, and planning releases. This meeting MUST be advertised on the project README and MAY happen on a phone call, video conference, or on IRC. Maintainers MUST send updates to the dev@opencontainers.org with results of these meetings. Before the specification reaches v1.0.0, the meetings SHOULD be weekly. Once a specification has reached v1.0.0, the maintainers may alter the cadence, but the meeting cadence MUST NOT be greater than once every four weeks. The release plans, corresponding milestones and estimated due dates MUST be published on GitHub (e.g. https://github.com/opencontainers/runtime-spec/milestones). GitHub milestones and issues are only used for community organization and all releases MUST follow the [list-based voting process](#list-based-voting).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this saying that immediately after releasing v1.0.0 that the weekly call will go to once a month?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On Mon, Jun 27, 2016 at 05:44:09PM -0700, Vincent Batts wrote:

+Planning a release: Every OCI specification project SHOULD
hold meetings that involves maintainers reviewing pull requests,
debating outstanding issues, and planning releases… Before the
specification reaches v1.0.0, the meetings SHOULD be weekly.
Once a specification has reached v1.0.0, the maintainers may
alter the cadence, but the meeting cadence MUST NOT be greater
than once every four weeks…

Is this saying that immediately after releasing v1.0.0 that the
weekly call will go to once a month?

What gives you that impression? I read it as:

a. Maintainers don't have to hold meetings ever if they don't want
(initial SHOULD in my excerpt).
b. Before 1.0, this document recommends spec-project meetings weekly.
c. After 1.0, this document does not have a recommended meeting
frequency.
d. After 1.0, this document sets a maximum meeting frequency of 28
days.

So after 1.0, the project maintainers may opt to transition to four
weeks, but they don't have to.

I agree that the section could be reworded for increased clarity
though. Having a MUST limit on frequency (that only applies after
1.0?) is strange if having meetings at all is only a SHOULD. I'll
file a PR against @philips branch (if he doesn't update it on his own)
once I see how philips#2 works out.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the meeting cadence MUST NOT be greater than once every four weeks
I think more clear language might be:
the gap between meetings MUST NOT be greater than four weeks
/cc @philips, @vbatts, @wking

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On Wed, Jun 29, 2016 at 11:30:45AM -0700, Rob Dolin (MSFT) wrote:

the meeting cadence MUST NOT be greater than once every four weeks

I think more clear language might be:
the gap between meetings MUST NOT be greater than four weeks

I think the tip of this discussion has shifted to [1](no PR for that
yet?) 2. The current wording there tried to address this issue 3,
but I'm fine with the wording you're proposing too.

 Subject: Re: Vote Required: OCI Image Spec Release Process
 Date: Wed, 29 Jun 2016 01:38:07 +0000
 Message-ID: <CAD2oYtPazRCBNHRHGyUt=wAA+=fber0AErqz5rnf4irc=QX9pQ@mail.gmail.com>


**Timelines:** Specifications have a variety of different timelines in their lifecycle.

- Pre-v1.0.0 specifications SHOULD release on a monthly cadence to garner feedback.
- Major specification releases MUST release at least three release candidates spaced a minimum of one week apart. This means a major release like a v1.0.0 or v2.0.0 release will take 1 month at minimum: one week for rc1, one week for rc2, one week for rc3, and one week for the major release itself. Maintainers SHOULD strive to make zero breaking changes during this cycle of release candidates and SHOULD restart the three-candidate count when a breaking change is introduced. For example if a breaking change is introduced in v1.0.0-rc2 then the series would end with v1.0.0-rc4 and v1.0.0.
- Minor and patch releases SHOULD be made on an as-needed basis.

[charter]: https://www.opencontainers.org/about/governance