Get a Jumpstart on Collaboration and Code Review in GitHub- PyLadies Remote Talk

Table of Contents

• About
• GitHub and Git Installation Instructions
• Important Webcast Links
• Additional PyLadies Resources
• Slides and Script Table of Contents
• Slides and Script
• Useful Resources
  • Links
  • Bash
  • Avoiding Cloning Conflicts
  • Local Development
  • Review Shared Repo Pull Request
  • Review Forked Repo Pull Request
  • Merge Pull Request Locally and Push to Master Branch
  • Alternatively, Fetch Individual Pull Request
  • Delete a Branch
  • Common Branch Commands
  • Common Add and Commit Commands
  • Common Push and Pull Commands
  • Fetch and Merge Versus Pull
  • Adding a Remote Upstream and Syncing a Fork
  • Keeping Branches Up-to-Date
• Attribution
• Contact Kati
• Copyright

---

About

Slides and script for a talk Katherine "Kati" Michel (Twitter, GitHub) gave for PyLadies Remote, Saturday, August 26, 2017 at 11:00 a.m. CST.

• Original slide deck
• Video recording

🔝 _{back to top}

---

GitHub and Git Installation Instructions

• GitHub and Git Installation Instructions

🔝 _{back to top}

---

Important Webcast Links

• Eventbrite Link (expired)
• PyLadies Remote tlk.io Chat Forum
• DjangoCon GitHub Repo
• DjangoCon U.S. 2017 Website Repo GitHub
• Collaboration and Code Review Classroom GitHub

🔝 _{back to top}

---

Additional PyLadies Resources

PyLadies and PyLadies Remote

• PyLadies, PyLadies GitHub, and PyLadies Slack
• PyLadies Remote Twitter
• PyLadies Remote Website GitHub
• PyLadies Remote YouTube Webcasts

🔝 _{back to top}

---

Slides and Script Table of Contents

• Get a Jumpstart on Collaboration and Code Review in GitHub
• Welcome
• About Me
• Goal
• I Don’t Want You to Be Like Me!
• Understanding the Process and Hands On Practice
• Resources
• 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?
• Social Network
• Repositories
• Local Development Environment Example
• 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
• Examples of What Write Permission Will Allow You to Do
• Why We Need Write Permission
• Write Permission and Collaboration Examples
• How to Fork a Repo
• Forked Repo
• Interesting Thing #1: Opposites
• Interesting Thing #2: User Account Shared Repo Disadvantage
• Interesting Thing #3: Write Permission Examples
• Interesting Thing #4: Inactive Pull Requests
• Section 2
• Fork and Pull Model
• Shared Repository Model
• Bash Commands
• Local Development 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
• Tidy Up
• Advanced Topics
• Section 4
• Practical Commands
• GitHub Flow
• Another Workflow
• Learn More About Workflow
• Section 5
• Getting to 10x Results
• Communication Strategy
• Documentation
• Templates
• Communication Forums
• Section 6
• Code Safety
• Additional Safety Considerations
• Productivity Helpers
• Triaging
• Sandboxing
• Go For It!
• Section 7
• Simulation Exercise
• Prerequisites for Getting Started
• Getting Help
• Debunking Myths
• Thank You

🔝 _{back to top}

---

Slides and Script

