Kubernetes New Contributor Series, 10 May 2018

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: 2018 Kubernetes Contributor Summit EU New Contributor Workshop Part 2

Description

First ever New Contributor Workshop!

Speakers Josh Berkus, Guinevere Saenger and Zach Corleissen walks us through how to contribute to the Kubernetes project.
In this part you’ll learn what the difference is between an issue and a PR, how to file a bug report, how to use GitHub labels, get an overview of the Kubernetes docs and a walkthrough on how to create your first contribution to Kubernetes.

A

How did everybody so we're gonna get started again? I will do a little bit of talking and then go ahead. A very will be up here to lead you through a hands-on exercise in contributing a PR, but first before we get to PRS.

A

There is a different level of contribution that you will generally start with, which is contributing by issue now. People are generally familiar with issues as bug reports right I. So that's, obviously your new contribution that actually honestly, is a contribution.

A

The because, if you can come up with a really good problem statement for something that's broken, often it's actually harder to do that than it was to write the fix, because sometimes the fix will be like two lines of code, but somebody had to first figure out how it was broken and why so that's one way to contribute, and so you can find now the first hard part for you is figuring out where to file the bug against right, because most issues for code stuff will against kuben aids.

A

Kubernetes users against Doc's will go against website and actually the doctor will make it super easy there. You go to any page of the kubernetes Doc's, there's a link at the bottom to file a bug against that specific page of the docs, which makes it really easy to do that.

A

File complete and detailed bug report, including labeling, which I will explain to you and then the other important part is follow-up. Don't file a bug that says when I do this and this and then this thing breaks and then not respond to any comments on that does not make you friends and it more importantly, it doesn't get stuff fixed.

A

So an example of a good bug report. This is a bit cheating because it's actually a bug report, in fact, filed by a kubernetes major contributor, but also like I, said you start with issues. So this is actually somebody who is a cig lead and how he's starting. He didn't just throw of koden how he is starting is by filing an issue explaining what's broken, and if you want to look at an example of a good one right.

A

So this person, it's a provisioning, existing juror dish in a pod, and you set these switches and this bad thing happens, and so he filed that issue and then he followed it up by filing the PR and they're both his. But the issue is very important project documentation for what was it he was trying to fix in the first place.

A

So even if you are going to be writing the code or the documentation to fix the problem, it's often helpful for the project for you to start with an issue, and that actually comes to how issues are used within the kubernetes project, which is we often use.

A

We use issues as our way of tracking specifications for changes so like, for example, one of the things I'm currently going through will be going through labels later on is I'm going through some label changes things that we're going to change about what lake gets labeled for what, and that starts with a specification for an issue of hey, we've been using this one label and it's really confusing people, and so we need to split it into these two other labels instead and that operates through an issue, and so we do all these specifications and future proposals and those are issues now the way that this works here generally, is you start with an issue?

A

You write the issued and submit the issue that proposes a change. However, we have something like a hundred new issues, a day open against kubernetes. Something like that. So that's not enough. So start the issue compose new to apply appropriate labels, see see on the issue any sig leads or concerned developers that you happen to know about. I mean don't spam people but like if you are already involved with the sig.

A

You know who the leads are you know, or you know who works in that particular thing like, for example, if it was a bug with one of the bots that does github automation and prowl, and that sort of thing you would probably see Ciaran on it and then yes,.

A

Sir I can't quite hear you.

B

Come back, you forego confirmation, that's a different phase and I'm used to it from Oakland steak. There people people don't get assigned yeah.

B

A

No, it does not run like OpenStack, because we don't have the centralized dashboard that OpenStack uses so and- and here I'm not actually talking about assignments, oh by the way.

A

The way that you do this in in github is you put an @ symbol and somebody's github handle after it in a comment the so and then, if this is something that is non-trivial, if this is something that needs attention and you are not and and either you're not going to be the one to write the codes or dock for it, Kota dock for it, someone else needs to do it or alternately. It needs discussion right. We need to make it change. The API, for example, might need discussion I, you know something.

A

Is this sort of thing I need to fix this performance problem, I'm, not sure it works already, but or needs discussion. Then you want to raise it with the appropriate sig at a meeting or on the slack channel or on their mailing list or whatever, to make sure that this particular issue that people notice that it's there. Why? Well?

A

Because if you're a regular contributor to kubernetes, you get something on the order of a couple hundred notices from github today, I think I'm up to like eight or nine hundred personally, and so as a result, the github event traffic is just not sufficient for somebody to notice something and by the way, if anybody has a good solution to that problem, you can make a ginormous contribution to kubernetes in the future and then most decisions in SIG's etc.

A

You know for anything, not super significant operate by what we call lazy consensus, which is that if a couple people approve of it and nobody voices strenuous objections, then it goes ahead now. I talked about labels and this is gonna become more important when also you go into the PR exercise, so we have an elaborate system of adding labels to issues and PRS in order to categorize them and all of these labels, because the github namespace for labels is flat.

A

