Jenkins Documentation Office Hours, 26 May 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Hands-on: Migrating plugins to documentation-as-code

Description

Oleg will show how to migrate a plugin documentation from Jenkins Wiki to GitHub. We will take a plugin and perform a full migration of the docs: initial export, copy editing of the pages, moving changelogs to GitHub releases, creating a pull request to the plugin and finally doing a plugin release.

Materials:
* Plugin migration guide: https://www.jenkins.io/blog/2019/10/21/plugin-docs-on-github/
* Export tool: https://jenkins-wiki-exporter.jenkins.io/
* Event page: https://www.jenkins.io/events/online-hackfest/2020-uiux/
* Migrated plugin: https://plugins.jenkins.io/chucknorris/
* Pull request from the session: https://github.com/jenkinsci/chucknorris-plugin/pull/99

A

Hell thanks for joining this training session today, we will be talking about intimidating, like in documentation to documentation, is code yeah. Now we had some wishes. One start into this session because we had to change the zoom blink on a very short notice, so apologies for everyone who wasn't able to join this session, but this recording will hopefully help, and if you have any questions, we have channels for that. So one of the channels is ringing.

A

Yes, hot fest, so on the communication channel for any topics about the jinkies you're here at first, and you can also contact the documentation, special interest group and edging is Jay's lead ox channel. So if you have any questions about the plug immigration, etc, please use one of these channels. So let's go to the topic itself. mmm I do not have specific slides, but I will briefly the user slides. We had adjoining been keep of session. So recently we have emigrated.

A

A number of Jenkins plugins to documentation is code and we had a blog post about that on the Jenkins website. Just second.

A

How to first think so here you can see guidelines which basically summarizes all sorry wrong, page the user documentation yep plug in the communication immigration guidelines. So the ID is that now we have new plug-in set. This plugin site is driven by the engine under the hood. So now it's a fully static website, which being so, it's really fast to load before that we'll be using Jenkins week as a source of documentation. But right now we read eliminating to github and the communication s code so that you can start documentation right side at repository.

A

So, for example, let's take a look at the inspirational quote plug-in. Oh here's a link here, so you can see a deputation here on the screen and this documentation comes straight from github. So if you go to the github page, you can discover the same page here and why it's helpful. Firstly, you can version the permutation. You can have the communication for particular versions. Then, when you develop changes, you can develop the communication in parallel.

A

So it's not something like somebody images a feature, then you ask nice right documentation for it and half of the times. Nothing happens so right now we as a maintainer of the depository and I require someone right at the communication during creation of the pull request. We can also recognize the communication. Contributors of example and configuration is called plugin. You can see that the research session section for documentation on dates and we try to keep it in parallel.

A

So thanks to all the communication contributors, there are multiple reasons why we migrated out of Weeki it's about stability, about the user experience, for example. For me, it was really difficult to even pass capture there. Sometimes so now we have the communication right hand, side, plugins and plugins that can visualize that, and we encourage you to do this mediation. It's not always trivial, because Pyramid emigration I.

A

We need not only to move from our Jenkins wiki, which is basically confluence, but also you need to copy edit, the documentation, for example, clean up terminology and up formatting, maybe a bit screenshots, etc, and in order to help you to do such mutation, we created to how to join speak exporter. I wish provides some basic I still resistance and creates skeletons for this documentation and we invite all contributors all in maintenance compared to the switch to help as a bit medication source.

A

So if you want to see the current progress, you can see that now once it loads, because this page is not really must go to steak so well so here you can see that we have already emigrated 400 plugins to github. Also they have 80 plugins, which are in progress. So basically pull requests are submitted, but haven't been released yet, and there are something like 20 hundred of plugins. We still need to be migrated, and today we will just do a quick, hands-on session.

A

I love negate one of the plugins to show how it can be done before that do have any questions before we proceed with the demo.

A

A

So we it, if you have any questions, just unmute yourself and ask: does anyone have the Dormition strong, mute, okay, so, okay, so I won't be deep dive into how to be great in practice and why we do that, because a people to drink this online meetup in historical events, you can find a recording of pigmentations sick meeting where we discussed that so just as a parent.

A

