Docs overhaul #176

vbatts · 2015-09-10T19:11:19Z

I'm sure this will cause a lot to need rebasing, but the layout was killing me.

I'm ready to move the source into a ./ref/go/ directory and start framing up protobuf structs or json-schema for a more canonical use as well, but that can wait for another change.

cc @mrunalp @philips @crosbymichael @LK4D4 @tianon @vishh

vbatts · 2015-09-10T19:11:58Z

View it

vbatts · 2015-09-10T19:14:51Z

so much more is needed, this is just a first pass.
Ideally, the *.md should be all someone needs, and the source is just an example.

wking · 2015-09-10T19:22:27Z

These seem like useful changes, but they're going to be a lot of conflicts with #126. What do I need to do to get some eyeballs on that?

jonboulle · 2015-09-10T19:26:50Z

👍

vbatts · 2015-09-10T19:31:10Z

@wking hrm. there is overlap, but you've got some file renaming too that is not idiomatic.

wking · 2015-09-10T19:38:27Z

On Thu, Sep 10, 2015 at 12:31:12PM -0700, Vincent Batts wrote:

@wking hrm. there is overlap, but you've got some file renaming too
that is not idiomatic.

I tried my best to be idiomatic, but I'm happy to make any adjustments
that folks ask for.

vishh · 2015-09-10T19:40:50Z

LGTM

crosbymichael · 2015-09-17T23:21:38Z

LGTM

@vbatts can you rebase plz?

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

vbatts · 2015-09-18T14:40:44Z

rebased. PTAL.

On Thu, Sep 17, 2015 at 7:21 PM, Michael Crosby notifications@github.com
wrote:

LGTM

@vbatts https://github.com/vbatts can you rebase plz?

—
Reply to this email directly or view it on GitHub
#176 (comment).

wking · 2015-09-18T15:09:30Z

README.md

@@ -1,17 +1,21 @@
 # Open Container Specifications

