Kubernetes SIG Docs, 12 Jun 2018

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Kubernetes Sig Docs 20180612

Description

Meeting notes: https://docs.google.com/document/d/1Ds87eRiNZeXwRBEbFr6Z7ukjbTow5RQcNZLaSvWWQsE/

The Kubernetes special interest group for documentation (SIG Docs) meets weekly to discuss improving Kubernetes documentation. This video is the meeting for 12 June 2018.

https://github.com/kubernetes/website

A

Hello Stig ducks people. This is Tuesday June, 12th 2018, and this is the weekly meeting of kubernetes sink docks, sick ducks channel all sick dogs. All the time do we have any new contributors, I see Takuya Tokido. Is this your first time with this.

A

I think so hello welcome. Takia has contacted me with interest for starting a Japanese internationalization of kubernetes documentation, so we are moving up and out in the world. It's happy news. Thank you. So much.

A

I think that's it for new folks.

A

Matt Farina is not new, but it's always nice to see men.

A

Let's move on to updates and reminders. So let's talk about the PRQ. Currently it doesn't look like we have anyone in the the PR Wrangler role for this week. I would love to take it, but I'm onboarding, a new hire at CN CF this week and I really I can't promise to do the job justice. So is there?

A

Is there someone who is able to take on the PR Wrangler role this week.

B

B

I can't do it this week, either just swamped with other things.

C

Close to GCB next we're just slammed gotcha.

D

Okay use someone Friday Wednesday, Wednesday Thursday I gotta, take my daughter to UNC Chapel, Hill orientation, but I could start Friday.

A

Friday is better than none yes and that there are PRS that need wrangling.

A

So last week as PR Wrangler, our PR q right now is insane just to let you know we have 85 on triage tissues and 105 open PRS, as of yesterday last week in wrangling PRS, normally I can get through about 15 to 20 hours a day depending on the size, but in one day last week, 20 PR is open, though it's there they're out stripping our ability to wrangle them effectively.

A

E

Little bit today, the last I looked maybe an hour ago was at 3:00.

E

D

I can do some tonight, so I can start some tonight and, like I said I just got two days. I gotta take my daughter to college, but for orientation, but that I can do someone Friday as well sure Thank, You, Brad, sure.

A

E

Wrangling anything that comes in that is related now. The topic group has gotten larger, cube, idiom, core D&S or in fact anything touchin, DNS and and we're working on that stuff as they can persuade the eager devs to do. They want to change all the things all the time.

A

Thank you for being on top of, on top of that particular subject, area Jennifer.

F

I can't claim sole credit 40 years.

A

So it's looking like ad-hoc assignments for PR wrangling is not working and we might need to do like a scheduled rotation in advance and I. Don't know what that looks like the only thing that comes to mind is doing like shift bids or schedule bids, but it doesn't look like we can rely. I think we're used to relying on people just sort of stepping up and saying yeah I can do it this week or next week, but I don't think we can continue with that model.

A

So, let's think about, let's think about how to get a regular, more reliable, PR, Wrangler assignment going and, of course, like folks, can trade and whatnot but yeah. We can't keep doing this ad hoc. It's not it's not working! It's not working for us. It's not working for for PR contributors, so I'm gonna make a note.

G

Because anyone here heard of or use at present something like opportunity or page or duty, essentially it puts someone on call and then schedule a rotation and everyone.

H

G

An approver will probably fall into this category and each is rotated for a week and it depicts- and you can see- and people can trade in there and just for certain specified period of time, they're on this, the PR Wrangler, and so then you know about six weeks ahead of time. When they're going to be involved or, however many leaders we have, the president could be a to be a way to kind of get a more rhythmic.

A

Out of it sure, and thank you for the suggestion, my only my only quibble with a like a pager model is that it works on an interrupt basis. The idea is that you don't do anything unless you're interrupted and the PR Wrangler will always require, like active participation and sort of like figuring out what you want to do in the process of doing it, and so it's something they got which actively, rather than on the interrupt basis. Yeah Jared, yeah.

C

We use a system internally similar to pager duty, where it's like it's full rotations and basically like it's for exactly this issue, where you just put in a queue of names and then once a week, it's just sort of goes through the queue and says like you're the person. Now that's gonna be wrangling all the issues, so the thing is is that you can also stick in when they're out of office and it will skip over you during that time.

C

