Jenkins Documentation Office Hours, 30 Aug 2019

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Docs SIG 2019 08 30

Description

Jenkins Documentation special interest group meeting Aug 30, 2019 including discussions of REST API docs, plugin site improvements using GitHub documentation sources, CommunityBridge subprojects for docs, and some metrics

A

Now welcome everyone. This is the Jenkins documentation, special interest group. It's the 30th of August 2019. Let's go through our agenda today, thanks very much for being here I'm going to share my screen.

A

So today's agenda includes a- and this is just a review first and then will actually run the agenda.

A

So a report on previous action items, discussion of collaboration with other special interest groups hosting the Jenkins rest day, API specs on swagger hub, adding a plug-in site to github integration, sub project from Oleg, and then community bridge sub projects for docs from Oleg and if time allows, we can talk about the latest data from the contributors to the site, based on some reports that I regularly gather any other topics that need to be added to the agenda.

B

Okay, that is what he would have a talk about, the documentary infrastructure, but um maybe it's relevant respects a project.

C

Yeah that maybe through cross cig communication products possible okay,.

A

All right: well, let's put it in there, so documenting the infrastructure, good good topic: okay,.

B

C

B

C

C

Lowercase, T and and Marky Jackson is one word: oh oh I'm, getting it wrong like that and then the M in the J is lowercase. Oh okay,.

B

So this is just the name to get hop: ID yeah.

A

B

A

I'll fake fix it later. Excuse me not getting things exactly right. No, no worries I'm, also on there. I can fix it. It may have edit super. So in terms of action items, I've still got the open action item to get the docs project. Ideas. I've gathered a couple more ideas, so there are more things growing in mind: I will get those posted, Oleg and I have decided that we're not going to bother with resume reviewing the google Summer of Docs topics again we'll take that up as we get closer to Google Summer of Docs.

A

Is that a fair statement? Oh like.

B

Yes, but partially, because even if we stop talking about Google season of dogs, there are two programs which are coming soon. So, for example, there is out reaching these deadlines late next week, and that is also coming into breach below and boasts topics. Basically, I'm, always the same in terms of projects.

A

Okay, so project ideas are helpful, no matter what and and consider them in the context of outreach, II and and community bridge thanks. But this thing then then be retained. You I'm gonna just delete this one and I think we need it. Okay,.

B

We really need to create project ideas page, but yeah just need to find contributors in this.

A

Great all right so doc seek summary. We've been doing that to highlight progress for governance, we'll continue doing that. That feels like it's just a standing action item, I'm, not sure if we need to leave it in the action item list, I guess: I'll leave it for now.

A

Hey next topic collaboration with other special interest groups. So any specific items here: google Summer of Code, for instance, Oh, like from you or Markey from you.

C

From from documenting of the infrastructure side, part I have I'm being on boarded and right now, I'm, starting to document how our community's infrastructure looks in Azur, and the next part that I will probably start working in terms of documentation will be documenting. The monitoring infrastructure.

D

C

There's a lot more to do, but that's just kind of where I've decided to throw myself in.

B

Just some bits, I started acquaintance to the plug inside the Chi system, though, via plug inside the guys system was already documented, pretty well, I would say: gee I'm, just doing some refactor and grouping called the documentation because it was heated across three repositories and yeah. It may also contribute.

A

Excellent, thank you. Any other say that are active. We should consider connecting and and encouraging.

B

Not to write the communication specifically correct, so you have full muscle regarding six, you have Chinese localization seek and they keep translating jinkin say your website. They start moving some documentation to Chinese so yeah, but the it happens within Chinese that relationship and definitely not with an infrastructure part alright.

B

Regarding other seeks to be honest, I'm, not aware about activities which would be specific to documentation. So here we need to do something called from seek. For example, I have a long-standing fiction item to documentary no support policy and propose it as a job, because I just don't have me into support policy.

A

Well and I have the long-standing action item for darker or for darker image: support policy; yep, good, okay. Thanks to that reminder,.

B

Yeah but yeah, basically since bust me and the marker I in both seeks. So we just occur our extensions from 160 another right. Sorry, yeah.

A

B

A

Okay, anything else, elaboration with other.

B

