Skip to content

Latest commit

 

History

History
286 lines (208 loc) · 9.69 KB

STYLEGUIDE.adoc

File metadata and controls

286 lines (208 loc) · 9.69 KB
Raw

Jenkins Documentation Style Guide

Caution
 This document is still a work in progress.

Terminology

  • Build

  • Job

  • Agent

  • Controller

  • 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.

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 syntax, the following should be used.

Scripted Pipeline

functionality defined a fully-featured, turing-complete, expressive, and extensible Groovy-based DSL. Scripted Pipeline preceded 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') {
      // Install dependencies
      sh 'npm install'
    }
}

// Declarative //
pipeline {
    agent { docker { image 'node:20.9.0-alpine3.18' } }
    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 jenkinsdoc inline macro can be used to link to the Jenkins Javadoc at https://javadoc.jenkins.io/.

It supports a variety of different syntaxes. For classes in Jenkins core:

  • jenkinsdoc:hudson.scm.SCM[] links to the full URL for the class in Jenkins core.

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

  • jenkinsdoc:SCM[] links to the /byShortName URL for the class in Jenkins core. 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.

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

For classes in plugins, the plugin’s name (artifactId) is put before the class name and separated by colon:

  • jenkinsdoc:git:hudson.plugins.git.GitSCM[] links to the full URL for the class in the git plugin.

  • jenkinsdoc:git:hudson.plugins.git.GitSCM#getRepositories--[] links to the full URL for the class in the git plugin, and includes a fragment.

These use a similar default label if none is set, but it also specified which plugin the class is in. For the previous example, that label would be hudson.plugins.git.GitSCM in git.

Two other inline macros, staplerdoc and javadoc exist and link to the Stapler API documentation and Java API documentation, respectively. These do not support the form of jenkinsci that only requires the short name, but otherwise work the same way. Examples:

javadoc:java.io.File#pathSeparator[the path separator]
staplerdoc:org.kohsuke.stapler.AncestorInPath[]

References to plugins

The plugin inline macro can be used to link to plugins on the plugins index at https://plugins.jenkins.io/.

Example:

plugin:git[The Git Plugin]

Handbook Style Guide

  • For consecutive sections that are related to or build on each other, include a reasonable "introduction" or preamble at the beginning of each section and a reasonable "closing" at the end, to provide continuity between the documents

Links and References

Asciidoc supports a number of types of links.

"Cross-references" provide a convenient way to add links between sections and pages of the current project. Asciidoc only supports "internal cross-references", linking to other sections within a page. AsciiDoctor adds the ability to do "inter-document cross-references", linking to sections on other pages. Internal and inter-document cross-references share the same basic syntax: <<target-string, display text>>.

Cross-references behave as follows:

Table 1. Cross-references
Type target-string Input Equivalent link text

Internal

does not contain #

<<section, display text>>

link:#section[display text]

Inter-document

contains #

<<page#section, display text>>

link:../page/#section[display text]

Invalid

starts with #

display text

display text (raw text)
Note
 The presence of slashes or dots (/, ./, or ../) has no effect on cross-reference behavior. The reference <<../using#, see "Using">> creates an inter-document reference to another page (link:../using/[see "Using"]). The reference <<../using, see "Using">> (without the #) creates an internal reference to an anchor on the current page (link:#../using[see "Using"]).

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 controller 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 controller. The agent
  must be able to connect to the Jenkins controller and have a Java runtime.installed.
. Via command execution on the controller, requires a command to be executable by
  the Jenkins system user on the controller. This method is generally used to support
  more advanced invocations of the agent `.jar`.
. Via a Windows service, requires that the controller is a Windows machine and has
  access to built-in link:https://en.wikipedia.org/wiki/Windows_Management_Instrumentation[Windows remote management facilities]

Note that each line item generally follows the same structure of "method, controller 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