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
   

   View Slide

2. Jenkins Online Meetup
   ● https://www.meetup.com/Jenkins-online-meetup
   ● Anything about Jenkins
   ● Starting regular developer-focused meetups
   ● Looking for speakers!
   2
   

   View Slide

3. Presenters
   3
   @oleg_nenashev
   oleg-nenashev
   @MarkEWaite
   MarkEWaite
   @halkeye
   halkeye
   

   View Slide

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
   

   View Slide

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
   

   View Slide

6. Overview of the
   Jenkins Documentation changes
   6
   Oleg Nenashev
   

   View Slide

7. Jenkins Wiki
   7
   https://wiki.jenkins.io/
   

   View Slide

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
   

   View Slide

9. 9
   https://groups.google.com/forum/#!msg/jenkinsci-dev
   /lNmas8aBRrI/eL3u7A6qBwAJ
   

   View Slide

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)
    

    View Slide

11. Migration paths
    11
    Jenkins Wiki
    jenkins.io
    Plugin repositories
    on GitHub
    Everything else
    Plugin
    documentation
    

    View Slide

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
    

    View Slide

13. 13
    jenkins.io
    Jenkins website
    ● User documentation, tutorials,
    How-to guides, and solution
    pages
    ● Admin guidelines
    ● Developer documentation
    ● Project governance docs
    

    View Slide

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
    

    View Slide

15. 15
    https://plugins.jenkins.io/
    

    View Slide

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
    

    View Slide

17. Migration paths
    17
    Jenkins Wiki
    jenkins.io
    Plugin repositories
    on GitHub
    Everything else
    Plugin
    documentation
    

    View Slide

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.
    

    View Slide

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/
    

    View Slide

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
    

    View Slide

21. Examples
    ● Mailer Plugin
    ● Gradle Plugin
    ● Role Strategy Plugin
    ● See https://jenkins-wiki-exporter.jenkins.io/progress for more links
    21
    *
    

    View Slide

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
    

    View Slide

23. Migrating Docs from Wiki to GitHub
    Demos
    23
    Mark Waite,
    Gavin Mogan
    

    View Slide

24. Jenkins Wiki
    Exporter
    24
    ● Exports Markdown or
    Asciidoc, supports images
    ● Pandoc under the hood
    ● Migration progress report
    https://jenkins-wiki-exporter.jenkins.io/
    

    View Slide

25. View Slide

26. View Slide

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
    

    View Slide

28. Let’s migrate a plugin!
    28
    

    View Slide

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
    

    View Slide

30. Demo time!
    30
    

    View Slide

31. Links
    31
    ● https://jenkins.io/blog/2019/10/21/plugin-docs-on-github/
    ● https://jenkins-wiki-exporter.jenkins.io/
    

    View Slide

32. Automating plugin changelogs with
    Release Drafter
    32
    Oleg Nenashev
    

    View Slide

33. ● jenkins.io
    Changelogs in Jenkins
    33
    

    View Slide

34. ● jenkins.io
    ● Jenkins Wiki
    Changelogs in Jenkins
    34
    

    View Slide

35. ● jenkins.io
    ● Jenkins Wiki
    ● CHANGELOG.md in repo
    ● GitHub Releases
    ● Changelogs elsewhere
    ● No changelogs
    Changelogs in Jenkins
    35
    

    View Slide

36. View Slide

37. ● jenkins.io - only Jenkins Core
    ● Jenkins Wiki
    ● CHANGELOG.md in repos
    ● GitHub Releases
    ● Changelogs elsewhere
    ● No changelogs
    Changelogs in Jenkins
    37
    

    View Slide

38. Nobody likes writing changelogs
    38
    

    View Slide

39. View Slide

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
    

    View Slide

41. Powered by pull request titles and labels
    41
    

    View Slide

42. ● GitHub Release Drafts
    ● Markdown format
    ● Configuration as Code
    ● Inheritance
    Release Drafter
    42
    

    View Slide

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
    

    View Slide

44. Categories, powered by labels
    44
    

    View Slide

45. Replacers
    45
    Hyperlinks
    Acronyms
    

    View Slide

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
    

    View Slide

47. View Slide

48. View Slide

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
    

    View Slide

50. Release Drafter adoption in Jenkins
    50
    

    View Slide

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
    

    View Slide

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
    

    View Slide

53. The end?
    53
    

    View Slide

54. 54
    ● Great start with Hacktoberfest 2019
    ● Featured project in Dec 2019
    

    View Slide

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!
    

    View Slide

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!
    

    View Slide

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
    

    View Slide

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
    

    View Slide

59. Thank you!
    

    View Slide