/get-a-jumpstart-on-collaboration-and-code-review-in-github-pyladies-remote-talk

:hammer: Get a Jumpstart on Collaboration and Code Review in GitHub- PyLadies Remote Talk by @KatherineMichel

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

Table of Contents

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.

🔝 back to top

GitHub and Git Installation Instructions

🔝 back to top

Important Webcast Links

🔝 back to top

Additional PyLadies Resources

PyLadies and PyLadies Remote

🔝 back to top

Slides and Script Table of Contents

🔝 back to top

Slides and Script

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

Slide 1

Get a Jumpstart on Collaboration and Code Review in GitHub

By Katherine "Kati" Michel

Slide 2

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.

Slide 3

About Me

  • DjangoCon Website Chair
  • DEFNA (Django Events Foundation North America) Board Member
  • DjangoCon Europe Website Committee Member
  • Project Manager
  • Web Designer and Developer

Slide 4

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.

Slide 5

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.

Slide 6

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.

Slide 7

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

Slide 8

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.

Slide 9

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?"

Slide 10

My First Pull Request

That was me. I became very determined to contribute and submitted my first pull request there.

Slide 11

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.

Slide 12

What are Git and GitHub?

GitHub is a website built on the version control software Git.

Slide 13

Social Network

GitHub is a social network. You can:

  • Make a user profile
  • Follow people
  • Follow their activity in your newsfeed
  • Find interesting projects

Slide 14

Repositories

But the really important part of GitHub is that users can store and work on code together in repositories

Slide 15

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.

Slide 16

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.

Slide 17

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

Slide 18

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.

Slide 19

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.

Slide 20

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

Slide 21

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.

Slide 22

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.

Slide 23

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).

Slide 24

Branches

(Animation)

You can create an unlimited number of branches and you can switch in between them to work on them.

Slide 25

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.

Slide 26

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.

Slide 27

How to Create a Branch

Let's go back to the screenshot of editing a file in GitHub.

Slide 28

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.

Slide 29

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

Slide 30

Section 1

  • Determine which collaboration approach to use (there are two)

Slide 31

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.

Slide 32

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

Slide 33

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.

Slide 34

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

Slide 35

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.

Slide 36

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.

Slide 37

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.

Slide 38

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.

Slide 39

How to Fork a Repo

(Animation)

There will be a message notifying you that it is being forked.

Slide 40

Forked Repo

  • The forking message will lead you back to your user account.

Slide 41

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

Slide 42

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).

Slide 43

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.

Slide 44

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.

Slide 45

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)

Slide 46

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.

Slide 47

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

Slide 48

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.

Slide 49

Fork and Pull Model

(Animation)

  • Fork the repo

Slide 50

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.

Slide 51

Fork and Pull Model

(Animation)

  • Make our changes, push the changes back to the fork

Slide 52

Fork and Pull Model

(Animation)

  • Submit the pull request

Slide 53

Shared Repository Model

Here's what it looks like when we use the "Shared Repository" Model

Slide 54

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"

Slide 55

Shared Repository Model

(Animation)

  • Make our changes, push the changes back to the shared repository
  • Submit the pull request

Slide 56

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

Slide 57

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.

Slide 58

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.

Slide 59

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.

Slide 60

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.

Slide 61

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.

Slide 62

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.

Slide 63

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)

Slide 64

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)

Slide 65

Working on a File Locally

(Animation)

  • Open a file in the text editor. Make your change and save it.

Slide 66

Adding and Committing

(Animation)

  • Add and commit our change to git version control, create a message "Creating branch and updating"

Slide 67

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)

Slide 68

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.

Slide 69

New Branch

(Animation)

You can toggle back and forth between the branches by clicking on the branches in the branches tab.

Slide 70

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.

Slide 71

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"

Slide 72

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

Slide 73

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.

Slide 74

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”

Slide 75

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.

Slide 76

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.

Slide 77

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

Slide 78

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 /

Slide 79

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>

Slide 80

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

Slide 81

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 :

Slide 82

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)

Slide 83

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

Slide 84

Practical Commands

https://github.com/KatherineMichel/get-a-jumpstart-on-collaboration-and-code-review-in-github-pyladies-remote#useful-resources

Slide 85

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.

Slide 86

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.

Slide 87

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

Slide 88

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

Slide 89

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

Slide 90

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.

Slide 91

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

Slide 92

Templates

See the Simulation Exercise

  • ISSUE_TEMPLATE
  • PULL_REQUEST_TEMPLATE'

Slide 93

Communication Forums

  • Wikis
  • GitHub Pages/Jekyll
  • Gists

Slide 94

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

Slide 95

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)

Slide 96

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)

Slide 97

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

Slide 98

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

Slide 99

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.

Slide 100

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

Slide 101

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.

Slide 102

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

Slide 103

Simulation Exercise

Explanation

Slide 104

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.

Slide 105

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

Slide 106

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

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

Pull Request Branches Created from a Fork

Advanced Collaborative Development Workflow Examples

10x Results

Documentation

GitHub Documentation Resources

Writing and Formatting

Setting Up and Maintaining Teams

Recover a Branch

🔝 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:

Thank you!

🔝 back to top

Contact Kati

🔝 back to top

Copyright

© 2017 to Present Katherine Michel. All Rights Reserved.