Merge remote-tracking branch 'origin/master' into tk/restore-hook-lifecycle

After unifying the pre- and post-split hook lifecycle information
(this commit's first parent), merge master to pull in subsequent
mainline evolution.

Conflicts:
    runtime.md

The conflict was a trivial collision with dd0cd21 (Add a 'status'
field to our state struct, 2016-05-26, opencontainers#462).

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

.pullapprove.yml

@@ -2,6 +2,9 @@ approve_by_comment: true
 approve_regex: ^LGTM
 reject_regex: ^Rejected
 reset_on_push: true
+author_approval: ignored
+signed_off_by:
+  required: true
 reviewers:
   teams:
   - runtime-spec-maintainers

.travis.yml

@@ -3,15 +3,19 @@ go:
   - 1.6
   - 1.5.3
 
-sudo: false
+sudo: required
+
+services:
+  - docker
 
 before_install:
   - make install.tools
+  - docker pull vbatts/pandoc
 
 install: true
 
 script:
   - make .govet
   - make .golint
   - make .gitvalidation
-  
+  - make docs

ChangeLog

@@ -1,5 +1,74 @@
 OpenContainers Specifications
 
+Changes with v1.0.0-rc1:
+	Breaking changes:
+
+	* runtime: Split create and start, #384, #450, #463, #464, #467,
+	  #468
+	* runtime: Remove exec, #388
+	* runtime: Enviroment MUST match the configuration, #397
+	* config: Runtime MUST generate errors for unsupported platforms,
+	  #441
+	* config: Windows mount destinations MUST NOT be nested, #437
+
+	Additions:
+
+	* solaris: Added platform-specific configuration, #411, #424, #431,
+	  #436
+	* runtime: Add 'annotations' and 'status' to the state structure,
+	  #462, #484, #485
+	* runtime: State no longer needs to be serialized as JSON, #446
+	* runtime-linux: Add /dev symbolic links, #449
+	* config: Allow absolute paths for root.path (which previously
+	  required relative paths), #394
+	* config-linux: Add linux.mountLabel, #393
+	* config-linux: Add suport for cgroup namespace, #397
+	* config-linux: Runtime SHOULD NOT modify ownership of any
+	  referenced filesystem (previously the restriction only applied to
+	  the root filesystem), #452
+	* specs-go/seccomp: Add ppc and s390x to specs-go/config.go, #475
+
+	Minor fixes and documentation:
+
+	* README: Add project.md to the Table of Contents, #376
+	* README: Consistenly indent the Table of Contents, #400
+	* README: Link to LICENSE, #442
+	* README: Weekly call is OCI-wide, #378
+	* config: Explicit runtime namespace for hooks, #415
+	* config: Explicit container namespace for uid, gid, and
+	  additionalGids, #412
+	* config: Fix 'string' -> 'array of strings' typo for process.args,
+	  #416
+	* runtime: The runtime MAY validate config.json, #418
+	* runtime: Move errors section out of operations, #445
+	* runtime: MAY -> SHOULD for post-stop error logging, #410
+	* schema/README: Document JSON Schema usage, #360, #385
+	* schema: Minor description updates, #456, #461
+	* schema/validate: Support reading documents via stdin, #482
+	* .pullapprove: Automate review approval, #458, #474
+	* .gitignore: Hide more auto-generated files, #386, #392
+	* .travis: git-validation detects Travis now, #366
+	* .travis: Regress on failure to produce docs, #479
+	* Makefile: Filename docs.* -> oci-runtime-spec.*, #478
+	* Makefile: Add install.tools target, #349
+	* Makefile: Allow native pandoc implementations, #428, #448
+	* Makefile: Prefer Bash, #455
+	* Makefile: Travis support for .gitvalidation, #422
+	* specs-go/config: Add missing omitempties for Process.Terminal,
+	  Root.Readonly, Spec.Linux, and Spec.Mounts, #408, #429, #430, #431
+	* specs-go/config: Remove incorrect omitempties for User.UID and
+	  User.GID, #425
+	* specs-go/config: Drop platform-independent comment, #451
+	* version: Include version in generated documentation, #406
+	* *: Anchor examples, #348
+	* *: Fix remnants from SelinuxProcessLabel to SelinuxLabel rename,
+	   #396
+	* *: Outsource code-of-conduct to TOB repository, #375, #413
+	* *: RFC 2119 consistency, #407, #409, #438, #444, #449
+	* *: Typo fixes, #390, #401
+	* *: Whitespace fixes and validation, #380, #381, #426
+	* ROADMAP: Remove stale targets, #435
+
 Changes with v0.5.0:
 	Breaking changes:
 
@@ -277,4 +346,3 @@ Changes with v0.1.0:
 	* Update Typo in ROADMAP.md
 	* Use unsigned for IDs
 	* version: introduce a string for dev indication
-

GOVERNANCE.md

@@ -0,0 +1,70 @@
+# Project governance
+
+The [OCI charter][charter] §5.b.viii tasks an OCI Project's maintainers (listed in the repository's MAINTAINERS file and sometimes referred to as "the TDC", [§5.e][charter]) with:
+
+> Creating, maintaining and enforcing governance guidelines for the TDC, approved by the maintainers, and which shall be posted visibly for the TDC.
+
+This section describes generic rules and procedures for fulfilling that mandate.
+
+## Proposing a motion
+
+A maintainer SHOULD propose a motion on the [email protected] mailing list (except [security issues](#security-issues)) with another maintainer as a co-sponsor.
+
+## Voting
+
+Voting on a proposed motion SHOULD happen on the [email protected] mailing list (except [security issues](#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 feeback), 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.
+
+Voting SHOULD remain open for a week to collect feedback from the wider community and allow the maintainers to digest the proposed motion.
+Under exceptional conditions (e.g. non-major security fix releases) proposals which reach quorum with unanimous support MAY be adopted earlier.
+
+A maintainer MAY choose to reply with REJECT.
+A 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 maintainers SHOULD try to resolve the concerns and wait for the rejecting maintainer to change their opinion to LGTM.
+However, a motion MAY be adopted with REJECTs, as outlined in the previous paragraphs.
+
+## Quorum
+
+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 [email protected] mailing list instead of [email protected], but should otherwise follow the standard [proposal](#proposing-a-motion) process.
+The [email protected] 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 ammended 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).
+
+## Subject templates
+
+Maintainers are busy and get lots of email.
+To make project proposals recognizable, proposed motions SHOULD use the following subject templates.
+
+### Proposing a motion
+
+> [{project} VOTE]: {motion description} (closes {end of voting window})
+
+For example:
+
+> [runtime-spec VOTE]: Tag 0647920 as 1.0.0-rc (closes 2016-06-03 20:00 UTC)
+
+### Tallying results
+
+After voting closes, a maintainer SHOULD post a tally to the motion thread with a subject template like:
+
+> [{project} {status}]: {motion description} (+{LGTMs} -{REJECTs} #{ABSTAINs})
+
+Where `{status}` is either `adopted` or `rejected`.
+For example:
+
+> [runtime-spec adopted]: Tag 0647920 as 1.0.0-rc (+6 -0 #3)
+
+[charter]: https://www.opencontainers.org/about/governance

Makefile

@@ -1,14 +1,17 @@
 
-SHELL  ?= $(shell command -v bash 2>/dev/null)
-DOCKER ?= $(shell command -v docker 2>/dev/null)
-PANDOC ?= $(shell command -v pandoc 2>/dev/null)
+EPOCH_TEST_COMMIT	:= 78e6667ae2d67aad100b28ee9580b41b7a24e667
+OUTPUT_DIRNAME		?= output/
+DOC_FILENAME		?= oci-runtime-spec
+SHELL			?= $(shell command -v bash 2>/dev/null)
+DOCKER			?= $(shell command -v docker 2>/dev/null)
+PANDOC			?= $(shell command -v pandoc 2>/dev/null)
 ifeq "$(strip $(PANDOC))" ''
 	ifneq "$(strip $(DOCKER))" ''
 		PANDOC = $(DOCKER) run \
 			-it \
 			--rm \
 			-v $(shell pwd)/:/input/:ro \
-			-v $(shell pwd)/output/:/output/ \
+			-v $(shell pwd)/$(OUTPUT_DIRNAME)/:/$(OUTPUT_DIRNAME)/ \
 			-u $(shell id -u) \
 			vbatts/pandoc
 		PANDOC_SRC := /input/
@@ -33,23 +36,22 @@ DOC_FILES := \
 	config-linux.md \
 	config-solaris.md \
 	glossary.md
-EPOCH_TEST_COMMIT := 78e6667ae2d67aad100b28ee9580b41b7a24e667
 
 default: docs
 
 .PHONY: docs
-docs: output/docs.pdf output/docs.html
+docs: $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html
 
 ifeq "$(strip $(PANDOC))" ''
-output/docs.pdf output/docs.html:
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html:
 	$(error cannot build $@ without either pandoc or docker)
 else
-output/docs.pdf: $(DOC_FILES)
-	mkdir -p output/ && \
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES)
+	mkdir -p $(OUTPUT_DIRNAME)/ && \
 	$(PANDOC) -f markdown_github -t latex -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
 
-output/docs.html: $(DOC_FILES)
-	mkdir -p output/ && \
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(DOC_FILES)
+	mkdir -p $(OUTPUT_DIRNAME)/ && \
 	$(PANDOC) -f markdown_github -t html5 -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
 endif
 
@@ -111,5 +113,5 @@ endif
 
 .PHONY: clean
 clean:
-	rm -rf output/ *~
+	rm -rf $(OUTPUT_DIRNAME) *~
 

README.md

@@ -75,8 +75,8 @@ When in doubt, start on the [mailing-list](#mailing-list).
 
 ## Weekly Call
 
-The contributors and maintainers of all OCI projects have a weekly meeting Wednesdays at 10:00 AM (USA Pacific.)
-Everyone is welcome to participate via [UberConference web][UberConference] or audio-only: 646-494-8704 (no PIN needed.)
+The contributors and maintainers of all OCI projects have a weekly meeting Wednesdays at 2:00 PM (USA Pacific).
+Everyone is welcome to participate via [UberConference web][UberConference] or audio-only: 415-968-0849 (no PIN needed.)
 An initial agenda will be posted to the [mailing list](#mailing-list) earlier in the week, 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 to the [wiki](https://github.com/opencontainers/runtime-spec/wiki) for those who are unable to join the call.
 
@@ -157,5 +157,5 @@ Read more on [How to Write a Git Commit Message](http://chris.beams.io/posts/git
   * 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: ...")
 
-[UberConference]: https://www.uberconference.com/ssaul
+[UberConference]: https://www.uberconference.com/opencontainers
 [irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/

RELEASES.md

@@ -0,0 +1,51 @@
+# Releases
+
+The release process hopes to encourage early, consistent consensus-building during project 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.
+Releases are proposed and adopted or rejected using the usual [project governance](GOVERNANCE.md) rules and procedures.
+
+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.
+
+## Parallel releases
+
+A single project MAY consider several motions to release in parallel.
+However each motion to release after the initial 0.1.0 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 involve 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 [email protected] 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 a meeting MUST be held within four weeks of the previous meeting.
+
+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 [project governance](GOVERNANCE.md) rules and procedures.
+
+### 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

bundle.md

@@ -5,19 +5,17 @@
 This section defines a format for encoding a container as a *filesystem bundle* - a set of files organized in a certain way, and containing all the necessary data and metadata for any compliant runtime to perform all standard operations against it.
 See also [OS X application bundles](http://en.wikipedia.org/wiki/Bundle_%28OS_X%29) for a similar use of the term *bundle*.
 
-The definition of a bundle is only concerned with how a container, and its configuration data, are stored on a local file system so that it can be consumed by a compliant runtime.
+The definition of a bundle is only concerned with how a container, and its configuration data, are stored on a local filesystem so that it can be consumed by a compliant runtime.
 
 A Standard Container bundle contains all the information needed to load and run a container.
 This MUST include the following artifacts:
 
 1. `config.json` : contains configuration data.
 This REQUIRED file MUST reside in the root of the bundle directory and MUST be named `config.json`.
-When the bundle is packaged up for distribution, this file MUST be included.
 See [`config.json`](config.md) for more details.
 
 2. A directory representing the root filesystem of the container.
 While the name of this REQUIRED directory may be arbitrary, users should consider using a conventional name, such as `rootfs`.
-When the bundle is packaged up for distribution, this directory MUST be included.
 This directory MUST be referenced from within the `config.json` file.
 
 While these artifacts MUST all be present in a single directory on the local filesystem, that directory itself is not part of the bundle.