6Mm r6, so regarding sub-projects yeah, there might be some investment in Jocasta communication, because Jenks traditional communication could be improved. There is a lot of community pool requests going into this documentation, but we can definitely put on do more, so it could be one of the projects for documentation. Is you catch yeah.

C

D

C

Question that I have is there or do we have any interest in reaching out to maybe plug-in maintainer x' for possibly documenting their plugins I. Don't know if that falls into what we're talking about in this sig I.

B

Will talk about it a bit later because there are some other latest activities awesome. Thank you all. So it's just my comments below.

A

Great yeah, so anything else on this topic before we move on to the Jenkins REST API topic.

A

Okay, so there's a let's go: there's a current there's a proposal recently raised by a Buddha Sharma, suggesting that we consider hosting REST API specifications on swagger hub there's a proposal throb thread in the Jenkins developers mailing list and an example that has been created on swagger hub I've, opened an account on as opened and has created an organization.

A

Jenkins woops Jenkins on swagger hub it's a 14-day trial, is all I assume. That means that they want to charge for it. I've sent the mail asking them if they would be willing to donate so that we could host as an open source organization without being charged for it.

A

B

What Good, Hope is hosted by smart bear all right, yeah, actually somewhat active, injects communicate. They maintain plug-ins for Jenkins, so they respond surrounding his fault. If I recall correctly, at least once so yeah there might be open to that, and here for the musician, which would be really interesting. The problem is for that that yeah right now there is no way to automatically generate best. Api specification, footings plugins.

B

It was one of the project IDs for google Summer of Code this year. We just didn't get applications accepted, but the project idea is still there, so it might be again used in community breeding and outreach in this up to some 120.

B

So, let's see, but here the project we have mentor team potentially for that. So if somebody is interested to just let the song.

A

Great thank you, and could you envision that there, during this trial that we could we could do a test drive with things interactively created the way I view a booty I did even without having the automatic generation from the project idea.

B

Yes, we could so if you just think it's to take several plugins, you should heavily use this at STP is and create this all get specification for them manually is something we can do or somebody, for example, could start the command in Jenkins core, because the agendas called I guess there is some more structured.

A

So I was I was thinking. I was going to engage Abuja over the weekend and try to document the notify commit API for the get plugin for instance, and see if I could get some experience with one little thing. But it's a little thing that I'm somewhat familiar with yeah.

B

So yes, what get is a pretty simple idea: okay, even a generation from step Lert. Well at least the engineer heating skeleton of swag. It shouldn't be a big deal, but it's just the question of somebody working on that great all.

A

Right anything else and dressed API on swagger hub, okay, the next topic addition an additional plug-in site to github integration. Sub-Project oleg. Do you want to take a delete on that yeah.

B

So they want to share sure that'd, be great, just second, to ensure that even have spoken, okay, I'm just second so now I can screen share. Okay. This is my screen. We do key so yeah. This is what I was referring to when Marty asked about plugin documentation. So one of the problems in his project has that now, almost all plug-in documentation is some way in the media. So, for example, we can google for marks, get plugin it's like in a weekend.

B

Yeah you can go there. You can discover that which is a lot of historical documentation and you can actually biggest problem time to exist. This documentation is quite long. Then, if you want to edit this documentation, there is a capture there's no review process. There is basically no recognition for contributors and yeah it's an old way which is hard to manage, but many plugins has already start moving to github. So, basically the communication is focus is a thing. And yes, even several years ago we had a lot of documentation. I mean hosted on github.

B

So, for example, I can take durations code, plug-in as an example ISO. So I just realized that that zooms panel has exactly the same background color as github header and yeah I was just confused. Okay, so yeah here you can see that there is documentation which is basically located in github now and we ate pretty common for many plugins and plugins spread in the move to get happy even now. The problem for us that this hub documentation is not easily accessible to users so, for example, the links going from up from plugin documentation, etc.

B

They basically put a pointer to plugins jang seong. So this is a plug-in side, and here what you can see, for example, for computation is code documentation for beginnings here. Iteration has got blinging. Well, you can follow them in and then you will get there, but it's not the best outcome. Sometimes a generation of the species also takes time, because basically it's been that they've drifted from confluence epi on the month.

B