Just change the focus, so it will post the recording later, but there should be a session. She doesn't capture I yeah. We do a lot of sessions so these days, so changes and drinks plug-in documentation and change logs. So this is session way. You can find all the materials of the DBA for about why we need that.

A

Session, so let's just go straight to the demo: I was thinking which plug-in to Ingrid and I so that it might be useful to take a plug-in which has some more images and cetera, and for that purpose I've chosen the Chuck Norris plug-in it's actually quite popular plug-in. It has more than 4000 installations and right now, if you go on the web site, you can see that this plug-in hasn't been immigrated to documentation of Scott.

A

Yet so, for example, hey, if you go to the plug-in side, you can see the documentation it comes from, the Aegean can speak nd. You have a link here that help us working from this page. So here, if you click you don't get. Basically these guidelines and, let's try being great in bed fermentation I, will be using our exporters tool. So here we have chat novice plug-in, so we can reference wiki, URL or just take plug-in. Id I will take plug-in ID here.

A

So, let's do termination for demolition. We have a number of options. We can even export it with markdown as markdown as if these images etc or is ASCII dog forget happy. Usually people use markdown, though it doesn't have a table of contents and other features out of the box, but whatever works. Let's do markdown export for this demo.

A

It will take a while okay, so now it produced just a chat, know of a CD which is basically the bundle we should be making and I already have a prepared repository, not what C, plugins Chuck Norris so yeah. This is our repository. Let's just make sure it's up to date, because I was doing some prep work yesterday.

A

Okay, so now we're on the master branch and we will just start our documentation, recording.

A

Okay documentation, so we have our repository radium and, let's just say, for the communication: bundle the right hand side this repository well, usually I, just save it on my desktop, then we will just get. Was there? Yes, ok, jinking plugins! Here we have Chuck Norris somewhere Oh, Chuck, Norris and I will save the zip file there and let's just times it, but this this file so we'll just have cheap and obvious dogs, so yeah I'm using Windows.

A

But if you do it another platform, you will get a pretty much similar experience and, let's start doing augmentation, but this time I will be using Visual Studio code. But basically you can do exactly the same in any other idiot, so I'm not using specific features here. So we have created a zip archive. We don't longer need that and we have further documentation say which has been exported, and here you can already see one problem because right now the main the landing page is actually in ASCII dog, not in markdown.

A

So for this particular plug-in I do not think it's principal, because it's not extremely big, so I would suggest to go with. Mark down or we can respect wishes of the original maintainer and export everything as ASCII dog- oh, let's just say, stick to markdown for now, so we will need to rename the main page to mV.

A

Okay and what did we have right now, so if you go to the.

A

Repositories, so we can see that the result will be a kind of stuff, but this stuff is not nearly close to what we have on the weekend. So let's just see whether we can replace it directly. So this plug-in that's absolutely delightful. Fish for the engines depend it will shortly so a fish of Chad Norris, okay, so there is just some fun in github here that is more less formal text. So let's just keep this formal text, but will within this part the demo.

A

So what we will do, I will just take all the content from here and put it to the big new file. Okay and saying we need to do the same for images. So all exported tulo already puts a convenient location for images when you export the file, so I just move it to the top entry, and here you can see that images are here and all images are ready to be worked on. So we can just drop our temporary directory right now and you have everything in a proper place for the next steps.

A

I will enable preview. So here we have a preview of the documentation. I wish we are working on and you can see that this documentation, it might be displayed a bit differently, I think it's something which provides you a starting point for reviews.

A

Okay, so you also change the name, maybe because we changed conventions and after that, let's take a look at the text. So he really got a good starting point, because our tools extracted TWiki it was replaced all the mattress etcetera. You can still find that there are some strange entries in the text. So let's try to clean it up, so here one of the first things we do.

A

We actually fix the line breaks because, unfortunately, when so weak exporters to use this pan dog under the hood and one dog, doesn't support line breaks based on sentences right now. So basically just does says limited alliance, so we will start breaking it down and just to make it friendly. Tv viewers and readers will break lines like so same here.

A

A

Yeah usually use another ID so but yeah okay, it's imperfectly and the answer question asks questions. So, for example, here you can see that what is the question and for that? Let's just try: okay, I'm getting non-existent cute exception in Hudson, lock file how to fix this problem. So here we had hit one issues with the content because yeah it's about Hudson, so somebody has written this documentation when Hudson was I. Think and you can see that the screenshot the first version of 1.3 1 7.

