<project>
...
<url>http://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 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.
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
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. http://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:
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.
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 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.
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.