Plugin Documentation-as-Code: Moving docs to GitHub
In September 2019 we announced support of GitHub as a source of documentation for the Jenkins Plugin Site. Thanks to Zbynek Konecny and Olivier Vernin and other contributors, now it is possible to store plugin documentation right inside plugin repositories instead of Jenkins Wiki which was historically difficult to maintain for plugin maintainers and for the Jenkins infrastructure team.
This blogpost may be interesting to plugin maintainers and to those who want to contribute to the Jenkins documentation. I will describe how to migrate plugin documentation to GitHub and to get pages like this one:
Why?
By using plugin GitHub repositories for documentation, plugin maintainers can follow the Documentation-as-code approach and make documentation changes a part of the pull requests so that documentation follow-ups do not get forgotten. It also gives an opportunity to review the documentation changes and to add documentation contributor recognition, especially if the story is combined with Release Drafter.
Unfortunately, before September 2019 usage of GitHub documentation was causing some issues. First of all, many plugin maintainers have already moved their documentation to GitHub, and it caused fragmentation of the documentation (Wiki, GitHub, jenkins.io). To address it, plugin maintainers still had to maintain stub Wiki pages with redirects, and users had to spend some time to find out where the real documentation is located. By supporting GitHub as a documentation source, we allow maintainers to phase out the plugin Wiki pages while improving the user experience.
And there are even more pressing reasons to do the migration now… If you are subscribed to the developer mailing list, you may have also seen an announcement by R. Tyler Croy about Jenkins Wiki stability issues and making it read-only as a temporary measure to stabilize the instance (mailing list thread). Although the functionality has been partially restored afterwards, there is a consensus in the Infrastructure team that we should gradually move to alternate solutions.
Examples
Since the announcement in September, more than 50 plugins were moved from Wiki to GitHub. Few examples:
How to enable GitHub documentation for your plugin?
-
Convert documentation from Wiki to GitHub Asciidoc or Markdown format if you have not done it yet.
-
It can be easily done in a semi-automatic way using Jenkins Wiki Exporter
-
See the guidelines here.
-
-
Change the
<url>field in pom.xml so that it points to GitHub (guide). Examples of valid links:-
https://github.com/jenkinsci/mailer-plugin- plugin site will use GitHub REST API to extract README -
https://github.com/jenkinsci/ssh-credentials-plugin/blob/master/doc/README.md- extraction of a plugin page from a custom location
-
-
Optional: Add badges to the page to improve look&feel and to provide quick links for users. There are standard badges for changelogs, chats, plugin site, and installation numbers.
-
Release the new plugin version
-
Wait a few hours till the change propagates. After that, the Jenkins Plugin Site will show the new documentation from GitHub.
What’s next?
The story is tracked as WEBSITE-406 which is a part of the wider subproject for using GitHub as a source of data for the Jenkins plugin site and update managers (WEBSITE-637). Later steps include support showing changelogs from GitHub releases, pulling plugin tags from GitHub, showing plugin logos, and using Repository Permission Updater as a source of the maintainer information.
How to contribute?
October is a great time to contribute! Plugin documentation is one of the featured projects for Hacktoberfest, and we will welcome all contributions to the documentation and to the codebase.
Contributing to Documentation
We are looking for contributors who are interested to improve plugin documentation and to help us with migration from Wiki to GitHub. For dozens of plugins the documentation is already in GitHub, and you are welcome to submit pull requests against any repository.
Migrating documentation:
If you have any questions about contributing to the documentation, please see this page or reach out to us in the Docs SIG Gitter chat.
Code contributions
Would you like to write some code in Java or JavaScript? Or would you like to work on CSS styles and improve Jenkins design? In such case you are welcome to contribute to the Jenkins Plugin Site. It is our own plugin marketplace implementation, and we invite contributions to this area. The plugin site is really easy to develop.
-
WEBSITE-637 - EPIC for Plugin site and GitHub integrations
-
jenkins-infra/plugin-site - Frontend (JavaScript, React, XSS, YARN)
-
jenkins-infra/plugin-site-api - Plugin site API and Docker packaging (Java, Maven, Docker)
About the author