 Welcome everyone this is pipeline help she code contributed she code Africa contribute on project meeting today's May the 12 2022 topics I had on the agenda questions and answers and what's next. Forgive the very weak agenda. Are there other topics you'd like to be sure we put on the agenda Sophia from you or nafisa from you. Maybe get plug in pull request progress from last meeting right because that's a good one. And actually it's pull request plural. Sophia is PR and office PR. Any other topics you'd like to be sure we get on the agenda. Yes, please. How to kickstart documentation for a chosen plugin. You probably discovered a plug in that actually needs documentation from the least that when you document let's say for instance, the issue to be request. Do you just go ahead and start documenting. Good question okay so let's put how to add documentation to a plug in and we'll put that as multiple locations and multiple levels of documentation that can be to improve good. Very good okay so is that an okay way to phrase it we'll put that on the agenda. Yes, yes. Okay good alright. Any other topics you want to be sure we cover on the agenda. During the gates right the gates documentation, it actually created like a separate branch. Yeah, we are working with that's what working with. So, for all that plugins are we going to do the same for the same pattern we use in the gates plugin. We just create like our own a separate branch then that's working with that branch. Good question and let's let's put that one is I'd call it the branching technique for pull requests. Maybe it's why did we use a separate branch branch for the get plug in. And why won't we use won't we use separate branches for other plugins does does that. Good topic for the agenda. Any other topics. Now I apologize but I have to set a hard stop at 45 minutes, because I think Bruno you and I may have. Maybe it's no no maybe not let me sorry I need to pause my sharing for just a minute to check my calendar my calendars a little frantic today. Let me do a quick check of my calendar. Oh, yes, I have a hard stop in 45 minutes because I'm preparing for another, another event that I have to host. So, so I apologize we'll have to stop in 45 but let's get this up on the screen again and share screen. Okay, good. So, alright so pull request progress branching technique how to add documentation to a plug in and what's next. Anything else that should be on the agenda. Okay, then let's go ahead with those and we'll. So we'll look first at progress here it's what we can see is. Thank you Sophia for yours that you've submitted. I've made a request for some changes. Oh and it looks like you've applied those changes good, and you did that. I'm not going to bed or after I disconnected yesterday. Excellent. Okay, so you've applied the changes and they should be changes, changes requested and applied ready for review again right. That's that's the process we like, and my apologies Afi that your PR came in just a little bit after Sophia's and I didn't get to your review yet so I am behind schedule there I need to review this one. And I haven't done the reviews yet thankfully the CI job did pass. So that gives me the confidence okay it's not see continuous integration did not find any problems with it. So, this one needs review needs review likely needs changes. And then. So, Afi what we'll do is, I will mark will review late today. So, by late today well after the time when you should be asleep and long asleep. So, Afi if you check tomorrow morning for comments and changes. Okay. Thanks for doing it both of you thank you very much for for spending the effort and for good progress there. I have a question that came out for the two of you on that experience of submitting those. Oh actually, that leads us to the next topic but any other questions beside the branching technique. Oh, you go ahead, go ahead. We kind of had a discussion yesterday so I guess that's what Sophia's about say. No, I was actually going to ask how to resolve requests. In case, like when you request for change up. Do I actually like resolve it because I noticed that some of the comments we are not outdated and I had to probably manually go resolve every requested chain. Yeah. Okay, so, so let me see if I got your question correctly when a change is requested. Should I resolve the comment. If GitHub did not resolve it automatically. Yes, yes. Good. Okay, and that's a, that's a question that so to highlight in case others may not be aware what that means. What you see here if oh whoops if we look at Sophia's with that had changes requested. What you'll see is. It shows this. I offered several suggestion there's my comment and then hidden behind these gray bars are a series of let's make that bigger so it's readable of things that are listed as outdated changes, and it says show resolved so if I click show resolved hey, this was Mark suggestion he suggested change, remove this text. And what Sophia did is she, she accepted that change I assume accepted it and then did the correct thing of mark the conversation resolved because she'd take an action on it. So, so usually, if your action that you're taking does what you feel would be resolved completely the conversation then you absolutely should do exactly what you did and market resolved, because it helps me as a reader later to know oh she's processed the correct thing she thought about them and decided yes this one is solved. And, and she, whether whether you accepted my change or not by you're showing it as resolved. That tells me, you've thought about it, and you've made the that conscious thought. Yes, this should be marked as resolved. So, did that answer your question Sophia. Yes, thank you. Now to give you that there's a subtlety hiding here. There are some places where a comment is made. And someone may say oh I think it's resolved a market is resolved, and others find it that. Oh no it's not really resolved and they may correctly say I'm going to unresolved this conversation because we need to need to talk more about need to chat about this. So, if we need to chat more about this, I may unresolve it. And some in some projects people will say hey please don't resolve my conversations because it makes it hard to find my comments. So be aware of the place where you're at but for me on the get plugin and for most people, they will find it helpful if you resolve the conversation when you think it's done. So I'm going to list it as now and now when you look at it you'll see oh here is this it's still outdated because the change actually as has been applied. But I unresolved it and now after it's resolved, then mark can resolve it then in mark or Sophia could resolve it. And so now I'm going to resolve it again. Good. All right excellent question. So did that did that. Yes, in most cases is the answer, and that's sufficient for your, your question Sophia. Yes, this great. All right, so now, Afi you had asked the question about the branching technique and I apologize that I even use that branching technique let's look at what what came of that as a result so what happened was Sophia submitted her as a pull request to the Jenkins CI ad whoops back. Let me get the page back sorry to the ad checkout SCM examples branch. That's that's fine in this case but what it means is that hasn't been made visible yet. And even when I merge it it won't be made visible yet to users, because things that are visible to users are done on the master branch. So the fact that I had I started with a template and shared with you a template a fill in these things. And that was a help helper to get you started, but ultimately I'll have to merge this from the ad checkout SCM examples branch to the master branch. And most maintainers will want you to submit your pull request to the master branch rather than to the to to any other branch they want you to be proposing changes that they will put into production. Okay, okay. So, yeah, so what it was is, why did we use a separate branch for the get plugin. Mark wanted to provide a framework where Sophia and Afi could write. And that was, that was the whole purpose there right I the outline was not ready for the master branch. Because I didn't want to publish it to everybody. So the outline was placed on a separate branch. And then we collaborated, we worked together worked on the separate branch. When the work is done. It will be will be merged by me to the master branch. So that that that complication, we wouldn't want to put that through for other maintainers, but this way Mark will merge. But for, for the two of you for this particular thing it was better for your experience that we did it on a separate branch. So other maintainers want your proposal to their master branch to their primary branch. We quit saying master shouldn't I, because the word master is no longer to their, it's to their primary branch master or main or default. There are all sorts of names people are using now to replace the word master. So Afi does that answer your question on the branching technique. So that means in the subsequent PRs will go to the, the main branch right and then we just push the or create a PR directly instead of going to a branch that probably will create or wonder you create. Yeah, I know I now understand why we did it like this. Well, well, and you said it very well and I would, I would say it even slightly differently it's that in your development. You'll always, you'll always create a separate branch. Do your work, then propose the change the poll request from your separate branch to the upstream primary branch. So in other words that would mean here we might be saying the branch, you may name it add pipeline docs or pipeline help. And you'll then propose to merge it to the upstream and the poll request will be to the upstream upstream slash master. So now is that are you okay with that concept and is that clear to you. Yes, it is. Okay, great. Yeah, one of the other things one of the other mistakes that some people make sometimes is they forget. Don't forget to create that that separate branch, because it's, it's complicates the life of a maintainer. If you're asking to, if you are asking to merge from your master branch to my master branch. And and it's, it's possible to do it it's just maintainers don't like it, they say please and that's why you'll see in these checklists. Be sure you're submitting this from a feature branch. Always submit from a feature branch slash topic slash I forget what the other fix branch. That's why this guideline exists in most of the poll request templates is, are you submitting from a feature branch it's because they don't want to bother the maintainer with how do I merge from your master to my master. Yeah, that that really makes sense. Okay, so the next thing I was going to ask, I think Sophie already put it there about the documentation that's one of the questions we had when we spoke yesterday. So, then how to add documentation to the plug in what software guides that we know where exactly or the parts are very relevant or where to put more information. So what I should choose one plug in let's say so over the weekend if we get time would like work on one particular plug in and on different areas for one plug in or you want us to take different ones and work on different places we wanted to like know your thoughts on that. Good question very good and that's that's an excellent question so so what I'd propose is let's talk about the different locations that you could improve and the levels you can improve because because there are different ways that people learn about and can experience Jenkins plugins right there are different different layers that they see things at so so what I'd propose is let's start with a discussion of plug in documentation from plugins dot Jenkins.io as the first level so let's call this. Can I do a number thing there I must be able to So plug in documentation documentation from Jenkins.io is for me one common place where people go and it already may be a place to improve the next is plug in is plug in online help from the pipeline keywords. See what's the and there's another word for keyword may not be the right word tasks, a mess call it from individual pipeline tasks and plug in online help from parameters of individual pipeline tasks. So, so what I'd say is let's first do those as a as talking points as to how each of the how you might do each of those levels and how you might help at each of those levels. So the first one here plug in documentation from plugins Jenkins.io is exactly what you did what you did for the get plug in. The reason I say that is if I go to plugins Jenkins.io and open up the get plug in. What we see here is exactly the contents of the get plugins read me file. This read me is the plug in documentation. And so by your submitting a pull request to update this read me file, you are improving the documentation on plugins Jenkins.io. Sorry. I'm so sorry things are growing in my in my area in the world and my allergies just caused a sneeze I hope I didn't defend any of you. So sorry. I really try to mute quickly and I didn't get it done in time. All right so. So the by submitting a pull request to the read me. You've submitted a request to improve the documentation on plugins Jenkins.io and, and we hope that's the first. So that's a common experience it may not be the first but it's the common experience for people to read the plug in documentation. And if we look at a typical plug in on Jenkins. So the get plug in has an awful lot of documentation because I've tried to work hard on making its documentation. If we look at other plugins let's look at the badge plug in for instance there's a different example I use this one quite a bit but if I look at its documentation. It talks about methods and their parameters very nicely but doesn't give any real helpful examples that I at least really get. So, so badge badges one where knowing why you would use badges and how you would use them and an example pipeline file could be could be quite a bit of help, or if we look at, let's choose other another plugin like maybe we pick. Oh, let's just look at some popular plugins let's browse and instead look at all of them. Maybe look at. Yeah, let's look at the script security plug in. Well, it's got pretty good documentation. Okay, so that was a bad choice. But what you do is you can look for plugins and documenting at the read me level is a good opportunity to help the plug in and improve what it does for users so maybe. She could use. Sorry, what was that. Oh good let's try that one thank you you're giving us all right so let's take this one. Okay, yeah, so here, here is the the HTTP request plug in. And now if we wanted to add additional help additional guidance to this, we can certainly write more. There are things we can improve here like stop this from being a wide scroll bar and and make sure that the code actually looks right when it's laid out on the screen so so there are lots of improvements to be made there. Yes. So this is a good one and the way you would do this is you just submit a pull request to the read me file. And here's the read me. And what do you know it looks exactly the same as the online help, because that is the online help page for that that that plug in. That's the first level is submit a pull request to the top level read me with the with more examples for instance, and more text describing the examples, just like you did with a get plugin. And that one, that one is a good help. However, it doesn't address one of the common mistakes that we saw from many users is many users complain that the individual pipeline task documentation are inadequate. Incomplete inadequate flawed etc so let's use HTTP request as an example. So first, first page top level read me. What about let's look for this same plugin in the Jenkins documentation set so I'm going to go to documentation let's go. Let's go to the right site and of course my navigation is not working from there. Here we go. Now we go here to HTTP request plug in. And this is the documentation for the HTTP request plug in. Interesting. Now if you want to improve this documentation, you have to find the location for that inside the plug in source code so this is the second level. All right, so pipeline task documentation is inside the pipeline the plug in source code. Because it is displayed to the user. As online help, and is also automatically extracted to the to the that's what we just to the online documentation page. So let's take the example here, where to go. No, I jumped too far. Here we go so this page pipeline step page is extracted from the GitHub repository. So if we look for some words for instance like this one performs an HTTP request. Now if we search here we should be able to find that text. Here it is. So it's in this HTML file. Now why an HTML file well because it's delivered as online help and we have to present it to the user using HTML. So what this is is extracted from HTML help page. And so if you want to improve to improve that that help page, submit a poll request for the HTML help. We've now talked about documentation for plugins that Jenkins that IO, and exists, what I should say differently, existing plugin online help for individual pipeline tasks. And what we did was find it there, and you could add to it. And that's a good way to add value of, hey, I'm going to provide some more examples, or I'm going to provide more details about this thing. Now the bigger challenge is when we have missing plugin online help from parameters of individual pipeline tasks. And again, this is why are we carrying because many, many users complain that the existing documentation is incomplete. Let's go back to our HTTP request plugin and see if we can find an example of something that's incomplete. Like. Yeah, here you go. Custom headers has no description. Telling us what what is custom headers how is it used what does it mean form data has no description. What is it, what does it mean. HTTP mode does but if we wanted to add a description of what our custom headers and what is form data, we need to find the place to create that that online help. So let's question so far. Sorry, I'm, I'm talking an awful lot here and I'm not letting you ask questions. Afi or Sophia do you do you have things that you'd like to ask at this point. No, no, no. Okay. All right, so, so what we saw then is here we've got custom headers that has no help text but HTTP mode does have help text. So what we would guess is help for custom headers probably needs to go into the source code somewhere near the help for HTTP mode. This is just me guessing but that's, we've got to insert something so we need to find the location, find the location where that help should be inserted in the source code. Insert some help compile the plug in run it in Jenkins and confirm that the help we added is visible. And that that's not as not as friendly as I'd like it to be. Right, but I have to openly admit that's the reality for right now that because this help is done. It's placed in specific locations by convention. The name of the help file is is chosen based on the name of the data field that it's documenting. And so we have to find that location and just and put it there. If you're okay we've got about 10 minutes I can try this experiment really quickly here and see if we can do it with HTTP request and custom headers. Would that be okay for the two of you admitting that I may fail. That'd be great to go ahead. Okay. And so here is my working environment. I haven't is the text there large enough to read. We have HT. Oh we already have HTTP request so apparently I've worked with it before. All right so we need a fork. Okay so the thing that we wanted to document is custom headers. So I'm going to first look for it. Okay, there are a lot of mentions of custom headers. And we've, I think that custom headers documentation will probably be somehow similar to the documentation for HTTP mode so I'm also going to look for HTTP mode. And there are lots of mentions of HTTP mode okay so so they're probably both in there somewhere. Now, there is already help text for HTTP mode. It says the HTTP mode of the crest such as so I'm going to copy that and try to search for that. Okay so notice that this file. Source main web app help HTTP mode HTML has some text in it that matches what I was seeking. So does this one. Another one. So let's look and look at those two files and see if we can guess which one is the one that we see on screen. Okay, I can't tell because they are the same exact text. No, there is one which is capitalized sorry to interrupt Mark. Oh, there is. Oh, very good Bruno. Okay. So this one is in lower case and the other one is in uppercase. Excellent, we get very lucky. Very good. So we know which one it is. Thank you Bruno. That's great. Alright, so we got very lucky that this is the one that is really being displayed in that page. Excellent. Okay, given that we could guess. Now let's look for HTTP so it's the path here tells us something about it so a source main resources okay it's text files, or it's not source code it's related to source code so text files HTML etc. This class path and for the class HTTP request step. Now, if we look at HTTP request step this class and where where does it occur in in the tree. We see oh here's a Java source file. Okay, so that's the implementation. Here's the configuration page for it. And here are a bunch of different help files for options or parameters to that HTTP request step. So this looks quite promising. Alright, we've got content type and if we look here, content type has this description. So somehow I'm hoping that custom headers is in this file. And is mentioned there, which it is, there's custom headers, and it's got this thing called the data bound setter which makes it. That's that's Jenkins Jenkins stuff to tell us yes we can use that. So, I wanted to add something for for custom headers. So what I do is, just as there was a content type. I'm going to cheat and copy that to custom dash custom headers, where that is this thing right here. I just killed my terminal. Oh, that would be sad. Oh, there we go. Okay. So now I've created this file I admitted it's got the wrong content, but I'm going to add some content to it. Okay, so this adds. And I'm going to make a guess add custom headers, HTTP heading headers to the request that is sent. Now this one really would beg for much more description because custom headers takes a name, a value and a mask value. But let's try just that much just what I did, because let's see if we can see that already. So maven clean Jenkins that version equals 2.347 HP I colon run. And what this is going to do is compile the plugin. Start a Jenkins version 2.347 with that plug in loaded so that I can experiment with it explore it and see if I can view the online help for it. Now while it's doing that because of the way I'm developing I have to turn on the tunnel. Sorry about this but my because I'm not developing on my own local machine I have to. Okay, I think the tunnel I want is this one. All right, so we're going to look at local host. And you won't have to do this because you develop on your own computer. There. Okay, so here we have Jenkins 2.347. And if we look at the installed plugins. We should see HTTP request right here, and it's private something something and wait. So we were successful. And if we're lucky it's got enough of pipeline loaded that when I do slash pipeline dash syntax. I'll be able to see the online help. It does, we got lucky. So HTTP request here the here's the online help that it already had under advanced. We're going to look for custom headers. Custom headers. I don't see my help. Okay, so I was not. I was not successful. It doesn't show my help there that I thought I was going to get. Okay, so sorry you've watched me fail. Once again, if you'd like I'd be happy we could schedule the session even tomorrow if that works for you to try to do this exercise again and try to get it so I succeed. Yeah, yeah, that'd be very good. And so if you were by you would be happy to go. No tomorrow. I think Monday. Monday, if Monday would be better for you Monday, let me let me double check my calendar just a minute I have to look at my work calendar. Monday at this time so right now we are at what time we are at. 8am so Monday. I could, I could move some things around and make this time work for Monday. So if Monday works for the two of you, Sophia and Afi, is that okay for you. Yeah, but I would love it to be an hour later than now. An hour later. Okay. Yeah, let me double check my calendar then. Just a minute for you. So, okay, so an hour an hour later is actually a little better for me as well. So that's great. So if I do, because right now we are at. Yeah so 9am 9am my local time sorry talking yes that time Monday would be great I can move that one event. And then for Monday, we will talk then I'll schedule it. And thanks for your patience as we go through this. Thank you to. All right. Have a great day. Bye bye. Bye bye.