diff --git a/.gitignore b/.gitignore index 0e1950011..f9663c923 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ output schema/validate -code-of-conduct.md version.md diff --git a/Makefile b/Makefile index d4a82278a..7188d1720 100644 --- a/Makefile +++ b/Makefile @@ -21,13 +21,8 @@ endif # These docs are in an order that determines how they show up in the PDF/HTML docs. DOC_FILES := \ version.md \ - README.md \ - code-of-conduct.md \ + spec.md \ principles.md \ - style.md \ - ROADMAP.md \ - implementations.md \ - project.md \ bundle.md \ runtime.md \ runtime-linux.md \ @@ -54,9 +49,6 @@ $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(DOC_FILES) $(PANDOC) -f markdown_github -t html5 -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES)) endif -code-of-conduct.md: - curl -o $@ https://raw.githubusercontent.com/opencontainers/tob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md - version.md: ./specs-go/version.go go run ./.tool/version-doc.go > $@ @@ -105,5 +97,5 @@ endif .PHONY: clean clean: rm -rf $(OUTPUT_DIRNAME) *~ - rm -f code-of-conduct.md version.md + rm -f version.md diff --git a/README.md b/README.md index d00a879cc..da17b22f0 100644 --- a/README.md +++ b/README.md @@ -2,38 +2,17 @@ The [Open Container Initiative](http://www.opencontainers.org/) develops specifications for standards on Operating System process and application containers. +The specification can be found [here](spec.md). -Table of Contents - -- [Introduction](README.md) - - [Code of Conduct](#code-of-conduct) - - [Container Principles](principles.md) - - [Style and Conventions](style.md) - - [Roadmap](ROADMAP.md) - - [Implementations](implementations.md) - - [project](project.md) -- [Filesystem Bundle](bundle.md) -- Runtime and Lifecycle - - [General Runtime and Lifecycle](runtime.md) - - [Linux-specific Runtime and Lifecycle](runtime-linux.md) -- Configuration - - [General Configuration](config.md) - - [Linux-specific Configuration](config-linux.md) - - [Solaris-specific Configuration](config-solaris.md) - - [Windows-specific Configuration](config-windows.md) -- [Glossary](glossary.md) - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119][rfc2119]. - -The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified]. - -An implementation is not compliant for a given CPU architecture if it fails to satisfy one or more of the MUST, REQUIRED, or SHALL requirements for the protocols it implements. -An implementation is compliant for a given CPU architecture if it satisfies all the MUST, REQUIRED, and SHALL requirements for the protocols it implements. - -Protocols defined by this specification are: -* Linux containers: [runtime.md](runtime.md), [config.md](config.md), [config-linux.md](config-linux.md), and [runtime-linux.md](runtime-linux.md). -* Solaris containers: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md). -* Windows containers: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md). +[charter]: https://www.opencontainers.org/about/governance + +Additional documentation about how this group operates: + +- [Code of Conduct](https://github.com/opencontainers/tob/blob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md) +- [Style and Conventions](style.md) +- [Roadmap](ROADMAP.md) +- [Implementations](implementations.md) +- [Releases](RELEASES.md) # Use Cases @@ -66,10 +45,6 @@ Issues are used for bugs and actionable items and longer discussions can happen The specification and code is licensed under the Apache 2.0 license found in the [LICENSE](./LICENSE) file. -## Code of Conduct - -Participation in the OCI community is governed by the [OCI Code of Conduct](https://github.com/opencontainers/tob/blob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md). - ## Discuss your design The project welcomes submissions, but please let everyone know what you are working on. diff --git a/RELEASES.md b/RELEASES.md index e220042c8..440fcc7f8 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -7,6 +7,14 @@ Releases are proposed and adopted or rejected using the usual [project governanc 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. +## Release Process + +* Increment version in [`specs-go/version.go`](specs-go/version.go) +* `git commit` version increment +* `git tag` the prior commit (preferably signed tag) +* `make docs` to produce PDF and HTML copies of the spec +* Make a release on [github.com/opencontainers/runtime-spec](https://github.com/opencontainers/runtime-spec/releases) for the version. Attach the produced docs. + ## Parallel releases A single project MAY consider several motions to release in parallel. @@ -47,5 +55,3 @@ Specifications have a variety of different timelines in their lifecycle. 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 diff --git a/config-linux.md b/config-linux.md index 4751b3e90..b665a4ca1 100644 --- a/config-linux.md +++ b/config-linux.md @@ -562,7 +562,7 @@ Its value is either slave, private, or shared. ## Masked Paths **`maskedPaths`** (array of strings, OPTIONAL) will mask over the provided paths inside the container so that they cannot be read. -The values MUST be absolute paths in the [container namespace][container-namespace]. +The values MUST be absolute paths in the [container namespace][container-namespace2]. ###### Example @@ -575,7 +575,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa ## Readonly Paths **`readonlyPaths`** (array of strings, OPTIONAL) will set the provided paths as readonly inside the container. -The values MUST be absolute paths in the [container namespace][container-namespace]. +The values MUST be absolute paths in the [container namespace][container-namespace2]. ###### Example @@ -595,7 +595,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa "mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811" ``` -[container-namespace]: glossary.md#container_namespace +[container-namespace2]: glossary.md#container_namespace [cgroup-v1]: https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt [cgroup-v1-blkio]: https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt [cgroup-v1-cpusets]: https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt diff --git a/project.md b/project.md deleted file mode 100644 index 2f8f0767d..000000000 --- a/project.md +++ /dev/null @@ -1,10 +0,0 @@ -# Project docs - -## Release Process - -* Increment version in [`specs-go/version.go`](specs-go/version.go) -* `git commit` version increment -* `git tag` the prior commit (preferably signed tag) -* `make docs` to produce PDF and HTML copies of the spec -* Make a release on [github.com/opencontainers/runtime-spec](https://github.com/opencontainers/runtime-spec/releases) for the version. Attach the produced docs. - diff --git a/spec.md b/spec.md new file mode 100644 index 000000000..386cc1d5d --- /dev/null +++ b/spec.md @@ -0,0 +1,33 @@ +# Open Container Initiative Runtime Specification + +The [Open Container Initiative](http://www.opencontainers.org/) develops specifications for standards on Operating System process and application containers. + +Protocols defined by this specification are: +* Linux containers: [runtime.md](runtime.md), [config.md](config.md), [config-linux.md](config-linux.md), and [runtime-linux.md](runtime-linux.md). +* Solaris containers: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md). +* Windows containers: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md). + +# Table of Contents + +- [Introduction](spec.md) + - [Notational Conventions](#notational-conventions) + - [Container Principles](principles.md) +- [Filesystem Bundle](bundle.md) +- [Runtime and Lifecycle](runtime.md) + - [Linux-specific Runtime and Lifecycle](runtime-linux.md) +- [Configuration](config.md) + - [Linux-specific Configuration](config-linux.md) + - [Solaris-specific Configuration](config-solaris.md) + - [Windows-specific Configuration](config-windows.md) +- [Glossary](glossary.md) + +# Notational Conventions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119][rfc2119]. + +The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified]. + +An implementation is not compliant for a given CPU architecture if it fails to satisfy one or more of the MUST, REQUIRED, or SHALL requirements for the protocols it implements. +An implementation is compliant for a given CPU architecture if it satisfies all the MUST, REQUIRED, and SHALL requirements for the protocols it implements. + +[rfc2119]: http://tools.ietf.org/html/rfc2119