| 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. |
The following list provides the migration steps:
Search for the plugin to update in the plugin migration progress report.
If the status of the plugin is TODO move on to step two, 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 as described 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.
Configure a redirect from the out-of-date wiki page to the migrated content.
| After migration, the continued existence of out-of-date wiki pages causes several problems, such as duplication, confusion, and unclear migration progress. This persistence makes it harder to identify which pages have migrated and those waiting for migration. If you cannot identify migrated pages, this creates a major technical obstacle in content migration from the wiki. |
Review/edit the migrated file formatting.
If the document includes "Table of contents", remove this section in Markdown
or replace it using the :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 or create GitHub releases for past versions.
If you create a changelog file, extract the 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.