Contributing with GitHub via command-line
OverviewQuestions:Objectives:
How can I contribute to an open-source project with GitHub?
What is the GitHub flow?
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 estimation: 30 minutesSupporting Materials:Last modification: Oct 18, 2022
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:
- Create a fork
- Clone your fork of this repository to create a local copy on your computer
- Create a new branch in your local copy for each significant change
- Commit the changes in that branch
- Push that branch to your fork on GitHub
- Submit a pull request from that branch to the original repository
- If you receive feedback, make changes in your local clone and push them to your branch on GitHub: the pull request will update automatically
- Pull requests will be merged by the training team members after at least one other person has reviewed the Pull request and approved it.
AgendaIn this tutorial, you will learn how to contribute to the GitHub repository:
- Introduction
- Create a fork of this repository on GitHub
- Clone the GitHub repository on your computer
- Create a new branch
- Make your changes on this branch
- Push your branch on your GitHub repository
- Open a pull request
- Make the requested changes
- Check the automatic tests
- Stay up to date
- Close the Pull Request
- Conclusion
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:
Forking a repository is a simple two-step process:
Hands-on: Fork the repository
- Go on the GitHub repository: https://github.com/galaxyproject/training-material
Click on Fork (top-right corner of the page)
CommentWhen 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”:
Hands-on: Clone the GitHub repository
- Get the URL of your fork. You can find this on the main page of your fork under the green button:
Click on Code (right)
Copy the URL
It should be something like
https://github.com/< Your GitHub Username >/training-material.git
- Open a terminal
- Navigate with
cd
to the folder in which you will clone the repositoryClone the repository with the command:
$ git clone https://github.com/< Your GitHub Username >/training-material.git
Navigate to the repository
$ cd training-material
CommentIf 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.
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: Create a branch
List the existing branch
$ git branch * main
The branch on which you are is shown with the
*
Create a new branch
$ git checkout -b my_new_branch Switched to a new branch 'my_new_branch'
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:
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 main
branch. It will contain data that is only on this new branch:
Hands-on: Make changes in a branch
- Open with your favorite text editor the
CONTRIBUTORS.yaml
file that is on your computerAdd yourself in the
CONTRIBUTORS.yaml
fileYou should use your GitHub username and add it followed by
:
at the correct position given the alphabetical order- Save the file
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")
Add the file and commit the changes
$ git add CONTRIBUTORS.yaml $ git commit -m "Add ..."
- 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: Push the changes
Push the changes to the GitHub repository
$ git push origin my_new_branch
When you
git push
ed, you specifiedorigin
. Git repositories can know that forks exist in multiple places. When you clone one, it creates a “remote” (a remote repository) which it namesorigin
, set to the URL that you used when you cloned. By having multiple remotes, you can manage more complex workflows.- Go to your GitHub repository
- Change to the “my_new_branch” branch:
Click on Branch: main (left)
Select the branch “my_new_branch”
- Check that your name is in the
CONTRIBUTORS.yaml
file
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:
Hands-on: Create a pull request
- Go to your GitHub repository
Click on Compare & pull request
Check that the selected branch are correct: main on the left and your branch name on the right
Fill in the pull request description
- Add a title for the Pull Request
- Add a message explaining the changes you made (Be kind )
- Click on Create pull request
- Go to Pull requests to check if it is there
Once the pull is open, it will be reviewed. There are two possible outcomes:
- Your pull request is accepted. Congratulations! Your changes will be merged into the main branch of the original repository. The website will be re-built and you will be in the Hall of Fame
- 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: Make further changes
Make the requested changes in the
CONTRIBUTORS.yaml
fileIt should look like
bebatut: name: Bérénice Batut
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")
Add the file and commit the changes
$ git add CONTRIBUTORS.yaml $ git commit -m "Add ..."
- Check that there are no more changes to commit with
git status
Push the new changes to GitHub
$ git push origin my_new_branch
The pull request should be automatically updated
- 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:
-
Yellow (with circle)
The tests are still running
-
Red (with cross)
When it is red, you can investigate why by clicking on Details. You will be redirected on Travis where you can see the logs of the tests. Get in touch with us on Gitter if you need help to understand the issue.
-
Green (with tick)
The tests passed. Good job!
Even it is green, we recommend to check the result of the tests, as some of tests are allowed to fail (to avoid too much noise).
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: Update the local copy
Move to the
main
branch$ git checkout main
Add a reference to the original GitHub repository
$ git remote add upstream https://github.com/galaxyproject/training-material.git
Comment: Error "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.Update the local copy of the repository by “pulling” in the content of the original GitHub repository
$ git pull upstream main
You can now restart the GitHub flow to propose new changes: start by creating a new branch.
Close the Pull Request
Great! You now know how to make pull request on GitHub, and how to make changes after a review. Reviewers can now approve and merge your pull request.
Because this was just a practice pull request, let’s close it again.
Hands-on: Close the Pull RequestOnce you have run through all these steps, please close the pull request again.
- Go to the list of pull request tab on GitHub
- Click on your pull request
- Scroll to the bottom of the page
- Click on “Close pull request” button
Whenever you add your first real contribution, you can add yourself to the
CONTRIBUTORS.yaml
file in that PR.
Conclusion
With this tutorial, you have learned some basics git
commands and principles:
You also learned the GitHub flow and its cycle:
- Create a new branch in your local copy
- Commit the changes in that branch
- Push that branch to your fork on GitHub
- Submit a pull request from that branch to the main repository
- Wait for feedbacks and make requested changes
- Update your local copy
- Restart the cycle
You can now contribute and help us to improve our tutorials!
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:
- Software Carpentry tutorial which explains a bit more in detail some git commands and the concept of remote, local and stagging
- Learn Git Branching by GitHub to test the different git commands
You should also download, print and keep always with you the Git Cheat Sheet
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
Frequently Asked Questions
Have questions about this tutorial? Check out the tutorial FAQ page or the FAQ page for the Contributing to the Galaxy Training Material topic to see if your question is listed there. If not, please ask your question on the GTN Gitter Channel or the Galaxy Help ForumFeedback
Did you use this material as an instructor? Feel free to give us feedback on how it went.
Did you use this material as a learner or student? Click the form below to leave feedback.
Citing this Tutorial
- Cyril Monjeaud, Bérénice Batut, 2022 Contributing with GitHub via command-line (Galaxy Training Materials). https://training.galaxyproject.org/training-material/topics/contributing/tutorials/github-command-line-contribution/tutorial.html Online; accessed TODAY
- Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012
Congratulations on successfully completing this tutorial!@misc{contributing-github-command-line-contribution, author = "Cyril Monjeaud and Bérénice Batut", title = "Contributing with GitHub via command-line (Galaxy Training Materials)", year = "2022", month = "10", day = "18" url = "\url{https://training.galaxyproject.org/training-material/topics/contributing/tutorials/github-command-line-contribution/tutorial.html}", note = "[Online; accessed TODAY]" } @article{Batut_2018, doi = {10.1016/j.cels.2018.05.012}, url = {https://doi.org/10.1016%2Fj.cels.2018.05.012}, year = 2018, month = {jun}, publisher = {Elsevier {BV}}, volume = {6}, number = {6}, pages = {752--758.e1}, author = {B{\'{e}}r{\'{e}}nice Batut and Saskia Hiltemann and Andrea Bagnacani and Dannon Baker and Vivek Bhardwaj and Clemens Blank and Anthony Bretaudeau and Loraine Brillet-Gu{\'{e}}guen and Martin {\v{C}}ech and John Chilton and Dave Clements and Olivia Doppelt-Azeroual and Anika Erxleben and Mallory Ann Freeberg and Simon Gladman and Youri Hoogstrate and Hans-Rudolf Hotz and Torsten Houwaart and Pratik Jagtap and Delphine Larivi{\`{e}}re and Gildas Le Corguill{\'{e}} and Thomas Manke and Fabien Mareuil and Fidel Ram{\'{\i}}rez and Devon Ryan and Florian Christoph Sigloch and Nicola Soranzo and Joachim Wolff and Pavankumar Videm and Markus Wolfien and Aisanjiang Wubuli and Dilmurat Yusuf and James Taylor and Rolf Backofen and Anton Nekrutenko and Björn Grüning}, title = {Community-Driven Data Analysis Training for Biology}, journal = {Cell Systems} }
Developing GTN training materialThis tutorial is part of a series to develop GTN training material, feel free to also look at:
- Overview of the Galaxy Training Material
- Adding auto-generated video to your slides
- Adding Quizzes to your Tutorial
- Contributing with GitHub via command-line
- Contributing with GitHub via its interface
- Creating a new tutorial
- Creating content in Markdown
- Creating Interactive Galaxy Tours
- Creating Slides
- Design and plan session, course, materials
- Generating PDF artefacts of the website
- GTN Metadata
- Including a new topic
- Principles of learning and how they apply to training and teaching
- Running the GTN website locally
- Running the GTN website online using GitPod
- Teaching Python
- Tools, Data, and Workflows for tutorials
- Updating diffs in admin training