A

So it's pretty old, it's maybe 10 years old, maybe twice so we will need to clean it up. So, let's take a look so ugly to chat no risk like in a 0 for- and you were to to get rid of this exception that so this information met in 2020 I, don't think so. So my suggestion would be actually just remove this section because it's not relevant. Let's focus on the content, which is needed for users testimonials and a kebab. Self-Check nervous is very much everything yeah, that's something we should keep for sure.

A

So, let's just do that.

A

Okay, so for common plugins I'm, not sure that we would allow such wording what this plug-in is designed for fun, so you probably will keep that so this blog post, let's check our links because I'm not 100% sure that all these things I still active. So what are the work and the content lets you define it? Okay, so this link is active. If you want.

A

The posters so web logs Java net, this one is most likely down yeah. This website was closed. So I guess this one. We have can just remove John Ferguson smart when technology sink because Jenkins plugins, so this one was likely done as well.

A

Okay, so yeah this one is done, but we have a link somewhere.

A

Okay, oh maybe we don't know everything is down so yeah. If somebody wants to post new testimonials about a Chuck, Norris plug-in, please do so right now we will just remove content which is obsolete.

A

Not here Chuck Norris the programmer farts. Again, we will do the same. We will check whether this link exists. Yeah, this links definitely exists, so we will keep that.

A

Okay, Chuck Norris the programmer farts another question: he is about emotional, hudson, plug-in or emotional Jenkins. So, let's see where this thing really lead us, because it's hot summer namespace it's a plug-in which probably doesn't exist anymore. My knee does so we will just try to follow the link, as our users would do, and here you can see that this plug-in is actually duplicated. Please use an emotional Jenkins plugin, so we follow the link again and the emotional Jenkins link leads us somewhere.

A

So this plug-in has been released five years ago, but it's actually or at least survival. So, let's just updated.

A

Sorry for my debug console ok, so we will just put a link to the emotional Jenkins plug-in now.

A

Ok, so we have done this part of the migration. The next step for us is to actually double check. Whether everything is fine content wise, so here plug in it's absolutely delightful fish holding hands each of Chuck Norris.

A

I'm also copy reading and some content, and here just for turning art.

A

Ok for more, please see the Associated week page we actually making this weekly page. So we will just remove that download installation. You can preferably install from the applicants update center or you can download it here.

A

So again, let's verify this thing, because.

A

Ok, this thing is still active, but yet guess it will eventually lead us. Well, we start using HTTPS, but let's keep it here for now.

A

If something that we can easily migrate, incrementally you can see that they also apply some studying so Chuck, Nori's, etc. After installing the plug-in go to the configuration page and she books wait check, novice should appear so just let's verify that they check the box is both like that, because most likely it has been renamed.

A

So, let's just go to the code: all I'm not really familiar with the code here.

A

So again, let's just keep it to this because again, I'm not sure what is to the button and they're definitely more to easy to one shoe this plugin and we'll verify the guidelines, so we can can do it incrementally if needed, I believe it's Chuck, Norris, okay, so the next step is keep the checkbox and safe for the configuration or for freestyle job check. Now this image will appear on the job page. That's right and we have this image. I run a build after it's completed, check.

A

Nervious image should be also build on the build page, it's a big bowl philosophy, style and maybe jobs and right now we also have that you know that it supports pipeline. So when it was done, the wiki page was updated. So we will just pipeline jobs here.

A

Just another, if you the communication, so here you can see that they're working from ah I didn't let some talks and you finally got to the images so for images. Images for themselves, look pretty good, but at the same time you can see that it displays Hudson version. So one of the ways to fix that is actually to launch the plugin and to retake the screenshots. So it's a way I would advise, but instead of that.

A

Well, let's do it other way. We can just fix the images and if the reservation which annoys us, let's just leave it aggression right so for that yeah I think it doesn't really matter what I will be using.

A

Okay, I will actually use paint.net because it it's a good practice to compress the images and if you nucleate a plug-in with a lot of documentation, please compress the images. So here, for example, we have this.

A

