 now. Welcome everyone. This is the Jenkins documentation special interest group. It's the 30th of August 2019. Let's go through our agenda today. Thanks very much for being here. I'm going to share my screen. So today's agenda includes a and this is just a review first and then we'll actually run the agenda. So report on previous action items, discussion of collaboration with other special interest groups, hosting the Jenkins Restay API specs on Swagger Hub, adding a plugin site to GitHub integration sub project from Oleg, and then community bridge sub projects for docs from Oleg. And if time allows, we can talk about the latest data from the contributors to the site based on some reports that I regularly gather. Any other topics that need to be added to the agenda. Okay. Yeah, that may be through cross sig communication for docs. Okay. All right. Well, let's put it in there. So documenting the infrastructure. Good good topic. Okay. Yeah. Mark correctly. Lowercase T. Oh, and, and Marky Jackson is one word. Oh, oh, I'm getting it wrong. Like that. And then the M and the J is lowercase. Okay. So the name to get hop ID. Got it. Yeah. Okay. I'll fix it. I can fix it later. Excuse me. Not getting things exactly right. No, no worries. I'm also on there. I can fix it too. I may have had it. Super. So in terms of action items, I've still got the open action item to get the docs project ideas. I've gathered a couple more ideas. So there are more things growing in mind. I will get those posted. Oleg and I have decided that we're not going to bother with reviewing the Google Summer of Docs topics again. We'll take that up as we get closer to Google Summer of Docs. Is that a fair statement Oleg? Yes, but partial because even if we stop talking about Google season of dogs, there are two programs which are coming soon. So for example, there is outreach. We used that line late next week. And there is also community bridge below. And both topics basically are the same in terms of projects. Ah, okay. So project ideas are helpful no matter what and consider them in the context of outreach and community bridge. Thanks. But this thing then be retained. You want me to just delete this one and I think just delete it. Okay. We really need to create project ideas but we need to find contributors in this. Great. All right. So a Docs SIG summary, we've been doing that to highlight progress for governance. We'll continue doing that. That feels like it's just a standing action item. I'm not sure if we need to leave it in the action item list. I guess I'll leave it for now. Okay. Next topic, collaboration with other special interest groups. So any specific items here, Google Summer of Code for instance, Oleg from you or Markey from you. From documenting of the infrastructure side part. I'm being onboarded and right now I'm starting to document how our Kubernetes infrastructure looks in Azure. And the next part that I will probably start working in terms of documentation will be documenting the monitoring infrastructure. Now there's a lot more to do but that's just kind of where I've decided to throw myself in. Just some bits. I started documenting the plugin site ecosystem. The plugin site ecosystem was already documented pretty well, I would say. Yeah, I'm just doing some refactoring and grouping of the documentation because it was completed across three repositories. Yep, it may also contribute. Excellent. Thank you. Any other SIGs that are active we should consider connecting and encouraging? To write documentation specifically? Correct. So regarding SIGs, you have Chinese localization SIG and they keep translating Jenkins IO website and they start moving some documentation to Chinese. So yeah, but it happens within the Chinese localization SIG. I'm definitely not using the infrastructure part. Oh, right. Regarding other SIGs, you have to be honest, I'm not aware about activities which would be specific to the documentation. So yeah, we indeed could do something in platform SIG. For example, I have a long-standing infection item to document Windows support policy and propose it as a job. Right. Just don't have Windows support policy. Well, and I have the long-standing action item for Docker or for Docker image support policy. Yep, good. Okay, thanks for that reminder. Yeah, but basically since Bosnian and the market are in both SIGs, so we just record our alternatives from one SIG to another. Right, sorry. Yeah. Okay. Okay, anything else on collaboration with other SIGs? Not SIGs. So regarding sub-projects, there might be some investment into JCASC documentation. Yeah, because Jenkins configuration documentation could be improved. There is a lot of community pool requests going into this documentation, but we can definitely do more. So it could be one of the projects for documentation SIG, actually. Quick question that I have is there or do we have any interest in reaching out to maybe plug-in maintainers for possibly documenting their plug-ins? I don't know if that falls into what we're talking about in this SIG. I will talk about it a bit later because there are some related activities. Awesome. Thank you. So it's just two items below. Great, yeah. So anything else on this topic before we move on to the Jenkins REST API topic? Okay, so let's go on. There's a proposal recently raised by Abu Jha Sharma suggesting that we consider hosting REST API specifications on SwaggerHub. There's a proposal thread in the Jenkins developers mailing list and an example that has been created on SwaggerHub. I've opened an account on, as opened and as created an organization, Jenkins, whoops, Jenkins, on SwaggerHub. It's a 14-day trial is all. I assume that means that they want to charge for it. I've sent the mail asking them if they would be willing to donate so that we could host as an open-source organization without being charged for it. Yeah, so SwaggerHub is hosted by SmartBear. They're actually somewhat active in Jenkins community. They maintain plug-ins for Jenkins, so they will sponsor in the Jenkins world, if I recall correctly, at least once. So yeah, that might be open to that. And for organization it would be really interesting. The problem is that right now there is no way to automatically generate REST API specification for Jenkins plug-ins. It was one of the project ideas for Google Summer of Code this year. We just didn't get applications we could have accepted, but the project idea is still there. So it might be again reduced in community breach, in outreach, in Resort 2020. So let's see. The project today, we have a mentor team potentially for that. So if somebody is interested, just let us know. Thank you. And could you envision that during this trial that we could do a test drive with things interactively created, the way Abuja did, even without having the automatic generation from the project idea? Yes, we could. So if you just need to take several plug-ins, which are heavily used as REST APIs, and create a swagger specification for them manually, is something we can do. Or somebody, for example, could start documenting the Jenkins core, because the Jenkins core REST API is some more structured. So I was thinking I was going to engage Abuja over the weekend and try to document the notify commit API for the get plug-in, for instance, and see if I could get some experience with one little thing, but it's a little thing that I'm somewhat familiar with. Yeah. So yeah, swagger is a pretty simple idea. Okay. Even the generation from Stapler, well, at least the generating skeleton of swagger shouldn't be a big deal. But it's just a question of somebody working on that. All right. Anything else on the Jenkins REST API on swagger hub? Okay, next topic. An additional plug-in site to GitHub integration sub-project. Oleg, do you want to take the lead on that? Yeah. So do you want to share? Sure, that'd be great. Just a second. Okay. Do you see my screen? We do. So yeah, this is what I was referring to when Mark asked about the plug-in documentation. So one of the problems Jenkins project has is that now almost all plug-in documentation is some way in Viki. So, for example, we can Google for Mark's get plug-in, get plug-in in Viki. And you can go there, you can discover that there's a lot of historical documentation and you can fill the first problem. Time to access this documentation is quite long. Then if you want to edit this documentation, there is a capture, there is no review process, there is basically no recognition for contributors. And it's an old way which is hard to manage. But many plugins has already started moving to GitHub. So basically, the documentation is a thing. And yes, even several years ago, we had a lot of documentation being hosted on GitHub. So, for example, I can take the configuration called plug-in as an example. So, I just realized that Zoom's panel has exactly the same background color as the GitHub header. And I was just confused. Okay. So, yeah, here you can see that there is documentation which is basically located in GitHub now. And it's pretty common for many plugins. And the plugins gradually move to GitHub even now. The problem for us is that this GitHub documentation is not easily accessible to Jenkins users. So, for example, the links going from a plug-in documentation, et cetera, they basically put a point to plug-ins Jenkins.io. So, this is a plug-in site. And here what you can see, for example, for configuration as code. Documentation for this plugin is here. The configuration is called plug-in. Well, you can follow the link and then you will get there. But obviously, it's not the best outcome. Sometimes, the generation of this page also takes time because basically, it's been retrieved from Confluence API on demand. So, performance is pretty bad. And the idea is that what if we just embed GitHub documentation straight into plug-in sites, straight in Jenkins update sites, Jenkins user interfaces. And yet, again, it's not a new idea in 2016. When we were running the Google Summer, of course, first time in Jenkins project, we already had a project for GitHub to plug-in site documentation publishing. The problem is that it has never been fully completed. There is a pull request from Uzbinik who actually wanted to publish documentation. So, yeah, this is GitHub for documentation. But yeah, when I started working on this story two months ago, basically, for me, it started from a release drafter because I wanted to have changed local automation. And really, I want to change logs to be also published on this site. So, at some point, I just converted it to the API with support in documentation and changed logs from GitHub. Plus, there are other relatively low-hanging routes. For example, posting plug-in logos, if you have some. For example, Mark would post a Git plug-in logo or something like that. So, yeah, just to make it look better. And, yeah, also, label integration because currently plug-in labels are partially defunct in the plug-in site because labels either come from Wiki. And the Wiki is not well maintained in terms of labels or from metadata in the update site, which is hard to manage. So, if you were able to pull this information from GitHub, it would be also preferable. So, yeah. I'm not sure I understood on the labels. What sorts of labels do you envision there? Okay. So, let's see. So, here you have a list of categories. You have a list of things. And basically, these categories come from labels. So, for example, you can go to, let's say, build tools. And you get something like 100 plugins. Okay. That's cool. You're probably, I need to offer an example with less results. Okay. So, for example, it should be somewhere here. Okay. It looks like, yeah, we wrote something. So, yeah, anyway, the problem that all these labels are kind of manually managed, they either Wiki, there is no user-relevant categories. For example, yeah, we have .NET, we have IOS, Ruby development. But for example, we don't have categories for Java developers, or something like that. So, yeah, it's hard to understand what's from where. And if we were just using a more relaxed way to label plugins, like GitHub labels, topics, it would actually help a lot though, yeah, it would require significant investment in aligning them. It's just idea from the top of my head. Right now, I rather want to focus on getting Xbenyx pull requests over the line because, yeah, it submitted them in May. But basically, there was no activity. And yeah, I want to have a bigger storage tree completed. And yeah, that's why I propose it as a sub-project for documentation seek. Because yeah, I think it would be important. Firstly, for better plugin documentation, then for recognition, because yeah, what we have that, for example, if you go to configuration as code is our automatic change logs and here are documentation updates. So, they're exactly the same. They also get to the change logs, private information to users. And the most important issue that documentation can be developed in parallel with this code, because yeah, it's now documentation is code. So, to answer your question, Marky, my preference would be to, yeah, to advertise better documentation, but yeah, better documentation, which would be a part of GitHub repositories and which would provide ways to review the documentation. Because right now, anybody can go to Git plugin and basically visualize this page if they want. Fortunately, it doesn't happen so often, but yeah, you had cases when somebody replacing pages with advertisement. So, yeah. My question would be, so first of all, just to add to plus one what you're saying, I think this is an awesome plan. I think it really goes to, if we start moving to sort of a Git style of infrastructure, I think that'll be awesome. Remember, the question that I do have is the particular page that you're on right now, will we be deprecating the use of this page? Because what my fear is, is that with this still being editable, people will still be able to edit that site. And it might create confusion. So, what I would suggest is, if it's possible, and we do go to the Git changelog style that updates the plugin site, we deprecate this particular Wiki site, if that's possible. Well, deprecating the entire Wiki site, it's unlikely possible because it's about solvents of repositories. And even if you have all Jenkins contributors working on migrating documentation, it will take a while. There is no good automated documentation, migration from Confluence to GitHub. I tried a few options. I didn't like any of them. But yeah, we can do something on the organization level. So, for example, you can install a plugin for Confluence, dump everything to mark it down, or ask it out and get it published. But yeah, we still need to get to it. So, what I do right now, so there is a label Verify plugin. You can see that it was a bit on July 20th. And basically what I did, I just moved all the documentation to GitHub. So, to two places. One is GitHub releases where now I have changelogs. And another one is just a route where I have documentation which used to be on the Wiki page. And here we have clear disclaimers. And the late evening, we can set up redirect or just put a big box saying that everything was moved outside. Beautiful. Okay, that's fine. That answers my question. And that sort of incremental transition is what I've used in the Git plugin as well for the changelog. I think others are doing the same thing, right? I didn't even bother to put the old changelog entries into GitHub. I just put a tombstone at the top of the changelog which says all future changelog entries are here and they link to GitHub. I moved the label to Verify because there were just 40 releases or something like that. So, it wasn't a big deal to just move that. But yeah, in some plugins, we have hundreds of releases. And, for example, for a new project, I just edited in like Mark said, it's not ideal, but whatever works. Got it. Okay, thank you. Yeah, so regarding the current status. So, yeah, there is some tooling for release drafter, which is evolving in a separate project. So, this one works pretty well. It's been explore request. It's ready to go. So, I'm waiting for Olivier to help use infrastructure. There is full request to Jenkins Info and GitHub tokens, because we need to retrieve information from GitHub. And yeah, it needs tokens. Otherwise, it's too slow. Yeah, I didn't prepare a live demo, but I can show you an example of the recent folder-based authorization plugin, so one which was created by a beauty. And you can see that this is just a screenshot of the current state of plugins site API. It's a backend repository which serves the information to frontend. And there you can see that information has been just retrieved from GitHub. If you go to this page right now, so it would look like something like that. Yeah. So, these pages are pretty embarrassing, because it's a landing page, so they didn't some documentation they wouldn't hit. Okay, so, yeah, this project is basically in progress. I would be interested if there are contributors and early adopters. Actually, yeah, once we have an infrastructure in place, we will have something like 20 or 30 plugins with information being put from GitHub, because we just rely on a URL specified in the metadata to understand what is the source of documentation. But yeah, going forward, once we have change logs today and other things, it might require some update. So, when you say URL and the metadata, which metadata is it so that I can make sure, for instance, that the Git plugin documentation and others like it will be pointed. Is it something in the POM XML file? Yeah, it's in POM XML. So, basically, we rely on this URL. So, your URL points to Viki. And in your case, Viki will be displayed. In the case of this plugin, for example, authorization. So, it already includes reference to GitHub in metadata, but it's still this place Viki because there is no GitHub. But, yeah, once we have the engine in place, it will start displaying GitHub and all plugins which have URL pointing to GitHub here, they will start displaying documentation from GitHub. The credentials plugin, for instance, has a very nice documentation inside of it. And all it would need is that its URL attribute points to that and then it's and it currently points to the Viki. So, it could be taught, though, to if this plugin were changed and pointed to its own documentation, then that will be extracted, concept should be extracted into the plugins.jenkins.io site. That's the idea. Yes. Yeah, that's the idea. So, original Apache from Hispanic, there will be some glitches with it because, yeah, our problem that if you use GitHub API, basically, you can get a readme page or any other page in a view-ready format, but this view-ready format relies on related things. So, you can adjust and eject the data to plug inside. You need to replace URLs, for example, to images or to internal references. So, there were some glitches with it, which I was fixing, but right now, I believe it's ready to go. So, that pull request then needs testing and verification steps and then merge and we watch what happens? Well, basically, I tested it as being tested it and we agreed that it's good enough. So, yeah, there was a branch here and waiting for infrastructure team to enable this drafter because there are other changes. But, yeah, basically, this is the biggest change we integrate and it's already in a master branch. Actually, it's not. So, yeah, there is a promotion pull request. The build is green. So, I'll probably just integrate it and after that, you'll need to update Jenkins infrastructure. And for Jenkins infrastructure, there is a pull request, which I'll go to link here. Jenkins infrastructure. Yeah, this one. So, this is a pull request which basically injects GitHub client-matter data. And, yeah, once we update Docker container because your plugin site is packaged in Docker. So, once we have this pull request, it should start magically working. But, yeah, basically the only way to test it right now is to test it in production. But, yeah, in the worst case, it will be a really simple fix to reverse it. So, yeah, this story is almost ready to go. Hopefully, we'll have a live demo at the next SIG meeting. But, yeah, the biggest story was wondering what is the level of interest from documentation contributors. Because, yeah, once it's integrated, we can do a lot with documentation. We can create maybe hundreds of new different tickets for migration of documentation and clean up. We can do many other things that need it. Well, that would enable me to have a place now to express all of the different details and tiny little pieces that are involved in the plugins I maintain. There are things that aren't described anywhere right now except in the online help. And that online help is insufficient. So, this is an ideal thing. I'm very interested in it. Thanks, Oleg. Very, very. Okay. So, if anybody is watching that, please feel free to contribute. There is a bunch of other stories. But, yeah, too long didn't read. We recover some activities around plugins. So, basically, it was small as tail since Jenkins 2.0. But, yeah, apparently, the development flow is pretty easy. So, there is front-end. There is back-end. Well, it is my very limited knowledge of whatever front-end stuff. I was able to get it running on top of some patches. So, yeah, I think that it's pretty hackable if you get support from the infrastructure team. That's great news. Thank you. Thanks very much. Okay. So, this is from me. Thank you. All right. So, we'll plan for a report two weeks from now on how that's gone. Next topic was community bridge sub-project for docs. And, Oleg, I think that's again you. Yeah. So, yeah, one of the reasons why we started talking about community bridge was Google's season of docs because we weren't accepted last spring. So, we can use community bridge to run projects. And, we already have a kind of framework for that. So, now there is a student, Slading Nunes, working on a JCASC. It's the first project we run on community bridge. Basically, the format is pretty similar to Google summer of code. We don't have restrictions about what can be handled there. So, yeah, we can use it to run documentation projects. But, to run documentation projects, we need mentors and we need a list of project ideas. So, yeah, here's the question. So, the question is, do we have mentors? Well, I need mentors, let's do project ideas. Okay, sorry, I get it. Yeah. So, yeah, we had a long-standing action item to just post project ideas and potential mentors. So, similarly to what we do for JSOC project ideas, we can post it independently of a program. So, community bridge, outreach, Google season of docs, they can basically take ideas from the simple, because the program is more or less aligned in terms of duration and effort to be put. So, yeah, for that, if we had a pool of maybe four and five potential project ideas with contributors who might be interested, it would be already a good start. You can add me as a potential mentor. Great. Okay. Yeah. But make sure to bring your own potential project idea. Yeah, I have two that I can think of off the top of my head. Would you have these ones? One would be just the infrastructure. I mean, we could just start leasing that out, right? If that's possible. Number two, I think using if we could get documentation for our onboarding process in terms of plug-in contribution. I think it would be awesome if maybe we could reach out to possible past Google summer of code students to see if they would be willing to come on to this particular project to say, I want to show you how to onboard a new plug-in. That's just something, and I'm thinking from the top of my head. Yeah. So, thank you, the documentation for onboarding procedures would be nice. So, right now, we have a landing page to participate. So, but the problem that if you start choosing options, you immediately get from a fancy interface to a fancy interface of your weekend, going to whatever random links. So, we still have a lot to improve there. Well, and we do have a pending pull request on how to do IDE setup for plug-in development. It's a pull request that was submitted few weeks ago, still is in my queue to review. So, I think that's the right direction. Absolutely. There's also, for me, there's the, in terms of ideas, there's the, oops, wrong place. The get use cases that I've enumerated out a whole bunch of different use cases. We also had a proposal for a tutorial to be added from the LabView team at National Instruments. They wanted to put up a tutorial and I offered, hey, yes, we'll happily code review it. Here's where you submit a pull request. Mm-hmm. That nothing happened, right? Hasn't happened yet. They only asked that one or two days ago. Oh, that's fine. I think another really good idea would be Kubernetes use cases as it pertains to Jenkins. The reason I think that would be a very good idea is it would get a lot of traction because that's such a hot space right now. Right. Or even, you know, use of Jenkins X is another idea. Well, Jenkins X is now a separate site. So it's basically not Jenkins. And currently, your car is working on setting up a framework for Jenkins X. Though, yeah, they will definitely welcome contributions. Well, you know, another part could be sort of maybe from a documentation idea, the difference between Jenkins and Jenkins X or how to go from Jenkins to Jenkins X. So maybe if there's sort of a bridge of documentation, that could be an idea. It would be nice. Yeah. So I'm actually having dinner with, I'm having dinner with Oscar tonight. So I'm going to bring that up to him. Okay. Yeah, it would be nice. Regarding Kubernetes use cases. So we had a cloud native specialist group. I'm not sure what tends to use there because right now this group is rather inactive. Right. I'm interested in recovering that. I just have no time. But yeah, there is Kubernetes operator project, which is ongoing. Sorry, I missed what you just, there was what project that's ongoing? Jenkins Kubernetes operator. Oh, oh, the Kubernetes operator project. Yeah, there is also a great progress around Helen charts. The Helen charts, I've issued the leaf outside the Jenkins organization. So they are maintained by Helen community. Speaking of that, they consider doing more integrations with configuration as code. But yes, still you have a lot of things like just Kubernetes plugin, whatever other integration plugins. So for me, it's a bit of a cloud native seek to drive it. But yeah, it can be whatever joint project. I need to get back as well. I need to get back into the cloud native SIG because I see that that's going to be a very hot area. And I think we can make it, I use hot in a loose term, but I think we could definitely re re put a fire under there. You see where I'm bringing the whole circle of hotness here. I think we could, we could read really reinvigorate that SIG and make it a little bit more. Yeah, I'm interested. Well, yeah, my interest rather comes from the Jenkins file runner perspective. Oh, it's about Kubernetes ticked on again. So yeah. Well, Jenkins file runner isn't really the Kubernetes use case. But yeah, there are so many layers. So finally, everything becomes Kubernetes. Yeah, well, but you're right. Yeah. So yeah, cloud native special interest group. If you mark your some of the other interests to just poke with this group, it would be nice because there is still pretty big mailing list. So if you just start sending stuff there, maybe there will be some replies. Yeah, I'll make it. I'll make it create a task for myself to start getting that moving again. Okay, that's cool. Great. Anything else? And so I'm going to take the project ideas we've listed here, the others that we gathered for Google's season of docs. And I will get those into a project ideas pull request. So anything else on sub projects that we want to discuss? I don't think so. Okay. It's rather a program of action. Yeah, maybe I need to do something. Yeah, certainly. Yep, you're right. Okay. So last item, we've got just two minutes left on our scheduled time for your info. I've been gathering every two weeks data on contributors to the Jenkins.io site. I don't know if this data is useful. I just gather it in case it might someday be useful. So for example, this is from the CDF site where they gather metrics. These are the pull request time from open to merged across the last 90 days as a moving average. The hyperlink there will take you to the graph and show you the current. My read of this graph is we have improved somewhat and we don't appear to be dramatically worse than we've been in the past. So those were measures that, okay, that indicator seems reasonably healthy. The next thing that I've been capturing is contributors for the last month. And we've actually increased both in the number of contributors and the number of contributions in the last month. So I consider that quite a positive. This graph I like a lot better than the one from a month ago, which was fewer contributors and fewer contributions. Then open pull request, this one, the number that we have closed has increased substantially in the last month. So that's a plus. The number that we have open is also increased. And that's somewhat of a cause for concern. Just a reminder to those of us who are reviewers, try to close pull request quickly. Any questions on the metrics? Well, metrics for the last month's problem are not that relevant because a lot of contributions come from Google Summer of Code. Well, even without Google Summer of Code, we had some blog posts posted. We had some changes in this site. But yeah, maybe it's better to have statistics for one year. Good, good suggestion. I've been gathering this one for the month thing. You're thinking this one would be good across the full year. I can't get the period of a year from GitHub, but good idea. Okay, let me see what I can do. Yeah, you can use the CDF graph on instance. Because it provides a lot of statistics and you can query for one year. Yeah, 90 days. If you query for 90 days, it's a question of how I spent the summer. And usually in summer there is much less contributions. Good point. Yeah, and one month was crazy because of JSOC, so the data wouldn't be relevant. Right, okay. Let me take that as I'll do that and we will increase to measure for a year, report for a year next time. Good, we'll do that. Thank you. Yeah, so we have five blog posts in the queue. Wish we need to handle. So yeah, I'm going to measure blog posts from Rika right now about CLI. Okay, yeah, that one's been a long time coming. Thanks very much. Well, there was issue with CLI because CLI for JSOC is not very stable. And it was failing for a while. No, I'm not happy that we deleted so much. Any other topics that we need to review in today's session? Nothing for me. Nothing for me. All right, thanks everyone. I'm going to stop the recording, stop the meeting, and thanks very much. We'll meet again in two weeks, same time. Have a good day everybody. Have a good evening and good weekend. Thank you. Thank you. Bye-bye.