-This project is where the [Open Container Initiative](http://www.opencontainers.org/) Specifications are written.
-This is a work in progress.
+[Open Container Initiative](http://www.opencontainers.org/) Specifications for standards on Operating System process and application containers.


What are “Operating System process … containers”? If I'm parsing that right (“for standards on ((Operating System process) and application) containers”?).

"open container" while it makes sense to us looking at projects like this and docker, are aware that these containers run on an operating system (https://en.wikipedia.org/wiki/Operating_system).
Those that are searching for "container standards" may get https://en.wikipedia.org/wiki/Intermodal_container or https://en.wikipedia.org/wiki/Containerization.
Further "open container" also has overlap with "Open Container and Consumption Statutes". Neither of these things has to do with operating systems.

On Fri, Sep 25, 2015 at 08:15:03AM -0700, Vincent Batts wrote:

-This project is where the Open Container Initiative Specifications are written.
-This is a work in progress.
+Open Container Initiative Specifications for standards on Operating System process and application containers.

… Neither of these things has to do with operating systems.

How about:

Open Container Initiative Specifications for application containers.
A framework for defining containers on several operating systems and containerization technologies.

To cover both Linux / Windows / … and Linux-containers /
Windows-containers / hypervisor-virtual-hosts/….

On Fri, Sep 25, 2015 at 12:46:43PM -0700, W. Trevor King wrote:

How about…

Ah, I see I'm post-merge ;). I'll file a follow-up PR.

Those are all operating systems...

wking · 2015-09-18T15:26:29Z

On Fri, Sep 18, 2015 at 07:40:45AM -0700, Vincent Batts wrote:

rebased. PTAL.

I left a few copy-edit suggestions with the branch at 159a3ea. The
only involved change would be mirroring something like my 4cfa584
(Move hooks from lifecycle.md to runtime.md, 2015-08-28, #126) to
avoid having duplicate hook documentation in both your runtime.md and
runtime-config.md.

vbatts · 2015-09-25T15:02:26Z

I guess the hook duplication needs cleanup too. Was hoping this would mostly be reorg.

vbatts · 2015-09-25T15:04:59Z

alrighty. I deduped the hook's docs.

Some of the docs were not even linked to, and did not have a logic outline for their grouping. Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

tianon · 2015-09-25T15:48:21Z

LGTM

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

crosbymichael · 2015-09-25T17:10:59Z

LGTM

Docs overhaul

The are not filesystem types, so they don't belong in 'type'. The specs claim mount(2) as inspiration for this modeling (which makes sense, since that's the syscall Linux runtimes will make to implement it), and there (recursive) bind is represented by mountflags (MS_REC | MS_BIND). Currently the 'options' property handles both mount(2)'s mountflags and data, so 'options' is a good spot for these two settings. We may eventually add entries for other mount(8) command-line options (e.g. --move, --make-shared, ...), but I've left those off until someone pitches a motivational use case for them. The example I'm touching used: "type": "bind", ... "options": ["rbind", ...] but I don't see a point to putting 'bind' in 'type' when it's not a filesystem type and you already have 'rbind' in options. We could have stuck closer to that example with an unset type and: "options": ["rbind", ...] and that would have been closer to mount(8)'s --rbind API, but I've gone with "recursive" here to stay closer to mount(2). This will scale better if/when we eventually add options for MS_SLAVE, etc. Since there are existing consumers using the old example format and similar things like: $ git log --oneline -1 | cat 03e8b89 Merge pull request opencontainers#176 from hmeng-19/set_oom_score_adj $ ./ocitools generate --template <(echo '{}') --bind ab:cd:ro | jq '.mounts[0]' { "destination": "cd", "type": "bind", "source": "ab", "options": [ "bind", "ro" ] } this may be a breaking change for some spec consumers (although that ocitools example will still work, because 'options' contains 'bind', which means the 'type' will be ignored). But even if there are broken consumers, we're still pre-1.0, the spec never explained what bind/rbind meant before this commit, and consolidating the Linux mount spec around mount(2) now will make life less confusing in the future. Signed-off-by: W. Trevor King <wking@tremily.us>

They are not filesystem types, so they don't belong in 'type'. The specs claim mount(2) as inspiration for this modeling (which makes sense, since that's the syscall Linux runtimes will make to implement it), and there (recursive) bind is represented by mountflags (MS_REC | MS_BIND). Currently the 'options' property handles both mount(2)'s mountflags and data, so 'options' is a good spot for these two settings. We may eventually add entries for other mount(8) command-line options (e.g. --move, --make-shared, ...), but I've left those off until someone pitches a motivational use case for them. The example I'm touching used: "type": "bind", ... "options": ["rbind", ...] but I don't see a point to putting 'bind' in 'type' when it's not a filesystem type and you already have 'rbind' in 'options'. We could have stuck closer to that example with an unset type and: "options": ["rbind", ...] and that would have been closer to mount(8)'s --rbind API, but I've gone with 'recursive' here to stay closer to mount(2). This will scale better if/when we eventually add options for MS_SLAVE, etc. Since there are existing consumers using the old example format and similar things like: $ git log --oneline -1 | cat 03e8b89 Merge pull request opencontainers#176 from hmeng-19/set_oom_score_adj $ ./ocitools generate --template <(echo '{}') --bind ab:cd:ro | jq '.mounts[0]' { "destination": "cd", "type": "bind", "source": "ab", "options": [ "bind", "ro" ] } this may be a breaking change for some spec consumers (although that ocitools example will still work, because 'options' contains 'bind', which means the 'type' will be ignored). But even if there are broken consumers, we're still pre-1.0, the spec never explained what bind/rbind meant before this commit, and consolidating the Linux mount spec around mount(2) now will make life less confusing in the future. Signed-off-by: W. Trevor King <wking@tremily.us>

They are not filesystem types, so they don't belong in 'type'. The specs claim mount(2) as inspiration for this modeling (which makes sense, since that's the syscall Linux runtimes will make to implement it), and there (recursive) bind is represented by mountflags (MS_REC | MS_BIND). Currently the 'options' property handles both mount(2)'s mountflags and data, so 'options' is a good spot for these two settings. We may eventually add entries for other mount(8) command-line options (e.g. --move, --make-shared, ...), but I've left those off until someone pitches a motivational use case for them. The example I'm touching used: "type": "bind", ... "options": ["rbind", ...] but I don't see a point to putting 'bind' in 'type' when it's not a filesystem type and you already have 'rbind' in 'options'. We could have stuck closer mount(2) by using: "options": ["recursive", "bind", ...] but while that approach extends more conveniently to the other recursive mounts (recursive shared, slave, private, and unbindable mounts), there has been resistance to a direct MS_REC analog [1]. I think that resistance is ungrounded (obviously the kernel and mount(2) feels like a composable MS_REC makes sense), but I'm not a mainainer. Since there are existing consumers using the old example format and similar things like: $ git log --oneline -1 | cat 03e8b89 Merge pull request opencontainers#176 from hmeng-19/set_oom_score_adj $ ./ocitools generate --template <(echo '{}') --bind ab:cd:ro | jq '.mounts[0]' { "destination": "cd", "type": "bind", "source": "ab", "options": [ "bind", "ro" ] } this may be a breaking change for some spec consumers (although that ocitools example will still work, because 'options' contains 'bind', which means the 'type' will be ignored). But even if there are broken consumers, we're still pre-1.0, the spec never explained what bind/rbind meant before this commit, and consolidating the Linux mount spec around mount(8) now will make life less confusing in the future. [1]: opencontainers#530 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

They are not filesystem types, so they don't belong in 'type'. The specs claim mount(2) as inspiration for this modeling (which makes sense, since that's the syscall Linux runtimes will make to implement it), and there (recursive) bind is represented by mountflags (MS_REC | MS_BIND). Currently the 'options' property handles both mount(2)'s mountflags and data, so 'options' is a good spot for these two settings. Before this commit, we were punting this sort of table to mount(8)'s filesystem-independent mount options. With this commit we drop the mount(8) reference and replace it with explicit requirements based on mount(2), as approved by Michael [1]. Personally, I prefer the old mount(8) punt, but have been unable to get (recursive) bind documented without removing it. The option strings still come from mount(8)'s filesytem-independent mount options with the following exceptions: * move, rbind, rprivate, rshared, rslave, and runbindable are exposed in mount(8) through long options (e.g. --move). * (no)acl is listed under filesystem-specific mount options (e.g. for ext2). This commit covers the MS_* entries from [2] with the following exceptions: * MS_VERBOSE, which has been deprecated in favor of MS_SILENT. * MS_KERNMOUNT, since the mount(2) calls won't be kern_mount calls and they are not covered in mount(8). * MS_SUBMOUNT and other flags documented as "internal to the kernel". * MS_RMT_MASK, since it's a mask and not a flag. * MS_MGC_*, since the magic mount flag is ignored since Linux 2.4 according to mount(2). The example I'm touching used: "type": "bind", ... "options": ["rbind", ...] but I don't see a point to putting 'bind' in 'type' when it's not a filesystem type and you already have 'rbind' in 'options'. We could have stuck closer mount(2) by using: "options": ["recursive", "bind", ...] but while that approach extends more conveniently to the other recursive mounts (recursive shared, slave, private, and unbindable mounts), there has been resistance to a direct MS_REC analog [3,4]. I think that resistance is ungrounded (obviously the kernel and mount(2) feels like a composable MS_REC makes sense), but I'm not a mainainer. Since there are existing consumers using the old example format and similar things like runtime-tools: $ git log --oneline -1 | cat 03e8b89 Merge pull request opencontainers#176 from hmeng-19/set_oom_score_adj $ ./ocitools generate --template <(echo '{}') --bind ab:cd:ro | jq '.mounts[0]' { "destination": "cd", "type": "bind", "source": "ab", "options": [ "bind", "ro" ] } this may be a breaking change for some spec consumers (although that ocitools example will still work, because 'options' contains 'bind', which means the 'type' will be ignored). But even if there are broken consumers, we're still pre-1.0, the spec never explained what bind/rbind meant before this commit, and consolidating the Linux mount spec around mount(2) now will make life less confusing in the future. [1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-05-09-20.07.log.html#l-24 [2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/fs.h?id=refs/tags/v4.11#n105 [3]: opencontainers#530 (comment) [4]: opencontainers#771 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

The capitalization in "Container Configuration file" (which we've used since 70372d3, *.md: update TOC and links, 2015-09-10, opencontainers#176) was halfway between "Title Case" and "Sentence case". The current spec isn't particularly consistent (e.g. we have both "Specification version" and "POSIX process"), but the ToC has used "Configuration" for this file since e7be40f (Cleanup the spec a bit to remove WG/git text that's not really part of the spec, 2016-11-14, opencontainers#626) so dodge the sentence/title issue and use that here too. Signed-off-by: W. Trevor King <wking@tremily.us>

The capitalization in "Container Configuration file" (which we've used since 70372d3, *.md: update TOC and links, 2015-09-10, opencontainers#176) was halfway between "Title Case" and "Sentence case". The current spec isn't particularly consistent (e.g. we have both "Specification version" and "POSIX-platform Mounts"), but the ToC has used "Configuration" for this file since e7be40f (Cleanup the spec a bit to remove WG/git text that's not really part of the spec, 2016-11-14, opencontainers#626) so dodge the sentence/title issue and use that here too. Signed-off-by: W. Trevor King <wking@tremily.us>

vbatts added 2 commits September 18, 2015 10:39

README: make header more concise

dbac706

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

principles: Give principles their own home

a28afa1

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

vbatts force-pushed the docs-overhaul branch from 6349c7b to 159a3ea Compare September 18, 2015 14:40

wking reviewed Sep 18, 2015
View reviewed changes

vbatts force-pushed the docs-overhaul branch from 159a3ea to 25cdae2 Compare September 25, 2015 15:04

*.md: update TOC and links

70372d3

Some of the docs were not even linked to, and did not have a logic outline for their grouping. Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

vbatts force-pushed the docs-overhaul branch from 25cdae2 to 3ed2a8d Compare September 25, 2015 15:47

vbatts added 2 commits September 25, 2015 11:50

runtime-config: add section about Hooks

dd6ae21

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

hooks: deduplicate the hooks docs

2d3065b

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

vbatts force-pushed the docs-overhaul branch from 3ed2a8d to 2d3065b Compare September 25, 2015 15:50

crosbymichael added a commit that referenced this pull request Sep 25, 2015

Merge pull request #176 from vbatts/docs-overhaul

03bf64f

Docs overhaul

crosbymichael merged commit 03bf64f into opencontainers:master Sep 25, 2015

vbatts deleted the docs-overhaul branch September 25, 2015 17:28

wking mentioned this pull request Jul 19, 2017

config: Simplify title to "Configuration" #901

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs overhaul #176

Docs overhaul #176

vbatts commented Sep 10, 2015

vbatts commented Sep 10, 2015

vbatts commented Sep 10, 2015

wking commented Sep 10, 2015 via email

jonboulle commented Sep 10, 2015

vbatts commented Sep 10, 2015

wking commented Sep 10, 2015

vishh commented Sep 10, 2015

crosbymichael commented Sep 17, 2015

vbatts commented Sep 18, 2015

wking Sep 18, 2015

vbatts Sep 25, 2015

wking Sep 25, 2015

wking Sep 25, 2015

vbatts Sep 25, 2015

wking commented Sep 18, 2015

vbatts commented Sep 25, 2015

vbatts commented Sep 25, 2015

tianon commented Sep 25, 2015

crosbymichael commented Sep 25, 2015

Docs overhaul #176

Docs overhaul #176

Conversation

vbatts commented Sep 10, 2015

vbatts commented Sep 10, 2015

vbatts commented Sep 10, 2015

wking commented Sep 10, 2015 via email

jonboulle commented Sep 10, 2015

vbatts commented Sep 10, 2015

wking commented Sep 10, 2015

vishh commented Sep 10, 2015

crosbymichael commented Sep 17, 2015

vbatts commented Sep 18, 2015

wking Sep 18, 2015

Choose a reason for hiding this comment

vbatts Sep 25, 2015

Choose a reason for hiding this comment

wking Sep 25, 2015

Choose a reason for hiding this comment

wking Sep 25, 2015

Choose a reason for hiding this comment

vbatts Sep 25, 2015

Choose a reason for hiding this comment

wking commented Sep 18, 2015

vbatts commented Sep 25, 2015

vbatts commented Sep 25, 2015

tianon commented Sep 25, 2015

crosbymichael commented Sep 25, 2015