Jenkins Developer Meetup: Changes in Jenkins plugin documentation and changelogs

Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

Overview of the Jenkins Documentation changes 6 Oleg Nenashev

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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)

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

15 https://plugins.jenkins.io/

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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.

Slide 19

Slide 19 text

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/

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Slide 26

Slide 26 text

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

Let’s migrate a plugin! 28

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

Demo time! 30

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

Automating plugin changelogs with Release Drafter 32 Oleg Nenashev

Slide 33

Slide 33 text

● jenkins.io Changelogs in Jenkins 33

Slide 34

Slide 34 text

● jenkins.io ● Jenkins Wiki Changelogs in Jenkins 34

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

Nobody likes writing changelogs 38

Slide 39

Slide 39 text

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

● Uses Probot Config engine, powered by deepmerge ● Global config repo: https://github.com/jenkinsci/.github ● Minimal configuration in repositories Release Drafter Global Configuration 43

Slide 44

Slide 44 text

Categories, powered by labels 44

Slide 45

Slide 45 text

Replacers 45 Hyperlinks Acronyms

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

Slide 48

Slide 48 text

Slide 49

Slide 49 text

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

Slide 50

Slide 50 text

Release Drafter adoption in Jenkins 50

Slide 51

Slide 51 text

● 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

Slide 52

Slide 52 text

● 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

Slide 53

Slide 53 text

The end? 53

Slide 54

Slide 54 text

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

Slide 55

Slide 55 text

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!

Slide 56

Slide 56 text

Plugin maintainer? ● Move the plugin documentation to GitHub ● Move changelogs ● Consider adding… ○ Badges ○ Repo topics ○ Communication channel links ○ Contributing documentation 56 Jenkins needs you!

Slide 57

Slide 57 text

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

Slide 58

Slide 58 text

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

Slide 59

Slide 59 text

Thank you!