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

Anchor examples #348

Merged
merged 2 commits into from
Apr 13, 2016
+80 −9
Merged

Anchor examples #348

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
547e00b
*.md: normalize the "example" anchors
vbatts Mar 17, 2016
7dbab77
style: add a section on examples
vbatts Mar 17, 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
16 changes: 9 additions & 7 deletions config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ The OpenContainer spec follows semantic versioning and retains forward and backw
For example, if an implementation is compliant with version 1.0.1 of the spec, it is compatible with the complete 1.x series.
NOTE that there is no guarantee for forward or backward compatibility for version 0.x.

*Example*
### Example

```json
"ociVersion": "0.1.0"
Expand All @@ -28,7 +28,7 @@ Each container has exactly one *root filesystem*, specified in the *root* object
* **`path`** (string, required) Specifies the path to the root filesystem for the container, relative to the path where the manifest is. A directory MUST exist at the relative path declared by the field.
* **`readonly`** (bool, optional) If true then the root filesystem MUST be read-only inside the container. Defaults to false.

*Example*
### Example

```json
"root": {
Expand All @@ -48,7 +48,7 @@ The parameters are similar to the ones in [the Linux mount system call](http://m
* **`source`** (string, required) a device name, but can also be a directory name or a dummy. Windows, the volume name that is the target of the mount point. \\?\Volume\{GUID}\ (on Windows source is called target)
* **`options`** (list of strings, optional) in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab).

### Linux Example
### Example (Linux)

```json
"mounts": [
Expand All @@ -67,7 +67,7 @@ The parameters are similar to the ones in [the Linux mount system call](http://m
]
```

### Windows Example
### Example (Windows)

```json
"mounts": [
Expand Down Expand Up @@ -118,7 +118,7 @@ For Linux-based systems the user structure has the following fields:

_Note: symbolic name for uid and gid, such as uname and gname respectively, are left to upper levels to derive (i.e. `/etc/passwd` parsing, NSS, etc)_

*Example (Linux)*
### Example (Linux)

```json
"process": {
Expand Down Expand Up @@ -159,7 +159,7 @@ _Note: symbolic name for uid and gid, such as uname and gname respectively, are

* **`hostname`** (string, optional) as it is accessible to processes running inside. On Linux, you can only set this if your bundle creates a new [UTS namespace][uts-namespace].

*Example*
### Example

```json
"hostname": "mrsdalloway"
Expand All @@ -170,6 +170,8 @@ _Note: symbolic name for uid and gid, such as uname and gname respectively, are
* **`os`** (string, required) specifies the operating system family this image must run on. Values for os must be in the list specified by the Go Language document for [`$GOOS`](https://golang.org/doc/install/source#environment).
* **`arch`** (string, required) specifies the instruction set for which the binaries in the image have been compiled. Values for arch must be in the list specified by the Go Language document for [`$GOARCH`](https://golang.org/doc/install/source#environment).

### Example

```json
"platform": {
"os": "linux",
Expand Down Expand Up @@ -216,7 +218,7 @@ The post-stop hooks are called after the container process is stopped.
Cleanup or debugging could be performed in such a hook.
If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.

*Example*
### Example

```json
"hooks" : {
Expand Down
8 changes: 6 additions & 2 deletions runtime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ This allows the hooks to perform cleanup and teardown logic after the runtime de
This is provided so that consumers can find the container's configuration and root filesystem on the host.

When serialized in JSON, the format MUST adhere to the following pattern:

```json
{
"ociVersion": "0.2.0",
Expand Down Expand Up @@ -99,8 +100,10 @@ The JSON describing the new process MUST adhere to the [Process configuration](c
This operation MUST create a new process within the scope of the container.
If the container is not running then this operation MUST have no effect on the container and MUST generate an error.
Executing this operation multiple times MUST result in a new process each time.
Example:
```

#### Example

```json
{
"terminal": true,
"user": {
Expand All @@ -118,6 +121,7 @@ Example:
"cwd": "...",
}
```

This specification does not mandate the name of this JSON file.
See the specification of the `config.json` file for the definition of these fields.
The stopping, or exiting, of these secondary process MUST have no effect on the state of the container.
Expand Down
65 changes: 65 additions & 0 deletions style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,70 @@ The redundancy reduction from removing the namespacing prefix is not useful enou
So we have a consistent way to identify unset values ([source][optional-pointer]).
The exceptions are entries where the Go default for the type is a no-op in the spec, in which case `omitempty` is sufficient and no pointer is needed (sources [here][no-pointer-for-slices], [here][no-pointer-for-boolean], and [here][pointer-when-updates-require-changes]).

## Examples

### Anchoring

For any given section that provides a notable example, it is ideal to have it denoted with [markdown headers][markdown-headers].
The level of header should be such that it is a subheader of the header it is an example of.

#### Example

```markdown
## Some Topic

### Some Subheader

#### Further Subheader

##### Example

To use Further Subheader, ...

### Example
Copy link
Contributor

Choose a reason for hiding this comment

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

Maybe clarify that this is an example of “some topic”. And if we prefer Sentence casing or Title Casing, it's probably best to use that throughout this Markdown literal as well.

Copy link
Collaborator

Choose a reason for hiding this comment

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

I agree with @wking. I was confused on first read of lines 28-34 until I read Trevor's comment.

Copy link
Member Author

Choose a reason for hiding this comment

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

this is not all what we do today.


To use Some Topic, ...

```

### Content

Where necessary, the values in the example can be empty or unset, but accommodate with comments regarding this intention.

Where feasible, the content and values used in an example should convey the fullest use of the data structures concerned.
Most commonly onlookers will intend to copy-and-paste a "working example".
If the intention of the example is to be a fully utilized example, rather than a copy-and-paste example, perhaps add a comment as such.

```markdown
### Example
```
```json
{
"foo": null,
"bar": ""
}
```
Copy link
Contributor

Choose a reason for hiding this comment

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

I think this is supposed to be a copy/paste example, but it's lacking the comment you call for above.

Copy link
Member Author

Choose a reason for hiding this comment

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

k

Copy link
Contributor

Choose a reason for hiding this comment

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

My concern here was addressed by 7b289f1 → e49ab0f, which added the
“Following…” comment to the full example. I think this example is
just “what not to do”, showing both the lack of comments and
meaningless values.


**vs.**

```markdown
### Example

Following is a fully populated example (not necessarily for copy/paste use)
```
```json
{
"foo": [
1,
2,
3
],
"bar": "waffles",
"bif": {
"baz": "potatoes"
}
}
```

[capabilities]: config-linux.md#capabilities
[class-id]: config-linux.md#network
Expand All @@ -30,3 +94,4 @@ The exceptions are entries where the Go default for the type is a no-op in the s
[no-pointer-for-slices]: https://github.com/opencontainers/runtime-spec/pull/316/files#r50782982
[optional-pointer]: https://github.com/opencontainers/runtime-spec/pull/233#discussion_r47829711
[pointer-when-updates-require-changes]: https://github.com/opencontainers/runtime-spec/pull/317/files#r50932706
[markdown-headers]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#headings
Copy link
Contributor

Choose a reason for hiding this comment

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

I think this would be a more canonical link, but both are likely authoritative enough for this situation.