This blog showcases all the work done in the project Building Jenkins.io with Alternative Tools during Google Summer of Code 2023.
About Project
The Jenkins documentation site is generated as a static website using Awestruct from AsciiDoc sources. One of the drawbacks of the current build method is that the technical documentation is not versioned. It is thus not possible to view the documentation for a given Jenkins version. Only the latest can be viewed. This can lead to unnecessary confusion and is a worse experience than many other documentation sites like the git site, Python, and others. Another drawback of Awestruct is that for the last two years it has only been maintained by people from the Jenkins project. Relying on Awestruct is not a good thing in the long run.
The preferred set of tools that will replace Awestruct are Antora for its out of the box versioning functionality and Gatsby for it’s super fast builds.
The migration was performed in the following 2 coding phases:
Phase 1
In this phase, the following tasks were completed:
I used Antora to migrate the user documentation which was versioned and the developer documentation which was non-versioned while keeping much of the functionality that we already have on jenkins.io.
I migrated Tutorials, Guides, and Solution Pages which were all non-versioned.
I fixed Interpage Linking across all the pages.
You can watch me talk about phase 1 of the project in the midterm presentation here.
Phase 2
In this phase, the following tasks were completed:
I used Strapi CMS with Gatsby. I would also have liked to integrate Git Workflow here which was not suggested by mentors. Hence, It was not the perfect fit for Jenkins.
I then moved to Gatsby and developed the blogs feature.
I developed other pages like LTS Changelog, LTS Weekly, Download page and many more.
Here’s the link to the Final Presentation where you can watch me talk about the project’s final phase.
Future Improvements
Some pages like changelogs and the Pipeline steps reference still need more refining and are missing some features that exist on the current documentation pages. I will continue working on the project to refine them and make it ready as a drop-in replacement for Jenkins.io.
Acknowledgments
I’m grateful that I got the opportunity to contribute to Jenkins under Google Summer of Code. I can say with confidence that Jenkins taught me a lot and I love learning so I don’t plan to stop contributing to Jenkins any soon. I was able to pull off the project to this extent only because of my mentors, Kris Stern, Mark Waite, Rajiv Ranjan Singh, and Yiming Gong. I am grateful for their constant support and guidance throughout the project. Their valuable feedback and insights into the project helped me a lot.
I would also like to thank the org admins, Jean-Marc Meessen for being a warm, father-like figure to me, Alyssa Tong for always making sure the meetings and the project demos go smoothly , Kris Stern for deep involvement in resolving development challenges. and Bruno Verachten for always checking up on me and all the other contributors.
Useful Links
Use the Gitter channel or community.jenkins.io in case you have any question(s) or feedback.