So performance is pretty bad and they do is, but would it be just the but github pigmentation straight into plug inside straight in my Jenkins update sites, James visitor interfaces, and yet again it's not a new idea in 2016 when you go down in google Summer of Code first time managing this project probably had a project for github to plug inside the communication publishing a problem that it has never been fully completed there is. There is a pull request from us being forward which wanted to publish documentation so yeah.

B

This is it happily for documentation but yeah when I start working on this story two months ago and basically for me started from Italy is drafted because I want to have changed local donation and in either one change load. We also published on this side. So at some point they just converged a bit today about supporting documentation and change lots from github, but rather the way to be low-hanging. Fruit, for example, posting plug-in Louis. If you have some, for example, mark put post, get plug-in logo or yes, something like that.

B

So yeah just make the footprint and he also label integration, because currently plugin label are partially defunct in flag inside, because labels either come from media and we make is not well maintained in terms of labels or from metadata in the update site, which is how to manage. So if you were able to pull this information from github, it would be also preferable. So the other yep.

A

I'm not sure I understood on the labels, with what labels, what search of labels do you envision there? Okay,.

B

So, let's see so here you have a list of categories, you can you have a list of things and basically these categories come from labels and ee said so, for example, you can go to let's say build tools. I have no way and you get something like 100 plugins. Okay, that's good! You probably need 200, for example, this less results.

B

Okay, so, for example,.

D

There should be somewhere here.

B

Okay, it would say, like yeah, look something so yeah anyway, the problem that all these labels are kinda manually managed they either weekend. There is no usability bogus, for example, you have good night. We have iOS Ruby development, but, for example, we don't have to go to for Java developers or something like that. So it's hard to understand. What's from where and if you just using a more relaxed way to label plugins I github labels of topics, it would actually help a lot, though yeah it would apply significant investment in aligning them.

B

It's just idea from the top of my head right now: I'd rather want to focus on getting being explored quests over the line because he submitted them in May, but basically there was no activity and we I want to have a bigger story completed and yeah. That's why I proposed it as a sub project for communication seek because yeah I think it would be important, I just leaf about the plugin.

B

The communication, then the full recognition, because here what you have that example, if you both the graciousness port, is our automated change, looks and here the communication updates. So they exactly the same. They also bit which change logs poet, information to users and be the most important issue that documentation and developed in parallel this code, because it's not the communications code.

B

So to answer your question mark here, my preference would be to get worse, taste better documentation but yeah better documentation which would be a part of it hops repositories and which would provide ways of private weights to review the recommendation, because right now an American go to get plug-in and basic underlies the spaceship. They want, fortunately, the happen so often, but you had easiest one: some behavior, the placing radius is advertisement so yep yep.

B

C

So yeah, my question would be so, of course, first of all just to add two plus one. What you're saying I think this is an awesome plan. It would I think it really goes to if we start moving to sort of a get on style of infrastructure. I think that'll be awesome, numbered. What question and I do have is the particular page that you're on right now.

C

Will we be deprecating the use of this page, because what my fear is is that with this still being edible, editable, not edible, people will still be able to edit that site and if it might create confusion, so I would suggest is if it's possible, and we do go to the get change log style that updates the plug-in site. We deprecate this, this particular wiki site. If that's possible, oh well,.

B

The preheating could enter a week aside, it's unlikely possible because it's about Southern's of repositories and yeah, even if you have all Jenkins contributors working on degree in recommendation to take a while. There is no boot automated documentation, mutation from confluence to github I tried few options, I didn't like any of them yeah. We can do something from the organization level. So, for example, we you can install a plug-in for confluence dumping, everything to mark it down or a skiddo and get it published, but they may still need to get to it.

B

So what I do right now? So a bit is label bit if I plug in you can see that it was a bit on July 20th and basically, what a beep I just moved, all the documentation to github. So two two places one is: it have releases where now I have change loads and another one is just a root where I have the combination which used to be on the wiki page, and here clip disclaimers and elite evenings, we can set up pretty rate for just mid-walk, saying that everything wasn't outside beautiful.

B

Okay, that that's fine that answers my question.

C

A

And that sort of incremental transition is what I've used in the get plug-in as well for the changelog I think others are doing the same thing right, I didn't even bother to put in the old change log entries into github I just put a tombstone at the top of the change logs, which says all future change. Log entries are here and they linked to github. So.