So, if you're like, if you're like mister you're you're managing the release, you probably don't want it in the monthly after the release, so you're out I think Pedro duty can do that. It might be worthwhile looking into a system. I can do it I think a few other SIG's are using similar processes. It might be worth tomorrow reached out. Community I can Thursday.

A

If you'd, like things, thank you, it would be and yeah if other six have a way to do this. That doesn't require us to reinvent the wheel. That would be. That would be awesome.

A

That's so should I put you down. Can we check in not speak on the 19th next weekly meeting yeah.

C

I won't be able to attend next week's meeting, but I'll send out an email with what I find out awesome.

A

A

All right, let's move on to 1.11 dr. Dietz from misty misty, our 11th ex doing.

H

Contributors, so it's going well for the most part, I assigned I, think I assigned one PR each to you, Steve Andrew and Zak Arnold to sort of get a few of them off of my direct plate, and hopefully that was okay. I am in the middle of some big rewrites for a few of them, because it would be better if the content goes in right. The first time for new features, it's been going well, I've been getting the feedback that I needed for the most part and the cig release. People have been super helpful.

H

I think that, as of this morning, we have something like 14 or 15 PRS in the 111 queue. We had kind of a weird thing happened last week: we're removing a whole, but there were a couple weird things that happened, because we had one PR that went in sort of by surprise. It was. It was ready, but I think that we forgot or I didn't realize that if you already have an LG TM or if you already have an approval, anybody can lgt em something.

H

And then anybody can remove a hold and I think that in that particular PR, the approval should have probably been canceled because content changed after it was approved. So I think there was a little bit of a bug in prowl, and so something got in. So there's not really an actionable thing for that and just kind of maybe be aware and be careful about when things have an approval and the the content change of that I. Don't really know what the action is except try to.

H

Let the final approval be the release Meister unless it's something that you've been assigned like for those ones that I assigned out I've, probably happy for those to be approved by you. That's kind of the point um and we have a couple of people who are Docs approvers who are not, as involved with cig Docs, and that's probably for historical reasons. But those people should like adhere to the Spider, Man logo of great power and great responsibility. Probably yes,.

I

H

I'm pretty new, so some of this is kind of cultural folklore, sort of stuff that I'm just not clued into yet.

D

B

My understanding of how this works and it might have changed but I think it's still the case. If anyone who is listed as an approver gives an LG TM, that's taking to also mean implicit approve and the thing will just get automatically merged. So that's is that still the case that.

A

Is the case that is not what happened in the case of Misty's particular PR.

B

And the other thing is I, don't think if anybody gives an LG TM, that's enough for the bot to emerge. It I think it has to be someone who's listed somewhere as a reviewer.

H

A

You cannot self approve or self LG TM your own PR, but anyone inside of the kate's org can issue an LG, TM or or revoke one, and they can issue or remove a hold. So that was a that was part of the shock will be true in a particular PR.

B

But this, if somebody in the org who's not listed as a reviewer in our repository issues in LG TM, is that enough for the bot. um If there's someone else's approved, is that enough at the bot to automatically merge the yes? That.

H

B

Not be that I mean just you agree that there should not be the case.

H

J

I'm sorry can we met please chime in yes, sir I just want to let you know that for the bot, it's a configurable thing. If I remember right, it can be configured so that everybody anybody in the cage org who gives it a look good to me- will give it looks good to me label or it can be configured so that only somebody who's listed as an appropriate owners, level, reviewer or approver can do it, because approvers can go ahead and do that as well.

J

That's all configurable, and so it could be the way you're configured, and if you want to change that or figure out the way you want it, that's just a configure option in the test info repo, excellent.

A

Thank you for that. Let's dig in and absolutely agree with you Steve I, don't think we should be. We should get people coming through and you know doing cowboy lgt, MS.

H

Than is I, don't think that an approve like a / approve should imply that that also means /lg, TM I. Think those two things should be separate, because I think that we can, if those of us who have rights to approve something, we can also LG TM something but a lot of times, at least in 111. So far, I've been using the LG TM to be something that the technical reviewer can set so that I know that they're good with the content yeah.

D

I mean I thought when we, when Joe heck, wrote everything up. That's what we agreed right, you you'd, let the the technical person do the /lg TM and we do the approve. Are we changing that or some we.

A

Are not so what we I'm going to call back to the discussion that we had about this when Pro functionality was originally enabled and remind us that if you are an approver that approvers have special magic, LG TM powers that, if you LG TM, something that you have approval rights over that also acts as an approved. So if you, if you /l g TM, something as an approver, you also need to add a hold so that it doesn't automatically emerge and then but yeah. That was.