We use a prefix with a slash and then something else in order to create an effective taxonomy of labels. So when you file an issue, two labels are required immediately, which is a label assigning that issue to at least one sig. You can also assign it to multiple SIG's and that's sig, slash Ana label, assigning it to a kind.

A

Now, when you're assigning to a say, that's going to be the sig you'll, see these labels they're saying the sig name right, so sig, slash off for cigar sig test infrastructure is a KPI. Machinery do be careful because some SIG's get referred to by a shorthand name. That is not the same as the label.

A

So just look at at kind of what labels there are and by the way you don't actually will not have permissions to just add the label in the right-hand column and github you're going to be adding those labels to bots, which you will learn how to do in a minute.

A

The second thing: that's required is a kind label, a kind defines what the type of the issue is. What general thing are you reporting or hoping to accomplish via the issue? Is it a bug? Is it a potential new feature or change to a feature? Is it documentation? Is it a design doc and that's generally used like it like API machinery uses design all the time? For you know, we're gonna have this new interface for controlling this and such is it are you? Are you with?

A

You know the testing group and you need to report a failing test to the sig, that's responsible for that task or a flaking test. Flaking tests are tests that fail, but not all the time and they're the most annoying ones. For that reason and refactoring etc goes under kind cleanup.

A

Those are two labels that you need immediately and if you don't put them in, the Bott will remind you and if you ignore the reminder, it will close your issue. So you need this immediately. Now, there's a couple of other labels that will get added relatively rapidly later on. First of all- and this is the secondary- you contribute to kubernetes you'll notice. There are a lot of open issues against kubernetes. You just go to KK. You will see that there are currently something on the orders like 1800 the issues open.

A

So one of the things that we need a lot is issue triage.

A

Some of the meetings started soon with sort of organized issue triage, but in the meantime importantly, we have these triage labels, and so these are labels that are applied to close an issue because it has been triaged.

A

So, for example, if this is, if six people reported the same issue with the CLI, then we're gonna close five of them as duplicates or if we ask the person for more information on the issue they file, they didn't respond after two weeks, then it might get closed as needs information, etc, and if you end up volunteering to help out with triage, really use these labels a lot now.

A

One of the things that's actually changing is I said we're migrating labels right now. Support is a kind. It will no be true your support. Why is that a closing label? Well, because we've already said we do not do user support via github issues. If you need help with how do I use kubernetes, then slack Stack, Overflow, hi, mailing lists not github. Issues next is priority issues and these priority issues will generally be assigned by the cig leads or in a cig meeting, and this says how critical is this issue now?

A

Sometimes party labels never get assigned when you see these getting filed is when we're getting towards a release because then they become acquired and the bots bounce issues and PRS that don't have them. I would really ask somebody who sometimes in charge of issues I, would really don't like them to be attached all the time, but there's a limited amount of nagging. We can do people but, and then this is a hierarchy right priority critical, urgent means. This is something that needs to be fixed immediately right.

A

uh You know, guberniya, send this command kubernetes crashes right priority, critical urgent, as opposed to priority backlog, which is something like hey the code for this is really messy and hard to read, and we ought to clean it up and that's going to be assigned a priority backlog. It's something we ought to do eventually, but there's no particular timeline attached to it and then sort of everything in between completely optional. So, by the way all the labels are gonna before are actually.

A

There we go in this hard-to-find subdirectory.

A

There is a file that defines all of the canonical labels that apply to kubernetes kubernetes and a lot of the other repos under the kubernetes namespace, like I, said, repos have individual sort of foibles and differences, but these are the canonical labels that are supposed to be for the whole project, and so the labels I was giving you aside from the cigs where it matches the list of cigs is actually the full list of labels that are available to you, because we're trying to limit this to a namespace- and these are all in this labels file maintained by test infra because they are in charge of the github bots the.

A

However, some labels are kind of open-ended. The aerial label is there for you to inform in a cig particular way. The kind of specific thing that you care about you're actually going to be using aerial labels in the upcoming thing. But there is no canonical list of aerial labels, because each cig defines its own, and so this is kind of freeform.

A

So there's only a thing like, for example, you know you might be in Signet work, but you're really filing a bug against DNS and you're gonna. Add an area DNS label because that's something that they use, but none of the other SIG's used area DNS.

A

Now here's a label, it's broken from the perspective of most people, which is you, will see a lot of issues with Help Wanted on them and for some people used to github, they jump in there, they're gonna, say: hey I'm gonna pick up one of these Help Wanted issues as a way to get started right now that doesn't work, because if you look at the majority of Help Wanted issues, they are Help Wanted, because the issue, the problem they are trying to solve is a complicated problem that requires outside expertise or tremendous commitment of time rather than newbie friendly issues rather than first contribute a friendly issues.

A

We are introducing another github label called good first issue that we will try to use to label issues that are actually good first issues, but right now do not assume that Help Wanted means good. First issue help one. It simply means this is something that's acknowledged as broken needing to change new spec and no one is working on it, but generally no one is working on it for good reason.

