| The Jenkins wiki was made 'read-only' in October 2019. In September 2021, Jenkins wiki was attacked and as a result, the impacted server was permanently disabled and the site was rendered static. Plugin documentation is now maintained in the GitHub repository of the plugin. See the plugin documentation guidelines for details. |
Plugin documentation is available from the Jenkins plugins site so that potential users can learn about the plugin without installing it.
All plugin documentation has been converted to markdown and is stored in the plugins-wiki-docs repository. This guide will walk you through the process of migrating plugin documentation from the plugins-wiki-docs repository to the plugin repository, so that it is sourced from the README file inside the repository’s root.
| If there is no ticket for the documentation migration created by the current plugin maintainers, make sure to create one and then discuss with the plugin maintainers. Similarly, Asciidoc/Markdown preferences should be also discussed with maintainers. |
There are the following migration steps:
Search for the plugin to update in the Jenkins Wiki Exporter
If the status of the plugin is TODO then move on to step 2, else retry step one with a different plugin.
Fork the plugin repository in GitHub and clone it to your local machine.
Search for and open the plugin page in the plugins-wiki-docs repository
Copy the README.md file and all docs/images to the plugin repository
You can merge the copied file with the existing README file or create a new one.
Copy-edit the documentation, see below
Modify the URL documentation page reference in the project file so that it points to GitHub (documentation).
Commit changes, push them to your fork and create a pull request against the repository.
Review/edit the migrated file formatting
If the document includes "Table of contents", remove this section in Markdown
or replace it by :toc: macros in Asciidoc (example).
If the source Wiki page includes code blocks, they will need to be manually converted. Pandoc exports them as tables.
Extract changelogs to a separate file
It is recommended to extract changelogs to a separate CHANGELOG.md file in the repository root.
It allows tools like Dependabot to read changelog summaries
Use versions as headers. Changelogs in Wiki often include release dates, but it is better to keep them in the text below the header.
Examples: EnvInject API Plugin, AWS Java SDK Plugin
Review the text
Verify formatting and spelling
Wiki pages are often outdated, and it is nice to review them before submitting (e.g. rename "slave" to "agent", "workflow" to "pipeline", "Hudson" to "Jenkins", etc.)
Check that the images are not outdated
A lot of UI changes have occurred, and wiki pages often contain out-of-date images (images that contain keywords like Hudson will need to be replaced)
Commit changes, push them to your fork and create a pull request against the plugin repository
Once the pull request is merged, create an INFRA Jenkins JIRA ticket to replace the content on Wiki by a link to the new jenkins.io locations