A

That was what we decided to do was to, if you add, a /lg TM to add a hold. If you're in approver.

A

And this is also a good time to remind reviewers that if they're, if a PR, please check the release branch of a PR, and if that is in a release branch, don't merge it. The only person who should be merging release PRS is the release Meister and for 1.11, that's misty. So please be careful to to please double check the branch of a PR before you give a merge to it. It's it creates a headache for the release, my sister, it creates a headache for the the the PR the developer.

A

Who's featured PR is in question. So just please be mindful, and only let misty let the release Meister merge, PRS associated with a release branch yeah.

H

And there may be times where there's something that you don't know, like maybe I'm in dialogue with somebody- and somebody has told me this shouldn't go in before X other thing goes in and maybe I haven't like gone in and specifically put a hold, but I know something so it might be worthwhile just to I mean it may feel, like you're saving me paperwork by merging it on my behalf, but that might not actually be the case and I'm the one who's gonna have to resolve conflicts at the time that we do their release.

H

So it's probably good for me to be cleared in.

A

Thank you all right. Moving on Andrew, let's talk about considering an alternate cig, docs weekly meeting time, to make it easier for for contributors in asia-pacific to to join us for weekly meeting. And do you want to talk about that? A little bit yeah.

I

Because there seems to be obviously we have like teaming and other people in China that aren't able to attend this meeting, because it's like in the middle of the night for them and then it seems like there's more interest in out in it from Korea and Japan as well. So we're we want to consider maybe having an alternate time. That's a PAC friendly. The issue is the big time difference because for for Korea and Japan like if we did it at like 4:00 p.m.

I

Pacific time, that would be okay, but then it still would be maybe a little too early for China. And if we did, if you know for China, then it wouldn't be told like after 5:00 p.m. Pacific, which seems kind of late for people. Since you know we're getting out of work at the time, so I I'm struggling to figure out a good time that would work for people and then also we should talk about frequency because I don't think we necessarily need to do it every other time.

I

But maybe if we had one like once a month, there's something that was the attack friendly. That would be good yeah.

C

It's just uh talking about it from us or the larger team perspective at Google. We've we've moved to some alternating meetings where we have a like a 10:00 a.m. meeting and then we'll have a say a three or four pm meeting I alternates every other week, and that actually seems to be pretty good.

C

P.M. seems to be the best time to try to coordinate both like we have folks in Dublin London and it's Sydney, so 2 p.m. seems to be the best time to try do like accommodate all those folks but Japan and China and Korea a bit further out. So that makes it trickier so I think the alternating method sounds better to me, but I leave it up to folks here. It's just how we solved it within within Google yeah people in India would definitely love to attend. Maybe like a tan enough or I.

C

Don't know. What do you folks here think when.

A

You say a10, what do you mean like 10:00 a.m. Pacific, 10:00 p.m. Pacific? What do you mean right.

C

Sorry 10:00 a.m. Pacific and 4:00 p.m. Pacific, the bulk of people, that we have a 10:00 a.m. what account would accommodate everybody folks in Europe who want to attend and it's an easy East Coast time and then the 4:00 p.m. is a is a fairly good time for people in Asia, actually Raja. What is 4:00 p.m. in 4:00 p.m. PST is what time and like where you're at.

A

It would be 4:30 a.m.

A

J

H

J

Have to go later than that is it 4:00 or 5:00 I'm to.

H

Remember Rhea.

J

I think you might have to go. 5:00 p.m. Pacific time is at 8:00 or 9:00 Korea time.

C

Yeah, it's brutal.

C

I

Korea and Japan are like +9 GMT and we're -7 right now. Wait.

A

A

It's almost 11 in the US or in on the west coast. It's 152 am in Beijing 252 am in Tokyo 11:52 p.m. in Bangalore, with a 3-hour spread in the middle there's, just no way to make folks to make everyone happy.

A

So we might want to consider three different times if we want to get India participation as well, so we would be looking at like.

A

See it's 1152 right now. It's 10:30! If we did I'm just trying to do the math in my head, really quick like even like. If we did a 5:00 p.m. meeting, that would be, if you add a 7 hour that would be 6 a.m. in Bangalore. If we did a 7 p.m. meeting that would be 8 a.m. in Bangalore, 10 a.m. in Beijing and 11 a.m. in Tokyo.

A

You so, and it's well after hours for the west coast. But it's like the least egregious it would maximize a pack participation and if we're going for a part we might, we might just have to eat it in terms of like once a month having a seven pm eating yeah.

