Contributing with GitHub via command-line

Overview

question Questions
  • How can I contribute to an open-source project with GitHub?
  • What is the GitHub flow?
objectives Objectives
  • Fork a repository on GitHub
  • Clone a remote repository locally
  • Create a branch
  • Commit changes
  • Push changes to a remote repository
  • Create a pull request
  • Update a pull request

time Time estimation: 30 minutes

Introduction

Most of the content is written in GitHub Flavored Markdown with some metadata (or variables) found in YAML files. Everything is stored on a GitHub repository: https://github.com/galaxyproject/training-material.

The process of development of new content is open and transparent, using git and following the GitHub flow:

Open source development process
Figure 1: Open source development process
  1. Create a fork
  2. Clone your fork of this repository to create a local copy on your computer
  3. Create a new branch in your local copy for each significant change
  4. Commit the changes in that branch
  5. Push that branch to your fork on GitHub
  6. Submit a pull request from that branch to the master repository
  7. If you receive feedback, make changes in your local clone and push them to your branch on GitHub: the pull request will update automatically
  8. Pull requests will be merged by the training team members after at least one other person has reviewed the Pull request and approved it.

Agenda

In this tutorial, you will learn how to contribute to the GitHub repository:

  1. Create a fork of this repository on GitHub
  2. Clone the GitHub repository on your computer
  3. Create a new branch
  4. Make your changes on this branch
  5. Push your branch on your GitHub repository
  6. Open a pull request
  7. Make the requested changes
  8. Check the automatic tests
  9. Stay up to date

Create a fork of this repository on GitHub

A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project:

Explanation of the forking
Figure 2: Creation of a fork

Forking a repository is a simple two-step process:

hands_on Hands-on: Fork the repository

  1. Go on the GitHub repository:
  2. Click on Fork (top-right corner of the page)

    Fork

comment Comment

When you click the Fork button GitHub will show you a list with your user account and any groups where you can create a fork of this repository (starting with @). If you see yourself only below “You have existing forks of this repository:”, it means you already have a fork and you have nothing to do.

Clone the GitHub repository on your computer

To modify the content of the repository, you need a copy of it on your computer. This step of importing a git repository is called “cloning”:

Explanation of the cloning
Figure 3: Cloning a repository

hands_on Hands-on: Clone the GitHub repository

  1. Get the URL of your fork. You can find this on the main page of your fork under the green button:
    1. Click on Clone or download (right)

      Get fork URL

    2. Copy the URL

      It should be something like https://github.com/< Your GitHub Username >/training-material.git

  2. Open a terminal
  3. Navigate with cd to the folder in which you will clone the repository
  4. Clone the repository with the command:

    $ git clone https://github.com/< Your GitHub Username >/training-material.git
    
  5. Navigate to the repository

    $ cd training-material
    

comment Comment

If you already have a local copy of the GitHub repository, you need to update it before doing any changes. To learn how to do that, please follow the last section.

Create a new branch

You have now your repository locally and you want to modify it. For this example tutorial, you will add yourself as contributor of the project to appear on the Hall of Fame.

In GitHub flow, there is a concept: one new feature or change = one branch.

When you’re working on a project, you’re going to have a bunch of different features or ideas in progress at any given time – some of which are ready to go, and others which are not. Branching exists to help you manage this workflow. You should develop different features on different branches to help keep the changes you make simple and easy to review.

Divergence of a branch compared to master
Figure 4: When you create a branch in your project, you're creating an environment where you can try out new ideas. Changes you make on a branch don't affect the master branch

Here for this tutorial, you will create a branch called “my_new_branch” in which you will modify the CONTRIBUTORS.yaml file, the file used to generate the Hall of Fame.

hands_on Hands-on: Create a branch

  1. List the existing branch

    $ git branch 
      * master
    

    The branch on which you are is shown with the *

  2. Create a new branch

    $ git checkout -b my_new_branch
    Switched to a new branch 'my_new_branch'
    
  3. List the existing branch to check that the branch has been created and you are now on it

This branch is added to your local copy:

Creation of a branch on the local copy of the repository
Figure 5: Creation of a branch on the local copy of the repository

Make your changes on this branch

You have created your first branch! Now you want to make the change in the CONTRIBUTING.yaml file. By changing a file in this branch, it will diverge from the master branch. It will contain data that is only on this new branch:

Divergence of the branch compared to master
Figure 6: The changes on your branch will not be on the master branch

hands_on Hands-on: Make changes in a branch

  1. Open with your favorite text editor the CONTRIBUTORS.yaml file that is on your computer
  2. Add yourself in the CONTRIBUTORS.yaml file

    You should use your GitHub username and add it followed by : at the correct position given the alphabetical order

  3. Save the file
  4. Check the changes you made

    $ git status
    On branch my_new_branch
    Changes not staged for commit:
      (use "git add/rm <file>..." to update what will be committed)
      (use "git checkout -- <file>..." to discard changes in working directory)
       
        modified:   CONTRIBUTORS.yaml
       
    no changes added to commit (use "git add" and/or "git commit -a")
    
  5. Add the file and commit the changes

    $ git add CONTRIBUTORS.yaml
    $ git commit -m "Add ..."
    
  6. Check that there are no more changes to commit with git status

Push your branch on your GitHub repository

The changes you made on your branch are only on the local copy of the repository. To propagate them online, you need to push them on your fork on GitHub:

hands_on Hands-on: Push the changes

  1. Push the changes to the GitHub repository

    $ git push origin my_new_branch
    

    details “push origin”

    When you git pushed, you specified origin. Git repositories can know that forks exist in multiple places. When you clone one, it creates a “remote” (a remote repository) which it names origin, set to the URL that you used when you cloned. By having multiple remotes, you can manage more complex workflows.

  2. Go to your GitHub repository
  3. Change to the “my_new_branch” branch:
    1. Click on Branch: master (left)

      Selecting branch on GitHub

    2. Select the branch “my_new_branch”

  4. Check that your name is in the CONTRIBUTORS.yaml file
Pushing changes to the fork from the local copy
Figure 7: Pushing changes from the local copy to the fork on GitHub

Open a pull request

You pushed your changes to GitHub, but currently they are only on your fork. You want to have these changes in the main GitHub repository in order to appear on our Hall of Fame online. You can’t add or push directly the main GitHub repository, so you need to create what we call a pull request:

Pull request
Figure 8: Pull Requests provide a way to notify project maintainers about the changes you'd like them to consider

hands_on Hands-on: Create a pull request

  1. Go to your GitHub repository
  2. Click on Compare & pull request

    "Opening a pull request"

  3. Check that the selected branch are correct: master on the left and your branch name on the right

    Branches in PR

  4. Fill in the pull request description

    PR description

    1. Add a title for the Pull Request
    2. Add a message explaining the changes you made (Be kind )
    3. Click on Create pull request
  5. Go to Pull requests to check if it is there

Once the pull is open, it will be reviewed. There are two possible outcomes:

  1. Your pull request is accepted. Congratulations! Your changes will be merged into the master branch of the original repository. The website will be re-built and you will be in the Hall of Fame
  2. Your pull request needs modifications: the reviewers will ask for some changes, possibly because the automatic tests are failing.

Make the requested changes

One of the reviewers of your pull request asked you to add your name after your GitHub username in the CONTRIBUTORS.yaml file

hands_on Hands-on: Make further changes

  1. Make the requested changes in the CONTRIBUTORS.yaml file

    It should look like

    bebatut:
         name: Bérénice Batut
    
  2. Check the changes that you made

    $ git status
    On branch my_new_branch
    Changes not staged for commit:
      (use "git add/rm <file>..." to update what will be committed)
      (use "git checkout -- <file>..." to discard changes in working directory)
       
        modified:   CONTRIBUTORS.yaml
       
    no changes added to commit (use "git add" and/or "git commit -a")
    
  3. Add the file and commit the changes

    $ git add CONTRIBUTORS.yaml
    $ git commit -m "Add ..."
    
  4. Check that there are no more changes to commit with git status
  5. Push the new changes to GitHub

    $ git push origin my_new_branch
    

    The pull request should be automatically updated

  6. Check that the new changes are added to the pull request on GitHub

Check the automatic tests

When a pull request is opened, some automated tests are automatically launched on Travis to be sure that the changes do not break the website, the URL are valid, etc.

On the bottom of your pull request, you can see the status of the tests:

Stay up to date

You now want to work on a new tutorial or make some other new changes. However since you get a local copy, some changes have happened to the original GitHub repository. You need then to update your local copy of the repository before changing anything.

hands_on Hands-on: Update the local copy

  1. Move to the master branch

    $ git checkout master
    
  2. Add a reference to the original GitHub repository

    $ git remote add upstream https://github.com/galaxyproject/training-material.git
    

    tip: Tip: “remote upstream already exists”

    If you have done step 2 before and try to remote add again, git will tell you that a “remote upstream already exists”. In this case you can safely continue to step 4.

  3. Update the local copy of the repository by “pulling” in the content of the original GitHub repository

    $ git pull upstream master
    

You can now restart the GitHub flow to propose new changes: start by creating a new branch.

Conclusion

With this tutorial, you have learned some basics git commands and principles:

Summary of the links between GitHub, fork and local repository
Figure 9: Summary of the links between GitHub, fork and local repository

You also learned the GitHub flow and its cycle:

  1. Create a new branch in your local copy
  2. Commit the changes in that branch
  3. Push that branch to your fork on GitHub
  4. Submit a pull request from that branch to the master repository
  5. Wait for feedbacks and make requested changes
  6. Update your local copy
  7. Restart the cycle

You can now contribute and help us to improve our tutorials!

tip Git in Depth

This tutorial was a quick introduction to explain the basics of contributing to the training material. We recommend that everyone follow a more detailed git tutorials:

You should also download, print and keep always with you the Git Cheat Sheet

keypoints Key points

  • Work on your fork
  • 1 branch = 1 feature
  • 1 pull request = 1 branch
  • Be careful of the branch you're working on
  • Check the automated tests

congratulations Congratulations on successfully completing this tutorial!

Developing GTN training material

This tutorial is part of a series to develop GTN training material, feel free to also look at:
  1. Overview of the Galaxy Training Material
  2. Contributing with GitHub via command-line
  3. Contributing with GitHub via its interface
  4. Creating a new tutorial
  5. Creating a new tutorial - Creating Interactive Galaxy Tours
  6. Creating a new tutorial - Defining the technical infrastructure
  7. Creating a new tutorial - Slides
  8. Creating a new tutorial - Writing content in Markdown
  9. Generating PDF artefacts of the website
  10. Including a new topic
  11. Running the Galaxy Training material website locally