Get a Jumpstart on Collaboration and Code Review in GitHub by Katherine Michel

Welcome everyone. I am so thrilled to have the opportunity to share with you what I've learned as the DjangoCon US website share. I want to teach all of you a process that will get you started collaborating and doing code review as quickly as possible. I'm going to show you a lot of screenshots and diagrams because I want you to understand what the process should look like. But don't worry if you miss anything because at the end of my talk there will be A link to some useful resources, including all of the commands I'll be showing you, and my slides and a video of my talk will be online later. So firstly, I want to tell you how I got started with open source contribution because it's a fun story and I think it will show you that there are

unique ways to get involved. So back in April of 2013, I signed up for GitHub and I didn't know how to get started. So my account sat unused for about seven months, and one day I was looking at Twitter And this man named Dan Sinker had made this incredibly delicious taco meal. And he decided to go on GitHub and create a project to collaborate in sharing taco recipes. So I went to the project information and there was one sentence that had a really drastic impact on me and it was, are you new to GitHub but want to contribute? Well, that was me, and I became extremely determined to contribute to that project, and I did. I submitted my first pull request there

and it was a little bit addictive to be honest with you So I kept using Git and GitHub and I kept getting better at it, and eventually I started to contribute to the DjangoCon US website. And this year I became website chair and a maintainer, and I'm going to use the DjangoCon US website as an example throughout my talk. So, firstly, let's be clear about what GitHub and Git are. GitHub is a website built on the version control system Git. GitHub is a social network. You can make a user profile, follow people, follow their activity in your newsfeed, and find interesting projects. But the most important part of GitHub is that users can store and work on code together in repositories.

For example, if you go to the DjangoCon US organization account, you'll see a list of repos. And at the top of this particular screenshot is the DjangoCon US website repo So if you click on the hyperlink, it will open up the repo and you can see the files and the folders, and you can look through the website code for the website. But when we are working on code, we can't do everything in a website. For example, you might want to make a copy of the DjangoCon US website code in your local development environment on your computer. and install whatever software is necessary and run the code in your local browser. For instance, if you want to add a feature or test a pull request branch. This is where Git is really useful.

It's installed in your local development environment and you can use it in your command line. And Git can make a snapshot of your project at any point in time, and you can even revert back to that snapshot if you need to. So on the screen is a screenshot of my local development environment, and in the background I have GitHub open in the browser, and in front of that I have my local folder window and my command line. And I could go to the repo in GitHub and I can take the web address from the GitHub repo and copy and paste it into a command in the command line and I can use that to make a copy of the repo. in my local development environment, which is called cloning. So I can then make changes to the code and push the changes back to GitHub.

And meanwhile, other people will be doing the same thing on their computers. And I'm going to go much more into detail about that process in a few minutes. But I want to tell you a concept that I think is really, really important that I don't hear people talk about. As your level of responsibility increases, you need to be able to switch between multiple tasks. For instance, you might want to keep your main code base up to date. create one or more features and do code review and you need to switch between these. When I first started using GitHub, it was pretty common that I might go into a repo in my own personal account and click on the pencil icon and open a file and make a change and click save. Well this is fine but imagine if you're working with multiple other people and you're all doing that.

It's not very practical. For instance, how would you give feedback if you're all just making changes? So there's actually a way to make changes that enables you to switch between multiple tasks the way that you need to to collaborate and do code review, and that is by using branches. They're best practice and any GitHub user can use them. So for instance, when you first create a repo by default, you're working in a branch called Master. So say for instance you want to make a change to the master branch, you can make a copy of the entire master branch and give it a new name. And now there are two branches in the same repo, the master branch and a feature branch. And you can do this an unlimited number of times, and you can switch between them to work on them.

So at some point the feature branch author may think that their branch is done and they submit a pull request and the the feature branch becomes a pull request branch. And if the changes are accepted, they'll be merged into the master branch. So the master branch will be like it was before except it will now have the changes in it. But something interesting to know is that feature branches and pull request branches are both just examples of branches and they can be worked on in much the same way. So let's go back to a screenshot of editing a file in GitHub. At the bottom, before you click save, there's a radio button that you can click to indicate you want to create a new branch And you can give it a new name. So now when you click to save the changes, they won't save in the current file.

You'll have a new branch. You can also create and work on branches through the command line, and I'm going to show you that process later. So in this talk, we're going to determine which collaboration approach to use. We're going to clone a repo into our local development environment, create a feature branch, make a change, push the branch to the GitHub repo we clone from. And submit a pull request to the DjangoCon US website repo. And then we're going to review the two different types of pull requests as a DjangoCon US website repo maintainer, and then I'll have a few recommendations. So let's determine which collaboration approach to use. There is a fancy term that actually just means How people work on software together.