Crop to the selection is here, so let's just take a reduced image and crop okay. So here's our new image and preview size is the current default same thing.

A

Layout will be just 15 kilobytes, nothing to worry about, so we save it. So we updated one image and we will do the same with others.

A

A

A

So it's actually what I would advise to do for content, which, which is not relevant, because you can just remove that the reservoir the can go to the right, so we will crop it out as well.

A

Okay, so this one is a bit bigger, but still okay and also check not a stump up. It's my actually ephemeral favorite image. So if you have ever seen, Chuck Norris it going nuclear, it's what I've created at some point for referring some issues and Jenkins.

A

This image, yes.

A

So we have all three images update okay, so now we would have a page which would include a lot of information, and this page is up to date, but still we could do better. So, for example, what's missing on this page change, locks I'm missing right now, and it would be useful for users to see their change logs. What do we have in this repository in this repository right now? We have nothing but yeah.

A

You can see that we have already adopted released after plugin again together with mark which we were presenting released after a while ago. So here we'll be basically using github releases for the changelog. So let's do it and previous versions just didn't have change, looks at all IPS so because, if they were based in weekly, they would usually APVMA is a part of the emigrated md file. So now, let's put it somewhere here, so here increased variation and, for example, just.

A

A section about previous notes- and here just.

A

My reference github releases because we have no nothing else to reference, so we have a change log section here right now. It helped releases.

A

Okay, so this would be a valid documentation, but we also can do some more improvements. For example, if you go to the configuration s code plug-in, you can see that there are pages here and there are some pages which actually useful to users, for example reference to plug in reference to change, local reference to installation numbers. Sometimes, though, there are also references to shirts or other charts, so we don't have anything like that for check nowadays, but for these labels I think we could reuse them, and let's just do that.

A

So the easiest way to do that is to actually copy paste from my existing plugin and yeah I'm, going to do exactly a bit so I open to the plug-in as markdown, and you can see that there are. There is a number of bridges, so I just copy once which I really want to us put them on my page.

A

Are they any questions so far? I spent a lot of time talking. So if you have any questions, please feel free to interrupt me and ask so yeah. There are some pages. These pages still reference configuration, is called plug-in and, let's get it fixed. So we know the idea of the plug-in and we know the application of the plug-in. In all cases it just uses Chuck Norris, so our update of bridges will basically boil down to just replace the figuration esporte by Chuck.

A

Norris know the labels, so you can see that some labels actually reference it Harper releases some.

A

Chuck Norris, so he you can see that our plugin not found so something goes went wrong with me. So changelog no releases found it's fine because we haven't done a chest release here, for example, a installation numbers. We also switch to check check novice. So later we could also polish numbers etcetera if needed, but the sort of mesh colors, but for now it should be okay. So we have been greeted documentation and we have a little links.

A

We have badges and right now we can just do the migration for that so I'm going to emit the code. I hope that purchased you'll be fine, is using markdown, if not you'll, regret it in a separate request. So yeah we have everything in place: I just committed any great documentation.

A

Yeah we key to github.

A

Ok, so then I will push it to my local Fork of the Chuck Norris plug you.

A

And yeah, you can see that suggestion to play the flute waste so in this pool request. Basically, it's a standard separation, so, for example, if I submit it to a plugin which I do not maintain I would quite great.

A

This so I submitted the pull request and I will say it label it. For example, we use it instructor, so here I will at a documentation label. So it's not something you can do as a contributor, but maintenance can do it for you, and also I will reference our existing project for plugging the communication education, so it's needed so that this project automatically appears in our weekly exposure. So you have seen this dashboard in progress and this dashboard is basically generated based on some information we have collected so again, so for a key status.

A

We basically get it from update Center. So if your plugin is mutated, which will be lift updated automatically, but for work and progress tasks, we have no way to get this information from our date Center. So we basically have a github project and there are tanks right huh because yeah I was going to do that so yeah. This is a common pitfall and right we are going to fix that. So they think that we need the Jenkins update Center, but to know from where to get the documentation for that we use a field in Feigenbaum.

A

It's like heated here so right this one. So if you do not change this field, the update Center will be still thinking that the documentation is like hitting on mica and we can just replace it there by URL. So.

A

And after that they will need to come into the code again.

