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

568e3391c8b528f2b255443e4cca27ca?s=128

Oleg Nenashev

November 22, 2019
Tweet

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/
  25. 25

  26. 26

  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
  36. 36

  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

  39. 39

  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
  47. 47

  48. 48

  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!