It's collaborative development model. And there are two different models. There's the shared repository model and the fork and pull model. And the two different models typically correspond to two different account types. And which model you use depends on whether or not you have right permission to the repo. So there are two types of accounts, organization accounts such as DjangoCon organization, and user accounts such as my own personal account. And write permission is really important in all this. When a user has write permission to a repo, it means that they can make changes directly inside of the repo. So let's look at a couple examples of write permission and collaboration.

So first we'll look at the shared repository model A shared repository is typically found in an organization account, which makes sense when you think of the word shared. So for example, this year I became a maintainer of the DjangoCon US website, so I was given right permission. To the DjangoCon US repo, which is a shared repository. So along with the other maintainers who also have write permission, I can make changes directly inside of the repo. The foregan pull model in contrast is typically found in user account repos. For example, when I first came across the DjangoCon US website repo, I wanted to contribute, but I wasn't a maintainer, so I didn't have right permission. So I needed to make a copy of the repo, which is called a fork, into my own user account

which I have right permission to. So then I could make a change to it and I could submit a request, a pull request to the DjangoCon US website repo. So let's look at how we fork a repo. For example, if we go to the DjangoCon US website repo, we can click the fork button. Or we can try to edit a file in a GitHub repo that we do not have right permission to, and GitHub will automatically fork the repo into our user account. And there will be a message notifying us that it has been forked. And the fork message will basically lead us back to our user account. And in the list of repos, there will now be an entry for the fork. It will say where it was forked from. And if you click on the hyperlink, it will open the repo.

And something useful to notice is that The repo you bar the forked repo URL will have your user account name in it because it's a copy under your user account. So the fork is an exact copy of the original repo at the time it was forked. And you can basically make any change to it, even delete it, and the original repo is not going to be affected So now we're going to clone a repo into our local development environment, create a feature branch, make a change, push the branch back to GitHub, and submit a pull request. So I made a couple of diagrams that I hope will give you an idea of what the process is like depending on which collaborative development model you're using.

So in the fork and pull model, you fork the repo. And you clone the fork, and it's useful to know at this point that Git will track some information about your project. For instance, it will know where your code was cloned from. So in relation to the clone in your local development environment, the GitHub repo we clone from is called a remote repo, and Git will call it origin. And we can now use the name origin in our command line to refer to the remote repo so we can push and pull changes back and forth between the local development environment and the GitHub repo. So we make our changes and we push the changes back to the fork and we submit our pull request. So

this is what it looks like when we use the shared repository model. We don't need a fork now because we have write permission. So we're simply cloning the shared repository. And the shared repository on GitHub is now our remote origin And we make our changes, we push the changes back to the shared repository, and we submit the pull request. So now I'm going to show you a generic process that you can use regardless of which collaborative development model you're using, we are simply cloning whichever repo you have right permission to. So let's go back to the screenshot of my local development environment and I can see that I'm working in my home directory and this matters because

The repo is going to be cloned into the directory we're working in. So at the top of my command line and in front of my command prompt it has the name of my home directory. So I'm going to type the command git clone and you can see the the little commands at the top. Git clone, I'll type that into the command line, and then I'll copy and paste the URL from the browser for the repo. And then hit hit enter. So there will now be a folder in my home directory by the same name as the GitHub repo, which is 2017. jangoCon. us. And it's going to be filled with the contents of the repo. So I now have a copy of the code on GitHub and also a copy in my local development environment.

So I need to change directory into the folder in my command line so that I can work there. So I type cd2 thousand seventeen. jangocon. us, which is the name of the folder. So I've also clicked on the folder manually in the folder window so I can see the contents visually. But I can see that I'm working in the new folder. because the name of it is at the top of my command line and in front of the prompt. And hypothetically, if I were to open up the GitHub repo and open up the folder window in front of it, I would be able to compare compare the files and see the corresponding files. But the files on GitHub are are going to render differently because they're rendered in the browser, whereas

The files locally are raw files. So then you can use the command git branch to verify which branch you're checked out on. And initially you will be on the default branch, which in this case is master. So then we create and checkout, which means switch to a feature branch, and we're going to call it example branch. And we want to branch off of the branch that we intend our changes to be merged into. And this is something really important to know. When you switch branches in your local development environment, the folders in the, the files in the folder switch to the files of the branch. And you might not notice it at first because when you create a branch it'll be an exact copy of another one, but if you make a change and switch to another branch, you'll notice that they're different.

So then we can open whatever file we want to change in a text editor and make our change and save it. And then we need to add and commit our change to To get version control. And we're going to make a message. By the way, make sure your change works, the change you're making to the code, and probably make a message that's more clear than this. And then push the new branch, example branch, to GitHub to our origin, the repo that we clone from that we have write permission to. So now if we go back to origin, there will be a branch in our repo, and there will be a message telling us that it's there. And if you click on the branch tab, you can choose the name of the branch. And switch to the new branch, and you can actually see the changes you've made.

