Skip to content

Latest commit

 

History

History
224 lines (164 loc) · 7.21 KB

STYLEGUIDE.adoc

File metadata and controls

224 lines (164 loc) · 7.21 KB
Raw

Jenkins Documentation Style Guide

Caution
 This document is still a work in progress.

Terminology

  • Build

  • Job

  • Agent

  • Master

  • Node

  • Pipeline - Scripted Pipeline - Declarative Pipeline

  • Executor

Mixing of these terms is incorrect

When needing to refer to the collection of executors and/or nodes it is best to refer to them collectively as "the Jenkins environment", for example:

[..] they will now execute in parallel assuming the requisite capacity exists in the Jenkins environment.

As opposed to "the Jenkins cluster", "agent pool" or any other phrase to describe the collective set of resources provided by Jenkins.

Pipeline

When referring to a Jenkins Pipeline via short-hand ("Pipeline"), it should always be title-cased. When referring to a conceptual pipeline ("continuous delivery pipeline"), it it should always be lower-cased.

With the Declarative Pipeline beta there are two different syntaxes for Pipeline which must be referred to when writing about the subject. When referring to the entire system, "Jenkins Pipeline" or "Pipeline" should be used. When referring to a specific sytnax, the following should be used.

Scripted Pipeline

functionality defined a fully-featured, turing-complete, expressive, and extensible Groovy-based DSL. Scripted Pipeline preceeded Declarative Pipeline so most older documentation generally refers to Scripted Pipeline.

Declarative Pipeline

functionality provided by the Pipeline Model Definition plugin. Declarative Pipeline is not a fully-featured, turing-complete, DSL but rather a strict subset of Groovy syntax.

Conventional Terms/Phrases

Syntax/Formatting

Below are some tips for keeping documentation consistently formatted to ensure that documentation follows the same "behaviors" across multiple documents and authors.

  1. Whenever referring to a file, directory or inline snippet of code put the entity inside of a pair of backticks. For example:

"Add the following snippet to the Jenkinsfile in the project’s root directory"

Add the following snippet to the `Jenkinsfile` in the project's root directory

Source code

All source code except Pipeline source code should use the [source] block macro, with the language specified in order ensure the code block has its syntax highlighted appropriately:

[source, groovy]
----
[1, 2, 3].each { println it }
----

Becomes:

[1, 2, 3].each { println it }

Pipeline code

There is a special AsciiDoctor extension located in lib/asciidoctor/extensions which adds the [pipeline] block for including Pipeline code. This block supports both Declarative Pipeline and Pipeline Script syntax. For example:

[pipeline]
----
// Script //
node {
    stage('Build') {
      checkout scm
      // Install dependencies
      sh 'npm install'
    }
}

// Declarative //
pipeline {
    agent docker: 'node:6.3'
    stages {
        stage('Build') {
            sh 'npm install'
        }
    }
}
----

This pipeline block will prefer the Declarative Pipeline syntax when rendering, and provide a link for toggling the Scripted Pipeline.

The // Declarative // or // Script // delimiters are MANDATORY, even when defining a [pipeline] block with only one syntax supported. These delimiters instruct the extension on how to render the given code.

Javadoc links

The javadoc inline macro can be used to link to the Jenkins Javadoc at http://javadoc.jenkins-ci.org/.

It supports a variety of different syntaxes:

  • javadoc:hudson.scm.SCM[] links to the full URL for the class.

  • javadoc:hudson.scm.SCM#all()[] links to the full URL for the class, and includes a fragment.

  • javadoc:SCM[] links to the /byShortName URL for the class. Due to the redirect, fragments won’t work here.

By default, all of these use the class name as label, but that can be customized if necessary by providing an alternative label between the square brackets.

javadoc:hudson.scm.SCM#all()[a list of all known SCM implementations]

Handbook Style Guide

  • For consecutive sections that are related to or build on each other, there should be a reasonable "intro" or preamble at the beginning of one section and a reasonable "outtro" at the end, to provide continuity between the documents

Assorted comments

  • Prefer "for example" over "e.g." which can be more clear to non-native english readers

  • Don’t use unordered lists (bullets) in place of section headers. Section headers offer a nesting/association of content in a way lists cannot

  • If you write a sentence such as "there are three ways to do this:" and then intend to follow that statement with a list, use a numbered list

    • If you are providing a list of "two ways", each description of a "way" should follow the same structure, for example:

By default, new agents can be connected to Jenkins with one of
following four methods:

. Via SSH, requires that the master be able to connect directly to an
  agent machine and have valid authentication credentials. The agent must have an
  SSH daemon running.
. Via Java Web Start, requires no special configuration on the master. The agent
  must be able to connect to the Jenkins master and have a Java runtime.installed.
. Via command execution on the master, requires a command to be executable by
  the Jenkins system user on the master. This method is generally used to support
  more advanced invocations of the agent `.jar`.
. Via a Windows service, requires that the master is a Windows machine and has
  access to built-in link:http://en.wikipedia.org/wiki/Windows_Management_Instrumentation[Windows remote management facilities]

Note that each line item generally follows the same structure of "method, master requirements, agent requirements." While not strictly required, this structuring can help readers compare and contrast the various options to make an informed decision on which path is suitable for them.

  • Titles should only have the first letter intentionally capitalized ("sentence case"). This ensures that casing of articles and prepositions, mixed with proper nouns, doesn’t get too confusing. For example: "Starting a JNLP Agent on Windows" versus "Starting A JNLP Agent On Windows" versus "Starting a JNLP agent on Windows". The latter will result in the most consistent titles.

  • Use American English

  • Only proper nouns should be capitalized, for example "Windows." But not "Windows Server" unless, of course, you’re referring to a product named "Windows Server."

  • Prefer explicit words/phrases over acronyms, for example:

and the stage names will be displayed as columns in the Stage View UI.

"UI" can me a lot of different things, the CLI is a "UI", the Pipeline script itself is a "UI," the Script Console is a "UI" and of course the web interface is also a "UI."

The statement above is better written as:

and the stage names will be displayed as columns in the Stage View web interface