A

So it's you say: github is the source of living. The connotation.

A

So I commit this change and I push it to my personal fork so that it will be processed so.

A

This is the pull request. We should be ready to go. We still need to give it some time to build because we have continuous integration. This continuous integration doesn't always pass a bit immediately because you have a number of incoming pull requests. It takes a while. So let's finish with other tasks, we will be doing as you are your ex harvest, because we ask you to report your contributions. For example, he here what I will do I will report my contribution to documentation.

A

A

No, this plug-in.

A

Documentation code.

A

Ok, I will just put a link here and I will say that rated dogs too.

A

So what this in Edo would you should have put whatever station and from check novice? Let's just do that right. So where do we have all these jokes? The effective generate right is now key. So if there is something about documentation.

A

It's a really important part of the demo Chuck Norris.

A

Okay, so let's see okay, what's funny, so I will just put it to the image.

A

Okay and I submitted my contribution, so it will be processed by the team and then it's very fine.

A

Just for fun, okay, any questions about the migration you. So if you have any question, please just unmute yourself and you discuss that.

B

Is there any checker process that could be contributed to like checking the links automatically if they are not info for or something that could help, and that a big given the big amount of links, yeah.

A

This is a good topic, so we have some say: floors set up for Jing to say: oh boy Finnick, so you can find it for junk aside for plugin documentation, there is no something out of the box, but actually github has a quite Budokai system of affections.

A

So it's just let's try to find something which helps these links. Let's see here.

B

Is a knock down link checker for sure, okay,.

A

So in chequered, for markdown and HTML files right yeah.

B

The question is, which which step? Do we want to check? Do we want to check the source code, and then you need the markdown link, check or ask a doctor based on the kind of source file, or do we want to check the final product generated and the documentation which might.

A

B

Topic. That's why I'm asking because it may.

A

B

A

Oh, so the first good step would be to just check links right inside the repository and then on the plug-in side. Yes, we could add additional checks, but right now we don't have one. So our plug-in side basically converts all the leads. It replaces things to github to relative once and it does it and automatically. So if something goes wrong, it's ready, but the plug-in website we would like to fix, but yeah right now.

A

There is no link checker configured for this website and if you are interested to contribute something like that, it would be great because, yes, that are broken name and we would be happy to clean them up.

B

Cool thanks for the answer. Okay,.

A

So yeah, if you want to try I, think we put enable I, would have a link. Checker I wouldn't be doing it right now, but yeah. What I would be doing it in mine, depository I would just didn't get her back. She does that or we could add something to the Jenkins pipeline, but right now we do not do it. So if we could enable it to for examples being, has a tool for verification, verifying things, so we could add it to the default pipeline Jenkins, for example, junkies, inter pipeline library.

A

Here we have this worse yet built plugin. So the this default plug-in builder flow, which is used by the most of the plugins, and if we introduce some new checking tools, we could edit right-hand side here. So they do. If you interest, you can do that, and this tool supports docker container steps, though yeah Daugherty is a bit of luxury resource. So now see an instance right now, because we tried to use either continued instances so basing good shot masters. So if you can use it in Linux without dr., it would be recommended.

A

But if you want to use dr., we can also introduce container steps and verify that so again you can contribute there.

A

Okay, so we've got the build, passing and then I will put on my maintainer head Andrew. Let's do the release, so we will go slightly over time for this demo, so they about that, but we started 20 minutes later due to in finishes so yeah anyway. If you have to a drop, we will have a recording okay, so yeah we have a link and you can see that release traffic has already picked it up. So we have one bug fix, which will which will also polish.

A

Let's just try to create a release of this planning, so food. This claim and I have never done that before and yeah. You can see that how the communication is already updated, so we we could do it a bit better by adding borders to these images but yeah. Let's keep it to this for now, and so we are going to do it reads so for that.

A

We will just initiate SH key because I don't grant myself admissions by default and historically it's a good thing to do so. You go to the master branch.

A

So we will just take master from origin, double check that we watched the pull request and we emigrated documentation. So we are thoroughly ready to release before the doing that. I will just check that I have petitions to release the debugging, because I believe that I have asked for permissions. A while ago, yeah yeah I have to admissions to release this plugin. So let's just do that.

