 All right, welcome to Jenkins documentations office hours. So proposed agenda topics, how to contribute a pipeline documentation example to a plugin. This is a little different than the typical documentation workflow. So I wanted to show it and we may use the recording and host a subset of the recording on the Jenkins YouTube channel so that we can point people to it when they have a question how do they do this. Then contributor summit is a topic, wiki migration plan, pull request progress and new contributors any other topics we should add to the agenda. Looks good. Okay, cool. So then let me first give an overview of what the challenge is so pipeline documentation. It's a pretty common complaint that hey please could you give me an example. Give me an example of how to do hopes, how to do Jenkins pipeline document a Jenkins pipeline. I want to do such and such the thing but I would really like an example because we learn very much better by examples and we do by anything else and so one user had said hey, here's an example. So today we're using the Jacoco plug in. And so I am going to look for the Jacoco plug in here on the pipeline steps reference page so this is reference documentation on the Jacoco plug in. And if we look at this reference documentation. There are a whole bunch of arguments. Delta class coverage type string is optional, but no explanation of what that is or what it what how it applies or how it does not apply, etc. and, and it's tough to know where to look for that information because it's not here. And some of them are not for instance class pattern to me is not immediately obvious what it means, or the one that the original submitter said was hey, I don't understand the meaning of minimum branch coverage. And here's what it says it says it is an optional argument of type string. And that's it. So, so correctly, the author of this problem said hey I need to know what this means did some searching and found this stack overflow article that actually described what it means. But now how do we get that into the this page. So how do we get it to Jenkins user so it's not only that needs to go into this page it also needs to go into a Jenkins installation. So because online help is available for for Jenkins installation so if I look here as an example. If I look at the pipeline syntax link here and do something with Jacoco so the step is called Jacoco. I've got it installed I do. So when I click Jacoco here. Here are a bunch of fields, but notice the question mark over here on the far right does not exist for the path to class directories, right, or for the always run coverage collection. The, the absence of help here also hurts the user experience because they come into this place and they say oh I don't know what this means. Okay what if I disabled that are here there's help for that. But there's no help for always run coverage collection even if build is failed or aborted. These things. It's like, I don't know what those fields mean so so there are lots of places where we could. What can we do to help the user. And the nice thing is when we add help to this page. It also automatically will be populated into this page. So, so the there's a plus there. If we can get help into the, this online page. We can get help also into the Jenkins doc site page. Okay, the help though comes from the plug in source code itself. So, in, whereas I'm, I'm accustomed to writing documentation for www Jenkins.io in this case in order to get something into this page on the Jenkins.io site. I have to go edit a plugin, not edit a not edit a page on the Jenkins.io GitHub site. So now let's go find the source code for the jacoco plugin. Here's the Jenkins plugins, and I'm going to search for jacoco. Okay, here's the jacoco plugin. And we see on the right here, a link to the GitHub repository that tracks this plugin. So here is the GitHub repository. And I'm going to. I've got to fork this repository because I need a copy of it and then I'm going to clone this thing and start some work on it. So let's get us a nice new terminal window. And here we're going to say get clone. And then I had copied the URL to that repository CD into that directory. And then I'm going to do a get add remote upstream. And now we're going to add the upstream repository, which is this one. Okay. Whoops, get remote. Maybe that. Yeah, pull all of things. All right, so right, so I now have my local branch master up to date with the upstream master and reasonably current with the latest release of this particular plugin. So I need a new branch. Add pipeline. Parameter. See pipeline help. How about that. All right, so now what we need is we need to figure out which the what thing it is that we're going to add help to so the thing that that Anton noted was. Hey, minimum branch coverage is the thing that we want to find. So I'm going to go look for that in the source code. Searching for it in the source code. Because minimum branch coverage. And I want to search for case insensitive. Okay, so here is Java source file for minimum branch coverage is mentioned there. Inside Jack Coco publisher. And here it is getting assigned. And here it is being referenced. Okay, so here is the form that takes the data in. That's interesting. Okay, so here is here is the form. Now we need to find some online help. There was some online help in this so let's see where the online help is an online help for Jenkins plugins is typically in his HTML files. So for example, here we see help build over build help change build status help skip copy of source files let's see if we can find that in the UI so path to exec files. Here, let's just borrow some text and go looking for that. Okay, so here it is. Here is the help for that page so if we look at this thing. What you'll see is allows to configure various various aspects aspects of jacoco code coverage so here is the online help for that in this directory so it's in source main source main resources Hudson plugins jacoco jacoco publisher and how did I find it. I just searched for it using using my ID ease search utilities. Right so whether that's visual studio code or let's see IntelliJ or in my case emacs or vi, any one of them you can just use whatever tools you have to search and find an existing example of the help file. Now the challenge here is we would like to add some help for. Let's see what about we had this other thing that was looking for minimum branch coverage and it's in that I had more places that I will. There we go. Okay, so again minimum branch coverage is is a variable inside jacoco publisher. Since it's inside, whoops. Yeah, since it's inside jacoco publisher then we should be able to put the online help at the same location as that other help was. So here is help dot HTML. And, oh yeah this is going to be nice and simple so we're going to say we want to create a new file. Instead of calling it help dot HTML we're going to call it help dash. And then the name of the thing that we're adding help to so it was minimum branch coverage. So here's my new help file. This jet so and I am just going to insert into that thing, the boilerplate that's already there so it seems to use divs to do the markup. So that's great. So now we just say, we put in there what the submitter told us is good text for minimum coverage. So, down this. So take this text, if coverage is below the minimum. Okay, we'll take that text. If coverage is below this minimum comma the bill fails. And we like sentence per sentence per line because it's easier to code review if the coverage is below the maximum. There's also a maximum. Right every minimum. Right. Okay, so is below this minimum, the bill if if the coverage is below the maximums, how would we say it specified by. And now we go get the other variable. Or do we make, or do we exist when just for the minimum, and then the maximum is for the maximum. Well, see that because they both, they, they both are involved in deciding what to do with the coverage, or what to do with the build result I think we ought to describe the two of them with pretty much the same text. I was thinking, if the coverage is below the maximum specified by maximum branch coverage. The build is unstable. Okay. And then if the build is if it is if the coverage, if the coverage is above maximum branch coverage. That doesn't make sense. It doesn't. Okay, so test this help me understand. If we're going to specify, why don't we put in front of below this minimum, why don't we specify minimum brand. Oh, yes, yes, good idea. Right. Just copy this and the below minimum branch coverage. Yeah, that's a good idea. Okay, good. If the men, men, minimum. Okay, if coverage is below minimum branch coverage, the build fails. If the coverage is below maximum branch coverage. And above. Isn't this what they're trying to say is that there are, there are three states for Jenkins build failed unstable or success. If we're below minimum. If we're between maximum, and how about we do it this way above minimum branch coverage and below maximum, the build is unstable. Why that doesn't make sense. Why not. Okay, if I tell you that you have to eat at least one apple a day, but no more than five apples a day. Then you're successful if you're under maximum and this is got a problem you that you've got to be over maximum to be successful. Right, right. So I think what you're saying is, that's a really surprisingly named. Feel, right. So, and, and, yeah, I think, I think I, I see your point and I don't check this to make sure that somebody didn't make a typo and stack flow or something. That's possible right because that doesn't, it just doesn't make sense. I think that my map that it's only successful if I exceed my maximum. I'm as a real I don't go over maximum. Yeah, so I think I understand your point and I think that's a good thing for us to the check to see so because I from the text there I suspect that this was written by someone who's native languages, Russian. The to allow construct is a good giveaway and it makes sense English should have it but we don't. Right, so let's see. So with all these strings that look very similar and if you're in your non native language it's easy to write okay. The build is unstable if it's nice. The build is unstable if the coverage is above minimum and below maximum. Okay. The build succeeds if the coverage is above maximum branch coverage yeah. So for me it's the parameter the names of those variables is a little surprising. But let's let's assume that this is accurate and we there are some more steps we need to take to to assure this is actually working so okay. All right so we've done. We've attempted to add help for minimum branch coverage. Now we would also want to do the same thing for maximum branch coverage because I think it should be the same text, right. So let's put it in an additional file the same exact text. Okay, now if we look at what's pending in my, I've got two files that haven't been registered with source control yet. Okay, so now here we are files registered. And now I'm going to try and build this thing. So I'm going to do a maven. HPI colon run so what this will do is attempt to run Jenkins. Actually I need to switch computers this I've made a mistake make this is good this particular help here I'll just do this. I need to kill a process that's already running that would make this job hard. So now, back to where we were. We're going to say. Maven clean. Let's say HPI colon run. And I think what this will do is take the jacoco plugin with our changes, compile it and started Jenkins that loads that jacoco plugin so we can look at it with the use from the user interface and see if it has the, has the help that we just added, right. Now I'm not sure where it's going to appear so let's go looking to see if we can figure out where it's going to appear. So here is. Oh, and I just stopped my other process so we'll have to look at a different Jenkins server. Okay, so how about let's look here. At pipeline checks been. So pipeline syntax is here. So let's install the jacoco, apparently I haven't installed the jacoco plugin on this Jenkins so let's install the jacoco plugin here while we're waiting. Install without restart. Okay. Now if we're, oops, if we're lucky we can do the same thing again. Find that pipeline syntax and it will have added jacoco. So restart. Okay, just a minute. And let's check to see how this is going so this has started and is running. Good. Okay, so I may be able to, to connect to it already so in my case, I need new tunnel port 8080 and sorry about this but I because I don't run. I run my windows miss windows computer. It's. I have to use this little tunneling thing. So, okay, so 8080 or 22. Save. Okay, let's try this. All right, so it says it's running a tunnel. I'm going to try it. It says, oh my God, I'm so proud that's good. Okay, so what we see here is, I'm running a tunnel to Jenkins in this case 2.164.3. And that's if we look at the list of plugins, we should see manage plugins installed jacoco. There it is. Good. And since it's got this snapshot private and wait stuff on it. So we were successful we have built the jacoco plugin from from my little repository there and have have it running now so now we need to create a new item. And, oh, that's no help. It's not got pipeline installed so we have to go get a bunch of plugins. It's okay it's just that's that's okay so we're going to, I'm going to cheat and take the easy way out. Let's go and this is interestingly old version of Jenkins 2.164.3 let's choose pipeline. Yeah, see it won't okay so so we've encountered a problem notice this pretty red text here. This plugin requires dependent dependent plugins that need Jenkins 204. Well, I can fix that with a very simple command line change. So instead of make clean HPI colon run I'm going to add one more thing minus the Jenkins dot version equals 2.263.4. I want to use the most recent version of Jenkins instead of using. So we're going to try it now and let's see if this will work. If it does work it's a lot easier because then I can do a whole bunch of things. Okay, so it did not like that. So now we have to find out. Well, let's try it with a little different version then. Is pipeline not one of the suggested plugins or did you do this system without the suggested plugins it when you when you use this HPI colon run technique it doesn't it doesn't take you through the path to get to the suggested plugins. I just I just wondered if, if Norm I thought people, they don't have to install any plugins to do a pipeline do they. They actually do plugins are required for pipeline but but the default, if you choose install selected plugins will install them for you right yeah so so then it keeps it nice and simple so let's go back here to the local where did I put that. Here. This one. Okay, here we go. So let's reload that. Okay, and we are going to get declarative pipeline, because that's usually a very good choice pipeline declarative. Here we go we'll take that one. It's such an old version of Jenkins, it can't do it. I am just stuck so we're going to have to do this with a freestyle job. So that's that's unfortunate in this case but that's just the reality of it so let's let's create a freestyle job and look at the online help with a freestyle job and see if we can confirm it. My video for other people will do it with the current version of Jenkins right. Well, I obviously need to do some more research before I'm ready to show this to anybody else so check pipeline help. Meanwhile I am learning stuff every second so. All right so let's add a let's see we want to record jacoco coverage reports so here it is. Okay, so change build status according. Okay, more than Delta thresholds. Okay, so I am not seeing any additional question marks here that I didn't or any help icons that I didn't see before. So I'm not sure that I was successful in adding any help. I don't see a disabled display of source dumb question what's determining what snippet generator is picking up, because jacoco clearly has a zillion steps and I don't see anything close to that number of options here I think. Right, and so the way the way the snippet generator does its work is it does this it. So it looks at let's see let's take an example from that text so how about it will actually let's go go grab the, the text from the original document that the came from this one so if we grab this. We'll find that in the source code. Here we go. Okay, so what what pipeline does is it uses Java's ability to look at itself to introspect, and it will actually go in and read the data bound constructor, this thing. And says, Oh, here's a constructor. In this case it takes no arguments and then it will look at every occurrence of the pattern public get something. So for instance, public string get minimum. What we did we have there. The one we had was minimum coverage is that right. So if we look at this thing it says let's look at get minimum branch coverage. And we should see here yet here is a public getter. And this thing so it says up there must be by by convention, a field named minimum branch coverage, because there is a method called get minimum branch coverage that can return its value. And what controls the English that's on the snippet generator. That is the is that resource file that I was showing. So, let's see. Let's this thing right here should appear on the resource file on the resource page. Okay. This thing, because what may be the build tool that we use for plugins likes to do things by convention. Right. So what they say is hey put put your things in this location will find them automatically. And so in this case, anything in this page that starts with help dash gets used as online help for fields for for things. That's the online help but I'm looking at the actual English that's on the snippet generator. And when you say English in the snippet generator you mean, you mean this one or this back to the snippet generator. The build if coverage degradation degrades more than the Delta thresholds. Where is that text. Yeah, let's go find that so fail the build. If coverage degrades more than the Delta threshold so. So here's what we're looking for. And here it is in jacoco publisher config dot jelly. Okay. So do you need to add something to the jacoco whatever jelly. I can pick that jelly file for this and know because the so if we look for instance at it's it doesn't go and config dot jelly goes in another file but then gets loaded when the user presses the question mark so for example, taking that exact build this coverage degrades when I click the question mark, it brings up. Come on. It brings up text. That's interesting. It says loading but then it doesn't load I wonder if I did some damage. Oh, right. Sorry, we were looking at looking at the wrong Jenkins server let's look at this Jenkins server. Okay, so. The Jenkins server that was stopped. Therefore it was not being well behaved. Okay, so here if we look at pipeline syntax and go for jacoco. Now when we click this question mark. Check this to set the build status to failure so if we take that text. Let's look for it inside the plug in. Here it is in help build over HTML. So, here's the file like that. Okay, oh and I see we have a bunch of steps that are Delta stuff, Delta something coverage. And each of those would need to go into this same directory describing oh what does that mean and oh what does that mean so we've got here we've got change build status. Let's see if we can find that in the pipeline syntax generator. So do I see anything. Oh here it is change build status according to threshold. And there it is. And so now if I generate that change build status is set true. And what does this say that really is check this to set the build stable status to. Yeah, okay, so it really is the field, the field help files are help dash. Help dash field name change build status dot HTML and then it's just plain HTML inside that file. And I'm looking on the step reference page we do have check this to set the build status to unstable if coverage thresholds are violated. Right exactly very good so that shows up for that one, but so we have so we've got to do something so that something is showing up for maximum star coverage and minimum star coverage eggs. Yeah so maximum branch coverage and minimum branch coverage were my initial targets and and those things. And so let's let's take a little different approach and see if we can, we can prove that it works. So get. So let's do a maven clean. Skip tests. Install and I'm going to do, I'm going to use a trick for me to give it give me access to it in a large scale environment very quickly we won't we wouldn't do this for demo for anybody else because they won't have this particular set of tools but Okay, what we're going to do is copy the jacoco plug in into my place where I put all of my Jenkins setup. Okay, and then I'm just going to do a Docker run detach. Now that plug in that we just that the jacoco plug in change we just made I have now put it so that it will be visible on this Jenkins instance. Okay. So I just did the equivalent of that maven HPI colon run. And that it is just the equivalent of it. But but okay so when when I get around to doing this recording again to show a cleaner path through it. Some of the challenges will be how do we, how do we deal with an outdated Jenkins base version. And the answer is you can just compile it and place it into your own Jenkins server so upload it to your own Jenkins server instead of using maven HPI colon run. Alright, so now if I do manage Jenkins manage plugins and I look at the installed plugins. If I then search for jacoco I should see snapshots something or other and wait so that's confirmed. I'm running the jacoco plug in that I just built right now let's go look at it in pipeline syntax. Here's jacoco. Okay, so what we're expecting to see is that some place disabled. Now where was it that we would expect to see. Okay, fail the build if degrades. Yeah, that's, that's correct. Change build status according to thresholds that's correct. Now what we don't. Oh, oh, I wonder so this one may be really strange because these fields. Oh, oh, oh Meg this one's a fun one. I don't think I think this is an example of a case where the online help is not accessible to the user, because of the plugins more sophisticated way of doing, doing their user interface so I'm going to say I want to set the the thing here to 45 and this one to 75. Now when I generate the pipeline script notice. Okay, I got it backwards. It's 75. And the the the sunshine there tells me okay it will be stable sunny if it's 75% and cloudy if it's 45% or above so if it's above 75% we're stable where we're success. If we're at least above 45% we're we're unstable but okay if it's below 45 it's a fail. So now there we go but what this really tells me is, I can't see the online help because this UI has no location where I could put where I could place the, the, what do you call it the help icon. Right, so the now now I could. No I really couldn't there isn't any other place to put the help icons, because of the layout of this UI. I mean it says, I need a way to put a help icon on this field, and there, there truly isn't a way to do that. Now is, but then there's nothing that groups all the minimum star coverage and maximum star coverage. There, there, the one place that groups them would be this documentation. Right, because what I was going to say I mean I can see that just from the information is all of these it actually is a nice user interface. It is right is the help on the always run coverage collection, even if it's the other good, but I want that and then I want to see that you've got all of these things that you said a minimum maximum. And this is how it works for each one. And they all work the same. So, which is actually in a way that's actually more useful than having help on each one of these boxes. Just for yuck so we've got 12345. So we've got six categories here. Let me see if that minimum 12345. 123456. And we do we have exactly six method line instruction complexity class and branch. Right. This is actually brilliant. All we need to do is get a help file on that general statement, always run coverage collection. Okay, oh, that's an interest. Well, but see, see the problem here is this, this always run collection is actually not associated with these settings at all. Okay, that's a completely independent setting. So, so there isn't a headline that identifies what the purpose of these fields are right now. For the user headline that's coverage collection. Well now. Well, where is the now we've got a question mark on fail the build of coverage degrades more than the Delta thresholds. What is in that. What's on the question mark there. It doesn't tell us what those deltas are. And this is only about deltas and these are the Delta values. Right, but that's what I'm saying is we want. Okay, if I were king and I could I mean I mean we're kind of stuck with the interface. I would expand the content of that to then describe all of the deltas. Yeah, so, so this is the same thing for always run coverage collection. Have that say check this to do whatever and then explain what all of these conditions are. Okay, well so it's a little bit of a clue but it gets me the information. Well but but maybe maybe that's that's again where should we consider exactly that same technique here with change build stats status according to thresholds so yeah. So here we've got a field that says change build status according to, according the thresholds okay according to the thresholds that is seems like it's associated with the concepts that are in this table. Isn't it. I think so yes I'm looking we don't have thresholds is not a. Yeah. So that build over build is coverage thresholds. Yeah if I don't, if I don't check change build status. I bet these fields will be ignored. Right. And so for me it seems like this this this thing this is actually the headline, the heading that belongs associated with these six, six, six columns in this table. I think coverage collections the keyword that these six these 12 these these are the coverage ones. Right okay so so are you saying then that really this thing should be change build status according to the coverage collection through thresholds. And this one says always run coverage collection, and then these are the coverage correct correction coverage collection thresholds. It's not exactly right but this is this is talking about what coverage collections are. Yeah, so interesting. Okay, because I'm looking at their. Build over build that's about Delta coverage. Um, change build status is covered okay change build status is also coverage thresholds. Oh, I. Yeah, let's see what else is here or not okay so we've got the deltas. Just a minute, I'm going to put something in that I can recognize. Okay, there's exclusion pattern exact pattern we've got those right. Yes. Okay, so just to see what we've yeah all right so when I generate maximum branch coverage maximum class coverage. Absolutely so here it is. Now if I clear that it's still set. If I uncheck that they are still set huh. Okay, so it's honoring the settings. I just don't know I'm not sure I believe it. We know that makes sense that that on a failed build I still might want to see what the coverage is. Yeah, the build failed so that makes sense. I agree I'm just not clear when so I guess maybe the answer there is these these two check boxes that are currently checked are both modifying how the values in the table are applied is that is that a fair way to say you think that right. Yeah, they're probably saying, Okay, honor the values in the table to change the build status and this one is no matter what the build status is. Run collect coverage data. Right. Okay. Interesting. All right, so. Skip copy of source files that's that's up in the top stuff right skip copy. And I suspect that's this one disabled display of source files for coverage. Yeah. And we've got source exclusion pattern source inclusion pattern and source pattern right and source inclusion is here exclusions are here. And those are again a case where we would probably need to put the general, the general guidance on those fields in this this help text, and then put additional text on each of these fields so that it shows up in this page. Right. Interesting. Okay. And then, and then from the step reference on any of them, I should be able to. Oh, I'm not, and I can't right click let's see the ones that's got some context. I can't right click to another page where I would have an example. That's actually what we're talking about. Right. And so well, and I'm not, I'm not as concerned actually about providing examples, because this generate pipeline script I think is the one true way to generate to create examples. If you, if you want an example you open up the sample step, configure it and then you press the generate pipeline script button and it does it. Right. And then context help and it's the benefit of this is it's doing it with exactly the Jenkins version that I'm running and exactly the Jenkins the plugin version I'm running, whereas this particular page, the jacoco plugin page on Jenkins that I is always the most recent release. And if I haven't upgraded the most recent release, it may have information that's wrong, compared to my installation. Right, but I have no explanation of what this means. I have, I mean I guess it's, it gives it does give me my code, but if I'm trying to understand what this means. I don't understand it you have to click these question marks. And so that's why I think we ought to choose for this one to put information about these six columns into the help for change build status right so take your idea of Hey, what what is instruction mean and what does percentage of branches and percent of percent complexity, etc. Right, what does each one actually check for right and then make sure that minimum and maximum means what I think they mean, which is not with the stack flow, what we what not what you got coded right now. That makes no sense as to how I understand I mean, if I say if I'm checking to see between a minimum and a maximum. It should not require exceeding the maximum to succeed that's not and and I this will be a fun one because I think I think I've got the right interpretation and can I but it'll be it'll be a worthwhile thing to try to prove it I think that in this case pipeline pipeline did something really cool they exposed internal variable names and when the internal variable names are poorly chosen, those poorly chosen internal variable names are exposed to the user. Right. And I've got a sort of a classic example or really embarrassing poster child example right here. Let's see this one not get we need check out. I'm going to show you some horrible terrible embarrassment. Look at this. Okay, so. This they all this is my new version I gotta use the old version. This is that this is the one that's got the fix. Here's the ugly version. But the mistake I made was made the state the mistake original Jenkins get plug in implementers made that I've never corrected until very soon coming up in a new release is this if I say check out. And I say get and nothing else. I'm still still on the wrong computer sorry Meg. You can tell me what it does I trust you. It just puts I've got to show it to you this is just too fun. It's the the embarrassment factor is amazing because what it does is it it exposes an internal implementation of something that has no user interface in in anything except in the pipeline. And the reason so notice this horrible thing do generate a sub module configurations faults. If a user ever says true on that thing. They will invoke code that I have never tested that has no automated tests has no safeguards in it. And I expect to die a catastrophic terrible horrible death. And so so it's one of these oh whoops somebody looked inside the get plug in source code did the Java code did is what did and sees there is a variable name generates some module can do generate some module configurations and they allow the user to set it. That is really cool, except that this thing is terrible code that is not intended to be used by anybody. Right. So sorry we are we are now at our time and we didn't even get through one item. Meg are there other topics I have I have no updates these people are blowing me off I don't know what the deal is but no problem. One thing I would say back to the beginning of this for this. We all the way you talk about the pipeline, the pipeline documentation, I would refer to this as steps reference. Very good yeah that's that's much more clear. I tell you how recently it was that I figured out that the snippet generator is generating steps. Right okay and then it ties to the steps reference, because we all just just talk generically a pipeline. Right, that makes everything makes so much more sense and try now we've got a new writer trying to make this stuff makes sense and it's like. So I would say that the other thing that I would propose after working with you for all this time. So it looks like there is a convention for the HTML file to have the name of the step in that. And name of the step or name of the variable yes that's correct that somehow perhaps we should have a test maybe it doesn't break the build, but puts out a warning if I try to check in a plug in with a step that does not have the document that does not have an HTML file of that name. Oh, that's an interesting idea an optional check that asserts help is available for every pipeline parameter pipeline argument pipeline step and pipeline argument. That's it that's an interesting one yeah. Because other, you know, otherwise if I'm and because we know we we didn't do the class on how to how to do how to do a plug in. There is nothing there I go out of plug in I test the code the code all works. I'm done. This would at least tell me that not quite. We don't. And we could decide I mean I'm a dock person I might get nasty and bust them and not let them merge it but. Well, but that's that is that should be an option left to the plug in maintainer. Because if that if that test were mandated for everybody all the time it would hard stop development and people just find ways to turn it off. So, but, but there is the concept in plug in development of an injected test. This is a test that is inherited from the parent. And so the plug in maintainer gets it for free. And that injected test does some things that every plug in is expected to pass. And so this, this, this idea could be at an injected test that checks pipeline arguments checks for pipeline help for help for pipeline steps and arguments. And now we are forcing them to name their HTML is in a certain way. But I can live with that, because I'm also thinking that if, if somebody drops support for a plug in and somebody else adopts it. That that's going to make maintenance much, much easier if there is that mapping. Right. But I don't have to figure out that somebody was being cute that day and named everything after their pets or. Right. Yeah, very good. So that becomes a rule they need these HTML files that include the name of the step or the variable or whatever. Um, what about, oh God, this is going to, um, the, the, the, the, the, the, what the declarative. What's the D word. I'm, God, I think the Alzheimer's is clicking in declarative pipeline. No, no. The other generator that goes with snippet generator. What does that do. Oh, right. Okay. That's, I think I know what you mean. You're talking about this thing right here, the declarative directive. Directives, that's it. What do we have for self documentation on the directives. So that there it's actually pretty strong. The challenge usually is that at least for me, it's not always that it does exactly what I want. So, for instance, I say stages and then if I say add a stage. The stage is going to be named. Let's see, get the code. Stage will contain sequential stages. And we're going to add agent. One of those stages needs to be running on the label that is windows. And then needs to be an agent stage that is running on, let's see. Well, so let's generate, just see what that does so far. Okay, so here we go. So is this what you were thinking of, which is the direct. I can't see your screen so. Oh, oh, sorry. Right. I've stopped sharing haven't I. All I can see is your face, which is lovely. Lovely face. Absolutely. What a marvelous face. Here's to the face. Okay. Here is the screen so if we make this large enough to actually read. So it's, I just added a generated stages. Stage, and then one or more stages to include inside the sequential stages block and now. Let's see, it's, it's for me the declarative generator is it works really well in those cases where, where it, it hits what I need their time so and I, I seem to bump into surprises where oh it didn't quite give me what I wanted so here's agent any. Here's I know I would like to be running only on Linux. No, I want only run on free BSD. There we go. And now if I do that. So the directive generator but it's my sense was it's pretty well described. And here we've got an entire section talking about the directive generator elements of the directive generator and then if I remember correctly. In this page there is actually a series of screenshots of the directive generator itself. And then code examples. And we'll, but plugins don't add to this to the directives right the directives are at Jenkins level. Plugin add a directive. I think it. Let's see if that would be that's a good question. I think plugins can, for instance, add to any of these things so for instance a plugin can add when conditions and if we check this triggered by is likely added by a different plugin then building tag. Okay. So plugins definitely can add and and users. It's again a reason why users should use the generator built into their system as their first choice and only go to the steps reference or to this declarative reference page as second choice. You know something and that steps reference page that's generated automatically. And that is, read more about how to integrate steps into your pipeline and the step section of the pipeline syntax page. It just never tells you that the snippet generator, generate steps for how to do with the syntax. Oh, all right so that might be. And that's what and then the pipeline reference. Those are the directives and that's for that you have the declarative directive generator. Right, right good point this. So this boilerplate text that appears on the top of probably written 10 years ago right long before there was a snippet generator. Actually, I think it's intentional that it's only talking about declarative but as a matter of practicality we owe it to the users to point them to, to scripted syntax as well so. So this says okay here's the pipeline syntax page and this is entirely declarative. No it's not. Okay so there's one little section on scripted. And what does it say about steps women it's got a two slides down scroll just a little bit down down down down. Okay, there are steps. It's fundamental part is the step function on scripted pipeline does not introduce any steps, which that should be that are specific to its syntax pipeline steps reference contains a comprehensive list of steps provided by pipeline and plugins. So this takes us to that long exhaustive reference. Right. But when we said, I said where are we going to put examples and you said well better than examples is to use the snippet generator and that will give you. Right. So the steps reference should link should point them to the snippet generator. I think so right so. So this. This should also have a pointer to because there actually is a page on on Jenkins.io that talks about the snippet generator. All right. And so let me find it because the get plug in links to it. So here is. Let's see video. I find syntax helper. Oh, come on. Now that's embarrassing, because I knew that I had placed trying to persuade people to use the syntax generator the snippet generator. And now I don't know what I've done with it. That's really sad. Huh. Okay, good. They were called we're referring to it as a syntax generator and the snippet generator we should choose a name and. But let me show you that we are there to different. No, well, okay, so here it's called snippet generator. Right. And but now you see in this context what it's doing it's saying the same thing as what I get here if I click pipeline syntax. So it really is the snippet generator pipeline syntax gives me three different choices for what to do with. So there's pipelines. There's pipeline syntax snippet generator, same page pipeline syntax declarative directive generator. Then there is steps reference. That one just global variables reference. Here's another one. Here's another one. So again, each of these is part of this overall page that is pipeline syntax. Okay, so snippet generator is part of pipeline. It's a, it's, it's one of the pages under pipeline syntax just like declarative directive generator is. Okay. Now, now, I think there's a problem here right snippet generator has this thing in the breadcrumbs has pipeline syntax in the breadcrumbs. Right. So declarative online docs. Oh, that's not that's jumps out steps, global variable reference has pipeline syntax in it. But declarative directive generator does not. And I think that would be a help if it did. Yeah. And then, then there are, I guess there's an ordering thing here. Some of these page some of these links go stay inside Jenkins others go to the Jenkins that I would doc site. And that's a little surprising to me the first to stay inside the next to go outside. But they do say their documentation. Oh, that's right they've got hints they got icons that hint that well no except look at this. This one stays inside, and is actually generating the pipeline syntax docs. While we wait. The steps reference basis. So that's not making to the steps reference page that's bad. No, no, it's, well, it's actually good in that what it's doing is generating the equivalent of that steps reference page based on the plugins I have installed. So this is my local precisely matched version. So if I hear this is a fun one because now I can check it. This time, let's see if we can see no. Oh yes, no. Huh. Okay, so I'm, I'm not sure. So this is another way that we could teach developers to check their, their online help. If they go to pipeline syntax and go to steps reference, it will regenerate the, it will generate the help by reading their, their plugin. Now, okay, this is all right. Yeah, look, this is my this is my stable machine, the machine that I didn't install the new plugin on. Here's my new machine. Where I did let's go to the steps reference. And we're going to look to see that jacoco plugin got my now it's still generating the page so patients patients patients. So, now if we look for jacoco here, expand this maximum branch coverage. Minimum branch coverage so my text got added. Okay, now, now this reminds that when recording this video this is the place to point them saying hey, click this, wait patiently, it will generate it and then you can go read the help for your, your, your, your thing. Right. Oh, I just have a whole new section to write in the training materials but this is this solves a problem. Well, so, so, and, and this reminds me that we've got a bunch of places that I like your idea of a check we've got a bunch of places that really need much more. Right. But it's nice that your get is is one of the better ones so that's good. Well, it's, yeah, but it's been an enormous amount of effort to get it that way. And so, right, I'm not sure we're going to persuade other people oh yeah you should, you should invest great large quantities of time in creating online help. So the interesting problem. Yeah. I apologize. I need to end. I am going to call us to a stop. Excellent. Any objections if I post the recording of this after it's not at all. Excellent session mark. Excellent. All right, thanks Meg. We'll see you. You take care. Talk soon. Bye bye.