A

So once you've filed your issue and that sort of thing once you've got our labeled, the important thing is to follow up, don't go away. People will ask for additional information. People may ask you to try things. People might if a doc gets updated. People might want to say, hey read over this, and does it actually answer your question and that is kind of critically important, because if you file this issue to go away, then chances are that fix will never get merged.

A

So having gone over issues, we are then going to move into their sort of main event here, which is making contributions by poll requests.

C

Don't mean not a meat anymore, excellent, okay, yeah I've been really looking forward to this part um I'm, going to give everyone about half a minute or so to get all their laptops set up and just get ready to do. Some live coding together, well coding, but I will walk you through the one of the most basic github workflow processes and bought response cycles that that you can encounter in the kubernetes repos.

C

For starters, I.

D

C

Like you to go to.

C

Alright, so who here is unfamiliar with github awesome, so all right, excellent! That's that's great! We are just going to walk through everything from scratch. If you what's.

A

One thing I'll say is: if you technically get stuck following along I'm, also here in the room raised during it,.

C

Basically went over to you and Josh can help you very cool. So what I would like for everyone to do is: go and open a browser of your choice and go to github.com, slash kubernetes.

C

Slash community.

C

We've shown you parts of the site before. Let me know if this is too small. I can definitely make my make my display I might make my language make it bigger. So then I want you to go to contributors and there are four folders and the bottom one is the new contributor playground folder, which is really just made for you. So before we do anything else, there are some rules. We have been very graciously allowed to space in the kubernetes community, repository for actually opening real pull requests against it.

C

So I would ask everyone to stick to this particular folder of the repository and really be responsible about this particular area of the of the repository.

C

Don't worry so the plan is that I'm going to go and pretend that I'm opening a pull request well I'm, going to open a pull request against this repository, and you can follow along and open a pull request as well as I go through it. Any questions, everyone ready, okay, very cool, so the first thing we're going to do is we're going to go to the top right corner and fork just repository. I already have a fork of this repository, but you might not so I'm going to go to my particular repository.

C

When you contribute to the kubernetes repos, you always want to fork any and all repositories to your own personal github account. That's there is. You will avoid a world of hurt and trouble. Do not try to do not try to clone the repository directly and then issue a pull request against it.

C

It's it's not recommended. So then we're going to go ahead and clone copy to your clipboard and open a terminal of your choice. Oh.

C

This one I'm gonna make bigger I'm. Sorry.

C

Here we go. Let me clear that here we are so it's on the top. Alright get clone and paste that oops. So this might take a while cuz it's a pretty big repository.

C

So um there we go and now, if I go and check it's in it's right in there, my folder now before we do anything else, I'm going to sit I'm going to do one more thing: I'm going to check my remotes get remote. Oh.

C

Sorry, yeah I gotta check into the community folder first I always do this. Who always does this and I think I'm? Okay, thank you.

C

Alright. So here we are and I'm going to check my kit. Remotes and I only have one remote and it is called origin, which is the get default before I. Do anything else on what I want to do is go back to the kubernetes community, repo and.

C

Get and copy that now this is not a clone, but what I want to do is I want to set the kubernetes repo as my upstream remote.

C

So the way to do that is get Ramon set upstream and you can you don't have to call it upstream, you can call it whatever you like, I prefer upstream I, always call it upstream that way, I don't get confused and then the website that I'm pasting in you can see now is kubernetes slash community rather than my github account slash community I'm going to go ahead and woops did I. Do that get set remote get remote. Add. Thank you.

E

C

Remote, be okay, very cool, so now I have my origin, and my upstream, this is going to be important for the workflow and again before I. Look at any code. I have I, have a little I have I have my get. What's that called I? Have it set up so that my command line actually tells me which branch I'm on not everyone's terminal is going to look like that, but I'm assuming you're, currently on the master branch?

C

It's generally good good practice to not do that, even though, technically you are on your own personal branch, the reason you want to keep master clean will become. A will become, will make sense later you really just want to not ever code against master, so we're going to create a git branch. Git branch, oops yeah, good branch check.

E

C

No, no, no wait a minute get I'm trying to write it so that it's not my usual shortcuts and I'm confusing myself so get check out B. That makes a branch and I'm going to call this branch kill con and now I'm on a kookn branch. Now I'm going to look at the repo I, don't know what use your use! Your code, editor of choice, I use, Visual Studio, because it's the prettiest.

C

So again, navigate to the contributors, folder.

D

Why is this not? Oh, hey! You know what I didn't do interesting. I'm gonna have to fix my good fetch upstream.

C

Master, what I'm doing right now is I'm actually pulling in the stuff that wasn't on my right kid.

D

Wish I can walk you through this later, okay, great.

C

D

Should be there all.

C

Right there it is there's my new contributor playground. Folder, you will see an owner's file, don't worry about the owners file, please don't open any PRS against the owners file and a readme. So for my pull request, what I'm going to do is I'm just going to create a new file and that's I'm going to call it new contributors, MD I'm, going to make it a markdown file, we're not going to actually do any code today. This is really just for the workflow.