B

I willing to do once a month, 7 p.m. meeting I, guess yes, and if you're thinking of using three three times um you know I feel pretty flexible about it, but Zack I kind of think it's your you know. You should put together the proposal since you're the one who would be running the meeting.

B

I mean the rest of us. You know, could miss if we had to but but you'd be committing to. To these times sure.

A

That's rough I've got a 7 p.m. weekly commitment on Tuesdays.

A

Might we consider a different day than Tuesday for the 7 p.m. meeting, maybe like a 7 p.m. Monday, because that would be Tuesday APEC time, yeah yeah.

C

That's something yeah.

D

Monday Monday, definitely better for me than Tuesday I have a similar conflict on Tuesday. Ok, then,.

A

I will I will put together a proposal for a 7 p.m. Monday evening, Pacific time meeting, and that would be what 8 a.m. 8 a.m. Bangalore 10 a.m. Beijing 11 a.m. Tokyo.

A

E

Thank you very much.

A

Ok, Raji that sounds good to you, Takuya, is, is that okay, 10:00 a.m. meeting on or excuse me 11 a.m. on the Tuesday? Who does that work is every time that works well, for you, great okay, let's I will put together a proposal for the for the first APEC friendly time.

A

Let's move on I haven't just a small item to go over how old works so like we like, we just covered earlier old works like LG TM. Anybody inside the kids org can issue or lift a hold Matt. Do you know if that is configurable as well? I.

J

Don't I think it is anybody last I checked it was not a configurable option. Okay,.

A

Thank you. It didn't look that way from the documentation but good to ask right and that's just slash, hold yep four slash. Holden slash will cancel so be aware that slash hold does not have it doesn't carry any additional weight. Anybody can put one on and anyone can take one off of any PR all right. Moving on so we had I was contacted by.

A

Took a yeah who is lucky, it was with us from Japan who's. Looking for sponsors for Kate's membership, I have included a link in the agenda to his PR history. If someone else would like to be a sponsor, please leave a note in the agenda or just let me know if you want to take a look at this PR history. First, it's a little thin but I still look at some of the quality I look at the quality of some of his PRS and I am satisfied if you want to.

A

If you want to defer until he submits a couple more PRS I would be totally fine with that or if you're willing to go ahead and and sponsor that would be equal to, but anyway, I sorry go ahead. Oh.

I

I was gonna, ask like if he might have time to help with the PR angling, because I think that would also show.

I

You having demonstrate some, you know some of visibility.

A

Sure we would have to the problem with Ringling ki ours is that you have to have approver permissions to do it.

I

Right but I mean he can maybe shadow someone in do most of the work and then like someone could just do the final approve or whatever. Oh.

I

A

Let me think about that. It's PR wrangling, I, don't know of. Let me think about it. It's, but thank you for this. Thank you for the suggestion.

A

Steve, you have an agenda item for a prototype by teaming in pre-1965. Do you want to talk about that.

B

Yeah, this is about the yamo files that we use in for little examples in the kubernetes Doc's and tutorials and tasks, and the problem that, right now, our practice has been to put the any yamo files associated with a task topic in the same directory as the task topic itself.

B

But there are two problems that come up with that one is that we're doing a lot of reorganizing of the table of contents and our directory structure, and that means that every time you move a task topic, you have to move all the associated yamo topics and the other problem is that we have this test that runs along with our you know as part of our Travis testing, and it goes through and make sure all these llamó files are valid and it uses a hard-coded list of where those yamo files are so every time you move a yamo file, you, you should go in and update that that list of vml files to be tested and what has happened in practice, is instead just to get things to happen.

B

We go find those llamó files and we just delete them from the list of files that should be tested, and so then now they've fallen off the radar and I think as we write new topics and create new llamó files, at least I haven't been even aware of that test file, so I haven't been going and adding them so I.

B

The proposal would be to have a a single place where we put all the VMO files, so we don't have to move them around as a member of topics around and then the question is: could we share that among different languages and after thinking about this in talking with tuning and Jennifer? Our thought is that we can't share them across languages, probably, but for a given language we should have one place where all the yellow files live and- and that would solve a couple of these. These problems.

A

I think that makes sense that I think you're absolutely right that it has to be on a per language basis, but that I I do I agree that it's possible to consolidate those in a single location per language, and that's probably the best approach is anyone else have feedback on.

A

How the? How best to store and monitor changes updates removals yamo files in the repo.