B

I'm not to label a bitter fight because they were just four degrees or something like that, so it wasn't a big deal to just moved it, but yeah in sometimes we have hundreds of religious and, for example, for a new friend Jack. They just edit a link like Mark said it's not ideal, but whatever works.

B

Okay, thank you yeah! So, regarding the current status, so yeah, there is some torrent for the reason offset which is evolved in a separate project. So this one works pretty well, it's been explored, a quest. It's ready to go so I'm waiting for oh you're here to help is infrastructure that is requesting to see in front and you get hub tokens because we need to retrieve information from github and yeah. It needs tokens.

B

Otherwise, it's too slow, yeah, I didn't prepare a live demo, but I can show you example of the recent folder based authorization plugin, so one which was created by a Buddha, and you can see that this is just a screenshot of the current state of applying insight. Api, it's a bit country predatory, which shows the information of front-end and the way you can see that information has been just retreat from github.

B

If you go to the this page right now, so it would look like something like that yeah. So these pages are pretty embarrassing because it's a landing page, so they didn't some documentation. They wouldn't here.

B

Okay, so yeah, this project is basically in progress. I would be interested in. There are contributors and early adopters, actually yeah. Once you have an infrastructure in place, you will have something like 20 or 30. Plugins use information beans from github, because we just rely only your real specified and immediate data to understand what is the source of documentation but yep going forward. Once you have change logs today and other things its money might require some a beat so.

A

When you say URL in the metadata which which metadata is it so that I can make sure, for instance, that they get plug-in documentation and others like it will be, will be pointed? Is it something in the pom XML file? It's.

B

Important well so, basically, miracle reply on this URL, so your URL points to beacon, and in your case week you will be displayed in the case of this plugin, for example, for work authorization. So it already includes a reference to each hub in metadata, but it's still displace Mickey, because there is no github at yeah. Once we have the engine in place, it will start at this time it hub and all limits which have URL pointing to github. Here they will start this Bank documentation from Mitra. Obviously,.

A

A

The credentials plug-in, for instance, has a very nice set of documentation inside of it, and all it would need is that its URL attribute points two points to that, and then it's and it currently points to the wiki. So it could be taught, though too, if, if this plugin were changed and pointed to its own documentation, then that will be extract conceptual to be extracted into the plugins Jenkins at I/o site. That's the ideas, yeah.

B

That's the baby, so additional a push from is being there were some glitches with it because yeah our problem, that if you use github API, basically you can get a readme page or any other page in a viewer, a department. But this you ready format relies metadata fields, so you can adjust image activated to plug inside means for to replace URLs, for example, two images or two internal references. So there were some glitches with it, which was fixing, but right now, I believe it's ready to go.

A

Also, the that pull requests and needs testing and verification steps and then merge and we watch what happens well.

B

Basically, this the treat has been tested and we agree that it's good enough, so yeah there was a range here and waiting for infrastructure team to enable this drafter, because there are other changes but yeah. Basically, this is the main, the biggest change to integrate, and we it's already been- you know, master branch of. Actually it's not so yeah. There is promotion to request. The build is green, so I'll probably just integrate it. And after that you'll need to be extra structure and for Jenkins infrastructure. There is a pull request. Shape of building here.

B

Yeah bit, if it's Jenkinson clay, Jenkinson neutron,.

B

Yeah this one, so this is a boot quest which basically injects github client. We enter data and yeah once we update docker container, because your plugin site is packaged in daughter. So once we measure this to pull request, it should stop magically working.

B

But yeah, basically the only test way to test it. Right now is test the introduction, but in the worst case it will be a really simple fix to reverse that.

B

So yeah this story is almost ready to go. Hopefully we'll have a live demo. The next stick meeting yeah the bigger story was wondering: what is the level of interest from documentation contributors, because here, once it's a integrate, we can make do a lot with documentation. We can create, maybe hundreds of maybe from the tickets for mutation of documentation and clean up. We can do many other things in it.

A

Right, well that that would enable the me to have a place now to express all of the different details and mmm tiny little pieces that are involved in the plugins I maintain right. There are things that that aren't described anywhere right now, except in the online help, and that online help is insufficient. So so this this is an ideal thing, I'm very interested in it thanks so like very, very I.