C

Did it just get dark in here.

E

C

E

C

Hello, everyone, please feel free to talk amongst yourselves. If you need help or ask questions.

C

I'm doing pretty well with the typing and talking at the same time, um great.

C

Am I still on master good.

D

C

There we are all right so now, if I check my git status, I see that I have added a completely new file to the repository.

C

So here's what I'm going to stop a little bit and I'm going to encourage perhaps one or two people from each table to go ahead and actually go through with submitting a pull request and everyone else can kind of watch.

C

What they're doing the reason is there is I, don't know how many people there are in this room, but in order for me to actually follow through and kind of show, what's going on with some of these things, we don't really 100 pull requests all at once, but you should still be able to at least see a lot of live flow, and all of you should be able to comment on the whole process and be reviewers as well. I, originally I hadn't expected everyone to come in with their CLA all signed.

C

So this is fantastic but but yeah. So we don't really want to completely overwhelm this repository, but we do have permission to just experiment a little bit.

C

Any questions so far.

C

You should all know each other from the from the from the from the exercise earlier. At least that was the hope all right, so.

C

So and again you can you can create an entirely new document, maybe introduce yourself or maybe I. Don't know it can be fun or you can also just change one of the existing documents and do that so I'm just going to create a new document right now, I'm gonna, add it I get a.

D

New contributor playground.

C

There we are new file and I'm going to go ahead and commit, and okay, so next part the commit message. So, ideally, your commit message will be a short title. This is a practice commit followed by a blank line, and then this is a paragraph describing in detail. What this commit is about.

C

The reason that we want this is because there's nothing more frustrating than to walk into some repository and find something like changed all the back ticks. Why.

C

Did it fix something? What was going on? What is the context and, and then you know, then it just becomes difficult. You have to read code, you have to guess at intent.

C

A lot of people will require you to write two paragraphs, I think as long as you're being detailed, yet concise. Your commit message is going to look pretty good with a title and a paragraph explaining.

C

All right now, if I check my git log there it is. This is a practice commit together with my paragraph, describing the next thing. I want to do is I want to push my branch to my personal github repository. Do not push anything to the kubernetes community repo, yet push it to your personal community, repo.

C

And if I do get push you origin is my remote and coupe con is my branch name all right. My git config is not messed up cool people following so far all right, let me give let me give folks a minute or so, to catch up and decide if they're opening a pull request. Excuse me all right. So if I go back to the kubernetes community repository and if anyone is getting confused, whether I'm talking about the kubernetes community repository in my personal community repository, let me know I'm really hoping to keep the two separate.

C

So this is where we go back to github and.

C

Open this pull request.

C

You'll notice that, because of the way, I've formatted my commit message, the title line is already pre formatted right here in the commit on github, and my paragraph is already in the main box. So then there are some extra information right in here, thanks for sending a pull request. If this is your first contribution, read our getting started guide we're gonna skip that just for today, if you are editing, seek information, follow these instructions, we're not doing that.

C

It is polite to get rid of this text, even though it will not show up on your pull request, because it is a comment, but it is its cruft, so I like to delete it and then it's as simple as hitting this button create a pull request.

C

Here we go so this is where things start getting interesting with the kubernetes robot. The first thing you see is that the robot is doing a whole bunch of things.

C

What I didn't do was add a label of my own, but I can show you how that works in just a minute, so the the robot added a size label. This lets any reviewer know how much work probably is involved in this pull request either that or how many files you are importing, because their dependencies I mean that happens too.

C

Then. The next thing that the robot is doing is it's requesting a review. Oh hey, Josh. It looks like you're going to have to review a pull request.

C

The next thing that happens is the robot is adding a label and these labels get added because of the owners file. Let me actually show you that real quick right here.

D

Contributor play around where I said: oh, oh,.

C

That's my interesting: that's oh I do need to revise you're totally right.

C

C

And there it is.

C

So, okay, the label gets applied because the owners file is where the bot will look for information. This is also by the way how the bot automatically requested review from certain people it's going to look into the owners file and check, who is a reviewer who is an approver and what the labels are I, only added people to this reviewer list that knew and we're available. That noon were available for being reviewers for this particular exercise in the real world. What this? What this?

C

What this file represents is a level of contributor that is that relates to the level of your knowledge and history of contributing. So a reviewer is somebody who has knowledge about that particular code base and can give helpful feedback and can go, go over a pull request and determine whether it's technically and factually a thing that we might want to merge and want to approve.

C

This is where the language gets a little bit weird, because an approver is actually a one level above reviewer an approver is somebody who, as a code owner, gets to decide if not if it is technically functional, but if this is something that we want in the code base, do we want this feature? Does this feature represent what this party? What the community wants, does? Does this match the direction we want to take?

C

Let's go back to my pull request.

C

