 Hi all. Thanks for joining this training session. Today we will be talking about migrating plugin documentation to documentation as code. Yeah, we had some issues once starting this session because we had to change the zoom link on a very short notice. So apologies for 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 Jenkins CI slash hardfist. It's our main communication channel for any topics about the Jenkins UIX hardfist. And you can also contact the documentation specialist group and the Jenkins CI slash docs channel. So if you have any questions about the plugin migration, etc, please use one of these channels. So let's go to the topic itself. I do not have specific slides, but I will briefly introduce slides we had during the kickoff session. So recently, we have migrated a number of Jenkins plugins to the documentation as code. And we had a blog post about that on the Jenkins website. Just a second, I will open a hardfist link. So here you can see guidelines, which basically summarizes the user documentation, plugin documentation migration guidelines. So the idea is that now we have a new plugin set. This plugin set is driven by the new engine under the hood. So now it's a fully static website with DN. So it's really fast to load. Before that, we were using Jenkins Viki as a source of documentation. But right now we are gradually migrating to GitHub and documentation as code so that you can store documentation right inside your repository. So for example, let's take a look at the configuration as code plugin. Here's a link here. So you can see a documentation 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 documentation, you can have documentation for particular versions. Then when you develop changes, you can develop documentation in parallel. So it's not something like somebody emerges a feature, then you ask, please write documentation for that. And half of the time, nothing happens. So right now, as a maintainer of the repository, you can require someone to write a documentation during creation of the full request. And we can also recognize documentation contributors. So for example, in configuration as code plugin, you can see that there is a section for documentation updates. And we try to keep it in parallel. So thanks to all documentation contributors. There are multiple reasons why we migrated out of VK. It's about stability, about user experience. For example, for me, it was really difficult to even pass capture there sometimes. So now we have documentation right inside plugins and plugin site can visualize that. And we encourage you to do this migration. It's not always trivial because during the migration, we need not only to move from Jenkins Wiki, which is basically Confluence. But also you need to copy it to the documentation, for example, cleanup terminology, cleanup formatting, maybe a bit screenshots, etc. And in order to help you to do such migration, we created a tool called Jenkins Wiki Exporter, which provides some basic assistance and creates skeletons for this documentation. And we invite all contributors, all plugin maintainers to gradually switch to GitHub as a documentation source. So if you want to see the current progress, you can see that now, once it loads, because this page is not really documentation, it was called the stake. So here you can see that we have already migrated 400 plugins to GitHub. Also, we have 80 plugins which are in progress. So basically pull requests are submitted but haven't been released yet. And there are something like 200 of plugins which still need to be migrated. And today we will just do a quick hands-on session. I will migrate one of the plugins to show how it can be done. Before that, do you have any questions before we proceed with the demo? So if you have any questions, just unmute yourself and ask. Does anyone have permissions to unmute? I guess so. Okay. So I wouldn't be deep diving into how to migrate in practice and why we do that. Because if you go to Jenkins Online Meetup in historical events, you can find a recording of the documentation's sync meeting where we discussed that. So just a second. It's a bit slow today. Okay. Just to change the focus. So I will post the recording later, but there should be a session. If she doesn't capture it, we do a lot of sessions these days. So changes and Jenkins plugin documentation and change logs. So this is a session where you can find all the materials of the deep dive about why we need that. We won't be doing it today session. So let's just go straight to the demo. I was thinking which plugin to migrate. And I thought that it might be useful to take a plugin which has some images, etc. And for that purpose, I've chosen the Chuck Norris plugin. It's actually quite popular plugin. It has more than 4,000 installations. And right now, if you go on the website, you can see that this plugin hasn't been migrated to documentation as code yet. So for example, here, if you go to the plugin site, you can see the documentation. But it comes from the Jenkins Weekend. You have a link here that help us to improve this page. So here, if you click, you will get basically these guidelines. And let's try migrating that. For migration, I will be using our exporter tool. So here, we have Chuck Norris plugin. So we can reference wiki URL or just take plugin ID. I will take plugin ID here. So let's do the migration. For the migration, we have a number of options. We can export as markdown, as markdown, zip, new images, etc. Or as a ski dock. For GitHub, 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. It will take a while. Okay. So now it produced Chuck Norris zip, which is basically the bundle. We should be migrating. And I already have a prepared repository. Maybe not. Let's see. Plugins Chuck Norris. So yeah, this is our repository. Let's just make sure it's up to date. I was doing some prep work yesterday. Okay, so now we're on the master branch and we will just start our documentation recording. Okay, docs migration. So we have our repository ready. And let's just save our documentation bundle right inside this repository. Well, usually I just save it on my desktop. Yeah, then we will just get lost there. Yes. Okay, Jenkins plugins. Here we have Chuck Norris somewhere. Chuck Norris. Chuck Norris and I will save the zip file there. And let's just zip this, this file. So they will just have Chuck Norris docs. So yeah, I'm using Windows, but if you do it on other platform, you will get pretty much similar experience. And let's start doing our migration. For this demo, I will be using visual studio code, but basically you can do exactly the same in any other idea. So I'm not using specific features here. So we have created a zip archive. We don't longer need to that. And we have other documentation which has been exported. And here you can already see one problem because right now the main landing page is actually in a ski dock, not in Markdown. So for this particular plugin, I don't think it's a principle because it's not extremely big. So I would suggest to go with Markdown or we can respect the wishes of the original maintainer and actually export everything as a ski dock. Well, let's just stick to Markdown for now. So we will need to rename the main page to MD. Okay. And what did we have right now? So if you go to the repository, check Norris. So you can see that there is already a kind of stop, but this stop is not nearly close to what we have on the weekend. So let's just see whether we can replace it directly. So this plugin adds absolutely delightful feature for Jenkins. It will show a picture of Chuck Norris. Okay. So there is just some fun in GitHub. And here there is more formal text. So let's just keep this formal text, but we will retain this part of the demo. Okay. So what we will do, I will just take all the content from here and put it to the review file. Okay. And same we need to do the same for images. So our exporter tool 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 we have everything in the proper place. For the next steps, I will enable preview. So here we have a preview of the documentation which we are working on. And you can see that this documentation, it might be displayed a bit differently in GitHub, but I think it's something which provides you starting point for reviews. Okay. So we will also change the name maybe because it changed naming conventions a bit. And after that, let's take a look at the text. So here we actually got a good starting point because our exporter tools extracted wiki, it also replaced all the macros, et cetera. 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, we actually fix the line breaks because unfortunately, so a wiki exporter tool uses a pandoc under the hood. And pandoc doesn't support the line breaks based on sentences right now. So it basically just does says limited lines. So we will start breaking it down and just to make it friendly to reviewers and contributors will break down by lines like that. So same here, same here. Usually we use another ID so that yeah. Okay, same for frequently asked questions. So for example here you can see that there is a question and for that let's just. Try. Okay, like that. I'm getting non-existent field exception in Hudson log file how to fix this problem. So here we had hit one issues with the content because it's about Hudson. So somebody has written this documentation when Hudson was a thing. And you can see that the screenshot refers to version of 1.317. It's pretty old. It's maybe 10 years old, a bit less. So we will need to clean it up. So let's take a look. So upgrade to chat notice plug in a zero four on you were to to get rid of this exception. That's this information matter into 720. I don't think so. So my suggestion would be to actually just remove this section because it's not relevant. So let's just focus on the content which is needed for users. This time monials on a cool box. Check notice is very motivating. Yeah, that's something we should keep for sure. So let's just do that. Okay, so for common plugins. I'm not sure that we would allow such wording. What this plugin 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 links are selective. So why don't you work in the content. Let's verify that. Okay, so this link is active. If you want. You can repost it so web logs Java net. This one is most likely down. Yeah, this website was closed. I guess this one we can just remove. Check notice in class Jenkins plugins. So this one was likely down as well. Okay. So yeah, this one is done, but we have a link somewhere in archive. Or maybe not. No, everything is down. Yeah. If somebody wants to post a new to this, then one else about Chuck Norris plugin. Please do so. Right now we will just remove content which is obsolete. Not here. Chuck Norris, the programmer facts again, we will do the same. We will check whether this link exists. Yeah, these links definitely exists. So we will keep that. Okay, Chuck Norris, the programmer facts. And another question he is about emotional Hudson plugin or emotional Jenkins. So let's see where this thing really does because it's Hudson my name space. It's a plugin which probably doesn't exist anymore. Maybe it does. So we will just try to follow the link as our users would do. And here you can see that this plugin is actually deprecated. Please use a main emotional Jenkins plugin. So we follow the link again. And the emotional Jenkins link leads us somewhere. So this plugin has been released five years ago, but it's actually. Well, at least it's available. So let's just update it. Sorry for my debug console. Okay, so we will just put a link to the emotional Jenkins plugin now. Okay, 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 the plugin that's absolutely delightful feature for Jenkins. A picture of Chuck Norris. I'm also going to be adding some content here just for the link to take. Okay. For more details, please see the associated wiki page. We're actually migrating this wiki page. So we will just remove that download installation. You can preferably install from the update center. You can download it here. So again, let's verify this link because. Okay, this link is still active. But yeah, I guess it will eventually lead us. Well, we started using cash to PS, but let's keep it here for. Now, if something that we can easily migrate incrementally, you can see the details apply some starting. So Chuck Norris, etc. After installing the plugin, go to the configuration page and she books. Chuck Norris should appear. So just let's verify that the check box is called like that because most likely it has been renamed. So let's just go to the code. I'm not really familiar with the code here. Chuck Norris with our global configuration. So again, let's just keep it to this because again, I'm not sure what is at the bottom. And definitely I'm not too easy to launch this plugin and to verify the guidelines. So we can do it incrementally if needed. I believe that it's actually Chuck Norris. Okay. So the next step is keep the check box and save for the configuration for freestyle job Chuck Norris image will appear on the job page. That's right. And we have this image around a build after it's completed Chuck Norris image should also appear on the build page. This is applicable for both freestyle and maybe jobs. And right now we also have that we know that it supports pipeline source. When it was done, the wiki page wasn't updated. So we will just that pipeline jobs here. So just another fix for documentation. So here you can see that they're working from idea that there's some tabs. And you finally got to the images. So for images, images 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 a good advice, but instead of that, well, let's do it the other way. We can just fix the images. And if there is a version which annoys us, let's just delete the version right. So for that, I think it doesn't really matter what I will be using. Okay, I will actually use paint.net because it's a good practice to compress the images. And if you create a plugin with a lot of documentation, please compress the images. So here, for example, we have this. Okay, now I will submit to the crop to the selection. It's here. So let's just take a reduced image and crop. Okay. So here's our new image and preview size. This is the current default 70 layout will be just 15 kilobytes, nothing to worry about. So we saved it. So we updated one image and we will do the same with others. So it's actually what I would advise to do for content which is not relevant because you can just remove that. That is awkward. Turn it over to the right. So we will crop it out as well. Okay, so this one is a bit bigger, but it's still okay. And also check notice thumb up. It's my favorite image. So if you have ever seen a check notice going nuclear, it's what I've created at some point for referring some issues in Jenkins. And yeah, can do that. So, yeah, I will also probably see much. Yes. 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 are missing right now. And it would be useful for users to see the change logs. What do we have in this repository? In this repository right now we have nothing, but you can see that we have already adopted a release draft plugin. Again, together with Mark White, we were presenting release drafter a while ago. So here we will be basically using GitHub releases for the change log. So let's do that. And previous versions just didn't have change locks at all IPS. So because if they were based in Wiki, they would usually appear as a part of the migrated MD file. So now let's put it some way here. So here I will also increase the relation. And for example, just a section about release knows. And here I just reference GitHub releases because we have nothing else to reference. So we have a change log section here right now, GitHub releases. Okay, so this would be a valid documentation, but we also can do some more improvements. For example, if you go to the configuration as code plugin, you can see that there are badges here. And there are some badges which are actually useful to users, for example, reference to plugin reference to change lock reference to installation numbers. Sometimes there are also references to GitHub charts or to other charts. So we don't have anything like that for check numbers. But for these labels, I think that we could reuse them. And let's just do that. So the easiest way to do that is to actually copy paste from existing plugin. And yeah, I'm going to do exactly that. So I opened the plugin is marked down. And you can see that there are there is a number of pages. So I just copy once which are relevant to us and put them on my page. Are there 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. Yeah, there are some badges. These badges still reference configuration as code plugin. And let's get it fixed. So we know the idea of the plugin and we know GitHub application of the plugin. In all cases, it just uses Chuck Norris. So our update of badges will basically boil down to just replacing configuration as code by Chuck Norris in all the labels. So you can see that some labels actually reference GitHub releases some Chuck Norris. So here you can see that plugin not found. So something goes went wrong. And it's me. So change log no releases found it's fine because we haven't done the first release. Here, for example, installation numbers, we also switched to Chuck Norris. So later, we could also polish batch numbers, et cetera, if needed, but sort of batch colors, but for now it should be okay. So we have migrated documentation. We have added links. We have added badges. And right now we can just do the migration for that. So I'm going to commit the code. I hope that you will be fine with using markdown. If not, you will revert it in a separate pull request. So, yeah, we have everything in place. I just committed a great documentation. We get to GitHub. Okay. So then I will push it to my local fork of the Chuck Norris plugin. And yeah, you can see that we got a suggestion to create a pull request. So in this pull request, basically it's a standard separation. So, for example, if I submitted to a plugin, which I do not maintain, I would like to migrate the books to see this blog post. So I submitted the pull request. And I will also need to label it. For example, we use a real structure. So here I will add a documentation label. So it's not something you can do as a contributor, but maintainers can do it for you. And also I will reference our existing project for plugging documentation migration. So it's needed so that this project automatically appears in a wiki exporter. So you have seen this dashboard in progress. And this dashboard is basically generated based on some information we have collected. So again, let's open. So for okey status, we basically get it from update center. So if your plugin is migrated, it will be updated automatically. But for work in progress tasks, we have no way to get this information from update center. So we basically have a GitHub project. And yeah, thanks, Raihan, because I was going to do that. So yeah, this is a common pitfall. Right, we are going to fix that. So they think that we need the Jenkins update center to know from where to get the documentation. For that, we use a filter in a plugin form. It's like heated here. So right, this one. So if you don't change this field, the update center will be still thinking that the documentation is located on wiki. And we can just replace it by URL. So you'll be fine. And after that, I will need to commit to the code again. So it's use GitHub as a source of documentation. So I commit this change. And I push it to my personal fork so that it will be processed. So 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 the build immediately because we have a number of incoming pull requests. It takes a while. So let's finish with other tasks. We would be doing this. Because we ask you to report your contributions. For example, here what I will do, I will report my contribution to documentation. So I will just put a link here and I will say that you can create all docs to GitHub. I guess in the middle world, you should have put whatever station on from Chuck Norris. Let's just do that right. So where do we have all these jokes. The effect generator ideas. Okay, so let's get there is something about documentation. It's a really important part of the demo Chuck Norris. Okay, it works for me. So I will just put it to the image. Okay, and I submitted my contribution. So it will be processed by the team and then it should be fine. I will just put it here just for fun. Okay, any questions about the migration? So if you have any questions, please just unmute yourself and we will discuss that. Is there any checker process that could be contributed to like checking links automatically if they are not in 404 or something that could help on that topic given the big amount of links. Yeah, this is a good topic. So we have some safe low setup for Genki Sayo by Zbinik. So you can find it for Genki Sayo for plugin documentation. There is no something out of the box. But actually GitHub has a quite good ecosystem of GitHub actions. So let's just let's try to find something which helps with links. Let's see. There is a markdown link checker for sure. Okay. So link checker for markdown and HTML files, right? Yeah, the question is which, which step do we want to check? Do we want to check the source code? So in 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 on the documentation, which might be another topic. That's why I'm asking because it might be simple. Yeah, so this. So the first good step would be to just check links right inside the repository. And then on the plugin side, yes, we put it additional checks. Yeah, right now we don't have them. So our plugin site basically converts all the links. It replaces things to GitHub to related ones. And it does it kind of automatically. So if something goes wrong, it's rather bug the plugin website we would like to fix. But yeah, right now there is no link checker configured for this website. And if you're interested to contribute something like that, it would be great because yes, there are broken links. And we would be happy to clean them up. Thanks for the answer. Okay. So, yeah, if you want to try, yeah, I think we could enable whatever link checker. I won't be doing it right now. But yeah, what I would be doing in my repository, I would just take a GitHub action which does that. Or we could add something to the Jenkins pipeline. But right now we do not do it. So we could enable it to, for example, as being has a tool for verification verifying things. So we could add it to the default pipeline Jenkins. For example, Jenkins into a pipeline library. Here we have, well, this was a built plugin. So this default plugin built flow, which is used by the most of the plugins. And if we introduce some link checking tools, we could edit right inside here. So if you're interested, you can do that. And this tool supports Docker container steps. Though Docker is a bit of a luxury resource on our CN instance right now. Because we tried to use Azure container instances. So basically a single shot masters. So if you can use it in Linux without Docker, it would be recommended. But if you want to use Docker, we can also introduce container steps and verify that. So again, you can contribute there. Okay. Okay. So we've got the build passing. And then I will put on my maintainer head. And let's do the release. So we will go slightly over time for this demo. Sorry about that. But we started 20 minutes later due to issues. So anyway, if you have to drop, you will have a recording. Okay. So, yeah. We have a link and you can see that release draught has already picked it up. So we have one bug fix, which will, which will also Polish box. And let's just try to create a release of this plugin. So full disclaimer. I have never done that before. And yeah, you can see that our documentation is already updated. So yeah, we could do it a bit better by adding borders to this images. Yeah, let's keep it as is for now. And so we are going to do it release. So for that, okay, we'll just initiate my SSH key because I don't grant myself permissions by default. And historically it's a good thing to do. So you go to the master branch. So we will just take master from origin. Double check that we mentioned the pull request and we immigrated documentation so we are ready to release. Before doing that, I will just check that I have permissions to release the plugin because I believe that I have asked for permissions a while ago. And here, yeah, I have permissions to release this plugin. So let's just do that. It doesn't have tests inside. Maybe it has some but definitely not enough to become a problem. So we will just do the release. And it may take a while on my machine because I'm running it on my windows is antivirus enabled and things which definitely don't help me 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 crudest router for the changelog. So once everything builds, I will publish a release for that. And so what else do we need to do here? Actually nothing because it will be a complete plugin documentation migration. So while it builds, do you have any other questions? Okay. So by the way, if you work on the plugin documentation, helping plugins to migrate changelogs to release drafter is also a good thing to do. Or maybe not to release drafter, but definitely migrate out of Mickey. But if you want to see some information and guidance, we have a recorded session, which I have already referenced. And also you can find information here in this taskie doc file. The steps to step guide how to enable release drafter and how to configure it for your repositories. So it actually runs tests. So it may take a few minutes more. So let's just fix the plugin a bit because I see that there are some issues here. So in Chuck Norris, we have labels, but these labels actually come from our wiki. But right now we support using GitHub topics. So for example, here we can just take UI because yeah, this is UI. So Jenkins plugin. Well, it doesn't really change anything, but it's fine. And let's say iterable for fun. Yeah. I'm not sure what exactly labels to put there, but yeah, maybe it's even a label for Chuck Norris. Yeah, Chuck Norris. Chuck Norris jokes. See, there are so many labels in GitHub which help us to show this plugin. So why not? So we put these labels. We also need to edit the description. So Chuck Norris plugin for Jenkins and we will fix the link so it points to our new location. So are you still able to hear me? Because I look close to the window. I'm back. So you can see that the migration is still running. But still, yeah, once everything passes, we will have some labels. And we can also check our update center for whether we have other labels to put. Okay, for that we have allowed GitHub topics filter. So here we have all topics which are supported right now. Yeah, we can actually add more later. But yeah, definitely there is no topic for plugins like that, which basically it's some fun or gamification. So yeah, probably another site we could improve later as user experience to group all of such plugins. But yeah, right now, okay. We'll just keep it to this. So if you want to label specifically for such kind of plugins, please do so. And here you can see that actually right now we are uploading Chuck Norris plugin and yeah release 1.3 has officially happened. So it will take some time to get it displayed here. Because our backend needs to process that it needs to regenerate the update center, then it needs to regenerate the plugin side. So it will take a few hours before it starts really displaying. Let's just finish the release and publish the change log. So here you have this change log draft. I just double checked before the release that it's actually what we need to do. So yeah, this is the pull request we will be releasing and I'm not sure why there are so big differences likely because of dependable. Now let's just check this pull request for example when it was released just to make sure that I didn't miss anything it was released in the previous session. So then I will just take this change log. Well, you can actually release it as this but I prefer to copy them and copy edit it. So let's say we have a version attack 1.3 which was pushed by our release flow. So I will say click the release version 1.3 and here is our change log. So remove repeated parts and the Jenkins core requirements. There is a type in my pull request. I will also move this to two entries. I use plugin bone for dependencies. Yeah, maybe it's not even dependencies. Okay. Yeah, I'll keep it here because it changed the dependencies actually using the update plugin form and these versions that we have nothing to do with user needs. So I usually put them to maintenance. But yeah, it's up to you as a maintainer how you handle that. For example, here we can just release it as this. And I think that it's actually ready to go. So publish the release. And hey, we have a change log down. So then users of this plugin which use that will receive the notification that the release is out. So you automated the communication. And after that, once everything passes and it is flushed, you will have a link here to the change log. So the migration is actually complete. It just automatic stuff which needs to be to happen before everything is displayed. So any questions? If not, yeah, I will just finish the recording. And again, thanks to everyone who participated in this section. And if you contribute to plug immigration is much appreciated. If you also want to improve for developer experience like adding clean team for links. It's also welcome because finally it helps users because they don't hit all these obsolete links everywhere. So any contributions will be appreciated. Okay, I'll stop screen sharing. Thanks a lot for your time. Thanks.