B

Think sorry, if anybody is watching that, please feel free to contribute. There is a bunch of other stories, but you have to long didn't read we recover some activities that are playing inside. So basically it was smallest failed since jank is to buzina, but he apparently, development flow is pretty easy. So that is front end. That is back end well and he is my very limited knowledge of whatever front end stuff. I was able to get the training and up for some patches, so yeah I think that it's pretty high table.

B

If you get support from infrastructure team.

A

That's great news. Thank you thanks very much, okay, so this is for me. Thank you, alright, so we'll plan for a report two weeks from now and how that's go on next topic, which community bridge sub project for dogs and all like I, think. That's again, you yeah.

B

So yeah, one of the reasons why I start talking about community bridge was Google season of dogs because we've intercepted last pinned last spring, so we can use community bridge to run projects and we already have a kind of framework for that. So now there is a student sliding working on Jake asked it's the first project we run on community bridge. Basically, the format is pretty similar to google Summer of Code, though we don't have restrictions about what can be handled there so yep.

B

We can use it to run documentation projects but to run documentation projects. We need mentors and we need a list of project IDs. So yeah. Here's the question.

C

So the question is: do we have mentors I need mentors? Oster project is okay, sorry I get it yeah.

B

So yeah we've had a long-standing action item to just post project, IDs and potential mentors so similar to what we do for G, so project ideas.

B

We can post it independent filter program, so community bridge out Richy, Google Docs. They can basically take ideas from the simple because of the program are some other salon in terms of duration and effort to be put so here for that. If we had a pool, maybe of four and all five potential project, IDs miss contributors who might be interested, it would be already a good start. You can add me as a potential.

C

B

Yeah but make sure to bring your potential project idea.

C

Yeah I have I have two that I can think of off the top of my head each other. This one's one would be just the infrastructure. I mean we could just start sub sublet leasing that out right, if that, if that's possible, number two I think using if we could get documentation for our onboarding process in terms of like plugins to their plugin contribution, I think it would be awesome. If maybe we could reach out to possible.

C

Past google Summer of Code students to see if they would be willing to come on to this particular project to say I want to show you how to onboard a new plugin. That's just something and I'm thinking from the top of my head, yeah.

B

So they knew the communication for onboarding players. He just would be nice. So right now we have a landing page drinks, a your participate so but the problem that if you start choosing options you immediately get from offense interface, always finds interface of unique Ian, pointed to whatever random links. So we still have a lot to improve their well.

A

Then we have it, we do have a pending pull request on how to do IDE setup for plug-in development. It's a pull request that was submitted a few weeks ago still is in my cue to review so that I think that's the right direction. Absolutely there's also for me. There's the in terms of ideas. There's the whoops wrong place, the get use cases that I've I've enumerated out a whole bunch of different use cases. We also had a proposal for a tutorial to be added from the LabVIEW team at National Instruments.

A

They wanted to put up a tutorial and I offered. Hey, yes, will happily code review it. Here's where you submit a full request.

B

A

Nothing happens, right hasn't happened, yet they only ask that one or two days ago, oh.

B

C

Think another really good idea would be kubernetes use cases as it pertains to Jenkins. The reason I think that would be a very good idea is it would get a lot of traction because that's such a hot space right now, right or even you know, use of Jenkins X there's another idea. Well.

B

Jenkins X is now a separate site, so it's basically no Jenkins and currently.

A

B

Cover you working on setting up a framework for Jenkins X, though yeah they will definitely welcome contributions. Well,.

C

You know another that could be sort of.

B

C

May be from a documentation idea the difference between Jenkins and Jenkins X, or how to go from Jenkins to jenkins X. So maybe, if there's sort of a bridge and documentation that could be an idea, it would be nice.

B

C

Actually, having dinner with I'm having dinner with Oscar tonight, so I'm gonna bring that up to him. Okay,.

B

Yeah, it would be nice regarding kubernetes kisses, so we had a cloud native special interest group I'm, not sure what tends to use there, because right now, this rupees it as a ruddy nectar right.

A

B

Interested in recovering that I just have no time but yeah. There was goodness a period project which is ongoing. Sorry.

A

I, missed I, missed what you just they, which what project the channel urgent? Yes, kubernetes operator. Oh, oh, the.

