Jenkins Documentation Office Hours, 24 Jul 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Docs SIG 2020 07 24

Description

Jenkins documentation special interest group July 24, 2020 with summary data from the last month of documentation development plus a question and answer session on techniques the Jenkins project uses to manage documentation development, documentation issues, and software issues.

A

Hi welcome to the jenkins documentation special interest group meeting. It's the 24th of july 2020.. Today. We've got several topics: uh let's go through those I'm going to start sharing my screen and we'll take a look at the topics and work through them.

A

So we're going to review review the agenda today uh report on previous action items. I have the action item to create the docsig blog post to highlight our current progress.

A

We've had great results on plug-in site improvements on all sorts of other areas that need the highlighting and we're going to reuse this as part of the cdf graduation at the end of july, and included also on jenkins.io, an open action item on our github apps and plugins that use them.

A

That oleg will take care of so that people know which apps we can use and how to use them well and I've completed the addition of the meeting url into the calendar we'll get into the jenkins io site later today, and we've got mentors reviewing the google season of doc project proposals.

A

So we also have ongoing effort to coordinate a community bridge mentorship program.

A

That effort will not happen until after we get started on google season of docs, but it is in progress and being given some thought grateful to those who are attending our doc's office hours. We had four who attended office hours on monday of last week and three who attended yesterday on thursday, we're willing to change those hours as needed. Grateful to have people helping in terms of the terminology updates terminology voting is in progress and on the terminology proposal chain, changing master to something more appropriate.

A

The advocacy and outreach sig is process handling that the voting will continue until july 29th and then the governance board will select the term that should be used to replace the term master.

A

We're also delighted that google season of docs we've received a number of very effective proposals for projects. Those projects will be reviewed and the reviews will be submitted to google by july 31st and after the july 31st submission uh it'll be about two weeks and then submitters will be notified of their uh of the project results.

A

uh Xena great to have you with us. I was just working through the agenda um last item on the agenda and then maybe we can ask if you have questions.

B

Okay, thank you.

A

Thank you thanks for joining, so we've got github issues, so this is the data section of our our monthly meeting. We can't gather data about the doc's progress. How things are working in the organization? Are we showing healthy patterns of behavior etc?

A

As an example, our number of github issues has decreased since last month the number of open github issues has decreased and the number of closed github issues has increased nicely about 20 20 plus issues were closed and we only have 67 open, whereas before we had over 70..

A

In addition, we're grateful to the the linux foundation they're, providing some metrics on uh various pull request statistics. Our this particular graph shows pull request time to engagement. That is the time from initial submission of a pull request until the first response.

A

That shows that someone has begun the process of looking at it, and we like this one to be under one day and what the data shows is that the median value is well under one day and has been well under one day for for many months. So that's a good sign time from pr open to merge is not quite as attractive in that it's showing we've got an increase of time to merge going from what used to be roughly two days, pushing more towards taking us up to four days to get pull requests merged.

A

So that's an area we need to improve. Our median is still still reasonably low. It's the median is still under 10 hours, but the the 80 percentile or 85th percentile is is going upwards and that one we need to do some more work on.

A

In the last month there have been 60 former pull requests, seven new issues created and 19 issues closed. We have 31 open, pull requests and we've closed in the last month. We closed 65, pull requests, so nice progress.

A

Now xena we'd love to put topics on the agenda. Are there any areas where you would like to to have specific questions that you wanted to.

A

B

So um the question also is for the user pages that are currently on wiki that are currently in migration process.

B

um The issues on github do they cover all pages on the wiki or one has to go to the wiki check the page find out which one is not yet on jenkins, dot, io and my migrate or you just go through the issues and pick up one issue that um states okay. This is for migrating, for instance, like remote access api. There was an issue created for that. So my question here is issues created for all pages on wiki or just some of them.

A

Good question very good, so so are issues created for all wiki pages and the answer is not yet because there is a triage process, a review process.

A

That is uh required before we decide.

A

We decide uh where to place a wiki page in the jenkins.ios infrastructure in the jenkins.io site and which content should be migrated and which should not so very good question.

A

