Merge pull request #768 from asears/md-doc-lint-updates-3

Fix linting issues in docs, add headers to json example, update errors into table
containernetworking · Jun 10, 2020 · 11db36c · 11db36c
2 parents 0016c95 + 9ec274a
commit 11db36c
Show file tree

Hide file tree

Showing 4 changed files with 78 additions and 48 deletions.
diff --git a/CODE-OF-CONDUCT.md b/CODE-OF-CONDUCT.md
@@ -1,4 +1,3 @@
-## Community Code of Conduct
+# Community Code of Conduct
 
 CNI follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
-
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,14 +7,14 @@ it easier to get your contribution accepted.
 
 We gratefully welcome improvements to documentation as well as to code.
 
-# Certificate of Origin
+## Certificate of Origin
 
 By contributing to this project you agree to the Developer Certificate of
 Origin (DCO). This document was created by the Linux Kernel community and is a
 simple statement that you, as a contributor, have the legal right to make the
 contribution. See the [DCO](DCO) file for details.
 
-# Email and Chat
+## Email and Chat
 
 The project uses the cni-dev email list, IRC chat, and Slack:
 - Email: [cni-dev](https://groups.google.com/forum/#!forum/cni-dev)
@@ -39,14 +39,15 @@ This is a rough outline of how to prepare a contribution:
 - Make sure your commit messages are in the proper format (see below).
 - Push your changes to a topic branch in your fork of the repository.
 - If you changed code:
-   - add automated tests to cover your changes, using the [Ginkgo](https://onsi.github.io/ginkgo/) & [Gomega](https://onsi.github.io/gomega/) style
-   - if the package did not previously have any test coverage, add it to the list
+  - add automated tests to cover your changes, using the [Ginkgo](https://onsi.github.io/ginkgo/) & [Gomega](https://onsi.github.io/gomega/) style
+  - if the package did not previously have any test coverage, add it to the list
    of `TESTABLE` packages in the `test.sh` script.
-   - run the full test script and ensure it passes
+  - run the full test script and ensure it passes
 - Make sure any new code files have a license header (this is now enforced by automated tests)
 - Submit a pull request to the original repository.
 
 ## How to run the test suite
+
 We generally require test coverage of any new features or bug fixes.
 
 Here's how you can run the test suite on any system (even Mac or Windows) using
@@ -67,15 +68,15 @@ cd libcni
 go test
 ```
 
-# Acceptance policy
+## Acceptance policy
 
 These things will make a PR more likely to be accepted:
 
- * a well-described requirement
- * tests for new code
- * tests for old code!
- * new code and tests follow the conventions in old code and tests
- * a good commit message (see below)
+- a well-described requirement
+- tests for new code
+- tests for old code!
+- new code and tests follow the conventions in old code and tests
+- a good commit message (see below)
 
 In general, we will merge a PR once two maintainers have endorsed it.
 Trivial changes (e.g., corrections to spelling) may get waved through.
@@ -87,7 +88,7 @@ We follow a rough convention for commit messages that is designed to answer two
 questions: what changed and why. The subject line should feature the what and
 the body of the commit should describe the why.
 
-```
+```md
 scripts: add the test-cluster command
 
 this uses tmux to setup a test cluster that you can easily kill and
@@ -98,7 +99,7 @@ Fixes #38
 
 The format can be described more formally as follows:
 
-```
+```md
 <subsystem>: <what changed>
 <BLANK LINE>
 <why this change was made>
@@ -112,6 +113,7 @@ This allows the message to be easier to read on GitHub as well as in various
 git tools.
 
 ## 3rd party plugins
+
 So you've built a CNI plugin.  Where should it live?
 
 Short answer: We'd be happy to link to it from our [list of 3rd party plugins](README.md#3rd-party-plugins).

diff --git a/RELEASING.md b/RELEASING.md
@@ -1,6 +1,7 @@
 # Release process
 
 ## Resulting artifacts
+
 Creating a new release produces the following artifacts:
 
 - Binaries (stored in the `release-<TAG>` directory) :
@@ -9,26 +10,31 @@ Creating a new release produces the following artifacts:
   - `sha1`, `sha256` and `sha512` files for the above files.
 
 ## Preparing for a release
+
 1. Releases are performed by maintainers and should usually be discussed and planned at a maintainer meeting.
-  - Choose the version number. It should be prefixed with `v`, e.g. `v1.2.3`
-  - Take a quick scan through the PRs and issues to make sure there isn't anything crucial that _must_ be in the next release.
-  - Create a draft of the release note
-  - Discuss the level of testing that's needed and create a test plan if sensible
-  - Check what version of `go` is used in the build container, updating it if there's a new stable release.
+
+   - Choose the version number. It should be prefixed with `v`, e.g. `v1.2.3`
+   - Take a quick scan through the PRs and issues to make sure there isn't anything crucial that _must_ be in the next release.
+   - Create a draft of the release note
+   - Discuss the level of testing that's needed and create a test plan if sensible
+   - Check what version of `go` is used in the build container, updating it if there's a new stable release.
 
 ## Creating the release artifacts
+
 1. Make sure you are on the master branch and don't have any local uncommitted changes.
 1. Create a signed tag for the release `git tag -s $VERSION` (Ensure that GPG keys are created and added to GitHub)
 1. Run the release script from the root of the repository
-  - `scripts/release.sh`
-  - The script requires Docker and ensures that a consistent environment is used.
-  - The artifacts will now be present in the `release-<TAG>` directory.
+
+   - `scripts/release.sh`
+   - The script requires Docker and ensures that a consistent environment is used.
+   - The artifacts will now be present in the `release-<TAG>` directory.
+
 1. Test these binaries according to the test plan.
 
 ## Publishing the release
+
 1. Push the tag to git `git push origin <TAG>`
 1. Create a release on Github, using the tag which was just pushed.
 1. Attach all the artifacts from the release directory.
 1. Add the release note to the release.
 1. Announce the release on at least the CNI mailing, IRC and Slack.
-
diff --git a/SPEC.md b/SPEC.md
@@ -1,18 +1,31 @@
 # Container Network Interface Specification
 
-- [Version](#version)
-- [Overview](#overview)
-- [General considerations](#general-considerations)
-- [CNI Plugin](#cni-plugin)
-  * [Overview](#overview-1)
-  * [Parameters](#parameters)
-  * [Result](#result)
-  * [Network Configuration](#network-configuration)
-  * [Example configurations](#example-configurations)
-  * [Network Configuration Lists](#network-configuration-lists)
-  * [IP Allocation](#ip-allocation)
-  * [Well-known Structures](#well-known-structures)
-- [Well-known Error Codes](#well-known-error-codes)
+- [Container Network Interface Specification](#container-network-interface-specification)
+  - [Version](#version)
+      - [Released versions](#released-versions)
+  - [Overview](#overview)
+  - [General considerations](#general-considerations)
+  - [CNI Plugin](#cni-plugin)
+    - [Overview](#overview-1)
+    - [Parameters](#parameters)
+    - [Result](#result)
+    - [Network Configuration](#network-configuration)
+    - [Example configurations](#example-configurations)
+      - [Example bridge configuration](#example-bridge-configuration)
+      - [Example ovs configuration](#example-ovs-configuration)
+      - [Example macvlan configuration](#example-macvlan-configuration)
+    - [Network Configuration Lists](#network-configuration-lists)
+      - [Network Configuration List Error Handling](#network-configuration-list-error-handling)
+      - [Example network configuration lists](#example-network-configuration-lists)
+      - [Network configuration list runtime examples](#network-configuration-list-runtime-examples)
+    - [IP Allocation](#ip-allocation)
+      - [IP Address Management (IPAM) Interface](#ip-address-management-ipam-interface)
+      - [Notes](#notes)
+    - [Well-known Structures](#well-known-structures)
+      - [IPs](#ips)
+      - [Routes](#routes)
+      - [DNS](#dns)
+  - [Well-known Error Codes](#well-known-error-codes)
 
 ## Version
 
@@ -146,6 +159,7 @@ Plugins should generally complete a `DEL` action without error even if some reso
 
 Runtimes must use the type of network (see [Network Configuration](#network-configuration) below) as the name of the executable to invoke.
 Runtimes should then look for this executable in a list of predefined directories (the list of directories is not prescribed by this specification). Once found, it must invoke the executable using the following environment variables for argument passing:
+
 - `CNI_COMMAND`: indicates the desired operation; `ADD`, `DEL`, `CHECK`, or `VERSION`.
 - `CNI_CONTAINERID`: Container ID
 - `CNI_NETNS`: Path to network namespace file
@@ -255,6 +269,8 @@ Plugins may define additional fields that they accept and may generate an error
 
 ### Example configurations
 
+#### Example bridge configuration
+
 ```jsonc
 {
   "cniVersion": "0.4.0",
@@ -274,6 +290,8 @@ Plugins may define additional fields that they accept and may generate an error
 }
 ```
 
+#### Example ovs configuration
+
 ```jsonc
 {
   "cniVersion": "0.4.0",
@@ -295,6 +313,8 @@ Plugins may define additional fields that they accept and may generate an error
 }
 ```
 
+#### Example macvlan configuration
+
 ```jsonc
 {
   "cniVersion": "0.4.0",
@@ -317,6 +337,7 @@ Network configuration lists provide a mechanism to run multiple CNI plugins for
 The list is composed of well-known fields and list of one or more standard CNI network configurations (see above).
 
 The list is described in JSON form, and can be stored on disk or generated from other sources by the container runtime. The following fields are well-known and have the following meaning:
+
 - `cniVersion` (string): [Semantic Version 2.0](https://semver.org) of CNI specification to which this configuration list and all the individual configurations conform.
 - `name` (string): Network name. This should be unique across all containers on the host (or other administrative domain).  Must start with a alphanumeric character, optionally followed by any combination of one or more alphanumeric characters, underscore (_), dot (.) or hyphen (-).
 - `disableCheck` (string): Either `true` or `false`.  If `disableCheck` is `true`, runtimes must not call `CHECK` for this network configuration list.  This allows an administrator to prevent `CHECK`ing where a combination of plugins is known to return spurious errors.
@@ -567,16 +588,16 @@ Note that plugins are executed in reverse order from the `ADD` and `CHECK` actio
     "interfaces": [
         {
             "name": "cni0",
-            "mac": "00:11:22:33:44:55",
+            "mac": "00:11:22:33:44:55"
         },
         {
             "name": "veth3243",
-            "mac": "55:44:33:22:11:11",
+            "mac": "55:44:33:22:11:11"
         },
         {
             "name": "eth0",
             "mac": "99:88:77:66:55:44",
-            "sandbox": "/var/run/netns/blue",
+            "sandbox": "/var/run/netns/blue"
         }
     ],
     "dns": {
@@ -768,11 +789,13 @@ The `dns` field contains a dictionary consisting of common DNS information.
 
 Error codes 1-99 must not be used other than as specified here.
 
-- `1` - Incompatible CNI version
-- `2` - Unsupported field in network configuration. The error message must contain the key and value of the unsupported field.
-- `3` - Container unknown or does not exist. This error implies the runtime does not need to perform any container network cleanup (for example, calling the `DEL` action on the container).
-- `4` - Invalid necessary environment variables, like CNI_COMMAND, CNI_CONTAINERID, etc. The error message must contain the names of invalid variables.
-- `5` - I/O failure. For example, failed to read network config bytes from stdin.
-- `6` - Failed to decode content. For example, failed to unmarshal network config from bytes or failed to decode version info from string.
-- `7` - Invalid network config. If some validations on network configs do not pass, this error will be raised.
-- `11` - Try again later. If the plugin detects some transient condition that should clear up, it can use this code to notify the runtime it should re-try the operation later.
+Error Code|Error Description
+---|---
+`-1`|Incompatible CNI version
+`-2`|Unsupported field in network configuration. The error message must contain the key and value of the unsupported field.
+`-3`|Container unknown or does not exist. This error implies the runtime does not need to perform any container network cleanup (for example, calling the `DEL` action on the container).
+`-4`|Invalid necessary environment variables, like CNI_COMMAND, CNI_CONTAINERID, etc. The error message must contain the names of invalid variables.
+`-5`|I/O failure. For example, failed to read network config bytes from stdin.
+`-6`|Failed to decode content. For example, failed to unmarshal network config from bytes or failed to decode version info from string.
+`-7`|Invalid network config. If some validations on network configs do not pass, this error will be raised.
+`-11`|Try again later. If the plugin detects some transient condition that should clear up, it can use this code to notify the runtime it should re-try the operation later.