<project>
...
<url>https://github.com/jenkinsci/your-plugin</url>
...
</project>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 an overview of these documentation types.
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.
We recommend storing documentation in the GitHub repository of the plugin. 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
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:
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
Modify your project URL to point to the GitHub repository, e.g. https://github.com/jenkinsci/your-plugin.
See the guidelines for Maven and Gradle below.
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:
https://plugins.jenkins.io/configuration-as-code using maven and README.md
https://plugins.jenkins.io/gradle using gradle and README.adoc
https://plugins.jenkins.io/mailer using maven and README.adoc
Valid URL formats for GitHub based documentation are
Loads README located in the root of YOUR-PLUGIN repository from the master branch
Load README located in the root of YOUR-PLUGIN repository from the tag or branch REF
Loads a Markdown or AsciiDoc file specified by path from YOUR-PLUGIN repository’s tag or branch REF.
If you use git tag for releases, you can make sure the plugin site loads a snapshot of your README relevant for the last release by setting the URL to e.g. https://github.com/jenkinsci/${project.artifactId}/tree/${project.artifactId}-${revision}.
Plugin labels are assigned to plugin repositories by their maintainers as GitHub topics. GitHub topics that match entries from the plugin label allowlist are displayed on the plugin site. Developers are encouraged to submit pull requests to the plugin label allowlist when they detect gaps in the list.
Plugin maintainers are encouraged to apply GitHub topics to the plugins they maintain.
Topics should be assigned to plugins when the plugin relationship to the label is well above average.
For example, the git plugin is labeled with git and scm-connections but is not labeled with bitbucket, github, gitlab, or gitea.
As another example, the configuration as code plugin allows configuration of many plugins but does not include labels for all the plugins it can configure.
Developers should not apply labels that are so broad they lose value due to overuse.
For example, a plugin that adds a few Pipeline steps should generally not be labeled with pipeline.
Plugins with the pipeline label should be significant contributors to the Jenkins Pipeline.
Jenkins Wiki became read-only in November, 2019. Requests to plugin documentation pages on the wiki now redirect to the plugins site. See this page for more information. It also include Wiki⇒GitHub migration guidelines.
You should link to your plugin’s documentation, whether on the wiki or elsewhere, in your plugin’s pom.xml, (using one of the valid URL formats) like this:
<project>
...
<url>https://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 = 'https://github.com/jenkinsci/your-plugin'
// ...
}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 change. |
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.
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
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:
CONTRIBUTING guidelines can be defined by plugin maintainers, we do not set a default guide at the moment.
See Setting guidelines for repository contributors for more information
Jenkins has a Code of Conduct which applies to all contributors and to all components hosted by the project. It is defined for all repositories using the jenkinsci/.github repository, plugin maintainers do not need to set it up.
Pull request templates: see Creating a pull request template for your repository.
Plugins that create their documentation in AsciiDoc may automatically generate a table of contents for the documentation.
The generated table of contents includes level 2 and level 3 headings by default.
The table of contents is requested by assigning the value macro to the toc variable and by inserting a reference to the toc variable at the location where the table of contents should be inserted in the page.
= Your Plugin Name
:toc: macro
[[Introduction]]
== Introduction
Some introductory text that is placed before the table of contents.
toc:[]
[[other-heading]]
== Other Heading
Text that describes more about the plugin and is placed after the table of contents.See the Git plugin as a table of contents example.