um So, let's, let's take an example, there is a triage uh spreadsheet, striat sheet that uh mark uses that I've used to record, which pages have been triaged, which pages have been reviewed, and so we could take a look at that now. Let's see if I can find that really quickly,.

A

C

A

Now, let's see how about wiki conversion progress, maybe that's it!

A

Yes, this is it good, okay, so I'll embed a link to this sheet into the meeting notes you know so that we've got it um so here's the triage sheet and what I do there is when I've reviewed a page and created a github issue for it. I make an entry in this sheet and the reason I do that is this access count column here.

A

Maybe we should make this sheet a little more readable there. This access count is an accid a count of number of times. The pages page was accessed in a 90-day period, and so what we did is we intentionally said: let's migrate, first, the pages that are most frequently accessed and let other pages wait.

A

And so, if we look here, you can see, for example, that pages like how to run jmeter at row. 72 is in that 90 day sample period was only accessed 4 000 times. Now, that's still lots of accesses. So it's interesting, but it doesn't yet have a github issue, so someone would need to triage it um all the the others above it have.

A

Github issues and on some of them I've made notes about which things are in progress which are done so so, if you find a wiki page that you think oh, this is one I would like to migrate if it does not already have an issue in jenkins, dot, io you're certainly welcome to create an issue and there's actually a template on the jenkins.io github site, which will which will guide you into the kind of information that's needed for that.

A

So as an example, if we go to issues here and if I click the new issue button wiki migration here is, is it provides a template of the kinds of information? We need to begin a wiki migration project process and it will ask which page are you migrating? Where should it? Where should it go? What are the notes that should be added about migration and then put additional comments there?

A

What we've found, particularly as we get further along in this wiki conversion process, is that there are some pages that require quite a lot of work. Other pages that should just be discarded, other pages that are are of a portion of the page is useful, but the entire page is not useful, as is we have to make significant changes to make it useful.

A

So that's that those are the kinds of techniques we're using right now we review the pages here and put notes into this sheet when a review is, is done and then go forward. That way. Did that address your question. Zinab.

B

Yes, it did so um well, I think, while I was working on the proxy documentation, I I think I saw another sheet, I'm not sure if it is this with pages like this old school, I think that had progress or something if it had been merged or it had a progress column to show if it had been matched and all that. So I was looking for a page, an issue, a github issue to work on. I noticed that there are some issues where you have someone. Okay, I want to work on this.

B

I want to work on this, the same person, probably on like five six seven issues. I want to work on it. I want to work. The person had indicated interest, but I don't see any pull requests or any um work associated to that issue ongoing already. So is there a wait like probably okay, one for one person?

B

I believe at a particular point you shouldn't like um indicate interest or more than two three issues at once when you're done with that you can move on to others, so other people can also have you know the opportunity of working, because when I see an issue- and I see someone has already indicated an interest- I wouldn't want so there won't be any conflict. But in a situation where I've seen one person indicating interest on like 10 different issues at once and work has not started on the issue.

B

It's I don't know, I don't know sure, but I think that was one of the reason why I decided to start working on plug-in documentation when I noticed that most of the issues already had someone who has indicated interest.

A

Good good question yeah, so how do we handle issues that are assigned but not making progress? Yeah? Because that's that's a very good question and what what I think we should do there is, um if you see something there was a.

A

There was a busy period during late may during the hackfest had many people who who said I want to work on this, but then later decided, oh, no, I'm not going to do it and did not did not indicate that they weren't it's not uncommon in our open source world to have people who are who become unavailable and may not tell us they're unavailable.

A

So so what we do is then so hackfest had many. Many has many examples right and just place a comment on an issue that looks idle and ask ask if the issue is is being actively worked actively developed.

A

Let's call it fix there. We go if, after a day or two, there is no response.

A

That'll be my trigger that will motivate mark to unassign the issue.

A

Because we it's difficult to know the the assignment of an issue in github is just a convenience. For me, um it's a way to see which ones are. We have someone that said they were interested or not.

A

So we can. We can easily unassign and you can work on an issue whether or not it's assigned to someone.

A

A

So the idea there is, let's, let's take some examples. I just did one of these yesterday, actually where there was a an issue that had been had been assigned but had not had any progress in a month or more, I'm not sure which one it was but but it it's not an uncommon thing to see.