The script is a general outline and varies somewhat from what was said during the webcast.

	Get a Jumpstart on Collaboration and Code Review in GitHub By Katherine "Kati" Michel
	Welcome 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.
	About Me DjangoCon Website Chair DEFNA (Django Events Foundation North America) Board Member DjangoCon Europe Website Committee Member Project Manager Web Designer and Developer
	Goal I want to teach you a process that will get you started collaborating and doing code review as quickly as possible. For one thing, there is more male participation than female. I want to see female participation increase. More women should be maintainers.
	I Don’t Want You to Be Like Me! I wish I had taken on more responsibility sooner For example, I thought that being a repo maintainer was for other people, and how it is done was a mystery to me Once I became a maintainer, I learned as I went along. I made mistakes in front of people. I sometimes had to ask senior developers to explain things to me or spend time researching online. Fortunately, I have been a maintainer in an extremely supportive environment. I want all of you to benefit from my trial and error.
	Understanding the Process and Hands On Practice This is a real process that you can learn and use. I'm going to be showing you a lot of screenshots and diagrams, because I want you to understand what the process looks like. At the end of my presentation, there will be an opportunity to practice reviewing a pull request in a no-pressure environment. I think this highly valuable, because if you learn the process first, you can be more confident to seek opportunities to collaborate and maintain.
	Resources If you miss anything during my talk, my slides and a replay of my talk will be online later On my last slide, there will be a link to Useful Resources where you will find documentation and all of the commands I will be showing you today. If you choose to take part in the simulation exercise, your repo will remain there indefinitely so that you can practice and experiment in the future. You are welcome to contact me if you have any questions
	Announcing TacoFancy I want to tell you how I got started with open-source contribution, which I think will show you there are many ways to get involved. I first signed up for GitHub in April 2013. But my account sat unused for 7 months. I didn't know how to get started. I happened to be looking at Twitter. I saw a tweet from a man named Dan Sinker. He had made a really delicious taco meal and decided to start a project on GitHub to share taco recipes. So I clicked on the link and went to the project to take a look.
	The One Sentence that Motivated Me to Start Using GitHub One sentence in the project information that had a huge impact on me: "Are You New to Github But Want to Contribute?"
	My First Pull Request That was me. I became very determined to contribute and submitted my first pull request there.
	DjangoCon US Website as Example Project 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. I am going to use DjangoCon US website as an example throughout this talk.
	What are Git and GitHub? GitHub is a website built on the version control software Git.
	Social Network GitHub is a social network. You can: Make a user profile Follow people Follow their activity in your newsfeed Find interesting projects
	Repositories But the really important part of GitHub is that users can store and work on code together in repositories
	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.
	Repositories (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.
	Local Development Environment Example When we are working on code, we can't do everything in the GitHub website. For example, we might want to make a copy of the DjangoCon US website code in the local development environment of our computer, install the necessary software, and run the code in a local browser so that you can add a feature to it, or test a pull request branch. There is where Git is very useful. Git is installed in our local development environment and used in the command line of your computer. You can use Git to make a snapshot of your project at any point in time and revert back if needed. Here is a screenshot of my local development environment. In the background I have GitHub open in the browser In front of that, I have my local folder window and my command line
	Local Development Environment Example (Animation) I can use the web address (URL) from the GitHub repo in the command line to create a copy of the repo in my local development environment. Making a copy of a repo locally is called cloning.
	Local Development Environment Example (Animation) I can make changes and push the changes back to GitHub. Meanwhile, other users can do the same thing on their computers. I will elaborate on this process later.
	Collaboration and Code Review Best Practice Workflow 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. You keep your main code branch (master) up-to-date Create one or more features Do code review
	Working on a File in GitHub 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? There is 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.
	Branches We need to use branches instead. Branches They are a best practice Can be used by any GitHub user When you create a repo, by default you are working within a branch named master.
	Branches (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 (GitHub will also refer to a feature branch as a topic branch).
	Branches (Animation) You can create an unlimited number of branches and you can switch in between them to work on them.
	Branches (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.
	Branches (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.
	How to Create a Branch Let's go back to the screenshot of editing a file in GitHub.
	How to Create a Branch (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.
	Overview Determine which collaboration approach to use (there are two) 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 DjangoCon US Website repo Review the two different types of pull requests as a DjangoCon US website repo maintainer Additional workflow and command info People, communication, documentation Recommendations Simulation exercise
	Section 1 Determine which collaboration approach to use (there are two)
	The Two Collaborative Development Models A Collaborative Development Model is a fancy term for how users contribute to a repo. There are two different models. "Shared Repository" Model "Fork and Pull" Model The two different models typically correspond to the two different account types and which model you uses depends on whether you have write permission to the repo.
	The Two Types of Accounts There are two types of accounts Organization accounts such as the DjangoCon organization User accounts, such as my own personal account
	Write Permission We are not talking about "write" permission in the context of English. When a user has write permission to a repo, it means they can make changes directly inside of the repo.
	Examples of What Write Permission Will Allow You to Do Edit files Push branches directly to the repo (instead of via fork) Merge and close pull requests https://help.github.com/articles/repository-permission-levels-for-an-organization
	Why We Need Write Permission Example: DjangoCon US website is a deployed live from the master branch and has a fairly high volume of traffic. We wouldn't want just anyone to be able to go into the DjangoCon repo and directly make changes. There is often a level of trust involved in having write permission.
	Write Permission and Collaboration Examples 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. For example, this year I became a maintainer of the DjangoCon US website, so I was given write permission to the DjangoCon US website repo, which is a “Shared Repository”. Along with the other maintainers I work with who have write permission, I can make changes directly within the DjangoCon US website repo.
	Write Permission and Collaboration Examples (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.
	How to Fork a Repo We've gone to the DjangoCon US website repo. Click the "Fork" button Try to edit a file in a repository that you do not have write permission to. GitHub will automatically fork the repo to your user account.
	How to Fork a Repo (Animation) There will be a message notifying you that it is being forked.
	Forked Repo The forking message will lead you back to your user account.
	Forked Repo (Animation) In the list of repos in your account, you will now see an entry for the fork, which will also tell where it was forked from
	Forked Repo (Animation) Click on the hyperlink and it will open the repo The repo URL will have my user account name in it The fork is an exact copy of the original repo at the time it was forked. I could make any changes I wanted to the fork, including deleting it, and the original repo will not be affected. In addition to using a fork to propose a change to the original repo, you can also use a fork for the starting point of a new idea of your own (depending on the license).
	Interesting Thing #1: Opposites It’s typical that a shared repository will be found in an organization and a fork will be found in a user account. However, it can be the other way around, it’s just not nearly as common. A repo can be forked into an organization account and user account owner can make a user account repo a shared repo by inviting other users to be collaborators on the repo. But there are a few advantages to using a organizational repo as a shared repository instead of an user account repo.
	Interesting Thing #2: User Account Shared Repo Disadvantage Organization account owners can create teams and permissions across multiple repos Otherwise, the repo “Shared Repository” settings are almost exactly the same. Teams and permissions are at an organization level.
	Interesting Thing #3: Write Permission Examples Organization account maintainer (an organizational account owner can give you write permission to one or more repos) User account owner (sources and forks, which is why you fork if you do not have write permission to shared repo) User account collaborator (a user account owner has given you write permission to one of their personal repos)
	Interesting Thing #4: Inactive Pull Requests A few minutes ago, I talked about how it’s impractical to go into a file and make changes directly if you are working with multiple people and that it’s better to use branches. If you fork a repo, you also want to use branches. Say for instance, you make a change in the file and submit a pull request (without using a branch), you’re stuck waiting for the pull request to be resolved. Normally, you want your main branch to stay up-to-date so that you create new feature branches, but you’ve made a change in your main branch. If you delete the fork and refork to make it up to date, the pull request remains, but is inactive. It will be harder for the maintainer and you to work on. Instead, you want to keep the main branch up-to-date and use branches, just like we talked about a few minutes ago.
	Section 2 Determine which collaboration approach to use (there are two) 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 DjangoCon US Website repo
	Fork and Pull Model 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.
	Fork and Pull Model (Animation) Fork the repo
	Fork and Pull Model (Animation) Clone the fork. 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.
	Fork and Pull Model (Animation) Make our changes, push the changes back to the fork
	Fork and Pull Model (Animation) Submit the pull request
	Shared Repository Model Here's what it looks like when we use the "Shared Repository" Model
	Shared Repository Model (Animation) The fork is not needed, because we have write permission Clone the shared repository. The shared repository will now be the remote "origin"
	Shared Repository Model (Animation) Make our changes, push the changes back to the shared repository Submit the pull request
	Bash Commands Bash commands are commands that you use in the command line to communicate directly with your computer operating system. The commands below are enough to be able to use git. The other commands we are going to use in this talk are git commands. A couple useful things to know Some tasks vary by operating system- check tabs at the top of GitHub articles for special OS instructions; For instance, not all command lines use a $ is a placeholder for the real thing Go to the home directory $ cd Change directory $ cd Move back a directory $ cd .. List the folders and files in a directory $ ls
	Local Development Environment 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. I am working in my home directory. The name of home directory is at the top of the command line, and in front of the prompt. The reason why this matters is because the repo will be cloned into the directory we are working in.
	Cloning (Animation) I am going to type the command $ git clone into the command line and copy and paste the URL from the browser of either the shared repo or fork, then hit enter.
	Cloning (Animation) A folder will appear in my home directory by the same name as the GitHub repo (2017.djangocon.us) and filled with the contents of the repo. I now have a copy of the code online in the GitHub repo and a copy in my local development environment.
	Changing Directory (Animation) I will now change directory into the folder so that I can work there by typing cd 2017.djangocon.us, which is the folder name.
	Changing Directory (Animation) I've clicked on the folder in the folder window so that I can see the contents visually. But I can also see I am working from within the folder in my command line because the name of the folder is at the top of the command line and in front of the prompt.
	GitHub Repo Versus Local Directory (Animation) You can pull up your GitHub repo and your local folder and compare the files. You can see the corresponding files. The format will be slightly different between one set is being rendered in the browser, and another set are raw files.
	Verifying Branch (Animation) Use the command $ git branch to verify which branch you are checked out on; initially, you will be checkout out on the default branch (in this case master)
	Creating a New Branch (Animation) Create and checkout (switch) to a feature branch. We are calling this feature branch example-branch. We want to branch off of the branch we intend our changes to be merged into (note how the local files switch to the files of the branch you are checked out on, exactly the same at first, because a copy, but if you make a change in a branch and then switch back and forth between branches, you can see the difference)
	Working on a File Locally (Animation) Open a file in the text editor. Make your change and save it.
	Adding and Committing (Animation) Add and commit our change to git version control, create a message "Creating branch and updating"
	Pushing (Animation) Push the new branch named example-branch to GitHub to your origin (the repo you cloned from that you have write permission to)
	New Branch There will now be a new branch in the repo that is your origin and a message telling you it's there. The branch will not be affecting anything else. It's just there. If you click on the branch tab you can choose the name of the branch to switch to the new branch.
	New Branch (Animation) You can toggle back and forth between the branches by clicking on the branches in the branches tab.
	Submit a Pull Request Go to the repo you want your pull request to be merged into, in this case, the DjangoCon US website repo. The reason why I saw this is because you can accidentally submit a pull request to yourself in your fork. In 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.
	Submit a Pull Request (Animation) Make sure that the base branch is the branch you want your change to be merged into Make sure compare branch is your branch Create a pull request title and perhaps a description If the pull request is via a forked repo, a box will be checked by default giving maintainers the ability to edit the pull request Double check your changes Click "Create pull request"
	Section 3 Determine which collaboration approach to use (there are two) 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 DjangoCon US Website repo Review the two different types of pull requests as a DjangoCon US website repo maintainer
	Pull Request Review Process When a pull request is submitted repo maintainers will receive a notification by browser or email to let them know there is a pull request Follow the link to the pull request tab in the browser Look over the information about the pull request. You can see the title and description and click on the “Files changed” link to see all of the changes that were made.
	Pull Request Review Process (Animation) Underneath that will be info 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”
	Pull Request Command Line 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.
	Pull Request Review Options 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 You look at the pull request changes, you can tell they can be accepted and click merge You look at the pull request changes. Something needs to be changed, but you can change it in GitHub. So you edit the pull request file in the browser, similarly to how we edited a file earlier, and click merge.
	Pull Request Review Options 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 Go back to the browser and click merge If a change needs to be made, you can Ask the pull request author to make a change to the pull request Make the change locally yourself and push additional commits to the pull request branch on GitHub Make the change locally yourself, merge the branch with the branch it is intended to be merged with locally, and push to the branch on GitHub
	Pull Request Branches This is why the pull request instructions are different. As a DjangoCon US website maintainer, we are able to fetch updates made to the DjangoCon US website repo into a hidden folder named .git in our local development environment. These updates will include branches made directly to the DjangoCon US website repo, but they will not include branches made through a fork, because they come from outside of the origin. Branches made through a fork need to be pulled individually into our local development environment. The branches in the .git folder will be remote-tracking branches and can be referred to aas /
	Pull Request Review The instructions on this slide can actually be used by any maintainer to work on any branch they have write permission to. If a pull request has already been made, the additional commits will be automatically added to the pull request, up to the point that the pull request is merged. For a shared repository pull request, we use the command $ git fetch origin to fetch the updates into the .git folder. We create and checkout to a new local branch, which we 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/. We can merge master to make sure the branch is up-to-date. If we make a change, we can push additional commits to the branch on GitHub. $ git fetch origin $ git checkout -b <local-branch-name> origin/<branch-name> $ git merge master $ git push origin <branch-name> 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 additional commits if we have been given permission to edit the pull request. $ 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>
	Merging 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
	Tidy Up After a pull request is closed, it’s good practice to delete the feature branch in the browser and locally. There will be a button on the pull request page that you can use to delete the feature branch in the browser, or you can delete it in the branches tab. Or, you can use the third command. The first two commands are to delete the branch locally. Delete local branch $ git branch -d Force delete local branch $ git branch -D Delete remote branch (instead of deleting directly through browser) $ git push :
	Advanced Topics I’m not really covering these, but it’s good to be aware of them if you want to go further with your knowledge Rebase Interactive rebase Squashing Merge conflicts Aliases Fetch individual pull request branches (commands in Useful Resources section)
	Section 4 Determine which collaboration approach to use (there are two) 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 DjangoCon US Website repo Review the two different types of pull requests as a DjangoCon US website repo maintainer Additional workflow and command info
	Practical Commands https://github.com/KatherineMichel/get-a-jumpstart-on-collaboration-and-code-review-in-github-pyladies-remote#useful-resources
	GitHub Flow The workflow we have been using is basically GitHub Flow. It consists of merging pull requests into a master branch, which, in the cast of DjangoCon US website, deploys directly to the live site.
	Another Workflow Some projects use both a master and develop branch. For example, in a mission critical project with a high volume of users, pull requests might be merged into the develop branch, where the development is done. The develop branch might deploy to a staging site where the changes can be tested. The develop branch will be merged into the master branch when the recent changes are ready to deploy live.
	Learn More About Workflow Some developers have passionate views about workflow (see comment threads in some posts). Sometimes people ask, “Which is the best workflow?” There is not really a “best” workflow. You should use the workflow that fits what you are trying to accomplish. They all have pros and cons. Git Flow (basically, what we’ve been using) A Successful Git Branching Model (more advanced) A Successful Git Branching Model Considered Harmful (alternative view) SemVer See also: Atlassian and GitLab docs (you can also find insights in the docs of other software built on top of Git) http://nvie.com/posts/a-successful-git-branching-model https://barro.github.io/2016/02/a-succesful-git-branching-model-considered-harmful
	Section 5 Determine which collaboration approach to use (there are two) 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 DjangoCon US Website repo Review the two different types of pull requests as a DjangoCon US website repo maintainer Additional workflow and command info People, communication, documentation
	Getting to 10x Results There are two resources I want to direct you to: One is a survey by Eric Elliott of ~1000 developers to find out what makes some developers achieve 10x more results than others. Not all of the answers were code related. The results showed that developers that achieve 10x the results tend to be mentors/teachers and communicator/collaborators. The other resources I want to direct you to is a Open Source Survey completed by GitHub. Even though documentation is considered extremely useful, it is often missing. https://medium.com/javascript-scene/getting-to-10x-results-what-any-developer-can-learn-from-the-best-54b6c296a5ef http://opensourcesurvey.org/2017/#insights
	Communication Strategy I hope that you will make your project documentation and attitude toward community members welcoming and positive. This is a way to increase the number of contributions and increase diversity.
	Documentation I recommend that you go to the Useful Resources Section, follow the links to the DjangoCon US website repo documentation and read it. README.md- gives general project information LICENSE- tells you the legal terms under which you can contribute and use the code CODE_OF_CONDUCT.md- a set of rules outlining the expectations and responsibilities of contributors CONTRIBUTING.md- gives info about contributing. https://github.com/djangocon/2017.djangocon.us/blob/master/README.md https://github.com/djangocon/2017.djangocon.us/blob/master/LICENSE https://github.com/djangocon/2017.djangocon.us/blob/master/CODE_OF_CONDUCT.md https://github.com/djangocon/2017.djangocon.us/blob/master/CONTRIBUTING.md
	Templates See the Simulation Exercise ISSUE_TEMPLATE PULL_REQUEST_TEMPLATE'
	Communication Forums Wikis GitHub Pages/Jekyll Gists
	Section 6 Determine which collaboration approach to use (there are two) 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 DjangoCon US Website repo Review the two different types of pull requests as a DjangoCon US website repo maintainer Additional workflow and command info People, communication, documentation Recommendations
	Code Safety My first recommendation is that if you have the authority, go into a repo’s Settings, click the Branches tab Protect the main branch so it can’t be deleted (for example, your master branch)
	Additional Safety Considerations Here are a few things you might want to do to keep your code safe Back up the repo (third-party software) Enable required reviews of pull requests, for example, a review has to be done before a pull request can be merged Use status checks (external) Revert pull requests, if needed Worst case scenario: How to recover deleted branch (link in Useful Resources section) Sensitive data warning (if made public, consider compromised, immediately remove and change)
	Productivity Helpers My second recommendation is to use productivity helpers Password caching Closing issues via commit messages by using keywords Saved replies Link to specific line numbers on GitHub
	Triaging Tips for getting started In the Useful Resources section there is an excellent checklist for evaluating a project and I recommend that you take a look at it. In general... My third recommendation is that when you are looking for a project to contribute to Search by tag to find projects that use triaging. Triaging is where issues are sorted by difficulty level As a collaborator or code reviewer, you can cherry-pick issues and pull requests that fit your skill level
	Sandboxing Tips for getting started My fourth recommendation is that you Practice your skills and workflow. Don't be afraid to delete and start over You can use your own user account as a sandbox. You can submit pull requests to yourself to practice.
	Debunking Myths I recommend that you be good to yourself. Myth: The repos look perfect. Reality: If you spend enough time using GitHub, you will begin to see errors and room for improvement (example: documentation, massive room for improvement) Myth: The people working on GitHub projects must all be experts; I probably don’t fit in here. Reality: People all types, all skill and knowledge levels contribute to open-source on GitHub, and you can too Myth: GitHub users seem to know exactly what to do. Reality: Behind the scenes, GitHub is actually a pretty messy place. There is plenty of self-organization, creativity, and debate Myth: This is all about code Reality: Not all GitHub projects involve code, and coding isn’t the only important skill needed on GitHub Myth: I don’t want to break something Reality: Git is extremely resilient
	Go For It! My last but 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 are always looking for more contributors. Let us know if you are interested.
	Section 7 Determine which collaboration approach to use (there are two) 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 DjangoCon US Website repo Review the two different types of pull requests as a DjangoCon US website repo maintainer Additional workflow and command info People, communication, documentation Recommendations Simulation exercise
	Simulation Exercise Explanation
	Prerequisites for Getting Started Create a free GitHub account online Install Git on your computer and set your email and username Find and open your command line (a.k.a. terminal) on your computer Be able to navigate via command line (See Bash commands) You might also want to have a text editor of your choice installed, to use to edit files You will find documentation for all of these things in the Useful Resources section.
	Getting Help Help via Git, GitHub Help and Guides (links in Useful Resources Section) Help via command line (exit by typing “q”) Help via GitHub Keyboard Shortcuts (type "?") $ git help <verb> $ git <verb> --help $ man git-<verb> $ git help clone $ git clone --help $ man git-clone
	Thank You Feel free to contact me. If you make progress based on my talk, I'd love to know. Send me a note if you get the chance. Useful Resources: https://git.io/v5kpy Twitter handle: @KatiMichel GitHub username: KatherineMichel

🔝 _{back to top}

---

Useful Resources

Links

GitHub

• GitHub

Getting Set Up

• Set Up Git
• Getting Started Installing Git
• Homebrew Git Formula

Git Official

• Git Homepage
• Git Doc (Docs and Pro Git Book
• Git Documentation
• Git Pro Git Book

Glossaries and Cheatsheets

• GitHub Glossary
• Git Cheatsheet
• GitHub Git Cheatsheet

GitHub Help and Training

• GitHub Help
• GitHub Guides
• GitHub Training Guides YouTube

GitHub Try

• Try Git
• GitHub Bootcamp
• GitHub Hello World Tutorial

GitHub Learning Resources

• Git and GitHub Learning Resources

GitHub Open Source Guides

• Open Source Guide
• A Checklist Before You Contribute

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
• Permission Levels for a User Account Repository

Pull Request Branches Created from a Fork

• Allowing Changes to a Pull Request Branch Created from a Fork
• Committing Changes to a Pull Request Branch Created from a Fork

Advanced Collaborative Development Workflow Examples

• Git Flow
• A Successful Git Branching Model (more advanced)
• A Successful Git Branching Model Considered Harmful
• SemVer (subtopic)

10x Results

• "Survey: Getting to 10x — What do the Best Developers Have in Common?"
• Open Source Guide Insights

Documentation

• DjangoCon US Website README.md
• DjangoCon US Website LICENSE
• DjangoCon US Website CODE_OF_CONDUCT.md
• DjangoCon US Website CONTRIBUTING.md

GitHub Documentation Resources

• About READMEs
• Licensing a Repository
• Adding a License to a Repository
• Adding a Code of Conduct to Your Project
• GitHub Pages Basics
• Customizing GitHub Pages
• Wikis
• Gists

Writing and Formatting

• Getting Started with Writing and Formatting on GitHub
• Working with Advanced Formatting

Setting Up and Maintaining Teams

• Setting Up Teams
• Maintaining Teams

Recover a Branch

• Can I Recover Branch After its Deletion in Git?

🔝 _{back to top}

---

Bash

Go to the home directory

$ cd

Change directory

$ cd <folder-name>

Move back a directory

$ cd ..

List the folders and files in a directory

$ ls

🔝 _{back to top}

---

Avoiding Cloning Conflicts

Normal cloning

$ git clone <repo-url>

Avoid a local path conflict by giving a clone a different name (for instance if you are cloning both a shared repo and a fork for practice!)

$ git clone <repo-url> <different-local-directory-name>

Local Development

$ 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>

🔝 _{back to top}

---

Review Shared Repo Pull Request

$ git fetch origin
$ git checkout -b <branch-name> origin/<branch-name>
$ git merge master

If we make a change, we can push additional commits to the shared repo feature branch or pull request branch

$ git add .
$ git commit -m "Your note"
$ git push origin <branch-name> 

🔝 _{back to top}

---

Review Forked Repo Pull Request

$ git checkout -b <branch-name> master
$ git pull https://github.com/<user-name>/<repo-name> <branch-name>

If we make a change, we can push additional commits to the forked repo pull request branch (pull request author needs to have given permission, and local branch name and remote branch name need to match)

$ git add .
$ git commit -m "Your note"
$ git push https://github.com/<user-name>/<repo-name> <branch-name>

If we make a change, we can push additional commits to the forked repo pull request branch, even if the local branch name is different than the remote branch name. In the pull request instructions for a fork, GitHub often adds pull request author username to the beginning of the suggested local branch name, causing the local branch name and remote branch name to be different (perhaps to avoid path conflicts?). (pull request author needs to have given permission)

$ git add .
$ git commit -m "Your note"
$ git push https://github.com/<user-name>/<repo-name> <local-branch-name>:<remote-branch-name>

🔝 _{back to top}

---

Merge Pull Request Locally and Push to Master Branch

$ git checkout master
$ git merge --no-ff <branch-name>
$ git push origin master

🔝 _{back to top}

---

Alternatively, Fetch Individual Pull Request

This will only work for pull request branches, not feature branches.

Fetch the individual pull request, checkout the branch, add and commit changes, push changes to the branch

$ git fetch origin pull/<pull-request-number>/head:<branch-name>
$ git checkout <branch-name>
$ git add .
$ git commit -m "Your note"
$ git push <remote-name> <branch-name>

Example

$ git fetch origin pull/1/head:patch-1
$ git checkout patch-1
$ git add .
$ git commit -m "Your note"
$ git push origin patch-1

🔝 _{back to top}

---

Delete a Branch

Delete local branch

$ git branch -d  <branch-name>

Force delete local branch

$ git branch -D  <branch-name>

Delete remote branch (instead of deleting directly through browser)

$ git push <remote-name> :<branch-name>

🔝 _{back to top}

---

Common Branch Commands

Checkout (switch) to a branch that already exists (-b is not needed, because is used to create branch)

$ git checkout <branch-name>

Create and checkout (switch) to a branch (you are in the branch you are branching off of, or there is only one branch, so you do not need to specify which branch you are branching off of)

$ git checkout -b <branch-name>

Create and checkout (switch) to a branch (you are not in the branch you are branching off of)

$ git checkout -b <branch-name> <branch-branching-off-of>

🔝 _{back to top}

---

Common Add and Commit Commands

Anytime you are working on a branch, whether it be a feature branch or a pull request branch and you have made a change, you can use these commands to add and commit your changes to git version control.

After you have checked out (switched) to a branch

$ git add .
$ git commit -m "Your note"

Alternatively, combine the two lines into one line

$ git commit -am "Your note"

🔝 _{back to top}

---

Common Push and Pull Commands

Pulling and pushing directly from and to a remote repository

$ git pull <remote-name> <branch-name>
$ git push <remote-name> <branch-name>

Common pull and push example

$ git pull origin master
$ git push origin master

Pushing and pulling via URL (handy when dealing with a branch outside our origin, for instance, when working with pull request from a fork)

$ git pull https://github.com/<user-name>/<repo-name> <branch-name>
$ git push https://github.com/<user-name>/<repo-name> <branch-name>

🔝 _{back to top}

---

Fetch and Merge Versus Pull

There are two ways to fetch feature or pull request branch to your local development environment.

• You can fetch and merge (two separate commands that provide greater control)
• Or you can pull ($ git fetch + $ git merge in one command)

Fetch new branches and commits from the remote repository to local .git folder (add a remote first, if needed), without merging them locally. The branches stored here are called remote-tracking branches.

$ git fetch <remote-name>

Checkout the branch you will be merging updates into (presumably the branch already exists)

$ git checkout <branch-name>

Merge remote-tracking branch updates with branch you are currently checked out on

$ git merge <remote-name>/<branch-name>

🔝 _{back to top}

---

Adding a Remote Upstream and Syncing a Fork

When a shared repository is updated, the fork does not automatically update with the change. You could delete and re-fork the fork, but this is not practical, for instance, if you have a pull request pending. So, you can add the shared repository as a remote to your local clone, fetch the updates, and push them to your fork.

Add a remote

$ git remote add <remote-name> <remote-url>

Add upstream remote repository (the name upstream is very commonly used in this situation)

$ git remote add upstream https://github.com/upstream-username/original-repository

Verify new upstream remote (cannot push to upstream unless you have write permission)

$ git remote -v
origin  https://github.com/your-username/your-fork (fetch)
origin  https://github.com/your-username/your-fork (push)
upstream  https://github.com/upstream-username/original-repository (fetch)
upstream  https://github.com/upstream-username/original-repository (push)

🔝 _{back to top}

---

Syncing Branches to Keep Them Up-to-Date

If you are working from the "Shared Repository" Model, you are fetching from the origin. If you are working from the "Fork and Pull" Model, you are fetching from the upstream.

Common origin example

$ git fetch origin
$ git checkout master
$ git merge origin/master

Common upstream example (including pushing changes to corresponding branch in forked repository in GitHub)

$ git fetch upstream
$ git checkout master
$ git merge upstream/master
$ git push origin master

Keep feature branch up-to-date (often merging master into feature branch)

$ git checkout <feature-branch-name>
$ git merge <branch-name>

Example

$ git checkout example-branch
$ git merge master

🔝 _{back to top}

---

Attribution

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!

🔝 _{back to top}

---

Contact Kati

• email: [email protected]
• GitHub: https://github.com/KatherineMichel
• Twitter: https://twitter.com/KatiMichel

🔝 _{back to top}

---

Copyright

© 2017 to Present Katherine Michel. All Rights Reserved.