The last thing the robot did. It did a bunch of things it added the CN CF CLA. Yes, because I did sign the CLA a while back and then the robot is going to come talk to you. This pull request has been approved by, and that is blanked because no one has approved it. Yet, please assign additional provers, and this line is something that newcomers are often like. What do you mean? Assign additional approvers and the rule tells you yeah go ahead and assign additional approvers?

C

These people are pulled from owners files, either at the level of your sub project, new sub folder or from other owners files levels above them I'm not going to sign error developer because he's not part of this workshop I believe or is he wait? No, he is nevermind I'm confused, but he's not here right now. So this is the line where, when I first saw it, I got super super nervous because I didn't know who this person was on github I'm like who is err, developer, I, don't know or whoever it was at that time.

C

C

Very cool hello, Kubb con, so what I can do is I can comment and say: let's see, sorry about this. Let's actually look at the details. First, it needs an approval from the proven each of these files, just the owners files. So what can happen here?

C

Alright, so I'm going to go ahead and assign somebody.

C

I'm actually I'm just gonna sign era developer, because there you go and so what's happening now, is that right here on the top right corner will see assignees and what this means is that Ilya is going to get a message in his inbox. That says: hey somebody assigned you, this pull request. Can you please review? Can you please approve.

C

So I see that I've been getting some comments. Number one. Is there an issue associated with this PR? This is a really good comment. Most of the time you want to go ahead. If you find a bug you to go ahead and file an issue first before you set down to working on it. The reason is that this makes people aware that there's an issue somebody might come and say: oh yeah, we are aware of this. Here- is a workaround or oh yeah. Somebody is working on this already.

C

You can absolutely offer that you're going to work on the issue once you filed it, but in general you want to file an issue first, so you can have the discussion about whether the pull request is necessary and then you would go ahead and submit a pull request every once in a while when something is like a tiny, tiny little fix it's okay to just go ahead, and you know you know how to fix it. It's a problem. It is definitely not completely impossible to just file a pull request and say: hey I noticed this.

C

Here's a fix, but especially with bigger fixes or when it's when a feature is involved. Every time a feature request is involved, always file an issue first filing an issue is just much easier than then submitting a pull request. That's why we're skipping that for this walkthrough, alright, so hello, everyone, please feel free. So now you see that somebody has commented on my pull request. All right, cool I'm, not gonna, comment back! That's mixed I'm gonna go back to my code and go ahead.

C

Hello, everyone all right and I'm also just going to go and make this into a title. Maybe there we go, get rid of that! Whitespace save so now again, I'm on my feature, branch coupe, con and I just made changes to my pull request. I'm, responding to the review that I'm getting from Josh I'm checking the diff all right, I put in an extra line.

C

C

Let's see, let me just copy this, so I was brought up to always specifically know sorry. I can't commit yet get add to always tips to always specifically add the file by name and sometimes lazy, and don't do that. But I can't do that in front of an audience, because no, you all should add each file specifically and then commit and then I'm going to address this.

E

C

Text is in two lines and then for better reading. Something like that explain why we want this text has been separated.

C

Alright, now I'm going to push and because I already have an upstream remote branch, I can just get pushed to that branch, because.

E

Let's see mmm what did I do: yeah I rebased! Well, let's see.

D

But I did rebase against us, so I'm a little bit confused. Let's see.

D

hmm There's nothing there.

D

Let's see I can go ahead poof. This is.

C

Cool I haven't run into this again. I haven't run into this in a while. mmm What did I do wrong? Let's go back here, oh right, very right because I rebased, thank you. Okay, every time you rebase, you have to force push, um let's see, get push f. This should work so.

C

Unfortunately, this is going to mess up my pull request.

C

Alright, so my pull request has been updated right here, because I had an open pull request on this branch. The update directly goes to the pull request. I still have a review requested now. The next thing I need after I've addressed. My comments is, I need to have an approval label from a code owner and I need to have looks good. An LG TM looks good to me label from a reviewer. The only people that can add an LG TM label as reviewers are kubernetes org members, who here is an order.

C

Somebody want to give me an LG TM on this. I'm right.

C

So, and the trickier part is to get an approval from code approver. That is what the bot is telling you that's why the bot is telling you to assign certain people, because those are the people that have the power to give the final label. Oh look: I got an lg TM right here, tada, who approved my PO eQuest.

C

Thank you all right.

C

All right very awesome, so two people gave me an approval label. That's excellent, so my pull request is well on its way. It is technically correct and it is ready to be merged, but but what is missing is that we need somebody from an owner's file. Who is an approver right here, so we need either well I'm not going to self approve my own pull request.

A

C

Do it, but they shouldn't sure, go ahead. This is the part of your pull request process that can take longer it's going to take.

C

You know because your approver might live an entirely different part of the world and they might just not see it on their github notifications. So what is sometimes worth the time is.

C

You know pinging them again or finding them on slack and saying: hey I have an open, pull request. What are your thoughts? Is there? Some is there some way that we can talk about this? Is there something keeping this from merging? Do you have concerns, and often people do have concerns it's a big community. Sometimes people have long discussions about things they feel strongly about, but a lot of the time it really probably just means that they were busy, and you know people have to sleep. People go on vacation things like that all right.