A

Let's see recently updated, let's try that.

A

A

Was um I apologize? I don't know which one it was that I was working on, but there was one that had. Oh yes here, it is good.

B

A

Okay, this one, I think, was one that it had an assignee and the assignee said. Oh hey I'd like to take this on, and this was my response, but notice that kumar harsh is not assigned here, so it could be assigned, but then again someone else could pick it up. This was just an I finally got to answer this question.

C

A

So does does that help with clarity? Now I think you were referencing oakland.

B

Yes, yes, it does.

A

Now you you did mention- and this is a good page for us to to to note the plug-in micro migration progress report page is a great place to go. If you're thinking, I want to migrate, plug-in documentation, but I think you were specifically interested in wiki pages that are not plug-in specific, but rather our general purpose. Documentation from the wiki is that correct.

B

Yes, I was referring to that, but I would also like a link to this also because I recently started working on plug-in migration also, so it would be nice to.

A

Yeah- let's put that in so that's a different all right. Let's put that! What if I'm migrating plug-in documentation from wiki to jenkins, to plug-in repos and really that's a different migration in the sense that it's.

A

Then it's wikiprogress.

A

Page, which is one good link, and then there is also the plug-in document- the plug-in migration documentation page that guides how to do that. uh There's the exporter here that can help with the.

D

A

And it's quite a quite a useful tool to have something that will provide the conversion for us. It reads the wiki page and provides it as either markdown or ascii doc, and we've got video recordings of people doing that live so that we could refer to to that.

A

Then there is also a github project that we use to track progress on that, and now I I'll have to think about where that github project is because plug-in docs progress. I think nope, that's not it docs this one here it is so this is a a github project which tracks the tries to track the various pull requests through their stages in progress merged and released.

A

I don't know that a contributor needs to worry about this, but it's been helpful for those of us who are trying to watch progress to see how how it's going so there's a github project that tracks plugins across the entire jenkins.

A

A

Okay, did you have other questions.

B

Yeah, finally, um when I was going through the resources before I started, contributing I saw a template issue on jira for migrating pages is jira? Is the jira issue still in use, because I'm trying to understand the link between um github issues and issues on jira also actually created one issue for the plug-in page, I'm currently migrating, but I just wanted to be sure if that is still very much active.

A

Good question all right, and so there are two answers to it. um The and the two answers uh jira is the the most common track: bug tracking system for four plugins right, plugins and jenkins. Core we've switched.

A

The jenkins.io site from jira to github issues, and, and so there are still issues in jira that are related to jenkins dot io, but we found for the the documentation purposes, it's easier for us to do. Jenkins.I o work in github issues. We get more involved people, they better understand how to use it, etc.

A

If we use github issues instead of jira issues, so there are some issues, some jenkins dot, io issues still in github area, is still in jira and they'll continue there until we close them.

A

The majority of them, though, are now github issues, and that was one of the things we learned from the hack fest hackfest showed us how much easier new contributors can contribute to issues on github than on jira. It's it's impressive. How much simpler it was based on that heck, fest experience.

A

Does that does that address your question? Do you have need further clarification.

B

So, just to be sure um for english. I o tub is the primary um source for issues, but for plugins jira is still in use.

A

That is correct.

B

Okay: okay, that's fine.

A

Yeah- and there are, there are some security and, for instance, the plugins.

A

Our our plugins and jenkins core security process means that we need there are times we need to be able to have a bug report that is hidden from public view, while the security team or a plug-in maintainer works on it and github issues doesn't really have a convenient way to keep a a an issue hidden from public view.

A

We've got a very solid workflow that works really well with jira. For that, thankfully, we don't have security issues on jenkins.io and therefore it makes github issues an easy choice for jenkins.io.

B

B

Okay, thank you yeah. I think that's all my questions.

A

Okay, all right, thank you thanks very much for joining that's excellent. Those are those are, are great topics to have in the notes. The meeting is being recorded and I'll create an archive of the meeting, and we will we'll upload the recording later today.

C

A

Thanks very much cena and we'll conclude the meeting now then.

B

Okay, thank you. Thank.

A