A

A

Steve I would say, go for it, it sounds like it. It seems technically sound to me. I think you guys are on the right track. Ok, I.

E

Can't wait for this to happen.

A

Ya know: yeah, thank you for thank you for dealing with the the headache and the frustration of watching that, if I break yet again for a reason but is opaque and digging into the solution, I appreciate your work. There.

A

A

Moving on status of Hugo migration, so Andrew and I took a look at outstanding PRS in the Hugo migration, milestone and energy. You want to say a little bit about what we looked at and what we found and how that will go. Yeah.

I

We're down to about 900, pin' HQ, so so we've gotten rid of most them I think the we only work from what I remember when we looked at it together. There was only really like a couple that would that still needed to be finished, I think they're they're done now, and the rest of them are they're, not low-hanging fruit anymore. It's like things that will either need yarn to help with or we'll just take up some time to fix, like there's CSS one there's a bunch of like moving stuff around ones.

I

So I, don't know I mean so. We've made really great progress, so I we just need to I, don't know, try to stamp out the rest of them.

A

Yeah- and it was really impressive to look at the Hugo milestone and see just how many PRS for cleaning that post Hugo migration had been done. Andrew Ender, summary is is accurate.

A

The the PRS that are remaining are either things that like b1, Eric, Peterson or maybe like Steve fancy I can consult on because there they are no longer low-hanging fruit. The the of the PRS that remain open in the milestone like three or four of them. I remember, are things like it's not broken, but in code samples the colors changed so things things that are technically different.

A

They technically broke but aren't broken during the build they're just different now, so they, if somebody feels very strongly about CSS and about design aesthetics, it would be great to tackle, but I mean they're they're p3, bugs they, we they're sort of optional to fix.

A

So I guess the good news is that the Hugo Hugo migration is mostly done and it looks really good.

A

H

One thing to bring up about the Hugo migration that we discovered late last week. I guess I think that the template system, as far as concept tests and a reference templates used to be somewhat more optional than it is now, because, if you're not using a template now your table of contents gets a little bit weird. So we did apply the template, lots and lots of topics that we found that didn't have template. So that's something to be aware of.

H

If you see double the bullet points or any bullet points at all in your table of contents entries, you know, I think it's doubled bullet points and that's a clue that that page needs to have a template.

B

Misty, do you think we need one more template for something like reference Docs that aren't you know they're, not pure reference Docs, but they're, just in the reference section talking about reference, II kind of things, because I noticed somebody said this. What I've done here doesn't seem to fit the idea of concept, tasks or a tutorial, and so what template should I use so.

H

I, don't actually know the answer to that question. I have worked with in systems before where we decided. We were working with the data and we decided that we were just going to use concepts for everything, because we could make everything work in concepts and it was like a lightweight approach, I'm kind of negative about the idea of making a template to fit content that doesn't currently to the template. Maybe we can make a really generic template or maybe that content needs to be reconsidered. I, don't know like making another thing for people to remember.

H

It seems like maybe the wrong thing, but I'm new, so I'm, not the one who would have the strongest opinion here. I didn't develop the templates yeah.

B

I think what what we've done, which is to just use the concept template as the catch-all for anything, that's not a task or a tutorial, is fine and it's at least fine for now. So we can. We can think about this more as time permits. I do.

H

Have a question about how the templates work, because I don't actually know so what's next thing at the bottom, doesn't always apply what happens if we leave that off right now of the template, I didn't test it to see and there's a similar thing for tasks which is like discussion and I. Don't actually know what's supposed to go into discussion for tasks, because it's not like we have most of our tasks, don't seem to have something that I would call discussion if I was just like looking at the rendered output.

B

I think in discussion, I'm as if I remember that's an optional one and I put that in there just in case there was some discussion needed, but I don't remember about the what's next. So yes,.

E

B

E

This is the way to fix if the symptom- it's like the the hard symptom for lack of template, is that um TOC behavior really have an issue with the generated rooftops and I proposed what I thought might be a fix in Steve's. The luminary pull request against the 111 branch for the generated Docs I was wondering whether we could simply suppress the TOC Rober fix is to wrap everything in a template. We're not doing that for the generated Docs at all is my understanding and recollection.

E

So we have another can of worms that possibly needs to get addressed outside the scope of this meeting, but I figured I'd better flag. It yeah.

B

Well, look at that with you. um This is making the the Hugo migration cleanup. Look a little farther in the distance I mean finishing. The cleanup looks like it's a little farther out.

