 Hi, everyone. This is the Jenkins documentation special interest group. It's the 27th of March, 2020. Thanks very much for joining us. Let's go ahead and look at the agenda and then we'll work through the contents of the agenda. So, first, first item will report on previous action items. Then we'll talk about plug in labeling principles and guidelines. Then the plug in adoption and deprecation processes. Then documentation roadmap. And those are the to and then Google season of docs 2020. Are there other topics that should be added to the agenda. Great. Okay, then let's go ahead and first is the action items. I apologize I'm still not I still haven't submitted my project ideas in a poll request I think what will happen there is we're going to use the roadmap as a place to hold some of those, at least as an initial capture and then we'll put more ideas as they are. Docs SIG summary I continue to post those to post the videos to Twitter and I'll do a blog post here in the next week or two on the ways that docs have evolved. Oleg you and I had talked about a palm and bomb developer meetup for the for for use of bill of materials in Maven. Is that stabilizing now or should we continue to hold this on the do it in the future. I think that we need to do that. I'm about organizing plugin for the zero. So it's on my list, maybe for the next week or the week after. And after it happens, we can definitely proceed so they meet up for that. Great. Okay. We're waiting for that. Everybody's welcome to join and talk about the anything else related to plugin development. So we had three or four meetups already. And we've got some audience today is interested in these topics because it's not only about Jenkins but also about the usage of software development tools. Even if you don't develop Jenkins plugins, you can study something from that. Excellent. Thank you. Then the last item was on listing the GitHub apps and the plugins that use them. I don't remember. I don't have recall the details on this one. Should I just delete this item. So it came from the request to clarify which applications can be used by the developers. And the current situation that common maintainer cannot access the release of fully approved applications. So we need to somehow document it probably in the GitHub repository. Okay, so this is so I as a plugin developer, don't know that release drafter is available to me or that or, let's see what are some others some of the the pro bot tools, the thing that does depend about for instance, and if I don't know them they're available I need to see a list somewhere. Okay. So it's something on the back burner for me. I will eventually do that but you're taking all other action items on my site. I wouldn't expect it soon. Right. That is something to have that. And I haven't seen strong need to have it so that seems very reasonable. All right, so next topic plug in labeling guidelines, labeling principles so here is that previously Jenkins plugins were categorized by by labels that were stored at one point on the wiki. And after the wiki was no longer particularly helpful. Let's see and all I get if I've got the right location the labels are right over here. So this goes to, to find all the plugins that match a particular label and storing them in the wiki the wiki is now read only so that won't work anymore. GitHub has a concept of topics. The plugins can be have topics controlled by the plugin maintainer, which, which are the can be used as labels to help people find things better on the on the plugin site. So one of the one of the discussions was hey are we do we have the right techniques for labeling plugins. And so I had sent out a proposal here, which suggested a scarred, which suggested some ideas for that's impossible to read ideas for guidelines we might use in labeling things because oh I can I had a discussion about, hey, what are the appropriate labels to use and not use on a on a particular plugin. The principles I was proposing were, let's try to label for users. And by default, we would only label from with white listed labels so labels that are chosen in advance and skip. This one was I think a controversial one skip labels provided by parents. And then, then the other controversy one was labels should be relevant to at least five plugins before they are added to the white list. Oh like you and I had conversations about this this is probably a good time for me to ask you to chime in. What are some issues you'd seen some problems or things you think we need to address here in the discussion. This discussion basically need to agree how we label things, because there are two approaches. My concern about this proposal was not specifically to the least. But the suggestions and below regarding principles. So for example how to label plugins for it happened, etc. Because your approach markers to label everything which might be useful to a GitHub user. My approach was to label plugins which are specifically related to GitHub. And yeah there is basically a conceptual difference in how the labels would be displayed. And right now, how well how labels were organized before you actually focus in technologies. So, for example, all plugins which are providing some functionality for Kubernetes would be marked as Kubernetes label. One of the ones we edit recently to highlight such future areas. My approach basically follows the one which existed before. And my understanding was that you proposed a different approach. Right. That's a good point. So a key difference there was should so in your in your in the in the way it's been in the past it's not even particularly yours right it's that how we've applied it in the past. A plugin that was specifically focused on GitHub would be labeled GitHub. Whereas this this example basic build branch build strategies would not be labeled GitHub, GitHub did I understand correctly. Yes, that's right. So, so this may be a place where where others are certainly welcome to chime in. I'm okay with either. We'd be perfectly fine to say hey, we're not where we're going to say it needs to be specific to that technology in in the specific benefit labeling technique. Oh, like do you envision how they would find basic branch build strategies, would they find it by some other means. Because there are still additional labels like SM, which could be used, then later you could add some analytics because we have usage starts. For example, we could provide information like people who install GitHub branch source plugin usually install this basic branch build strategies, something like that. So how other marketplaces like Amazon operate. Okay, so that there we would use the, use the data after the initial labeling use the data that that can be gathered from the association of plugins in an installation. I'm not, I'm not sure I'm clear on where we get that data. Yeah, association or maybe just documentation references or whatever. But yeah, for me, it's how it would be done practically, because otherwise you will have explosion of configurations. For example, everybody uses pipeline, not everybody but 70% of Jenkins users. So, would you mark all pipeline plugins with GitHub label, because if you use GitHub, you would definitely benefit from pipeline. So, such approach causes a lot of pitfalls like that. And I would prefer to be careful about that unless there is strong documentation where the boundaries. Good point. So we have a, we have a pool of 1500 18 1000, almost 2000 plugins. And you're right that if, if the, the, this, this tends to be a broader proposal than, and it would thus tend to generate many, many hits on on the word pipeline or the word if, if the example you give pipeline label is assigned to every plugin that provides anything, any extension to pipeline, then when I search for pipeline, I will probably get almost every plugin in the system. I'll get hundreds and hundreds of them. And that's, that's not particularly valuable to me. Good. Okay. So, yeah, that's was my point about that. And yeah, my preference would be to proceed to use how Jenkins operated before. And it would be also more convenient for maintenance. Because we expect plugin maintenance to manage GitHub topics. And I use my GitHub for calming permissions to set topics where I feel it's reasonable. But in general, it's up to plugin maintenance. So if you set up a complicated policy, it won't help. Well, and, and maybe is it what it even be simpler than to say, Hey, we're not going to worry about a policy particularly, we will allow it to grow entirely organically and thus it would follow the pattern. That we've used in the past. Or do you do feel strong that hey, a stated policy will help even if the stated, even if the stated policy is specifically to continue as we did before. I wouldn't spend too much time on that. We definitely need some kind of summary in plugin developer and plugin maintenance documentation. Because right now we don't document that one can use it for topics on the documentation. It's not a big deal because many popular plugins do use labels, so people will discover that they actually make some effect. And now it's also visible in the Jenkins front end, because the same labels are consumed from a great center by Jenkins installations, but still some kind of documentation would be nice. So in hosting sessions, so when you submit your plugin you can also set up labels, etc. But I wouldn't expect to have a strict process or Jeff for that, because it's basically a set of guidelines. And I think I think I've understood more clearly now your rationale and I'm fine with that. How about if we put the action item on me, or are there others in the meeting that would like to comment, give insights on hey, I would like this or that. We have Daniel on the call and Daniel spends a lot of time on Jenkins plugin manager. Hi, sorry, I had to accept delivery just now. Where exactly are we regarding the rules here. So the idea was to bias instead of instead of taking the rules of the patterns that I had suggested. We stay with Jenkins more common way of doing things which is if a plugin specifically focuses on delivering a capability to a particular keyword GitHub in this example. It would be labeled with that but in this example basic branch build strategies would not be labeled GitHub, because it's not specific. Thank you. That is what I would also have suggested. Because what would happen is basic branch build strategies would get two dozen labels for every implementation of SCM that is compatible with it and that would seem very weird to me. So I agree with this. I only have one other specific feedback if I may please. I don't think we should. This specific example that's currently being screen shared looks like fairly strict restrictive rules about plugin labeling, which seems to go counter to where we're going with the labeling by supporting GitHub topics, which is a lot more organic. And allowing people to just add labels they think makes sense within the whitelist constraints obviously. But there seems to be a tension here between we want strict control that's the correct label that would be an incorrect label. And on the other hand, I mean we support GitHub topics you can define your own just do whatever. And I'm not quite sure what the direction here is. Well so and my my intent in describing these was only to give samples, and not to state them as rules, rather as samples and I think given the guidance from both you and from Oleg, that we should be more, more, more jank and let's be accept that this will be organic that it will be flexible so what I was thinking I should do is offer a pull request to the, to the developer docs page on hosting that says that hey you can use labels, and you should choose the labels from the whitelist. You may, and bias towards, and yeah bias towards fewer labels, not, not being overly broad, and focus on the value that your plugin is giving to the user. So keep it very simple no no strict rules describe no no rigorous enforcement of anything. As an addition to that, I think it makes sense to encourage users to propose new labels to be whitelisted. Because I mean, we don't know everything maybe a new niche is created in terms of Jenkins plugins multiple plugins. Like if you think back five years or something, there was like probably like one Docker plugin or something. And at some point there would have been this critical mass of five Docker plugins where label makes sense. So yeah, totally agree. And that that makes a lot of sense. Okay, so let's see if I can capture that I'm going to actually put it into an action item here so mark to submit mark submit a PR to the dev docs. That proposal that says it hub topics are supported and encourage topics that match a whitelist will be displayed on plugins that Jenkins that I encourage proposals and encourage proposed proposals to add to the whitelist and suggest that labels focus on the key value provided to the user. Is that a reasonable way to say it or how would you how would you suggest, I would suggest using a word other than key there. Oh, good. Okay, how about just that. Yeah, that works. Basically what we're trying to say here is labels are when users are looking for something or administrators are you looking for something. But they don't know exactly what they're looking for but rather you know the general topic the category the technology stuff like that. And, yeah, so labels should focus on that. Nobody cares the technology about the technology that your plugin is implemented in. But if you or the build system that you're using so limit your use of the Maven label to, you know, Maven specific features in Jenkins. And not, you know, because you have a POM XML. Well, or I like the the one that Oleg and I discussed earlier was, it should not be that the that every plugin that extends pipeline uses the pipeline label. Because if every plugin that extends pipeline uses the pipeline label, the set of labeled pipeline the pipeline label will become almost useless there are so many things in it. Is that a fair example Daniel or by now pipeline as a label is akin to labeling a Jenkins plugin using Jenkins and plug in. Right, exactly. No sense inside Jenkins. Right. Obviously, is pipeline a white listed label it probably is right. Okay. So whether it adds any value to our global topic because right now there are maybe 60 or so plugins. But the principle that is labeled for that. Although, but with only 60 that's not as bad as I had feared because I think if we looked at implement those who are implementing pipeline it's probably double or triple that. Yeah, because not everybody puts on the pipeline topic. It's easy. Yeah, this. So, I just spend some time to clean up common labels like Kubernetes a but WS OpenShift. Whatever. And that's some time to put this github topics but please be sure that I wasn't going through my plans against because practical value for this label is not that high. Maybe maybe something like the following makes sense use labels. Or if if the plugin is well above average related to the label, because if you just implement simple build step and now pipeline compatible. Well above average. But if you're, you know, an actual pipeline plugin, then the label would be redundant but it wouldn't actually make sense. Something along those lines perhaps. Good. I like that guidance. Excellent. I mean, ultimately, it's it's not just it's just that what's the physical philosophical do what everyone would be able to do and the outcome of that would be reasonable. If everyone labeled their vaguely related plugin with pipeline the label would be useless. So maybe we can work this nicely to explain the principle. Good. Yeah, I like that. Okay. Thanks. Excellent. Okay. Thanks for the extra time here. I propose we move on to the next topic I think I've got I'm settled on the on the discussion the next stop will be a pull request. Any objections to that. So one thing which I would express the reserve in the documentation you create that Jenkins GitHub or card means reserve their right to manage labels for plugins without asking for permission. For example, in the case of GitHub topic randomly is in the case of when we just feel it's reasonable to add a label and help maintainers we can do that. Without the consulting maintenance. It seems very reasonable. Yep. It's not how we come on the approach the plugin ecosystem. But since it goes directly to updates and maybe it's something. Right, I think, I think say saying may or are allowed to is very fair. I think that's a reasonable thing to tell them that if if there is some reason and typically org admins don't act act that way unless there's a motivating reason. Good. Thanks. Okay, next topic. New plugin adoption and deprecation processes. Oh, like would you like to take us through this one. Yeah, stop sharing. Okay. I spent some time preparing pages before the meeting and then I closed everything. Okay. This is my screen. Yes, thanks. Okay, so while we're here, let me show you labels how they look on the plugin side, because we spoke a lot about how to label that. But you're from the user perspective, it looks like that. Look for plugins. And here you can discover plugins which are related to Kubernetes. I just launched a search and here you can see that there is 18 plugins. You can see that there are labels. So not all plugins are labeled so far. There is still some technical depth jobs of labeling. You can also discover plugins which are related to Kubernetes and you can do it for common queries. So we spent a lot of time updating white yeast. So you can find it. There are still some gaps here and there, but we built just help to make the plugins discoverable. There are two specific cases related to plugins at the moment. One is deprecation. So it's deprecated plugins, plugins which are no longer supposed to be used by users due to whatever reason. This doesn't include depublishing plugins. So for example, if the Jenkins security team decides to depublish plugin because of the critical issue, or if it gets removed from the Jenkins Update Center because maintainers decide to sell, then this plugin is not listed. But there are some plugins which you still can install, but which are marked as deprecated. And if you never get a warning that yes it's deprecated. So what we had on the weekend, what we have now on the plugin site. Same for plugin adoption. There is a special label called adopt this plugin, which basically lists the plugins which are for adoption. And right now there are 77 plugins which are marked like that. There is a pull request from Daniel which is a couple of hundred more. Also I have a full up to do task, but plugins from Nikola and you still need to update this list, but at least it makes the plugins discoverable. Same here you get a warning. All of Nikola's plugins should be in my pull request because I batch removed him from the uploader's list in response to his devlist thread. So when you said he's formerly a maintainer and you contacted him, he wasn't. He was already removed from the plugin. Okay, so the problem that he's not explicitly marked, the plugins are not explicitly marked for adoption. We have this case for Dr. Java API delivery. So it's Dr. Java API plugin which is used for example in Docker plugin and we have this plugin is not marked for adoption, but now we know that it's a for adoption. And for example, how to fix it quickly. Right now using GitHub topics. If you have right permissions in the repository, you can just put adopt this plugin label. And that's a bit. You just save it. And after some time, Jinx Update Center will pick it up. It takes a while now, maybe up to 24 hours. It has some notion of eventual consistency because plugin installation manager on the static site. It has multiple containers running and serving categories. So sometimes not everything gets updated at once, but eventually you get it updated and you will get this label on the plugin interface. And if you're a plugin maintainer, it's just a few clicks within GitHub and you get it running. So, yeah, that's how it works. So here you can see that there is Docker, there is API plugin and there is adopt this plugin label. And if you go to the plugin interface, now you see that there is API plugin and Docker. So both of these labels actually came from GitHub because we annotated them at some point. And yeah, that's how Common Engine works. Going back to adoption and deprecation. I spent some time to document the process. Yeah, it's basically at one GitHub topic. But we needed to migrate the old guidelines from Wiki and also extend them according to the current process. So on the Jinx documentation site, now you can find a refreshed documentation which started with GitHub specifically. We still reference this label definitions as a Plan B. So you can go and set up a label explicitly in this center resources if you don't want to use GitHub topics. Sometimes it's reasonable. For example, there might be a deprecated plugin with archived code. And basically you just can set a GitHub label or you have a multimodular repository and you want to deprecate on their particular plugin. Again, you cannot do it using GitHub topics. But for such cases, you have an escape hatch like this file. Well, the most of these labels are added for historical reasons. When we were migrating out of Wiki, thanks to Daniel, he generated this file. So this file was basically our dump of labels set up on Wiki. So our adoption processes document some other bits. So for example, comment topics, how can I plug in for adoption? And it's not only about setting the label. We also recommend the documentation. If you want to set specific information, for example, I'm actually looking for com idea for something like that. And you're recommended to send a message to the mailing list because we had cases when somebody wanted to step down. Then you send the message and you find new maintenance who are interested. So instead of just stepping down and disappearing, you can organize some knowledge transfers and it helps the community a lot. And yeah, there are also other knowledge bits, but basically all this information comes from Wiki and it was facelifted to reflect the new process. And you can also, yeah, to remove this query entirely because it's not all under needed. But the documentation is up to date. It's exactly the same for duplication and the removal of plugins. So we spend some time to document it. We just put a topic. It's recommended to update plugin documentation to highlight why it's duplicated. And then it's recommended to release the plugin because we enjoy this system. We rely on the conditioners code from GitHub. So our recommendation is when we duplicated the plugin, you actually do a final release so that people can see that this documentation on the front end. Well, and I believe that, for instance, when fine bugs plugin and PMD were deprecated in favor of warnings and G that final release gave some hint to the user, didn't it? Hey, but the new plugin is this. We can take a look. So here one interesting thing you can see that it is duplicated and there is Tom Stone. It's actually supplied to by we have to, I believe. So here, yeah, the plugin has reached the end of life. So that's it. And I believe that it comes from GitHub. And I believe we did it without actually releasing the plugin because it's also possible to just guide update center to supply to write wiki URLs. Yeah, so for those who are not familiar with that, there is a file called wiki overwrites where you can basically set custom locations for documentation sources. Even the common engine discovery engine doesn't work. And here you can see that this is a patch by older. So he just redirected on the older plugins to their basically GitHub premise. Without releasing these plugins. I did the same later for JavaScript libraries. And here you can see that they actually reference a written file, not in the root, but it still works. And I believe that in the future you'll need to get rid of all this stuff and immigrated to GitHub. Yeah, we get contributions, so we're glad that we migrated these things. So I hope that this list will finally contain only GitHub URLs for plugins which are not only used. Thank you. Okay. So I guess that's it. This adoption and deprecation. Everything is recoverable. But the guidance are here. And if there are plugin maintenance who are willing to provide some feedback, it will be much appreciated. Now a side note on deprecation. I currently have pull requests in flight that would slightly change how deprecation works. Specifically deprecation would also be possible for plugins that are no longer being distributed. Where the benefit is if a Jenkins instance has plugin installed. Right now the problem is if we then suspend distribution, we cannot provide any information about that plugin anymore other than security issue notifications. And deprecation specifically would work similar in that it would not be part of the regular available version metadata, but rather beside it. And that would allow us to show deprecation inside Jenkins, even for plugins not currently being distributed. And the current proposed approach would also have a deprecation URL, which would probably typically link to plugin documentation. But there can be other sources. For example, when we suspend plugin distribution because of a security issue. So that may change soon. As I said, it's currently open pull requests. And may or may not change. Yeah, I think it's a great improvement. Because right now if you publish a plugin, you can discover it at all. And if you generate thumb stones, it will be helpful for everyone. Thanks for doing that. So, so Daniel then what you've that your pull request proposes a UI improvement to Jenkins that will for the user actually tell them that they are using something that is now deprecated. I mean, in that already exists to an extent. I mean, there is an open pull request by Tim, I think, or Joseph, I'm not entirely sure right now, who implement that the straightforward way is similar to how we recently did adopt this plugin. Where you look for the plugin label in the updates in the metadata. Yes, that's that's it. And if the label exists, you highlight it very visibly in Jenkins with an admin monitor and such. And my feedback to that pull request in its current form is it's not enough because we need to label plugins that are deprecated and no longer being distributed. And so there are two parts to this one part is the server side and updates in the two in which we need to add an additional kind of data to the updates in the JSON file. And allow it to be configured. We are property file or JSON file or whatever nobody cares. And that you can also add the label to plug in source distribution is currently suspended. That's the server side and then client side, we need to extend Jenkins to consume the new metadata and adapt to the son's pull request to make use of new metadata as well. So a similar cycle to what we did for a lot of labels and data updates, but it's quite straightforward. Got it. Okay, thank you. Thanks for that clarification. So it's the your pull request is really about getting the extra data for a type of thing that does not exist today in Jenkins the notion that a plugin has been removed from the update center, and we need to alert them that it was removed. That has been depublished. Right, because there is some overlap between a public plugin whose publication whose publication is suspended or distribution is suspended and deprecated plugins and the current approach with the deprecated label that's implemented in the pull request and I mean to an application is also implemented right now in Jenkins because you can look at what deprecated label is, but it's not highlighted in any way. You will only see that for plugins that we currently distribute. There's a way above a rich chance that the plugin that's deprecated is also no longer being distributed, because if the service it integrates with has been shut down. There's no reason to continue distributing it other than to inform users that, well, you this plugin no longer does anything and can be removed. So, yeah, it's an open. Oh, yeah, that's so that's the ignore list and there's a bunch of stuff. Many of them due to services being shut down, a few got renamed back when that was easily and accidentally even possible, because we had no fine grained upload permissions. Years ago, specific releases don't really matter. And then of course there's plugins that are suspended because of your security vulnerabilities. So this list is quite long. And there I am. I can see myself right in that list. Yeah, thank you. Okay, that's severe, severe problems are expressed in this list. Yep. Yeah, whatever. Okay, so same. Exactly. Well, anyway, this this thing helps. We can really make some use of that. So yeah, thanks Daniel for the heads up. I think it would be really good improvement for the plugin to link. Right. And while we're talking about adopt this plugin. That's now I think already in the latest weekly. So this plugin label visualization. Yeah, that's in 2227. So also related to this and it was just simpler to do than. Yeah, the last one there. Yeah, that's why I use GitHub releases, because it's easier to navigate the way requests contain screenshots. The link is also in the Jenkins changelog. So yeah, this is this this works similar to what chatter since current pull request is for deprecation, because if if some things up for adoption, it's typically not suspended. Now that's not true 100% of the case. But 100% of the time but I think it's close enough that this one makes more sense to have for just distributed plugins and we can always later extend it as well. So that the next LTS that this will be included in is probably three months away. Right. So this will, this will have time to soak for a period of multiple weeklies. Great. Thank you. There's a lot of other changes. So yeah, let's see where it evolves. Okay, we are slowly running out of time for this meeting and we still have two items on the agenda. So what would be your proposal about them. So let's I'd say let's take on let me get a look at those agenda items. Jenkins roadmap and the Google season of dogs. I'm not sure that any of them can be discussed in a couple of minutes. Right. Well, let's how about I had intentionally to set this meeting back to once every four weeks. What if we say we'll meet again in two weeks and discuss those two topics. Is that well actually season of docs. I love. Um, so only roadmap. Yeah, well, if possible, I would prefer to discuss it next week, or start the same promise discussion in the main increased because we can proceed a lot without him. Yeah, let's I think let's do roadmap discussions on the mailing list. It's a good place to do it. And I would like to do I think the same thing with season of docs in part because I would love for the Jenkins project to be part of season of docs, but I personally don't have capacity to run Google season of docs. So what I was going to do is post to the mailing list that we think it would be a good thing, but it's not going to work if I have to run it. So if someone would like to assist and and lead the effort Google season of docs is a fascinating opportunity that Google provides to encourage professional technical writers to who may not have open source experience to contribute to open source. It's different for me then then summer of code right it's, it's not targeting students it's really targeting people who are already in the technical writing field, but therefore it has some different needs and some different expectations. Yeah, but anyway, the mentors, because engaging with open source communities completely different from professional duties or for freelancing terms of communications in terms of how things happen, the cadence changes being integrated. So we still need mentors. Well, and even, even the I think of one of one of my colleagues make McRoberts is on online with this. She comes from a tech professional technical writing background and get was not a familiar thing for her when she first started contributing to open source. And so just things like introducing technical writers to get and how we interact through get is already a subtlety. That's not true actually I had worked for three other places where we used to get. But everybody does it slightly differently this is the first place that's used forks. And it's, I'm sure if I don't have profound knowledge of get, and then it all makes sense but so it was all different for each place. So, which is it also some of the other technical writers for one in two to back to back to Oleg's point that open source contribution is really different. Yes. Okay, so like did that address your two questions on those last two topics let's do them by mailing list and, and that's perfectly fine. Great. All right. Those are all the topics that we had for today. Anything else before we close the meeting. All right, I will flag the action items and post the recording. Thanks everyone. We'll see you. See you again in four weeks.