B

Kubernetes operator project yeah the results, great progress around round charts the helm, charts officially live outside the jinks urbanization, so they are maintained by help community. Speaking of that that they consider doing more integration system, Eurasian and sport. But yes, still, we have a lot of things like just calm, balanced plug-in, whatever other integration plugins. So for me it would better the cognitive sick to drive it, but it can be whatever join project. I need.

C

To get back as well, I need to get back into the cloud native sick because mm-hmm.

B

C

See that that's gonna be a very hot area and I think we can make anyone I use hot in a loose term, but I think we could definitely re re put a fire under there. You see where I'm bringing the whole circle of hotness here well,.

A

C

We could we could read really reinvigorates that got sig and and make it a little bit more yeah.

B

I'm interested, oh yeah mines was that other comes from the urging his fellows perspective, though we it's about Google data, stick to on again so yeah well, jinx. Further on that, isn't really kubernetes keys, but yeah.

B

There are so many lives, so fun and everything becomes kubernetes. Yeah.

A

Well, at but you're right, yep.

B

So yeah cognitive special interest group, if you mark you look, somebody else are interested to just poke with this group. It would be nice because there is still pretty big mailing list. So if you just start sending stuff, there may be a day, maybe some replace yeah.

C

Or make it or make it or create a task for myself to start getting moving again. Ok,.

B

That's cool great mm-hmm, anything.

A

Else on so I'm gonna take the project ideas we've listed here, the others that we'd gathered for Google's season of Docs and I will get those into a project ideas full request.

B

A

Anything else on sub projects that we want to discuss.

B

Don't think so: okay, it's rather program of action, do something.

A

Yeah certainly yep you're, right, mm-hmm, okay, so last item we've got just two minutes left on our on our scheduled time for your info I've been gathering every two weeks: data from contributor on contributors to the Jenkins at I/o site. I, don't know if this data is useful, I just gather it in case it might someday, be useful. So, for example, this is from the CD cdf site, where they gather metrics. This is these: are the pull request, time from open to merge across the last 90 days as a moving average?

A

The hyperlink there will take you to the graph and show you the current. My read of this graph is: we have improved somewhat and we don't appear to be dramatically worse than we've been in the past, so those were measures that okay, that indicator seems reasonably healthy.

A

The next thing that I've been capturing is contributors for the last month and we've actually increased both in the number of contributors and the number of contributions in the last month, so that I consider that quite a positive, this graph I like a lot better than the one from a month ago, which was fewer contributors and fewer contributions, then open pull requests this one. The number that we have closed has increased substantially in the last month. So that's a plus.

A

The number that we have open is also increased and that's a somewhat of a cause for concern. Just a reminder to those of us who reviewers try to close ball requests quickly. Any questions on the metrics.

B

Metrics for the last month problem another trade on because a lot of contributions come from Google Summer of Code. Well, even without Google Summer of Code, we had some blog posts posted. We had some changes in the side, but yeah, maybe it's but to have for City 601 year, yeah.

A

Good good suggestion I've been gathering this one for a the month thing you're thinking the this one would be good across a full year. I can't get the period of a year from github, but good idea. Okay, let me see what I can do. Yeah.

B

You can use the VA funding instance. It should it provides a lot of statistics and you can not wait for one year, those yeah ninety days, if you waited for ninety days, it's a question of how I spent of the summer and usually in some other various modulus constitutions, good point, yeah and one month was crazy because of JSOC, so Bolivia wouldn't be relevant right.

A

Okay, let me take that as a I'll do that and we will increase increase too.

A

For a year report for a year next time, good we'll do that. Thank you. Yeah.

B

So we have five look what's in the queue you should need to handle, so yeah I'm, going to mention blog post from a week right now about CLA.

A

Okay, yeah. That means that one's been a long time coming thanks very much well.

B

The was issue BCI because a footing say who is not very stable, I mean it was failing for. Well, no gem, not effective, it regulated so much.

A

All right, any other topics that we need to review in today's session.

D

Nothing from me nothing.

A

For me all right thanks, everyone, I'm gonna, stop the recording, stop the meeting and thanks very much we'll meet again in two weeks same time, I'll be good to everybody, have a good evening and good weekend. Thank.

C

A