A

Steve can I ask you: when do you do you want to follow up in a week? Do you want to follow up in two weeks.

B

Yeah I I'd like to follow up in a week and in two weeks, because I think we got a really push on these kinds of things before the you know for the 111 release, yeah.

E

That's my worry to I. I am probably not available real soon, but by the end of this week, if, if you want help or when it brainstorm, Steve yeah.

B

E

A

But just for perspective, I think I.

A

Remember serves 1.11 is currently scheduled to drop on Wednesday next week, so 6:20. So if we come back next week, that's basically have like eight days so.

E

Worst case scenario, we ship from 111 with some extra bullets on these pages in Queens I mean I mean it's not it's not great. We need the templates I'm, not saying that we should let this slide indefinitely, but we're clearly approaching getting caught between a rock and a hard place over.

H

Controversial suggestion that we could also have a temporary fix somehow in CSS, by just like figuring out some CSS way to suppress like if it's in the table of contents and the list item doesn't have any text. So they don't show a bullet for it like. It seems like that may be something that somebody could devise in CSS and the short term at.

A

This point I'm going to moderate lightly and suggest that we move this out of this off line and move this. It's a to a separate discussion in a dedicated meeting.

A

A

All right, let's move on so Jennifer I, see you added an agenda item based on today's discussion in cig Docs, for guidelines about documenting alpha features or Docs at any specific feature state.

A

Can you sum up quickly and briefly and when you propose to do about it or that we do about it I we.

E

Need I think that we need a write up, that is guidelines both for us and for folks contributing to feature Docs a new release, Docs Docs per release. This has been a source of confusion in every release that I've been involved with in the past. So when it came up today in sig Docs, that's why I flagged it I'm not prepared to provide anything specific right now, I wanted to put it into the agenda so that we didn't lose it I'll follow up in two or three weeks: I, don't want to commit to any.

E

Sooner than that, we're heading up to the release. It's not going to affect 1:11 anyway,.

A

Thank you for catching that I saw the discussion. Go by I didn't have the chance to dig in before the meeting, but that was Tim all clear. No.

E

Tim Sinclair, which is the other reason I like it. Also we kept you, but it is it's a valid concern because I've seen it come up and I would I'm not even sure who the stakeholders are. So that's really all there is to say about it at this point, I think: okay,.

A

Thank you for thank you for highlighting it and I agree that we absolutely need to be mindful and how how we document features state is right. Now, it's kind of haphazard and.

A

Trs working where future state comparison has come up, it's been difficult to discern a single source of truth, so anything we can do to provide clarity. There I think, will be helpful and.

E

This is not just for the folks inside Doc's. This is guidance. We need to promote yeah.

B

Absolutely so it's the problem that we don't have a mechanism for doing this or is the problem that we have a mechanism and we just don't stick to it. We.

E

Have the feature state flag seems to me to be applied more systematically than it used to be on. The issue that came up today in the slack channel was where apparently in releases passed and I think I probably helped to usher them assure PRS through some eager devs. Anxious to comply with the feature tracking stretch for the release have provided pretty thorough documentation for alpha features, which really aren't meant to have like pages devoted to them when they are still in alpha.

B

E

A question and we don't have a standard or agreement about it and I've heard it discussed in big sorts of terms um on at least to release teams now yeah.

B

A

A

Moving on Zach Arnold I see you have what is what is this a prototype link checker and go turning everything in.

G

This is we're, gonna go right, took a stab at it and for those who can enjoy the intricacies of depth-first search. This will probably fascinate you, but.

G

Essentially, this will print out two standard out. All of the broken links pick a depth of five. If I remember correctly, links away from Canaries that I owe and I'll just reverse the whole website. It takes like 30 minutes to do at present, at least in my first few runs on my local machine. So my question was: what do we do with broken links? Should this be emailed somewhere? Should this be run as like? An AWS lambda function that so? How often should should should this thing open, PR issues on github for broken links?

G

Should this be a a thing that must pass when we merge PR s? This is about I, have.

J

One quick thought on the: should it merge before we past PRS? Is there anything.

G

J

Pr that could break it.

G

Oh totally I mean had a link that that that randomly now 404 is outside the PR could totally cause that, which is why I was not super set on that suggestion. But I just wanted to toss out all of my thoughts. I.

D

Think we talked about this in the past. Is this something we'd run every month a few months or something or right before you know, I think that's how we talked about before, and it generates a lot of good stuff for Docs, prints and what-have-you, but I didn't think we wanted it running every time.

