Jenkins Developer Meetup: Changes in Jenkins plugin documentation and changelogs

In September 2019 we announced announced support of GitHub as a source of documentation for the Jenkins Plugin Site. Later in October we put Jenkins Wiki into the read-only state due to the infrastructure issues, and there is an ongoing migration of Jenkins documentation to GitHub and jenkins.io. How does it impact plugin maintainers? How to migrate the documentation and changelogs?

Meetup link: https://www.meetup.com/Jenkins-online-meetup/events/266465039/
Recording: https://www.youtube.com/watch?v=PaQsvli92XY
Google Slides: https://docs.google.com/presentation/d/16T5IkmVKQPrjjizMHeTk4c9w-LSFNve8Qrl5NXW8PAE/edit?usp=sharing

Transcript

1. Changes in Jenkins plugin documentation and changelogs 1 Jenkins Online Meetup. Nov 22, 2019
2. Jenkins Online Meetup • https://www.meetup.com/Jenkins-online-meetup • Anything about Jenkins • Starting regular developer-focused meetups • Looking for speakers! 2
3. Presenters 3 @oleg_nenashev oleg-nenashev @MarkEWaite MarkEWaite @halkeye halkeye
4. Today - Online meetup by the Documentation SIG • Oleg Nenashev - Overview of the Documentation changes • Mark Waite, Gavin Mogan - Migrating Jenkins documentation from Wiki to GitHub and jenkins.io • Oleg Nenashev - Automating changelogs with Release Drafter • Q&A / Open Discussion 4
5. Questions? • Zoom chat or https://gitter.im/jenkinsci/docs • “Raise hand” in Zoom for immediate question • We will ask presenters • Open Q&A in the end 5
6. Overview of the Jenkins Documentation changes 6 Oleg Nenashev
7. Jenkins Wiki 7 https://wiki.jenkins.io/
8. Jenkins Wiki in 2019 • Self-hosted setup, Jenkins LDAP • Not enough infra admin capacity • User experience • Outages, performance issues • Security upgrades • Spam attacks 8 Jenkins Wiki
9. 9 https://groups.google.com/forum/#!msg/jenkinsci-dev /lNmas8aBRrI/eL3u7A6qBwAJ
10. 10 Jenkins Wiki is read-only • No Jenkins user/developer documentation updates • No plugin doc updates • No changelog updates • No label updates (update center categories, adoption)
11. Migration paths 11 Jenkins Wiki jenkins.io Plugin repositories on GitHub Everything else Plugin documentation
12. 12 Documentation-as-code on GitHub • GitHub === frontpage • Easy to contribute ◦ GitHub Markdown or Asciidoc ◦ Editing in the web browser ◦ Preview • Docs in feature pull requests • Versioning • Contributor recognition
13. 13 jenkins.io Jenkins website • User documentation, tutorials, How-to guides, and solution pages • Admin guidelines • Developer documentation • Project governance docs
14. Migration to jenkins.io • Started in parallel with the new website in Jenkins 2.0 ◦ https://github.com/jenkins-infra/jenkins.io • Awestruct, Asciidoc, Ruby, special macros • We are moving docs… slowly ◦ No migration tools before Oct 2019 ◦ Tools will be presented later • jenkins-infra/jenkins.io/blob/master/CONTRIBUTING.adoc 14
15. 15 https://plugins.jenkins.io/
16. 16 plugins.jenkins.io Jenkins plugin listing • Lists plugins and their summary pages • Takes data from Jenkins Wiki and Update Centers • Since Sep 2019 - support of GitHub as a doc source • REST API in Java, Frontend - JavaScript/React
17. Migration paths 17 Jenkins Wiki jenkins.io Plugin repositories on GitHub Everything else Plugin documentation
18. 18 History • 2016 - GSoC project for docs publishing from GitHub • May 2019 - GitHub Docs support by Zbynek Konecny • Sep 2019 - Plugin site update in the background (WEBSITE-637) • Oct 2019 - Wiki outages • Oct 2019 - Migration guidelines, Hacktoberfest, etc., etc.
19. 19 Ongoing effort • WEBSITE-637 - Support of GitHub info source for the plugin site ◦ Documentation ◦ Changelogs ◦ Plugin Labels, maintainer info, etc. • INFRA-2328 - Migration of Plugin documentation • https://jenkins.io/blog/2019/10/21/plugin-docs-on-github/
20. November 2019 State • Wiki is read-only, migration banner • Plugin documentation from GitHub is fully supported by plugins.jenkins.io ◦ GitHub Markdown, Asciidoc ◦ Custom locations in the repository • Migration guidelines and tools • 120+ plugins are already on GitHub, and counting 20
21. Examples • Mailer Plugin • Gradle Plugin • Role Strategy Plugin • See https://jenkins-wiki-exporter.jenkins.io/progress for more links 21 *
22. Thanks to all contributors! 22 Zbynek Konecny And all plugin maintainers who moved their docs! Gavin Mogan Olivier Vernin Mark Waite Tim Jacomb Oleg Nenashev
23. Migrating Docs from Wiki to GitHub Demos 23 Mark Waite, Gavin Mogan
24. Jenkins Wiki Exporter 24 • Exports Markdown or Asciidoc, supports images • Pandoc under the hood • Migration progress report https://jenkins-wiki-exporter.jenkins.io/
27. Migrating a plugin to GitHub documentation Links: • Announcement on Oct 21, 2019 • Plugin documentation • Migrating plugin documentation from Wiki to GitHub • Template issue for plugin docs migration 27
28. Let’s migrate a plugin! 28
29. Migrating a Wiki page to jenkins.io • Wiki exporter can help as well! • Moving documentation from Wiki to jenkins.io • Use Asciidoc! ◦ https://wiki.jenkins.io/display/JENKINS/Before+starting+a+new+plugin ◦ 29
30. Demo time! 30
31. Links 31 • https://jenkins.io/blog/2019/10/21/plugin-docs-on-github/ • https://jenkins-wiki-exporter.jenkins.io/
32. Automating plugin changelogs with Release Drafter 32 Oleg Nenashev
33. • jenkins.io Changelogs in Jenkins 33
34. • jenkins.io • Jenkins Wiki Changelogs in Jenkins 34
35. • jenkins.io • Jenkins Wiki • CHANGELOG.md in repo • GitHub Releases • Changelogs elsewhere • No changelogs Changelogs in Jenkins 35
37. • jenkins.io - only Jenkins Core • Jenkins Wiki • CHANGELOG.md in repos • GitHub Releases • Changelogs elsewhere • No changelogs Changelogs in Jenkins 37
38. Nobody likes writing changelogs 38
40. 40 • Created by Tim Lucas, @toolmantim • Open-source: ◦ https://github.com/toolmantim/release-drafter • Based on the Probot framework • GitHub App: ◦ https://github.com/apps/release-drafter • GitHub Actions Step Release Drafter
41. Powered by pull request titles and labels 41
42. • GitHub Release Drafts • Markdown format • Configuration as Code • Inheritance Release Drafter 42
43. • Uses Probot Config engine, powered by deepmerge • Global config repo: https://github.com/jenkinsci/.github • Minimal configuration in repositories Release Drafter Global Configuration 43
44. Categories, powered by labels 44
45. Replacers 45 Hyperlinks Acronyms
46. 46 Using Release Drafter in your plugin 1. Enable Release Drafter ◦ GitHub App: https://github.com/apps/release-drafter if you are a repo admin ◦ GitHub App: INFRA ticket if not ◦ GitHub Actions: Add action, see the doc 2. Add labels to the non-released pull requests (categories) 3. Update documentation to reference the new changelog location 4. Release the plugin! 5. Open the changelog draft, fix tag, copy-edit content 6. Publish the draft! jenkinsci/.github/blob/master/.github/release-drafter.adoc
49. 4 months with Release Drafter • Almost all development tools use Release Drafter • 100+ plugins use Release drafter • Experienced several bugs, fixed • 4 contributors to Release Drafter from Jenkins 49
50. Release Drafter adoption in Jenkins 50
51. • Integration with plugin site • Changelogs in Jenkins Web UI • Aggregated changelogs for plugin bundles (e.g. jenkinsci/bom) • Tweaks in the changelog formats Our wishlist 51
52. • Release Drafter Docs ◦ toolmantim/release-drafter • Our docs ◦ jenkinsci/.github/blob/master/.github/release-drafter.adoc • Our global configuration file ◦ jenkinsci/.github/blob/master/.github/release-drafter.yml • Q&A ◦ https://jenkins.io/sigs/docs/ ◦ https://gitter.im/jenkinsci/docs Release Drafter. Links 52
53. The end? 53
54. 54 • Great start with Hacktoberfest 2019 • Featured project in Dec 2019
55. Where do we need help? 55 • Docs SIG! • Plugin documentation migration • jenkins.io docs migration • Migration tools • Plugin site (WEBSITE-637) • Reviews and copy-editing Jenkins needs you!
56. Plugin maintainer? • Move the plugin documentation to GitHub • Move changelogs • Consider adding… ◦ Badges ◦ Repo topics ◦ Communication channel links ◦ Contributing documentation 56 Jenkins needs you!
57. Docs SIG at DevOps World | Jenkins World! • Hackfest on Dec 02 ◦ https://www.meetup.com/jenkins meetup/events/266201129/ ◦ Plugin docs work • Contributor Summit on Dec 03 ◦ https://www.meetup.com/jenkins meetup/events/264795368/ ◦ Unconference and ignite talks • Community Booth during the conference (Dec 04-05) 57 https://www.cloudbees.com/devops-world/lisbon Use the JWFOSS code for 30% discount
58. Contacts Documentation SIG: • https://jenkins.io/sigs/docs/ Gitter: • https://gitter.im/jenkinsci/docs Mailing list: • https://groups.google.com/forum/#!forum/jenkinsci-docs 58
59. Thank you!