Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Jenkins Developer Meetup: Changes in Jenkins plugin documentation and changelogs

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

Oleg Nenashev

November 22, 2019
Tweet

More Decks by Oleg Nenashev

Other Decks in Technology

Transcript

  1. Changes in Jenkins plugin
    documentation and changelogs
    1
    Jenkins Online Meetup. Nov 22, 2019

    View full-size 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 full-size slide

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

    View full-size 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 full-size 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 full-size slide

  6. Overview of the
    Jenkins Documentation changes
    6
    Oleg Nenashev

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size 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 full-size slide

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

    View full-size 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 full-size slide

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

    View full-size 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 full-size slide

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

    View full-size 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 full-size slide

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

    View full-size 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 full-size 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 full-size 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 full-size slide

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

    View full-size 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 full-size slide

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

    View full-size 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 full-size slide

  25. 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 full-size slide

  26. Let’s migrate a plugin!
    28

    View full-size slide

  27. 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 full-size slide

  28. Demo time!
    30

    View full-size slide

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

    View full-size slide

  30. Automating plugin changelogs with
    Release Drafter
    32
    Oleg Nenashev

    View full-size slide

  31. ● jenkins.io
    Changelogs in Jenkins
    33

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  35. Nobody likes writing changelogs
    38

    View full-size slide

  36. 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 full-size slide

  37. Powered by pull request titles and labels
    41

    View full-size slide

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

    View full-size slide

  39. ● 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 full-size slide

  40. Categories, powered by labels
    44

    View full-size slide

  41. Replacers
    45
    Hyperlinks
    Acronyms

    View full-size slide

  42. 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 full-size slide

  43. 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 full-size slide

  44. Release Drafter adoption in Jenkins
    50

    View full-size slide

  45. ● 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 full-size slide

  46. ● 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 full-size slide

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

    View full-size slide

  48. 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 full-size slide

  49. 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 full-size slide

  50. 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 full-size slide

  51. 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 full-size slide