A

It doesn't have her test inside if it has some, but definitely not enough to become a problem. So we'll just do the race.

A

And it may take a while with my machine because I'm running it on my windows is antivirus, enabled and things which definitely don't help me when to operate properly. So, let's just let it run for a while and if nothing breaks it should just pass on my machine in a few minutes and let's take a look at our next steps. So, yes, we will be using previous draft for the changelog, so once everything builds I will publish every is for that, and so what else do we need to do here?

A

Actually a nothing, because it will be a completely plug in the communication creation. So while it builds do have any other questions.

A

A

A

Okay, so, by the way, if you work on the plugin documentation, helping plugins to migrate change logs to release draft is also a good thing to do, or maybe not to release rafter, but definitely emigrate out of media. For that. If you want to see some information and guidance, we have a reported session which I have already reference, and they also haven't been information here in this ASCII table file, restart two step guide: how to enable release drafter and how to configure it for your repositories, so it actually runs test.

A

So it may take a few minutes more.

A

So, let's just fix the plug-in a bit, because I see that there are some issues here so.

A

In Chuck Norris we have labels, but this labels actually ago come from our baqia, but right now we support using it hot topics. So, for example, here we can just take UI because yeah this is UI, so Jenkins plug-in.

A

Well, it doesn't really change anything, but it's and let's say a variable for fun: yeah I'm, not sure what exactly labels there but yeah. Maybe this even a label for technologies, yeah, Chuck, Norris, Chuck, Norris, jokes, well, see there are so many labels in github which help us to show this plug-in. So why not?

A

So we put these labels. We also need to edit the description so Chuck Norris plug-in for Jenkins and we will fix editing. So it points to our new location, so I used to label to Kimmy because he'll close the window.

A

A

I'm back so you can see that the mutation is still running but still yeah. Once everything passes, we will have some labels and we can also check our deed Center, for whether we have other labels to put okay for that. We have allowed to github topics, I filter.

A

So here we have all topics which are supported right now and you can actually get more later, but yeah definitely other is no topic for plugins, like that which basically it's some fun of unification, so yeah, probably on our side, we could improve later, as user experience to group all of such plugins, but right now, okay, we'll just keep it in this. So if you want to add a label specifically for such kind of plugins, please do so, and here you can see that actually right now we are plotting Chuck, Norris planning and care release.

A

1.3 has officially happened, so it will take some time to get it displayed here, because our back-end needs to process so that it mr. geometry in the update Center. Then it needs to regionally the plug-in side so which will take a few hours before it starts really displaying. Let's just finish the release and publish of the changelog. So here we have this change. Log draft, just a double checked before the release. That is actually what we need to do. So this is the pull requests.

A

We will be religion and I'm, not sure why there are so big differences likely because so far dependable now, let's just check this request. For example, when it was released just to make sure that I didn't miss anything. It was released in the pre discussion. So then I will just take this change. Look well. You can now actually at release it as this, but I prefer to copy them and copy edit beat. So.

A

Let's say we have a version attack I, wonder three wishes was pushed by our lease flow, so I say click the release version 1.3 and he is our change lock. So I remove repeated parts and the Jing his core requirements. There is a type in my pull request.

A

I will also move this to two entries begin bone for dependence, which is it maybe it's not even dependency is okay, yeah I'll keep it here because changed the dependencies actually using update to a genome and these sessions they have nothing to do with user needs, so I usually put them to maintenance, but yeah. It's up to you as I'm making and how you handle that, for example, here we can just release disease and I think that it's really actually ready to go so published the release.

A

Okay, we have a change log down so when the users of this plugin a which use that we received a notification that the release is out. So you automated the communication and after that it wants everything, passes and metadata is flushed. You will also have again here to the change log, so the migration is actually complete and it just automatic stuff which needs to be to happen before everything is displayed.

A

So any questions.

A

If not yeah, we'll just finished the recording and again thanks to everyone who participate in this section and if you contributed like immigration, it's much appreciated. If you also want to improve the developer experience like Aiden Clinton for links, it's also welcome because, finally, it helps users because they don't hit all this obsolete links everywhere. So any contributions will be appreciated.

A

Okay, I'll, stop screen sharing and thanks a lot for your time.

B