Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
147 lines (99 loc) · 6.17 KB

CONTRIBUTING.md

File metadata and controls

147 lines (99 loc) · 6.17 KB
Raw

Contributing to the Docs

Thanks for contributing to the documentation repository! The documentation is licensed under Apache 2.0. Before patches are accepted and merged, we require that these relatively simple guidelines be followed:

  • Adhere to the documentation style guidelines
  • Sign your work

Also, read an overview on Technical Writing from Google on authoring good technical content!

Documentation style guidelines

This documentation is authored using reStructuredText as a markup language and uses the Sphinx documentation generator.

Filenames

Use only lowercase alphanumeric characters and hyphens - where required. Filenames are suffixed with the .rst extension.

Headings

Use title case for headings. Refer to https://titlecase.com/ for more information.

The headings follow this convention:

  1. H1 or document title based on # with overline
  2. H2 based on * with overline
  3. H3 based on =
  4. H4 based on -
  5. H5 based on ^
  6. H6 based on "

If you need more levels, then consider creating a new document. A document has only one H1.

Writing Style

Write for a reader who is skimming under time pressure. The following rules come up most often in review.

Make the reader the subject. Start with "you" and an action, not with a gerund or an abstract noun.

  • Instead of: "Using these images removes the need to build and host your own driver image."
  • Write: "You can use these images to avoid building and hosting your own driver image."

Use "must" for requirements. Prefer "must" to "have to be", "has to", or "there is a need to". Prefer "to" over "in order to".

  • Instead of: "Custom images have to be built and hosted by you."
  • Write: "You must build and host custom images."

One idea per sentence. Split a sentence that contrasts two behaviors with "while" or "whereas". Aim for fewer than 30 words.

  • Instead of: "Pinning to the major tag picks up new releases automatically, while pinning to a fixed tag keeps the version constant until you change it."
  • Write: "Pinning to the major tag picks up new releases automatically. Pinning to a fixed tag keeps the version constant until you change it."

Avoid parenthetical asides. Set an example off with commas or move it to its own sentence.

  • Instead of: "Use a fixed tag (for example, 580.65.06) to pin the driver."
  • Write: "Use a fixed tag, such as 580.65.06, to pin the driver."

Re-check nearby statements when a fact changes. If your change adds a supported option, a vendor-provided image, or a new default, read the limitations, notes, and prerequisites around it and remove or narrow any that are no longer true.

Guideline for Kubernetes Object Types in Body Text

Prefer lowercase plain text such as namespace, pod, daemon set, container, service, and so on. This guideline applies to multi-word types like custom resource definition.

Use the camel case name only if you follow the name with object, resource, and so on. For example, "Delete the Pod object..." However, that example is not compelling and is just as clear when written as "Delete the pod..."

Console Outputs

Directives

For console outputs in this document, use code-block:: console directive. This results in a red prompt, which makes it easy to distinguish between the prompt and the command.

Commands

Separate each command into its own code-block. Since this repository uses the Sphinx copy-button to allow for easy copy/pasting of commands by users, it makes sense to separate each command for readability and usage.

If you need to aggregate multiple commands, then use the separator, 2-space indentation and && on each line as shown in the example below:

$ command1 \
    && command2 \
    && command3

Outputs

Separate outputs and commands into their own code-block sequence. Since the repository is configured to copy everything (including items after the prompt lines by setting copybutton_only_copy_prompt_lines to false), it is desirable to only copy commands.

Sign your work

The sign-off is a simple line at the end of the explanation for the patch. Your signature certifies that you wrote the patch or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below (from developercertificate.org):

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

Then you just add a line to every git commit message:

Signed-off-by: Joe Smith <joe.smith@email.com>

Use your real name (sorry, no pseudonyms or anonymous contributions.)

If you set your user.name and user.email git configs, you can sign your commit automatically with git commit -s.