Plugin Documentation

Documentation is an important part of any Jenkins plugin. It includes user documentation (plugin pages, changelogs, user guidelines, etc.) and the contributor documentation (how to contribute, developer guidelines, etc.). This section provides overview of these documentation types.

Plugin pages

Plugin pages are hosted on the Plugin Site. These pages are generated automatically using the metadata from the latest plugin release and an external documentation page. External documentation can be retrieved from GitHub or from the Jenkins Wiki.

For new plugins we recommend storing documentation in the GitHub repositories. It allows plugin maintainers to provide the same documentation from README pages and the Jenkins plugin site, and at the same time it allows using the Documentation-as-Code techniques when the documentation is a part of the repository and hence all common practices can be applied:

  • Pull requests and reviews

  • Creating documentation in parallel with features

  • Editing docs from GitHub Web UI, with preview support

  • Versioning, documentation for previous plugin versions can be easily accessed

Using GitHub as a source of documentation

The plugin site can pull documentation from the root README pages or from other locations defined by the plugin URL (see below). Multiple formats are supported: GitHub Flavored Markdown, Asciidoc or raw text.

To publish the plugin documentation on GitHub:

  1. Create a README page and put the plugin documentation there. This page will become a landing page for the Plugin site.

    • More documentation pages can be introduced inside the repository and linked from the README, the plugin site will display both absolute and relative links

    • Images from pages will be displayed by the plugin site as well

  2. Modify your project URL to point to the GitHub repository, e.g. http://github.com/jenkinsci/your-plugin. See the guidelines for Maven and Gradle below.

  3. Release the new plugin version. Once the plugin site picks up the release (which can take up to a few hours) it will also display the documentation from GitHub.

Documentation examples:

Using Jenkins Wiki as source of documentation

Jenkins Wiki can still be used for previously created plugins or for new plugins if there are reasons to do so. See this page for more information. It also include Wiki⇒GitHub migration guidelines.

Referencing the documentation page from the project file

You should link to your plugin’s documentation, whether on the wiki or elsewhere, in your plugin’s pom.xml, like this:

<project>
  ...
  <url>http://github.com/jenkinsci/your-plugin</url>
  ...
</project>

If you’re building your plugin with Gradle, you can set the URL in your build.gradle like so:

jenkinsPlugin {
  // ...
  url = 'http://github.com/jenkinsci/your-plugin'
  // ...
}

Maintainer Information

Maintainer information is listed for every plugin on the plugin site. It is currently sourced from the Maven metadata.

There is a plan to use repository-permissions-updater, See WEBSITE-658 in the issue tracker. Once it is implemented, the guidelines below will changed.

In your POM, make sure to include developer information, such as:

<project>
  ...
  <developers>
    <developer>
      <id>exampleauthor</id>
      <name>Author Name</name>
      <email>author@example.com</email>
    </developer>
  </developers>
</project>

The id is your jenkins.io account. The name is a human readable display name. This ensures that the update center and related tools are able to properly display the maintainer for your plugin. It’s advisable to include an email address so that people can contact you (this will be shown in the plugin infobox on the wiki), but it’s optional.

Changelogs

Once you have made your first release, you should add release notes to your plugin. You have many options how to do it:

  • use GitHub Releases (possibly with the help of Release Drafter), add a link to releases page to your documentation page (recommended)

  • create a CHANGELOG file (Markdown, Asciidoc) in the repository root and link it from the documentation page

  • include the changelog content in the documentation page

Contributor documentation

For open-source plugins it is important to have contributor guidelines to attract more contributors. GitHub offers standard ways to define guidelines and to show them to contributors, including contributing guidelines, code of conduct, pull request templates, etc.

Some notes:

References