And that's a way that you can look at different branches by toggling back and forth between the branches and the branch tab So now to submit the pull request, if you're ready to do that, we want to go to the repo that you want your changes to be merged into. So we're going to go to the DjangoCon US website repo. if we're not there already. So there will also be a message there telling us about the branch if it was through a fork because GitHub will detect it. So we want to click on the compare and pull request button and make sure the base branch is the branch you want your changes merged into and make sure the compare branch is your branch. and create a title and perhaps a description for the pull request.

If your pull request is through a fork, there will be a box checked by default That will give maintainers the ability to edit the pull request. So double check your changes and click pull request, create pull request. So now we're going to review the two different types of pull requests as a DjangoCon US website repo maintainer. So when the pull request has been submitted, people who are maintainers for DjangoCon US Website repo will receive a notification either by browser or by email letting them know that there's a pull request. And that notification will lead them to the pull request tab in the browser. So then they want to look over the pull request information.

There will be the title and description and there will be a little hyperlink that says files changed. And they can click on that to literally see a summary of what the changes are. So underneath that there will be information about how to merge the pull request. There will be a merge button that you can click to merge in the browser, or there will be a link that says command line instructions. So when you click on that link, it will open up a set of instructions for how to review and merge the pull request in the local development environment. These instructions will be different. be different depending on whether the pull request was submitted through a fork or through a shared repository, which I'm going to explain in a minute.

But first, let's go over what the options are of what you can do when you review a pull request. So the first two options would involve just clicking the merge button in GitHub without running the code locally. For example, you might look at the pull request file and see that you don't need to make any change to what has been submitted, and you might just click merge Or you might look at that and see that there's just a small change that needs to be made. And similarly to how we edited a file earlier, you might just go into the pull request file and make a small change and click merge. The other options involve fetching the pull request branch into your local development environment and running the code there.

So say for instance you do that and you're happy with it and no change change needs to be made. You can go back to the browser and just click merge Or if a change needs to be made, there are a few different things that can happen. You can ask the pull request author to make a change to the pull request. Or you yourself can make a change to the pull request branch. You could then push the additional change to the pull request branch on GitHub. Or you can merge the branch with the branch it's intended to be merged with, and you can do that locally, and then push that live to the branch on GitHub. So this is why the pull request instructions are different.

As a DjangoCon US website maintainer, you're able to fetch updates From the DjangoCon US website repo into a hidden folder named. get in your local development environment The updates will include the branches made directly to the DjangoCon US website repo. They will not include branches made through a fork. Because those came from outside of the origin. So branches made through a fork have to be pulled individually into our local development environment. So I want to point out something, and that is that even though these instructions, the instructions from the pull request page for fetching the branch locally, Even though they say that they're for a pull request, they can actually be used by any maintainer to work on a branch that they have right

permission to. If a pull request has already been made, the the changes will simply be added to the pull request up to the point that the pull request is merged. So for a shared repository pull request, we use the command git fetch origin. to fetch the updates into the. get folder. We create and check out to a new local branch which we gave it give a name to, and we insert the pull request branch contents from the. git folder into the new local branch. by referring to the branch as origin forward slash in the branch name. We can merge master into that feature branch to make sure it's up to date in case there were any changes made since the pull request was made. And then similarly to before

when we had a branch and we made a change and we added and committed the changes to version control, if you do that. To this pull request branch, you can push the additional commits to the branch on GitHub. For a pull request submitted through a fork, We create a new branch off master and pull in the contents of the pull request branch from the fork. If we make a change, we can also push the additional change to the forked to the fork branch if we have been given permission to edit the pull request. So this piece of code would be if we decide to merge a pull request locally and push to the master branch. You are checking out to the master branch, merging the feature branch into the master branch, then pushing the change to the live master branch on GitHub.

So I want to just give you a few quick recommendations. My first recommendation is that you go to the Useful Resources section and follow the links to the DjangoCon US website repo documentation. And read it and make your documentation in your own projects as welcoming and positive as ours is. We have really great documentation. My second recommendation is that if you have the authority, go into a repo settings and click on the branches tab and protect your main branch or main branches so that they can't be deleted accidentally. For example, your master branch. My third recommendation is that when you're looking for a project to contribute to, you can search by tag to find projects that use triaging.

Triaging is where issues are sorted by difficulty level. For instance, as both a collaborator or a code reviewer, you can actually cherry-pick issues and pull requests that fit your skill level And that can help you to level up over time. And my fourth recommendation is that you practice your skills and workflow. Don't be afraid to delete your for instance your folder locally if you have to start over if that's what you need to do You can also use your own account as a sandbox. You can actually create a repo and submit pull requests to yourself and practice that way. And my last but definitely not least recommendation is that you become a contributor to the DjangoCon

US website next year We have a diverse group of contributors of all skill levels and we're always looking for more contributors. So let us know if you're interested. And thank you everybody. Feel free to contact me, check out the useful resources, and I'm going to take questions in the hallway later. Thank you.