Slides and script for a talk Katherine "Kati" Michel (Twitter, GitHub) gave at DjangoCon 2017 called Get a Jumpstart on Collaboration and Code Review in GitHub.
The style of this transcript is heavily inspired by:
- Ana Balica's (Twitter, GitHub) transcript of her Humanizing among coders keynote for PyCon CZ 2016.
- Honza Javorek's (Twitter, GitHub) transcript of Anna Ossowski's (Twitter, GitHub) keynote Be(Come) A Mentor! Help Others Succeed! for PyCon CZ 2017.
Thank you!
- Get a Jumpstart on Collaboration and Code Review in GitHub
- Welcome
- Goal
- Announcing TacoFancy
- The One Sentence that Motivated Me to Start Using GitHub
- My First Pull Request
- DjangoCon US Website as Example Project
- What are Git and GitHub?
- GitHub: Social Network
- GitHub: Repositories
- Local Development Environment
- Collaboration and Code Review Best Practice Workflow
- Working on a File in GitHub
- Branches
- How to Create a Branch
- Overview
- Section 1
- The Two Collaborative Development Models
- The Two Types of Accounts
- Write Permission
- Write Permission and Collaboration Examples
- How to Fork a Repo
- Forked Repo
- Section 2
- Fork and Pull Model
- Shared Repository Model
- Local Dev Environment
- Cloning
- Changing Directory
- GitHub Repo Versus Local Directory
- Verifying Branch
- Creating a New Branch
- Working on a File Locally
- Adding and Committing
- Pushing
- New Branch
- Submit a Pull Request
- Section 3
- Pull Request Review Process
- Pull Request Command Line
- Pull Request Review Options
- Pull Request Branches
- Pull Request Review
- Merging
- Section 4
- Documentation
- Safety
- Triaging
- Sandboxing
- Go For It!
- Thank You
|
|
By Katherine "Kati" Michel | |
|
|
Welcome, everyone. I'm Kati Michel. I'm thrilled to have the opportunity to teach you what I've learned as the DjangoCon US Website Chair. | |
|
|
| |
|
|
| |
|
|
One sentence in the project information that had a huge impact on me: "Are You New to Github But Want to Contribute?" | |
|
|
That was me. I became very determined to contribute and submitted my first pull request there. | |
|
|
I kept using Git and GitHub and getting better at it. I eventually became a DjangoCon US website contributor in 2016, then became the Website Chair and maintainer in 2017.
| |
|
|
GitHub is a website built on the version control software Git. | |
|
|
GitHub is a social network. You can:
| |
|
|
But the really important part of GitHub is that users can store and work on code together in repositories | |
|
|
(Animation) For example, if you go to the DjangoCon US organization account you will see a list of repos and at the top is the DjangoCon US website repo. | |
|
|
(Animation) If you click on the hyperlink, it will open up the repo and you will see the folders and files filled with the website code and you can look through. | |
|
|
When we are working on code, we can't do everything in the GitHub website.
| |
|
|
(Animation)
| |
|
|
(Animation)
I will elaborate on this process later. | |
|
|
There is a concept that I think is very important. In order to be able to increase your level of responsibility, we need to have the freedom to switch between multiple tasks.
| |
|
|
When I first started using GitHub, I would go into my own GitHub repo, click on a file, click on the pencil icon to open the file, make a change, and save it. This is fine, but imagine if there were multiple people all working on a repo and all of them were going into files and making changes and saving them. It wouldn't be very practical. For instance, how would you give feedback?
| |
|
|
We need to use branches instead. Branches
When you create a repo, by default you are working within a branch named master. | |
|
|
(Animation) Say for instance that you want to make a change in the branch, you can make a copy of the entire master branch and give it a different name. Now there are two branches, in the same repo, the master branch and a feature branch. | |
|
|
(Animation) You can create an unlimited number of branches and you can switch in between them to work on them. | |
|
|
(Animation) At some point, when the feature branch author thinks it's done, a pull request will be submitted and the feature branch will become a pull request branch. | |
|
|
(Animation) If the changes are accepted, they will be merged into the master branch. The master branch will be like before, except with the changes from the branch. But both feature branches (a.k.a. topic branches) and pull request branches are examples of branches. We can work on them in much the same way. | |
|
|
Let's go back to the screenshot of editing a file in GitHub. | |
|
|
(Animation) There is a radial button you can choose to indicate you want to create a new branch. There is also a place to give the branch a new name. When you click to save the changes, they will not save in the current file. Instead, a new branch will be created. You can also create and work on branches through the command line in your local development environment, which I will show you later. | |
|
|
| |
|
|
| |
|
|
A Collaborative Development Model is a fancy term for how users contribute to a repo. There are two different models.
| |
|
|
There are two types of accounts
| |
|
|
When a user has write permission to a repo, it means they can make changes directly inside of the repo. | |
|
|
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 about the word shared.
| |
|
|
(Animation) The “Fork and Pull” Model is typically used in user account repos. For example, when I first came across the DjangoCon US website repo, I wanted to contribute, but I was not a maintainer, so I didn't have write permission. So I made a copy (a.k.a. fork) of the DjangoCon US website repo in my user account, which I have write permission to, made a change, and submitted a pull request to the Django US website repo. | |
|
|
We've gone to the DjangoCon US website repo.
| |
|
|
(Animation) There will be a message notifying you that it is being forked. | |
|
|
| |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
| |
|
|
I've made a couple of diagrams that I hope will give you an idea of what the process is for working locally for each collaborative development model. | |
|
|
(Animation)
| |
|
|
(Animation)
Git will track some details about the project, for instance, where we cloned our code from. In relation to the clone, the GitHub repo we cloned from is now a remote repo and Git will assign the name "origin" to it. We can use the name origin in the command line to refer to the repo so we can push and pull changes back and forth between the local development environment and the GitHub repo. | |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
Here's what it looks like when we use the "Shared Repository" Model | |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
What I'm going to show you now is a generic process that you can use for a shared repository or a fork. You will clone the repo you have write permission to. Let's go back to the screenshot of my local development environment.
| |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
(Animation)
| |
|
|
There will now be a new branch in the repo that is your origin and a message telling you it's there. If you click on the branch tab you can choose the name of the branch to switch to the new branch. | |
|
|
(Animation) You can toggle back and forth between the branches by clicking on the branches in the branches tab. | |
|
|
Go to the repo you want your pull request to be merged into, in this case, the DjangoCon US website repo. There will also be a message here telling you about the branch and suggesting that you submit a pull request, even if the branch is in a fork, because GitHub will detect it. Click on the "Compare & pull request" button. | |
|
|
(Animation)
| |
|
|
| |
|
|
| |
|
|
(Animation) Underneath that will be info about how to merge the pull request.
| |
|
|
When you click on that link, it will open up a set of instructions for how to review and merge the pull request in your local development environment. The instructions will be different depending on whether the pull request was submitted from within the shared repository or from a forked repo. I will go over that in a minute. | |
|
|
But first, let's go over the options for what you can do when you review a pull request. The first two options involve clicking the merge button in GitHub without running the code locally
| |
|
|
The other options involve fetching the pull request into your locally development environment and running the code there. If a change does not need to be made, you can
If a change needs to be made, you can
| |
|
|
This is why the pull request instructions are different.
| |
|
|
$ git fetch origin
$ git checkout -b <local-branch-name> origin/<branch-name>
$ git merge master$ git push origin <branch-name>
$ git checkout -b <local-branch-name> master
$ git pull https://github.com/<user-name>/<repo-name> <branch-name>$ git push https://github.com/<user-name>/<repo-name> <branch-name> | |
|
|
This piece of code is for merging a pull request locally and pushing 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. $ git checkout master
$ git merge --no-ff <local-branch-name>
$ git push origin master | |
|
|
| |
|
|
My first recommendation is that you go to the Useful Resources Section, follow the links to the DjangoCon US website repo documentation, read it, and make the documentations in your own projects equally welcoming and positive. | |
|
|
My second recommendation is that if you have the authority, go into a repo’s Settings, click the Branches tab
| |
|
|
My third recommendation is that when you are looking for a project to contribute to
| |
|
|
My fourth recommendation is that you
| |
|
|
My last but not least recommendation is that you become a contributor to the DjangoCon US website next year
| |
|
|
Feel free to contact me. Useful Resources: https://git.io/v5fRh
|
GitHub
Getting Set Up
Git Official
Glossaries and Cheatsheets
GitHub Help and Training
GitHub Try
GitHub Learning Resources
GitHub Open Source Guides
Collaborative Development Models and Permission Levels
- About Collaborative Development Models
- Types of Collaborative Development Models
- Permission Levels for an Organization
- Repository Permission Levels for an Organization
Documentation
- DjangoCon US Website README.md
- DjangoCon US Website LICENSE
- DjangoCon US Website CODE_OF_CONDUCT.md
- DjangoCon US Website CONTRIBUTING.md
Recovering a Deleted Branch
Go to the home directory
$ cdChange directory
$ cd <folder-name>List the folders and files in a directory
$ lsMove back a directory
$ cd ..$ git clone <repo-url>
$ cd <repo-name>
$ git branch
$ git checkout -b <branch-name>
$ git add .
$ git commit -m "Your note"
$ git push origin <branch-name>$ git clone https://github.com/djangocon/2017.djangocon.us
or
$ git clone https://github.com/KatherineMichel/2017.djangocon.us
$ cd 2017.djangocon.us
$ git branch
$ git checkout -b example-branch
$ git add .
$ git commit -m "Creating branch and updating"
$ git push origin example-branch$ git fetch origin
$ git checkout -b <branch-name> origin/<branch-name>
$ git merge master$ git push origin <branch-name> $ git checkout -b <branch-name> master
$ git pull https://github.com/<user-name>/<repo-name> <branch-name>$ git push https://github.com/<user-name>/<repo-name> <branch-name>$ git checkout master
$ git merge --no-ff <branch-name>
$ git push origin master© 2017 to Present Katherine Michel. All Rights Reserved.