Get a Jumpstart on Collaboration and Code Review in GitHub
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Part Number | 22 | |
| Number of Parts | 48 | |
| Author | ||
| Contributors | ||
| License | CC Attribution - ShareAlike 3.0 Unported: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this | |
| Identifiers | 10.5446/33190 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
DjangoCon US 201722 / 48
2
5
6
14
16
23
26
30
31
32
34
39
43
48
00:00
CollaborationismMachine codeProcess (computing)Software repositorySheaf (mathematics)WebsiteHome pageElectronic data interchangeLine (geometry)Revision controlSoftwareControl flowComputer networkSelf-organizationElectronic mailing listIntegrated development environmentCloningTask (computing)Computer iconComputer fileBranch (computer science)Type theoryLocal ringSoftware maintenanceEndliche ModelltheorieData modelWritingMathematicsWindowDependent and independent variablesTerm (mathematics)MultiplicationCollaborationismNeuroinformatikLevel (video gaming)Different (Kate Ryan album)Instance (computer science)Projective planeLocal ringWeb browserComputer iconTask (computing)Process (computing)Branch (computer science)Shared memoryIntegrated development environmentDefault (computer science)Software testingHyperlinkUniform resource locatorComputer fileTouchscreenPoint (geometry)Multiplication signWebsiteSoftwareDiagramMachine codeLink (knot theory)Revision controlOpen sourceArithmetic meanInformationSlide ruleVideoconferencingMessage passingUser profileBitSelf-organizationSoftware repositoryEndliche ModelltheorieWritingSoftware maintenanceOcean currentSoftware developerType theoryGreatest elementElectronic mailing listWordForm (programming)FeedbackGenderEntire functionContrast (vision)NumberTwitterAuthorizationCloningOpen setMultilaterationMereologyMetropolitan area networkRight angleComputer animation
09:52
CollaborationismIntegrated development environmentLocal ringCloningSoftware repositorySheaf (mathematics)WebsiteData modelDirectory serviceBranch (computer science)Computer fileType theorySoftware maintenanceProcess (computing)Line (geometry)Data miningComputer configurationMachine codeWeb browserWritingIntegrated development environmentWeb browserCollaborationismText editorRevision controlLocal ringUniform resource locatorContent (media)Type theoryEndliche ModelltheorieBranch (computer science)WindowThermal conductivitySoftware developerProcess (computing)CloningMathematicsInstance (computer science)Theory of relativityMereologyDirectory serviceSocial classAuthorizationPerturbation theoryProjective planeSoftware repositoryMultiplication signVideo gameDiagramInformationPoint (geometry)Computer fileLink (knot theory)Set (mathematics)Default (computer science)Machine codeComputer configurationDifferent (Kate Ryan album)PlotterSoftware maintenanceDescriptive statisticsHyperlinkWebsiteMessage passingPairwise comparisonRule of inferenceCuboidSummierbarkeitCASE <Informatik>WritingRemote procedure callEmailComputer animation
19:44
Software repositoryShared memoryBranch (computer science)Branch (computer science)Revision controlMathematicsContent (media)Software maintenanceWeb pageSoftware repositoryPoint (geometry)CASE <Informatik>Machine codeComputer animation
21:20
Branch (computer science)Sheaf (mathematics)CollaborationismType theoryIntegrated development environmentCloningLocal ringSoftware repositorySoftware maintenanceContent delivery networkMachine codeCone penetration testWebsiteLevel (video gaming)Local GroupTwitterSheaf (mathematics)Branch (computer science)WebsiteMathematicsLink (knot theory)Projective planeSet (mathematics)Group actionLevel (video gaming)Software bugSoftware repositoryOnline helpInstance (computer science)Machine codeCollaborationismMultiplication signComputer animation
23:39
XML
Transcript: English(auto-generated)
00:16
Welcome, everyone. I am so thrilled to have the opportunity to share with you what I've
00:22
learned as the DjangoCon US website chair. 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
00:43
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
01:03
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
01:21
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,
01:46
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
02:02
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.
02:21
You can make a user profile, follow people, follow their activity in your news feed, 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
02:44
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
03:05
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
03:20
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
03:41
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
04:02
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
04:23
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
04:44
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
05:03
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. Their best practice, and any GitHub user can use them. For instance, when you first create a repo, by default, you're working in a branch called master. Say, for instance, you want
05:25
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. You can do this an unlimited number of times, and you can switch between them to work on them. At some point, the feature branch author
05:45
may think that their branch is done, and they submit a pull request, and the feature branch becomes a pull request branch. 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
06:01
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. Let's go back to a screenshot of editing a file in GitHub. At the bottom, before you click save, there's a radial button that you can click to indicate
06:24
you want to create a new branch, and you can give it a new name. 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.
06:40
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 cloned from, and submit a pull request to the DjangoCon US website repo. Then we're going to review the two different types
07:01
of pull requests as a DjangoCon US website repo maintainer, and then I'll have a few recommendations. 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
07:22
shared repository model and the fork and pull model. 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. There are two types of accounts, organization accounts such as DjangoCon organization, and user accounts such as my own personal
07:45
account. Right permission is really important in all this. When a user has right permission to a repo, it means that they can make changes directly inside of the repo. Let's look at a couple examples of right permission and collaboration. First we'll
08:04
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. For example, this year I became a maintainer of the DjangoCon US website, so I was given right permission
08:21
to the DjangoCon US repo, which is a shared repository. Along with the other maintainers who also have right permission, I can make changes directly inside of the repo. The fork and 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
08:45
I wasn't a maintainer, so I didn't have right permission. 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. Then I could make a change to it, and I could submit a request, a pull
09:00
request, to the DjangoCon US website repo. 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. GitHub will automatically fork the repo into our user account. There will be a message
09:25
notifying us that it has been forked. The fork message will basically lead us back to our user account. In the list of repos, there will now be an entry for the fork. It will say where it was forked from. If you click on the hyperlink, it will open
09:41
the repo, and something useful to notice is that the forked repo URL will have your user account name in it, because it's a copy under your user account. The fork is an exact copy of the original repo at the time it was forked. You can basically make
10:01
any change to it, even delete it, and the original repo is not going to be affected. 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. I made a couple of diagrams that I hope will give you an idea of what the process
10:24
is like, depending on which collaborative development model you're using. In the fork and pull model, you fork the repo, and you clone the fork. It's useful to know at this point that Git will track some information about your project. For instance, it will
10:41
know where your code was cloned from. 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. 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
11:05
environment and the GitHub repo. We make our changes, and we push the changes back to the fork, and we submit our pull request. 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,
11:22
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. Now I'm going to show you a generic process that you can
11:42
use regardless of which collaborative development model you're using. We are simply cloning whichever repo you have write permission to. 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
12:04
in. At the top of my command line and in front of my command prompt, it has the name of my home directory. I'm going to type the command git clone, and you can see the little commands at the top. Git clone, I'll type that into the command line, and then
12:22
I'll copy and paste the URL from the browser for the repo, and then hit enter. 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.
12:41
I now have a copy of the code on GitHub and also a copy of my local development environment. I need to change directory into the folder in my command line so that I can work there, so I type cd2017.jangocon.us, which is the name of the folder. I've also clicked
13:02
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. 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
13:25
the files and see the corresponding files, but the files on GitHub are going to render differently because they're rendered in the browser, whereas the files locally are raw files. Then you can use the command git branch to verify which branch you're checked
13:41
out on, and initially you will be on the default branch, which in this case is master. Then we create and check out, which means switch to a feature branch, and we're going to call it example branch. We want to branch off of the branch that we intend our changes to be merged into. This is something really important to know. When you switch
14:04
branches in your local development environment, the files in the folder switch to the files of the branch. 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,
14:21
you'll notice that they're different. Then we can open whatever file we want to change in a text editor and make our change and save it. Then we need to add and commit our change to git 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
14:42
that's more clear than this. Then push the new branch, example branch, to GitHub to our origin, the repo that we clone from that we have write permission to. Now if we go back to origin, there will be a branch in our repo, and there will
15:00
be a message telling us that it's there. 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. That's a way that you can look at different branches by toggling back and forth between the branches and the branch tab.
15:22
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. We're going to go to the DjangoCon US website repo, if we're not there already. There will also be a message there telling us about the branch if it was through a fork, because GitHub will detect it.
15:45
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.
16:01
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. Double check your changes and click create pull request. Now we're going to review the two different types of pull requests as a DjangoCon US website
16:23
repo maintainer. 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. That notification will lead them to the pull
16:43
request tab in their browser. 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
17:01
changes are. 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. 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
17:25
environment. These instructions will 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. First, let's go over what the options are of what you can do when you review a pull
17:42
request. 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
18:00
just click merge. Or you might look at that and see that there's just a small change that needs to be made. 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
18:23
environment and running the code there. Say, for instance, you do that and you're happy with it and no 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,
18:44
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
19:05
live to the branch on GitHub. 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 .git in your local development environment.
19:26
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. Branches made through a fork have to be pulled individually into our local
19:43
development environment. 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
20:07
pull request, up to the point that the pull request is merged. For a shared repository pull request, we use the command get fetch origin to fetch the updates into the .git folder. We create and check out to a new local branch, which we give a name to, and
20:25
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
20:42
made since the pull request was made. 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
21:05
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 fork branch if we have been given permission to edit the pull request. This piece of code would be if we decide to merge a pull
21:24
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. I want to just give you a few quick recommendations.
21:42
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.
22:00
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 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
22:26
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. That can help you to level up over time.
22:44
My fourth recommendation is that you practice your skills and workflow. Don't be afraid to delete, 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
23:01
create a repo and submit pull requests to yourself and practice that way. 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. Let us know if you're interested.
23:25
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.