C

So the thing that now after I receive I collect all the necessary labels. Up here the approved label, oops yeah. You can actually click on the labels and see all of them the the CL a label, the LG TM label. Then the bot knows that, for this particular repository I have collected all the labels necessary for it to run tests and pass.

C

For folks who are not org members, they might need additional labels so now I have successfully merged and in my pull request has been successfully merged full walkthrough.

C

Let's go back to my slide and, let's kind of see what we did here. This is the github workflow we're going to go to github kubernetes. In this case, we used kubernetes.

C

Community first thing is fork: the repo to the user github account, then we're going to get clone into a local working directory step, 3 we're going to work on a feature branch work on the feature branch and commit keeping in mind that we want to do good, commit messages whoops if you ever get interrupted- and we actually saw this because I'm yeah, because I didn't because I didn't pull down the most recent version of the of the community repository we have to fetch and rebase and we can walk through that one more time, if necessary, so and then I commit to my local branch.

C

Then I push my branch up to my right here. Step 6 push it up to my github repository, my personal github, and after that we create the pull request and, after that, it's interacting with your reviewers and with the bot commands.

C

I want to kind of see what happened with some other pull requests on this repository so who here has opened a pull request? A couple people? Yes, all right, I see lots of awesome labels, so I'm just gonna go ahead and filter by that label, all right, hooray, so um one label that is showing up on all of these. Not just almost all of these is the red label. That means needs okay to test, and this is an extra.

C

This is an extra step that we put on pull requests by non org members, but fear not. It is actually not that difficult to become a member of the kubernetes org. You need to have a couple of pull requests. I think the number the number was five when I joined, but it might be more, it might be less and it always just kind of depends.

C

And then you need to have sponsors from the community, which does mean you have to go and attend the sig meeting or find people on slack, but in general, if you've submitted a few pull requests, you will know who reviewed your pull requests right. So it's pretty easy to find them and ask them hey. Do you mind I've been committing for a while? Do you mind sponsoring me for membership and after that, it's a formality before you are a member?

C

Let's see- and let me see here ooh this one- this one looks nice, so I added link, and this one has me assigned as a reviewer. It looks like that's my owl cool everyone. I have never been assigned as an approver to any kind of pull request. It's kind of awesome I wish this weren't just for practice all right when navigating the readme, you can now click to be redirected to the repository community. Okay, let's see I'm going to look at that file.

C

Subfolder, let's see, can I have you it see if that works, awesome, totally works, cool.

C

C

So this looks good to me. This is a good idea. I like this. Let me go back here. There's one commit right and what I need to do here before I can do.

C

Anything else is going to talk to the bot, and this is going to be an example of me talking to the and the way that you talk to the botton is you tape do type a slash that starts your bot command and then I'm going to add the label okay to test in a comment just like this: that's all it takes and now notice that the needs okay to test label the red one is gone right here and now it is removed and look what's going on right here.

C

Now all the test Suites that are applied to this repository are running. This is a fairly short test suite.

C

The most of the other repositories have a whole slew of tests running against it, the reason being that the community repo is mostly documentation all right, so I'm going to go ahead and I'm, both a reviewer and an approver, so I'm going to I'm going to say I'm gonna, add the approve label just like this, but I'm going to wait for somebody else to maybe go ahead, sascha proof and there it is- got updated just now, I'm going to let somebody else add the LG TM to it.

C

So some of the things that you can do on your tables right now is to go ahead and find your tablemates pull request, go to pull requests area, new contributor track and see what you think of their pull requests and go ahead and comment on them. Go ahead and review I'm going to give you about a few minutes for that.

C

um Does anyone have any questions yeah all right? Let me mute this.

C

Alright I have notified that we should probably wrap up this part of the workshop. Pretty quick, but before I do so. I heard two questions and one of them I heard twice so I'm, definitely going to address that one question was: what is the procedure for squashing commits when you have a lot of commits in your history when you've been working on it and some of the commits just look like I'm gonna. Try this again or I have never done that ever.

C

Never, so the the basic we doing we don't automatically squash commits there's no button enabled on the get on the kubernetes repositories. The basic concept is: is that everything that sort of content wise belongs in one commit should be in one commit and we want to somewhat preserve the commit history. For example, if I change code somewhere and then add tests and then add documentation, I want those to be separate.

A

C

Know just this changes, this changes something and this adds a function. This adds tests for that function and this talks about what the changes are or how to use it. From now on. Those should be an we want to keep that commit history, but anything that sort of reflects your workflow should be squashed into those commits. If you have a really really small commit, like you know, add a welcome message right here. That's you know clearly, just one single commit and that's fine.

C

The other question that I had was what exactly is the difference between C? What's the difference between approved and lg TM, the difference is LG. Tm says this commit is to this pull request is technically sound. I I think this will work. I have looked at the code and I'm trying to avoid the word approve, but I have looked at the code and I believe this will work and I think this is good code and no more changes need to happen. The approval label is the label of a code owner these are these.