E

Right well, we know that the site contains many broken links. Yeah. It seems like not such a good idea, but one option would be to get things as cleaned up as we can and for some reasonable, currently undefined value of reasonably cleaned up and then to incorporate it.

E

But I guess. My main point is a caution against doing anything that involves the PRS at this stage of the game. I think it would be lovely to get something like this going sooner rather than later, though, because we keep III, don't know about anybody else, but I have sure wrangled multiple pull requests against the same broken links in the same files, yeah.

B

Yeah we want that this will save us that not only will it do the right thing, but it will save us so much time in these small PRS that come in and then we have to wrangle is.

I

There a way to just apply it to the files in a given PR, because I feel like there's two levels like the doing scan the whole site, which takes a long time. But then, if it's just limited to the files in the PR, that should be pretty fast and no chance. Yeah.

G

I actually really like that suggestion, we could probably have it just read through the github API, take the metafile link and then the change set that exists read through scan for any href tags which would be links and then just scan those and make sure that's all good to go.

G

H

A pretty naive approach, though, because the PR could be reorganizing files in such a way that it's causing broken links in other places like I, think that's a good first start, but that shouldn't be considered sufficient to know that there.

I

Should be multiple levels like where we should still run like you know the monthly whatever? That does the in-depth thing, but just like to minimize the impact on PRS, we could limit the scope for that I.

A

Like it I think, I mean obviously a 30-minute. Gae check is undesirable, but if we can limit the scope of if we can limit the scope to simply the PR, the files that have been changed well, that's not well as misty points out. That's not a wholly sufficient approach. It sure beats what we've got now so yeah I think this is I. Think it's a wonderful idea, hi Jennifer! Thank you for joining us, I!

A

Think yeah. Let's, let's take a look, it would be honestly exact. It would be really helpful to see like a sample output. Sure if we I am really I'm curious to see what kind of issue output it could generate in in github.

G

Probably I mean so again. All of this is completely we're talking pie-in-the-sky at present. What it does is simply crawl through the whole website scan for a depth of five and output on the command line, what what links are broken so everything else that we would love for it to do. That's something that I could totally build, and it's configurable so I think at this point, we're sort of saying and I'm happy to send sample output, but I think at this point. What I'm mostly saying is like now that it works.

G

What direction do you want to take it so.

A

It sounds like if I'm hearing, folks correctly, it sounds like limiting the scope to files changed into PR and having that as a including that the CIA gate checks is the way to go. Am I hearing that right, yeah.

I

Well, I was thinking if we had different modes right, so one would be for the PR gate checks, but then there might be another one that we might run more, that's a site-wide, that's you know, maybe monthly or something that could do the more in-depth thing, because because misty is right like it's not gonna, if we just limit to the PRS, it's not gonna cover everything, so we just need sort of different tiers that will kind of catch. The different level of rounds.

B

Yeah and any time one of us, you know, gets inspired to fix, broken links. We can run the link checker on the whole site right, fair.

G

That, then, leads me to my next question, which is when someone gets inspired to run the link checker. What? What exactly does that look like I mean my prototype was to toss it up in AWS, lambda and it you know it just runs as a as a go binary. It goes and check stuff and has an output which is lovely, but that's pretty much constrained to the only person who can invoke. That is me because I have access to my AWS account yeah.

G

So how would this thing best be leveraged by the entirety of sig Box I was I'd. Look to democratize this as much as possible. That's a good question.

B

Acidic go buying a single go binary, we could just download and run but totally of.

G

Course, I probably could cross compile it for the various architectures that we all run on Linux Mac good windows, but it absolutely could be done. It.

H

Would be better to have it in a docker container instead of having to have us download a a binary, orb, potentially compiled binary. I also think it would be really nice eventually if it could run somehow unattended and create the PR with the problems that it finds or update an existing PR. There used to be a Jenkins plug-in. That would let you do that. That would let you like reuse, the same pull request.

G

Well, I mean I think if that would actually be pretty easy to accomplish if there was a consistent way in which it created pull requests that it could obviously just go check there and say: hey did I recently mention this in in the cache and I know the way that I tend to make requests so I I will check to see. If that's something I've already opened an issue on in the repo, in which case I won't do it again, I.

G

Like it, it was I said most of this was for ID ating and then I'll go and iterate and build more stuff based on you. Guys's feedback awesome.

A

Yeah I look forward to hearing more. Thank you.

A

