 Welcome. It's the 11th of April. This is the Jenkins Project in Sheikot, Africa, Contributon. First session to get started on Jenkins Inclusive Naming Project. Thanks for being here. We're being recorded. A copy of the recording will be available in about 24 hours through community.Jenkins.io. So peace and Catherine, welcome. Thank you, Mark. So what I think we should go through today, what I'd propose anyway is let's talk through the tasks and let you ask any questions you may have about the tasks or, or hey, how are we going to approach it? What I'm working from is this document. I'll paste a link to this document into our chat channel. It's available in that folder that I already shared with you and is also available mentioned in the Slack channel. So this talks about the initial tasks and what I'll use is I'll use this document acts as a place for our notes for this session. And we'll then discuss and talk through what questions you may have and we'll answer them and take notes in the document. Does that work for the two of you? Yes, it does. Okay, great. So let's start with the sort of high level picture. There are a number of places in Jenkins where as a 15 year old project, it uses some terminology that is not as inclusive as we'd like it to be. What we've done is been through the effort to identify what the replacement should be and how to make those changes. So the term master, for instance, is being replaced by controller. The term slave is being replaced by agent. The term white list is being replaced by allow or allow list in phrasing. The term blacklist is being replaced by deny or disallow. Those are the terminology corrections we want to make. There are many, many, many places where we have to make those corrections. So Jenkins is a system of, well, of a core component that is already quite a large component. And then if we look at plugins and just browse them, you'll see 1,800 plugins in Jenkins, and there may be terminology mistakes in any one of these plugins. So we want to be to be able to correct those mistakes, actually submit pull requests to correct those mistakes to as many as we reasonably can in the project, we know we won't get through all of them. We know that the top four or 500 of these plugins are the most interesting to Jenkins users in general. And therefore, will it will approach those first. And when I say top what I really mean is number of installation so if we look here, this right now let's search, let's sort by most installed. And you'll see that there are 308,000 installations of the script security plugin so 308,000 controllers in the world that use this plugin. If there's a terminology mistake in it, fixing it in this one plugin can fix it in 308,000 installations so it's a nice nice way to have a big impact very quickly. Excuse Mark, can you zoom your screen a little if I can't see it. Sure can is that better. Yes, yes. Let's see so is that is that is that workable piece. Yes, yes, it's okay now. Great. Excellent. Thank you. Thanks for the reminder. So, so what we see here is there are, there are many many plugins that need to be checked to see if they have an issue with the terminology. Now in addition to the many plugins there are each Jenkins plugin includes several different forms of content. So, they are Java source code. There are HTML files that are used for help. And there can be property files that are used for strings or jelly files that's j e l l y jelly files that are used to define the user interface. And there can be terminology mistakes in each of those three places with different changes needed in each so it needs a little bit of thought and some programming skill to decide how to make the changes and which things to change and which not to change. So inclusive naming actually is a hybrid of a change text and think about programming and do programming experiments to be sure that that's the right thing to do. So we'll need both your skill as identifying things and your ability as a developer you'll need to do some compilation and run compile things and see that they work. Any questions so far. Okay, then let's not from my hand. Okay, great. So then first step is you'll need Java. For Java 11. Check that you've got it you'll need Apache Maven, and I've been using Maven 3.8.5. You can use 3.8.4 either is fine. You've already connected to the channel, the, and have both of you already registered for a Jenkins account. Yes, I have. Okay. Great. Thank you. So then you need to use these installing instructions to install yourself a local copy of Jenkins. Now the local copy of Jenkins it's probably better for you. If you do it using the war files technique, rather than using a for instance the Windows installer now which platform development platform each of you using so Catherine are you on Windows Linux or Mac OS. Okay, and, and piece Linux Mac OS or Windows Windows okay good so so for both of you it's probably best to follow the instructions in war files because you're going to be doing more development centered things, whereas these install instructions on Linux and Windows are mostly about people who want to run in production. So you're going to be doing development work so use the war files technique to do your installation. Let me make a note of that. Okay so use the war file install instructions so that you have an easily maintained local development instance. And then you don't have to become the root user in order to make changes you don't have to create an administrator account on Windows, any of those things. Now this suggests that you should install Jenkins install the recommended plugins and the blue ocean plugin. Now there's, there's good information about blue ocean. You will you may or may not need it if you're interested in learning more about Jenkins and, and it's pipeline visualization tool called blue ocean. You can go to this location and read all about it. I'll put that link in the in the document as well. Yes, I was trying to install blue ocean and it says I need to have administrator permission. It said you so Jenkins said that you needed to have administrator permission. Yeah, I'm reading it wrong. No, no, that's that's so. So if your Jenkins is, if you did a relatively specialized Jenkins configuration you might not be logged in as the administrator. Let's do a quick check be sure. For instance, if I look, let's do this way weekly dot ci dot Jenkins that I was a is a running instance and if I attempt to do, I can't do a put an installation here because I don't even have managed Jenkins. Now if I log in. Now I have managed Jenkins, and in this case then I can install plugins. That that may be what you need to check if that's not enough. Then let me know and we can do some further exploring. Okay. As another example, yours. Yeah, well, other examples won't help. It's the same, same thing just be sure that that you are, for instance, logged in here, and that you have available to you choices like configure. So, and getting Jenkins running with blue ocean is a is a good step for for your familiarizing yourself with what this, what this means and what it is to run Jenkins and what can I do with Jenkins Oh I want to create a new job therefore I do this I want to, I want to administer it I do that. So this is a good thing for you to explore during these two weeks of preparation. Using your GitHub account fork up plug in repository. For instance, they're here it suggests pipeline build step, and be sure that it's visible in your account so by that I mean you go to the Jenkins pipeline build step. And here if I click the fork button. And it says marquee wait that says I've got it forked already. So I have a fork already of this. And if I go there like this, instead of Jenkins see I go to marquee wait you'll see here is my copy of that of that plugin. And when I want to update it I click fetch upstream and that gives me the most recent copy into my copy of it. And this would be a working place where you could make changes, and they're just yours. You don't have to share them with anyone. They're there all yours. Have, have, have you each had some experience with GitHub and forking and pull requests yet or should we do a session later on forks and pull requests. Yes, I have an idea, but I would love on a section because the, the time I use GitHub that was the first time I was using it and since then I have not used it that much. So, I would like you to give us a session on that please. Great. Okay, so we will plan for that. There is actually a mark, I will be presenting a session on GitHub. It's April 2021. And we could, we could have a session that lets me practice for that. Would the two of you be willing to be my test case so I can test what I'm going to present to everybody else to the two of you first. Okay, and, and could I ask one of the two of you to be my, my assistant presenter so, in fact, maybe I should ask both of you to be my assistant presenters if you're willing. Have you both had at least some experience with GitHub. Yes. Okay, good. So, so if you're willing, let me let me create some, I'll, I'll get an idea and we'll in our next session attempt to do it together and then you can decide if you're willing to be my helpers at the presentation to the rest of the group. Okay. Please can I ask a question. Sure. Yeah. So, the basic said, join get up and ensure that you can fork a gene king plugin repository. The plugin we are, we're going to fall. Is it the one that is listed on this Excel sheet. It may be, but we may find a way. So yes, you'll have to fork many plugins each time you need to make a change to a plugin you'll need to fork it. So each each plugin you need to change will need to be forked. So in that sense, yes, and the sheet that we're using. Where did I put that sheet now shame on me where is that sheet. It is right here. So the plugins on this sheet are exactly the plugins you'll be working so peace. For instance, you'll look at script security and see are there any inclusive naming problems there. If there are, you'll note it and then then you may submit a poll request to fix that. If you find those kinds of issues, you'll definitely want to fork it but you don't particularly have to fork it until you find that you need to make a change. Do you have a question. Yes, that's exactly what I'm asking. So I need to first find out if I would require if a plugin needs a change before I can talk that blogging that there is right there is no benefit to you to forking a plugin before you know it needs a change. And as an example script security as a test I went through it and I did not see any reason that it would need a change. I didn't need to change it I would think you would not fork it. So, for instance, when I look here for the word master. The only two places where the word master occurs is in a file that is Java source code and it's Java doc. That's harmless. Yes, you could change it, but it's much lower priority than us changing things that are visible in the UI. And here, this is another one this is in sandbox whitelist blacklist so the file name is is not inclusive right that's that's a poor choice of file name, but renaming a file is really difficult. Whereas changing because then you have to find all the source code that refers to it and you have to upgrade users. So we're not even going to attempt a file rename. So here it says, oh, this one is a comment, and you could change this one from master to controller. But again it's not terribly valuable because it's a comment inside the file so yes it needs it. Now if we instead said, what about slave. That's another non inclusive term. No references at all. Let's see how about blacklist. Okay, there are a few but again these are function calls in Java we won't change those and a string get resource that's an interesting one I don't know about that one. Yes. Yeah, so therefore no we don't have to, we don't have to worry nearly as much about making tests inclusive as making the product inclusive that people see. So did that did that address your question piece. Yes, but I want to have so if the name will want to change is in form of a script, we don't have to change it. If you find if you find something let's let's take this example we were just in that one it was let's see it was master right. And here, what I see is. Oh, okay this says there's there's a reference to master. We could change that and maybe let's go ahead and do that. We can't however change, and we could change a comment in the in the in this Java doc in this Java comment without harming the the softer functionality. We can't rename this file without making significant changes to support the files rename. We would not make, we would not change this file name. Now we might go in and change this file, instead of using the word see what was master right. We might hear. Now I'm just going to do this live and this is not the way I would recommend you do it, because I like forking and doing that work myself or doing it from my local computer instead of using their web interface but here we'll do it from here and we might say hey, we're going to change this. I did not give me this on the master branch sorry I've got to go find this, just a minute. Now I would like to edit that. Now it's put me into my editor. So I look for master. And I could change this. It's not harmful to change it it's just a comment. It really isn't helping much either for me to change it. And yes, I can now I'm going to go ahead and submit it. Fix a comment. That is, let's make make a comment more inclusive, rather than master use controller. Okay so what you're seeing me do actually is I am creating a poll request to the script security plugin to fix an issue. And, and I did it through the GitHub UI. Now I think you'll find it much better to do it from your desktop. But this at least shows you hey it can be done from the GitHub UI. What I'm doing now is I'm checking each of them. Okay I have not provided tests. So I'm going to use the till double till to the market out. And now I'm going to create the poll request. So now what I can do is I would put this into our inclusive naming sheet and say, there's a poll request. Actually it's even better if instead of that I just paste it like that. And I would, it would have been better if I'd done multiple changes in that one poll request, so that I didn't have to link to multiple times but this is good enough for now. Any questions so far. I do have a request. Is it possible we schedule another meeting, I think the next Monday, where we can pick one issue and then we go through the whole process. Absolutely. Yes, you bet. And if next Monday, that's a good thing because I'm, I'm sort of at the end of my time I've got other things I've got to do. If next Monday or we could meet earlier if that's if it's crucial to you but next Monday would be easy for me. And I think we might be able to schedule a 60 minute time so that we could do this kind of thing again would that be okay for the two of you. Yeah, that would be good for me. Yes, that'll be okay for me but I have a question please. Yes. What I was asking the other time was, if we, if you showed us a comment of white blacklist on a script. So I'm asking doesn't mean that we can't change like we can change the name when the, when the, when the name is on the script for you. Okay, you typed blacklist, and then it brought out is your breath with white this is brought out some codes where blacklist is included a kind of JavaScript file. Right. So I want to know, is it that we cannot change a script like in, we cannot rename a script is just the, the documents or will I say the read me file. So, so what I would phrase it slightly differently. It's that there is a there is a, there is a set of priorities that we have and let's so let's talk about that so there are priorities, priorities and, and improving success and increasing the likelihood of success. So, and now I'm going to outline which things so priority one. Whoops. Yeah, there we go priority one. HTML files are used for online help all terminology. It can be fixed in our HTML, and if they occur. So let's say differently, any terminology issue detected in HTML. Okay. And be fixed. And that's because it's, it's help text right. It is help text. And even if that's imperfect, but it's close enough, let's say almost any terminology issue detected in HTML can HTML can be fixed because it's help text. So we do that jelly files are used to define the you to bind the web page to the job objects. What that means is they have. They include some components that are variable names inside Java, and we can't change those variable names. They include some components that are just text strings that are UI text strings. We can change those components, we can change those strings. So peace, does that does that help you get a sense of those two things. Then there's a third layer which is Java files. Provide the core logic strings in Java files, often can be can be updated Java identifiers, like, let's see like, what's a good example. File path or slave to master callable cannot be updated without breaking compatibility. And we don't want to break compatibility. Our first focus is these HTML files, the jelly files. And if we find things in the Java files that we confidently can change without breaking compatibility, we would want to do that but more important is we want to preserve compatibility. So peace back to your question you asked, hey, couldn't I change blacklist. Right. That was, that was that example in script security plug in. Right, so let's get the Jenkins script security plug in here it is. And now you may ask, well, why couldn't I change that. Where was it. Yes. Okay, this one it's easy why you can't change it. It's an identifier blacklist is a Java method name. It's also not shown to users so that's okay, we don't change it. This one is more complicated because it may in fact just be a string shown to users, but it's inside a test. And because it's a test, it's not shown to users so we wouldn't bother with it. So let's look for master. That was the one that I think we found yes, why not rename this file, and my guess is and this is just me guessing but my guess is that this is a data file that's being provided with the product and other code depends on this exact name. I can't change the name without changing all the other code that uses it. So, did that, did that address your question about, hey, why didn't we fix this inclusive naming problem. Yes, it does. Okay, good. All right, so. Question. Yes, go ahead. Is there a list of or a document that shows the best practices, or the kind of instances that we cannot change the names. There, there isn't, and I think what we want to do is we'll assemble that here. So, so things that we cannot rename include. See if I can get it to do an indent. Java identifiers. That's variables, class names, package names, etc. Okay, so, so if, for example, we looked in the Jenkins Java doc, this is a good one for an example of lots of things we cannot change. So here's the Jenkins Java doc for Jenkins core. In Jenkins core, I'm going to search for slave. There's an entire package. So a bunch of classes Hudson dot slaves dot, etc. None of these things can be renamed. Because they're Java identifiers that are dependent on by other other things. If we were to rename them we'd have to rename everything everywhere we just can't do that. So there's an example of a, we can't make that change and proposing that change will just waste people's time they'll say sorry that's not acceptable we would break Jenkins completely if we made that rename. So Java identifiers know we can't change those resources resource file names, typically can't be renamed so again this is a form of Java identifier, it's not really a Java identifier strictly but it's it's the same kind of thing where a resource file name is probably used by others. Now if we talk about things we can safely rename Java dot comments. HTML file contents. HTML help file contents. We can do jelly file strings. We can do Java source code strings with several caveats with several risks that we have to evaluate, because there are a number of places where a string in Java source code may in fact, not be safe to. Oh, maybe we should say it this way. Localizable. Java source code strings. We can change other Java source code strings we may not be able to change and when I say localizable. What I mean there is strings that when running in French could be shown in French does does that help and we can certainly talk further about this in later sessions. It's a good, it's a good place to start. Great. Okay. So in terms of what I would hope is I'd hope that the two of you are able to go through the getting started as much as you can this week before we meet next week. And it would be really great if you were able to submit a pull request proposing a change. It would be as simple as you as you would like the one word change that I did would be that kind of thing would be just fine. If you would like to do it on a plugin that I maintain. Let me offer you several that you could you could consider this way will assure that you've got a reviewer and I can help so some plugins to, and these are not important plugins most of them they're just plugins that you could use to check out and use for experiments include the elastic access probe plug in the let's see the platform labeler plug in the test and G plug in the schedule build plug in, and if you're freely feeling brave to get client plug in, and the get those are all plugins that I maintain, and therefore you could, when you submit a pull request I'll see it, and I can coach you on it. Now ultimately, none of these are important enough, except these very last two to probably be on your list for a very long time they're all small infrequently used plugins. I apologize, I've got to end for now. Next Monday, same time for 60 minutes is that okay for the two of you. This is perfect. Thank you. All right, I'll schedule I'll schedule a session for next next Monday and we'll go from there. Thank you. Thank you. Yes, go ahead. What was that from with your calendar, because I don't know if it's the same thing for you. Easter Monday. Oh, we won't do it right next Monday would be a bad choice, you're right thank you because that's a bank holiday in many countries would Tuesday next week work okay for the two of you. And, and actually I had a quite a request from from nafisa our project manager, if we could move it earlier looking at my calendar I wonder, would you be available any earlier in the day so that we're not quite as late in your day. Well evening is all here with me. But I think we can move it on the, let's say, 7pm. Okay, and what's your offset from utc what what time is it now for you. Right now it's 945. Okay, so if we if we move to seven that would be moving it two hours earlier is that right. Yeah. Okay, and two hours earlier. One to two hours earlier would work for me based on that calendar let me check another calendar and stop sharing my screen to check my work calendar. Okay, so. All right. Okay, so next Tuesday the 19th at yes two hours earlier would work great for me if it's okay for the two of you. Okay, well he does. So, so good let's go for two hours earlier next Tuesday. And would Tuesday be okay in general could we move this meeting to Tuesday, my calendar on Tuesday is easier than my calendar on Monday. Okay. I don't mind if you move it to choose this or Tuesday every other week. Actually, we would actually try to do Tuesday every week. And, and if that works for the two of you. Let's go for Tuesday peace is that okay with you. Yes, that's okay with me. Great, I will schedule us for Tuesday each Tuesday and I'll make it two hours earlier in hopes that wait a sec Tuesday did I see. I've got to look at my calendar more carefully. Tuesday we are now here. One, two, one. Yes, two hours earlier works great for me. Okay, good. That's, I can, I can make that work. So, two hours earlier each Tuesday and, and we'll go ahead from there. Okay. Thanks both of you. Thanks very, very much and thanks for joining the Jenkins project. Thank you. Thank you. Bye.