 Welcome everyone. Thanks for being here. It's documentation office hours. The 11th of the 11th of August. Thank you. Sorry about that for the brief, the brief loss of consciousness there. I think it'll come back eventually great. All right, thanks topics I've got Google Summer of Code. Upcoming LTS. A question and a document structure topic for discussion in terms of how should we structure this particular section this is one that raised by Kevin. And how to describe the process of choosing a plug in bill of materials if we've got time. And the others I think could wait for another another session I'm a little weary today and so I'm hesitant to say that we'll do more than 30 minutes today, just because it's been a very long day. There are other topics you want to put on the list. Oh, it sounds good. Nope. Okay. All right, Ashutosh with you here. Is there something you'd like to specifically discuss with regard to Docker compose. Ashutosh you're muted. Okay, well, so if, if something comes up. Oh, go ahead Ashutosh is there something you want to specifically show to us or, or bring to the to this session of Docs office hours. Can you guys hear me. Can now yes. So, I wanted to discuss about how the, how eventually will work for documentation to update for the documents. Okay. Yeah, that's the main issue. All right, so let's let's I think that's a good one to discuss so what we have today. We have a GitHub repository or Jenkins.io. That includes the tutorials right with all their details. And we have Docker containers. Containers provided for each weekly and LTS release controller. We have Docker containers provided for agents. And I believe you're using SSH agents correct. Okay, so, however, what we and one and then the other thing we have is an awful, ugly, horrible set of instructions. Okay, that's the unkind but we've got a very, how do you really feel. Yeah, we've got a complicated set of instructions. Right, is that a good way to say it Ashutosh. What we want in the future is we want all those those first three things. But then we also want I believe Docker containers for the for use by Docker compose. Is that correct Ashutosh. User does not build this does does not build the container. So right now we are using my personal Docker repository for this. Sorry you're using say that again I didn't hear the what you were using. Right now we are using my personal Docker repository for this hosting the images, but in future we'll shift to the official Jenkins one. But so you're already storing the containers today. Yes, now you're using them as images. Good. Okay, so we just need, need to enlist help from the info team to create a repository for the container definitions, and that's currently in your account I assume. Yes. We have also created detection files for whenever there are changes to the Docker Docker files, it automatically creates and updates them is this. Okay. Do we need a policy for how many old ones we continue to hold up there. Usually, usually we just keep them all. So with every other container set we have we just keep them all. Well and and it's it's simpler because I don't know of a way it's it's uncommon for people to dispose of old containers on Docker hub. Okay. Okay, so Docker have location for the container images. And that's currently. Ashutosh is personal. Good. All right. Then once we have those will need a poll request. Jenkins.io to use the new container. For the tutorials, and the, and let's see. I don't recall if we had it in the install guide or not I think we did right. We do have it. Okay, good. Did that does that describe the future state well enough. So I wanted to ask the questions about how exactly should I create the pool request like, should I create one big pool request containing everything should I separate it out in small batches. So mark prefers small, small poll requests. One per tutorial. One for the install guide. We have one arrive and it be reviewed before you do the others in case there are some surprises. So what about the old instructions do we need to retain those any place for anybody who wants to use them or anybody who would choose that as such a mutant that we don't want them messing with Jenkins anyhow. I think we need to retain the old ones, but we'll have them and get hubs history in the get repository history. So if we need to bring them back, we certainly can. Okay. So Ashutosh does that answer your question in terms of pull requests. Yes, okay. And I also wanted to get your views on another thing. Okay, like one of the tutorials contains like highly depends on the blue ocean plugin. And we were thinking that we will avoid using blue ocean plugins since it's not being updated. Okay, since that one requires highly do we were thinking of not updating that one fully like we are trying to get rid of Docker and Docker and everyone every tutorial. So, we're thinking if we should update that that tutorial or not. Yeah, and well, while I gave you so so my view is, even though blue ocean is not actively developed. I'd rather not sacrifice, rather not sacrifice the tutorial. Due to blue oceans, less active development. Yeah. Because we expect them to discard these container images anyway, no reason to hide to to not include blue ocean in the. Now, let's ask Meg and Chris. I think that the blue the tutorials should include low blue ocean and that you should update this one so that we get rid of Docker and Docker completely. But if that's huge. If that's bigger than will fit in the time you've got I understand if that one doesn't make it. I would agree with that. I still think blue ocean is a great way to get started with Jenkins. I like blue and when I first use Jenkins. Well so I'm now strongly partial to pipeline graph viewer, but but I'm also a very different user than the first time users, right I am not a first time Jenkins user. The thing I like is there's a bunch of just tedious crap you have to do to get where any you can make anything happen. And with blue ocean that becomes very easy. And you can see what Jenkins says, and I think you pretty quickly see the blue ocean is pretty cumbersome. If you want to use it for production but right and you have a good point and Ashutosh's work actually reduces a big chunk of the tedium in the setup process. It doesn't magically make Jenkins job definition easy, etc. So yeah, fair. All right. Ashutosh what other questions do you have. That's it. Thank you for answering this. Okay, I'm also thinking of including blue ocean. Because I, when I first used Jenkins I, the first tutorial I saw was with blue ocean so. Yeah, I like. Right. And I understand if your mentors say hey but blue ocean is kind of not an actively developing they're correct it's not, but it works, and it works well for the tutorial. Great. All right. And version documentation for Jenkins.io so Chris I believe Vande is still planning on a demonstration next Wednesday or Thursday. Yep, and also and maybe in our demonstration to dogs office hours. Oh, good. So it's like August eight. Oh, good. All right. Yeah. To docks office hours Europe. Europe here because he can make it to this time. Oh, good. Oh, that Kevin would love to have Kevin and Bruno both I'm sure would enjoy that that would be great. Okay, I'll be there too. All right. And so you say you're planning for that next week. Yep. Friday. So that will be the seven or is the first day 16th. Yes, Thursday. It's Thursday. So next week, August 17. 2023. You time. Yep. Great. Excellent. Anything else on version documentation. I think, um, I think today's the first meeting after that is exam that we're going to talk about like how to fix turn towards site. There are some issues with still, but to most meeting, we'll carry on and we'll talk about like how to proceed for the block feature. All right. Very good. Okay. Okay. Anything else. Um, probably not. All right. Thanks Chris. Thanks very much for your leadership there. On get that plug in modernization next meeting on that one is in about 12 hours. And Mark's testing still has some questions. I just posted them. But the code code is working. Right. So that's good. Yeah. To and and it looks up looks positive. Okay. Great. Thank you. Thank you. Any other questions? If you have any questions, please call us on Google summer of code. All right. Next topic then was upcoming long-term support release. We'll release it really be the release candidate released. Wednesday. And ready for people to start testing the change log and upgrade guide poll request is available. We'll do that until after I return from vacation. If others can review it, that'd be great, but it will need to wait. Any questions on LTS. Okay. So now we've got a structural question and this one is a. Meg and Chris in particular with your experience on documentation structure. This is for, for your, your consideration. We have on the Jenkins documentation site, a number of documents that are not directly linked into the left side navigation. So for instance, if we look at Linux. And we look at the prerequisites document here, you'll see. At the, in the section called prerequisites, there are links to hardware recommendations links to software requirements. And these are useful and valuable policy documents. Right. They talk about, Hey, we only support Linux versions that the vendor supports. The Jenkins project won't support unsupported Linux versions. We only support certain servlet containers and certain specific versions of those useful things, but they're nowhere in this index on the in the navigation on the left. Now, Kevin noted, Hey, maybe for this, that's okay. But then we've got some other things that are. For example, the upgrade guide from Java eight to Java 11, the upgrade guide from Java 11 to Java 17. Eventually here in the next few months, the upgrade guide from Java 17 to Java 21. And those are not linked anywhere immediately obvious at least. But you have to get lucky and find them usually it's updating to Java. And even that didn't find it. So update. Oh, yeah, so that's my search. My search tools are my search skills are weak apparently. But the answer there is this upgrade Java guidelines and Java to 17 is not linked in anywhere linked into the documentation navigation anywhere. And what Kevin was asking is, should we consider putting in a section that might be called support policy underneath system administration. So in system administration we have right now as an expanding subsection called reverse proxy configuration. What was, should we add a new sex subsection to submit system administration that is again an expanding section that has support policies or has. And I'm not sure it's support policies or if we call it something else. Platform documents or general. I don't know. Yeah, title is tough, but, but I definitely like the idea. And so that helped me with the title then because the kinds of things in it Kevin lists them here. All right, so Jenkins on Java 11. That's how do you run. How do you do the transition to Java 11 Jenkins on Java 17 there will be a Jenkins on Java 21. Java dot a doc is our, I believe our general Java support policy. Let's look and see if I'm even right about that. Yes. Okay, this is the Java requirements document where we say you must have one of the job supported Java versions we don't support other Java versions. So we've got support policies then we've got the upgrade guide so let's look at that one Jenkins on Java 11. Apparently not. I'm not calling the section something like platform reference, which would be for all. And but that is the point I mean if, if this is my if I'm a new administrator installing Jenkins for the first time. This stuff isn't that useful and I should be reading the guides that'll point me to it when I need it anyhow. Yeah, but this is something that that that an advanced experienced person might need to go to regularly. I don't know what references or weapons. Good, good question. Okay, so we do we generally have used geren's here in the heading so viewing backup. So I confess platform references would be fine with me as well platform reference reference info gets around the singular or plural but it makes for a longer. Well, how about platform information. Ah, that works. That works to you. I could dance to that. Okay, so if the idea then would be in the system administration section and make what you said resonated with Kevin as well was when I'm doing the install. It's a natural thing to read the prerequisites. Right. But when I'm after I've done the install it is not naturally come back here and look at the prerequisites again. Right when I'm in system administration mode it's natural to look in the system admin section. And the fact that there isn't a platform information section here is a hindrance so I like information is better than reference. I like that. I mean another might be platform details. But I think, well, I'm open to either what comments. I'm open to platform information because there might be something that isn't terribly detailed. Oh, good point. I like that. Okay. All right. I think it's broad as possible so because you've got this stuff now I'm thinking once you have the section you're going to find other things you want to put in there. Right, right. Well, and, and it fits this is sort of these are the kinds of things that are discussed in the platform special interest group they really are. So shall we support web browser XYZ shall we support Windows version this or that shall we support this or that Linux version and and those those are very much platform sig thing so using the word platform feels really good to me. Yeah. Yeah. Okay. Good. Thank you we have we have an answer I'll pass that along to Kevin. Great. Thanks very much. Kevin I like the way he thinks I will pass that along to as well. Yeah. Yeah. Yeah. Yeah. Great. All right. So next topic and this will probably be our last topic because I'm sort of running out of gas I'm running out of steam here. But this one is an open question on how best to describe a complicated technical topic. So here I'm going to open it and let's look at it and talk about it because I want some coaching. I just gave some good ideas but but the real challenge here is what I'm trying to describe something to a developer that is at least for me in describing rather complicated. Okay, so here's the story how it goes. Jenkins plugins have versions right and their versions have different capabilities. Usually it's that a new version gets more capabilities than an old version did but right versions change and those versions. One of the complications for a plugin maintainer is that when I'm writing automated tests that depend on other plugins I must explicitly list the version number of those other plugins. I don't have a great marriage to manage because I have to find the set of plugin versions that all work together. So we have this thing called a plugin bill of materials that avoids that problem by generating a set of plugins that are known to work together. The plugin bill of materials is very helpful for me as a plugin maintainer. I insert this little bit of thing into my into my plugins palm dot XML file, and magically, I can now refer to a plugin without caring what for without having to specify the version, because the version is embedded in this bill of materials. Okay, so you go ahead question. Oh yeah I love it. This is and in fact we use it in the get lab plugin we use it in many many many plugins and are very very happy with it it works very well. However, this this question the question came from this person saying, what's the value that I put here. Because notice the ellipsis there is admitting not clear what value you should put there. Yeah, no explicit. Right, and, and the reason it's not explicit is is all right on one hand. New releases of this thing come out all the time. So let's go look at those new releases. For instance, we're going to scroll down here and look at. Here are the releases. So, a release came out yesterday. And another and you'll notice the release number is not some immediately obvious number it's complicated long string of bits. And last week there was a release and the week before that there was release and the week before that. So, so, however, these releases are tied specifically to a subset of the total available versions. And that's where the explanation gets complicated. Okay, so what what what Kyle Leonard asked was, Hey, how do I choose the version. And so I tried to explain it. One of the questions for first was, Hey, I know what the artifact ID is. Should I choose the one that's like my Jenkins version so up here. Bomb dash two dot 387 dot X is like Jenkins two dot 387 dot three. So it's good that those match. And, and my answer was, it's good but not strictly enforced. So it is, it is highly recommended but not strictly enforced. However, there is something that is strictly enforced. When I choose a bomb line or release line. There are numbers that I can't go bigger than because we stopped doing bill of materials releases on those older lines. So, to this 346. The last version was this and then releases on that line stopped while releases on 361 continued until this point. And then 375 until this point and now 387 is active and the 2312 that's listed here is actually already out of date. It's now 2329. The complication here is how to describe how they choose the version. And now one idea is tell them to use depend of odd and let it do the work for them. And I really like that version that that choice because that helps them get it updated regularly anyway. However, that's that doesn't help them choose the initial value for that version. Some alternatives. Now we're up to the, or any questions so far Meg or Chris either of you know I have to understand what you said so. Okay, well, and part of the problem here is, I, I found this quite a complicated topic. As I was learning it myself, right and I'm not sure that I'm explaining it clearly and effectively even now and I feel like I grasp the concept very well. But it might be well suited to have diagrams or something, you know how sometimes we have stacked bars where there's a release lifecycle Ubuntu 18 lives for this long and then the next step is 20 and then 22. And these lines are sort of like that in that they reach a point where we stop doing any additional releases on that line. And so maybe a picture like that might help people visualize. Oh, that's what happens. This this one is hot. It's the changing one. These others have become immutable. They won't won't change any further. Why is 2.401.x not the hottest one. Oh, it's that we we maintain two or three or sometimes even for that are hot. Okay, so the last two are actually hot. Right the last two and actually right now there's even one more bomb dash 2.414.x is also hot with the same thing. Okay. So from looking how if you're not explaining it to me how do I know what's hot. You don't. And that's, that's why that's why the first story is, you should use depend about so that you know if the so that depend about will take care of you. And propose pull requests. If there is a new version on your line. So, so that was why this idea says, yeah, you should use depend about. But it doesn't help you choose the initial version and the initial version needs to be found by looking at the available releases. So one technique I used was here. Look at this page. You're not accustomed to reading web pages with lists of version numbers. But here it is. So here we see 2.387.x. And at the very bottom is the most recent version 2329. So this thing is the authoritative location for version numbers of these bill of materials like, let's go back to 2.346.x. There's the that the final version, the terminal version of that, of that line. And the question that was like to the other versions got the same version number. They do. Well, and, and now it's, it's, that's, that's accurate as far as it goes. So if you look at 414, it has three versions in it, because it didn't exist prior to this 2278 release. So when you look at 4.401, you'll see 2278 was preceded by by many. But 414 didn't exist yet. So when 414 came into existence, this is when it came into existence. So, so the authoritative place to find these releases is in this directory structure. And it gave me as tempted to just tell people, go, go navigate to this location and read it. It'll tell you what, what the latest version is the other, the other technique I use, but it requires some, some reading is I'll go to this site and look at the releases. But I have a personal bias towards only supporting my plugins on hot versions. I plugins that there aren't on hot versions are not, not as interesting to me. So I tend to base either on 387 or something newer than that. All right, so coaching comments, what do you think what's in is there a some recommendation on ways that you think would make it easier to understand how to make those choices. I mean, I'm thinking that when in doubt a good starting place to be the most recent, right? Yeah, in fact, that is the, that is the strongly preferred most recent is strongly preferred, because most recent has the best set of the most recent set and the largest set of plugins that are part of part of the the bill of materials. Right. But now maybe I have to support older versions too. And that's, and that's one of those choosing which version to support we've already got a page that guides people on that right the we've got a page that guides them about how do you make the compromise between between this minimum Jenkins version or that minimum Jenkins version and and this should probably link to that to remind them choosing this thing is in fact choosing a Jenkins minimum version. Also, you should keep them together they should kept be kept in lockstep. Yeah, you know I think the way I mean, so you're not going to cookbook it. The general thing that you could use the way you explained it I mean written up is pretty good it's a soft thing you know, start with the most current version, try it and see what happens do some testing for bonus points. I think it's like robo dot to to do it, you know, and compare those two, and look at these lists to see and make sure you can understand what you know, it is it's I think it's like chicken sexing it's like one of those things that's really really hard to choose to tell somebody else, but you let them sort of watch how you would do that. Maybe even take an example of one and you say you know I did this, and here was the problem I found. And so by looking here and here and here I figured out that this was the cause of the problem. And so I changed. Okay, now one of the things that I'd considered was just putting into this document into this section here putting into the, or not, sorry into the into the top level read me this thing right here. Examples that do that go back to the older bombs. So import the latest bomb. We could put another subsection here that says earlier Jenkins versions and then list 2.361 and say this is the first version support Java 11 to dot 346 this is the last version to sport Java eight. So if we give then the version in those cases would be explicit and non varying. Right, so we could we could document that and say, Hey, here is Java eight, the final version the terminal version. Here is the first version that did Java 11 required. And this one is the latest bomb is the preferred. Now, another would be, we could probably use update CLI to script this thing to actually insert the explicit value there. It would just require somebody with update CLI skills to do it. So maybe actually maybe I talked to Bruno Verruchten about that because he knows how to do that quite well. Let me make myself a note. But whatever you do. You're also talking about some maintenance here. Because soon I'm going to be looking for the last version that supports Java 11 and the first that supports Java 17 and right well and before you know it it's going to be Java 37. Well, I'm, I'm not going to go there but okay that's so update the version string explicitly that the benefit of that is then it avoids any explanation right we don't have to tell people how to choose it that we just say, copy and paste this text you're set. Are they always set if they do that. Yes, yes, if, if it doesn't work when they do that, then they've got some other changes they need to make and the other changes need further guidance. They may have to ask on a developer list or somewhere else hey what do I do this didn't work as smoothly as I hoped. Okay, so they would, but it wouldn't, it isn't like they have to go back I mean I can see some of these, you know, that, like, six months ago, I needed to support both Java 11 and Java 17. So do I need to, can I do that with one version or do I need two versions or something. I think a nice little I mean you, the blogs, I don't know blogs are so often you know like things with general purpose, but I still think the story of you working through one or two of them might be very nice and it wouldn't need to be updated I mean when you tell them what you had to do for Java 11 or something. They can extrapolate that when they're looking at Java 32. Okay, well, no that's, that's an interesting idea because we might use that as seed material for Hacktoberfest. Ah, right because that's a good point. Certainly there are plenty of places in the Jenkins plugin plugin ecosystem, where this is not yet applied, or where it's been applied but the, the contents have improved. And the plugin did not keep up. So they've, they're, they're specifying things they don't need to and and so it's yeah, good, good idea. Okay, good. Yeah. I always wanted to have put a corner in the docs with like hints, hints from the curbed margin with Darren Pope's things that were always like not a fit but you know make a persona out of it. Make a persona out of you too because the two of you are obviously a good, you know, you know, you're more by the book than he is but you know, but something where it identifies it's a persona and these are some, you know, here's Uncle Mark sitting down and explaining how he does this. And, and it works and you might come up with, you know, and not saying, you know, this is the way you have to do it or else you're going to, you know, be a turn to the eighth circle of hell for life or anything like that. I do love the references. Very good. All right, thank you. That covered the topics I had. Any other hot topics before we close for that and let me get some sleep. Sorry, Ashutosh go ahead. No, I just don't know. Okay, great. All right, then recording will be available probably within 24 hours. Thanks everybody. Thanks.