Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: INFRA-2255 - Document using GitHub README as a documentation source instead of Wiki

...

No Format
<scm>
  <connection>scm:git:ssh://github.com/jenkinsci/MYPLUGINNAME.git</connection>
  <developerConnection>scm:git:ssh://git@github.com/jenkinsci/MYPLUGINNAME.git</developerConnection>
  <url>https://github.com/jenkinsci/MYPLUGINNAME</url>
</scm>

Creating a Wiki page

We recommend that you create a wiki page for your plugin.

Note

Until March 2017, this was a requirement for your plugin to be published at all. This is no longer the case.

...

Hosting the plugin page

Plugin pages are hosted on https://plugins.jenkins.io/, these pages are being generated automatically using the metadata from the latest plugin release and an external documentation page. External documentation can be retrieved from GitHub and from Jenkins Wiki. It is possible to not create the documentation page at all, but we recommend to create one to improve user experience for your plugin.

Since the introduction of GitHub documentation support in September 2019 (announcement), this is the recommended way to host documentation. It allows plugin maintainers to provide the same documentation from GitHub 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 (versioning, pull requests and reviews, creating documentation in parallel with features, editing docs from GitHub Web UI).

Using GitHub as a source of documentation

The plugin site can pull documentation from the root README pages and from other locations. For new plugins it is recommended to use README pages as a source of documentation. Markdown, Asciidoc and TXT formats are supported in such case.

How to publish the plugin documentation from Github?

  • Create a README page and put the plugin documentation there
    • This page will become a landing page for https://plugins.jenkins.io/
    • More documentation pages can be introduced inside the repository, and the plugin site will display links as long as these pages are linked from README using relative or absolute 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

Documentation examples:

Creating a Wiki page

Jenkins Wiki serves as documentation, links to the source code and issue tracker, and makes it easier for people to find your plugin via search engines. For new plugins it is recommended to just use GitHub README files, but Wiki still can be used if there are strong reasons to do so.

  1. Visit the Plugins page, hover over the "Add" menu at the top right, and choose "Page".
  2. If you're asked to log in, you should use your jenkins-ci.org account details
  3. Enter a page name matching your plugin's name, i.e. with each word capitalised, ending with "Plugin" (e.g. "Snapchat Notification Plugin")
  4. Add a plugin "infobox" with your plugin's ID, e.g.:

    No Format
    {jenkins-plugin-info:snapchat-notification}
  5. Under the infobox you are encouraged to include the description from your plugin metadata, or some other brief introduction to help people know what your plugin does.
  6. Give your wiki page a label like "plugin-scm" or "plugin-misc" (click Labels at the bottom of the wiki Edit page and start typing "plugin-" to see all the possible labels).
    This will ensure the page shows up as a link in the appropriate section of Plugins.
  7. Fill out the CAPTCHA and press Save

...

If you wish, you can also manage your documentation in your GitHub repo.
See, for example, the Job DSL Plugin.

...

Adding your documentation page to your project file

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

Code Block
xml
xml
<project>
  ...
  <url>https<url>http://wiki.jenkins-ci.org/display/JENKINS/Snapchat+Notification+Plugin</github.com/jenkinsci/your-plugin</url>
  ...
</project>

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

Code Block
jenkinsPlugin {
  ...
  url = 'httpshttp://wiki.jenkins-ci.org/display/JENKINS/Snapchat+Notification+Plugingithub.com/jenkinsci/your-plugin'
  ...
}

Or if you have a plugin written in Ruby, you must edit your .pluginspec file like so:

Code Block
Jenkins::Plugin::Specification.new do |plugin|
  ...
  plugin.url = 'httpshttp://wiki.jenkins-ci.org/display/JENKINS/Snapchat+Notification+Plugingithub.com/jenkinsci/your-plugin'
  ...
end

This ensures that the update center will list your plugin correctly once the new plugin version is released. If this is missing, or does not point to your Jenkins wiki page, your plugin will not be included in the update center.

...