All right, let's see that Timothy st. Claire, you have joined us in the few minutes that we have remaining. Let's do let's go back and talk about guidelines for documenting alpha features. Now that we have Jim Sinclair with us, yeah.

K

Good, the put-putting documentation out in the wild for alpha features on the main website is generally can be a supportability nightmare, both from a Doc's perspective and from a development perspective, because helpful features guarantee you. There are no guarantees for alpha features other than that can break, and it also requires a set of other cascading changes that typically have to occur to enable those alpha features so they're not typically enabled by default they're, typically disabled on purpose because and they're not tested.

K

So putting those things on the forefront in main documentation can be problematic and I've been finding. We've been as part of this sequester lifecycle release we're trying to systematically take a look at what has grown organically and try to restructure and reflect our Docs to make it clean, and, as we dig into all of the dependencies that go out, we find that it kind of sprawls further and further, sometimes getting to the point where we have, for example, like the cloud provider integrations where it's it's very difficult to follow.

K

It's not a it's, not a cohesive guide and it calls out a bunch of details that we probably should never call out in the wild. So that's the TLDR there, but I had another come in for a different thing after this okay. So.

A

If we just had a summary of don't document, alpha features in the wild, would that would that suffice as a guideline.

B

So I like the idea of not documenting alpha features, but this really I mean the reason we do is we got a lot of I won't say pressure, but you know we were asked strongly to document. Alpha features with the idea that we want people to try the coolness stuff. So the the reason we've been doing it is that the thick, the core of the kubernetes core developers have been asking us to so is so Tim. Are you saying that we just really want to shift in an attitude about this? We.

K

If we do, there should be some type of like Siri of clauses or standard set of things that we put at the top of everything that says like warning, warning warning you know you're treading off-the-beaten-path. These are not fully tested features and if you rely on them all of these things could occur so I think.

K

If we do, we can either have like a link out right from the main document that sort of links to how do you enable these things or or some type of set of clauses that you know it makes it clear as day that what a person is the the journey that they're about to embark upon is not standard, supported, kubernetes well,.

B

I love the idea that we could get out of the business of documenting alpha features.

B

H

Yeah right now, I'm in the thick of this for 111 and I, believe because of historical work. Humvee hat on the part of sig Docs sig release is actually fairly strong about kicking issues out of the milestone if they don't have at least some minimal Docs, including alpha features and I. Think this is the only way that they have to enforce that.

H

Every feature should have some kind of Docs because something graduates from alpha to beta, and maybe nobody remembered to document it so I think that their thinking is, if you at least get something in for the Alpha, then at least you have some kind of Docs and yeah. How are people going to test it and move it from alpha to beta if they don't know that the feature exists or how to use it?

H

So there's like a tension there between wanting to have a very stable product and wanting to have a fast-moving cutting edge I like.

A

The idea of having a standard, disclaimer and I'm sorry, but for the purposes of time Tim you mentioned you had another comment: we have a hard stop at 11:30, so I'm going to leave it up to you whether you want to address your other comment or continue with the discussion about alpha features.

K

A I think we can, we can punt on the Alpha features one. That was not the major reason we could took. We can leave that for another time, but the the restructuring and reformatting of some of the contents.

K

That's there I, don't know if there's a policy or process by which we do some of this, but I'm looking to restructure some pieces just to make it so it's lumped together because right now, underneath the administrative guide, there's like a separate set of Docs, which are not it's not visible to the user- that this these Docs belong to. Qadian and I, put a subfolder just to have it so that it's clear that all of these Docs belong to Canadian and nothing else right. So it's not confusing to anybody. Who's browsing through the details.

A

That sounds awesome to me. I would suggest just open.

K

A PR and go for it. There is a PR open, misty coming tonight. Yeah awesome.

B

Is Jennifer rondo involved in that PR she punted to misty, okay,.

H

Characterization I think she asked for me to give additional feedback I think her feedback is also valid and she still wants to work on it.

A

Okay, but I just wanted to confirm that I'm so happy to hear that there's an open PR and it sounds like it is in the review process. So to me that sounds like everything is going as as it should.

K

Go ahead: are there any questions about because there's only one level deep in the talk structure are there? Are there concerns about that.

A

Possibly but I think that that discussion is probably best confined to the PR. Okay, if you want, if you want to assign me in, is that Zachary Sarah I'm happy to take a look at to your some weights and things like that sure awesome all right. We are right up to time. So thank you. Everybody, great signe, ting, really good discussion and see you next week take care.