C

Are these are kubernetes members that have a long history of experience with this particular code base and they make more overarching decisions on you know they would say well sure the code works, it's technically sound, but I. Don't really think we need this feature so I'm not going to approve it. Does that make sense? Alright, just there was some confusion. I wanted to clear that up all right. um Everyone is welcome to have a little bit more fun with this particular repository for the rest of the day, but before I stop.

C

This is a this is a playground repository and we really are only going to use it as part of this workshop. So please don't! Please don't create noise by using this tomorrow, because you wanted to check out how labels work or something like that, but yeah. Alright, any last-minute questions.

C

F

E

A

Yep absolutely.

C

All right, let's move on, and let me free this back up game plan test infrastructure. Thank you! So much for being here yay we had some last-minute changes with our presenters. Yes,.

G

Yeah Aaron's flight, his drive is delayed. My name is San. I am from sick testing, so welcome everyone to cue, Kong and.

G

So for six testing, what our job is, um it's like interacting with the bots. Basically, as you see like when you say a /lg TM, but we'll add LGD M label, for you, that's what we program to teach about how to interact with github comments and, more importantly, we also maintaining the kubernetes testing infrastructure, which means we want to make sure your PR pass out a test. Your PR does not break like all the community's codebase see.

G

Let's try to go to a actual community are.

A

G

Works right. Okay, so, as you can see, this is the PR in kubernetes, slash, kubernetes. There's one contributor make some change in the sender APR. So if you scroll to the bottom of the PR, you will see a whole bunch list of our kind of tests. We are running. Basically, we want to make sure your PR, your PR pass our test and it's okay to merge.

G

As you can see, there are different kinds of tests. First, very obvious: there is like a failed test and passed tasks and there are tests labeled with required, and there are tests like now label with required.

G

So what's the difference here so are the required tests are the tasks you need to get to pass before your PR can be merged? Those are we something we call merge blocking tasks if we, if you don't get the pre submit to pass, your PR won't be able to merge these there's. Also tests like without a required label, for example, there's a GPU device plugging test. That test is also always been running against your PR, but it's not going to block your PR from merging because it's mmm most likely a test against a specific feature.

G

There's also test marked as skipped. Those are tests only run when you change certain part of the file. For example, the pool kubernetes cross Butte is the only going to run if you enter just like the cumin, a dispute files. If you want to like change how we build communities same as the GAE part, if we only change like GAE specific code, that has well be wrong. Okay,.

G

Let's go back to top, as you can see, for this PR there are two tests actually are failing. I mean one day when you make make a PR two cubanelle, you see you my like see the same issue. Oh geez, my the test is failing on my PR. What should I do don't be panic. First, you can click into the details link.

G

So this this tool is called groove inator. Basically, it shows the details of a single test run. You can see. The test has succeeded, 419 tests and have also have like three failed tests test suite, and it took about 50 minutes to go through the tests. Okay, how do I charge this like I know? My test is failing. If you scroll down a little bit, there's a little nice trapped and twisted hell, you like here's the test that has been failed.

G

For example, for this one looks like it's: some Hugh was just stackdriver logging agent. If you want to further digging to the test, you can click the artifacts link. Basically, those are all the artifacts we uploaded for your Canaries change. What we do is we for the for the canary for the kubernetes end-to-end test. We will.

G

We will clone your your PR from kubernetes app, a community's cluster use the community dispute from your PR, and we run our test collect all the result and, as you can see, there are the build log, which is basically a log file for the current rung of the task.

G

If we want to dig further into it, hitting the artifacts there there's a lot of j-unit on the score or food XML. Basically, those are test entries example.

G

Those are like the the test entry file generated by the our III framework. Basically, to tell you like, you have wrong, we have been running all these kind of tests and there's also you can see there is the Erie Runner / master folder. You can find all kind other like logs from the community subsystem, for example, darker darker locks, etcd logs and also like it has to relax. If you like, really want to find out, what's going wrong with my PR, what did I break.

G

From the top of your page, if you click on link of your PR, you will see all the priests image jobs has been associated with your PR. I can see. I got this about 13 jobs running and got two of them failing mm-hmm. At this point you might you might still asking. mmm Is this feeling like associate it's like really associate with my PR? What, if, like someone else, breaks something in other places I just at this time?

G

If you you can click into the puku at cdc link, this might take a while this this tool is called test grit. Basically, it's a front-end. Basically, this place are a collective of all. The test has been running. The same test has been running for across different PRS from here you can see. Each single row here means a entry of a engine test, and each test should be associated with a sig.

G

For example, if your test is failing like by stack stack, drivers should, should you know in just logs, if you like, really don't know how to debug this test, like what you did wrong with our PR there's the sick. Next to it, you can probably label the label up here as like sick instrumentation and find someone from tastic to take help. You take a look like why your test has been failed and if you click wind up the sales here it will, it will bring you back to a good Nader page.

G

mmm You see another another thing: I want to cover. Is me one sec.

G

There's this read has command. Basically, if you see your test has is failing and you feel like hey, this might be a flake.

E

G

We mentioned flake is something that it's not always failing. It's probably not the issue with your PR and you can do a slash retest here.

G

What will happen is the bots will receive this last retest command and it should trigger it. Should reach figure out a failing test and to let it run again?

G

This might take a little while we will go back to this PR a little nice page here that I want to show.

G

We have a command help page. Basically, you might be you might have. The question like I can like slash everything to the bot Oh. What how do we make sure the bot can understand my command right? So basically, this page lists you, like all the possible command. You can issue to talk with the bots. For example, the top one is slash approve and if you click the there's a little detailed description like say what this this plug-in does.

G

We also have a lot of fun plugins in the end like we have, you have like slash joke or a slash male if I do a retry this.

G

This is something we just implemented for fun by the way, as you can see, after I stretched, we test those two tests have been rich sugared again and we can wait for the reload and after a /mu, basically the bot will say hey. Let me give you a cat picture and hopefully have a good day yeah.

G

That's the that, hopefully the basic things you need to know if you have anything like curious like how we really run the engine test from the back. You know welcome to join the Siq testing d-type session, and we will have a more indeed in that discussed about, like the details lab what how do we run each the engine tests.

G

There should be everything on the cover. Any questions.

G

G

You mean the command page, so we have a thing called prowl dotted style. Oh, so that's a dashboard for where all of our test job, um both pre estimate and periodic like they are running and if you're clicking to the command help page, then you can find like our this list of comment. You can do product a style.

G

A

So next up, we have Zack from sick docks who's, going to explain how contributing Docs is a little different because you're going to do it.

F

Okay say your first slide.

F

Hey, can you hear me: okay, excellent, so hi I'm, Zach cor, listen, Zachary, Sarah on github and I'm here to talk about kubernetes documentation.

F

Anyone can contribute to Docs. I am one of the leads for cig documentation and when I say that anyone can contribute to Docs I mean it literally. Anyone can contribute to Docs. You do not have to be a member of the kubernetes organization in order to contribute to Docs, but contributing to documentation is a great path to org membership. If you are interested in becoming an org member, contributing to documentation totally counts, if you contribute substantive Lea at least five PRS to the documentation repository that kubernetes website is the documentation repository.

F

You contribute at least five substantive PRS I'll, totally sponsor you for membership in kubernetes in the kubernetes org. So this is how you find kubernetes Doc's. If it is on the website at kubernetes io, that's part of cig Doc's. Everything that is published to kubernetes do comes from kubernetes website. This is the github repository kubernetes website. So if it is published on kubernetes io at all, you can find it by coming to kubernetes website, and you can also find us on the kubernetes slack.

F

We're sick, Doc's super friendly, really easy to find us so I'm going to go over briefly what it means or how to work with Doc's and a little bit about why it's different from every other kubernetes repository. So, first and foremost, we use prowl, we use the kubernetes bot, so working with cig docks are working with the website. Repository is the approval process, for a pull request is identical to every other repository you'll, see an LG TM to denote technical accuracy and approve is the the command that allows pull request to merge.

F

So here is the main difference in working with kubernetes documentation, as opposed to any other kubernetes repository in order to make in order to update current docks branch from master I understand that in other kubernetes repositories, master is a changes to master, do not immediately go live in kubernetes website, pull requests that are merged to master immediately go live to the website. So if you are working on documentation for an upcoming release, for example, 1.11 then branch our branch, your pull request from release 1.11, for example- and that will not go immediately live.

F

So this is the key difference. We do this backwards from every other repository in kubernetes and there's a reason for this. The reason is we release for specific releases and we release continuously, so other repositories will you'll you'll, merge, two master and then particular commits will be cherry-picked into a release branch because we, because we release continuously because changes to the website are continuous and ongoing.

F

We sort of cut out that step and just merge directly to master, so any changes made to master will immediately be published, live so right now the current release for kubernetes is 110, so any commits that you make to master. We will merge those commits into the release, 110 branch, but that's work that we do on our side. So.

F

That's the the main difference is just make sure that you are branching from master if you, if you want to have a version specific commits for 1.10 or if you would notice a something that needs to change right now, merge make a PR and branch from master if you are working for a release, a head for release 1.11 if you're making a feature docs for 1.11 branch from release 1.11- and we are really good about monitoring PRS.

F

So if you make a mistake, don't worry we'll totally jump in and help we're pretty friendly and pretty easy to work with. So that's just the main difference to be aware of is that we branch differently. Our branching strategy is different from any other repo.

F

So just remember you do not have to go through a giant formal process. If you see something that needs to be changed on the website, please open the PR we were will we will happily walk you through the process. We have contributors from all over the world, people who are not part of the kubernetes org who are regular contributors. So anyone and please I, wish everyone would contribute to kubernetes Doc's thanks very much.