Most of the GTN 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, which we will walk you through:

Open image in new tab

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 original 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 GitHub account, if you have not already
2. Create a fork of this repository on GitHub
3. Clone the GitHub repository on your computer
4. Create a new branch
5. Make your changes on this branch
6. Push your branch on your GitHub repository
7. Open a pull request
8. Make any requested changes
   1. 1: A reviewer commits their own changes to your pull request
   2. 2: A reviewer suggests changes
   3. 3: A reviewer posts comments to be addressed
9. Check the automatic tests
10. Stay up to date
11. Finishing the pull request
12. Conclusion

Create a GitHub account, if you have not already

Hands On: Create a GitHub account

1. Go to the GitHub website
2. Create an account & follow the instructions. If anything is unclear, you can check their documentation on account creation.

Create a fork of this repository on GitHub

Hands-on: Choose Your Own Tutorial

This is a "Choose Your Own Tutorial" section, where you can select between multiple paths. Click one of the buttons below to select how you want to follow the tutorial

You can engage with GitHub via either an application on your computer, called GitHub Desktop, or through using the Command-line. If you’re not used to using the Command-line, or you just like a user interface, then use the GitHub Desktop.

Desktop Command-line

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

Open image in new tab

Forking a repository is a simple two-step process:

Hands On: Fork the repository

1. Go on the GitHub repository: https://github.com/galaxyproject/training-material

2. Click on Fork (top-right corner of the page)

   

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

Open image in new tab

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.

Open image in new tab

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.

This branch is added to your local copy:

Open image in new tab

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:

Open image in new tab

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:

To check this has worked, you can go to your GitHub account.

Hands On: Push the changes

1. Go to your GitHub repository on a web browser
2. Change to the “my_new_branch” branch:

   1. Click on Branch: main (left)

      

   2. Select the branch “my_new_branch”

3. Check that your name is in the CONTRIBUTORS.yaml file

Open image in new tab

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:

Open image in new tab

Hands On: Create a pull request

1. Go to your GitHub repository

2. Click on Compare & pull request

   

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

   

4. Fill in the pull request 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 or switch to Create draft pull request from the dropdown menu

      

      Details: "Draft pull requests"

      Creating a pull request as a draft serves as an indication that you are still working on the content. Reviewers may comment on the current state and give general feedback, but they will know that they are not looking at the final version of your contribution.

      In the Galaxy Training Material repository we have also disabled the computationally most expensive automated tests on draft pull requests, and we encourage you to use the draft stage as a small contribution to sustainable computing.

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 main 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 any requested changes

For example, one of the reviewers of your pull request may have asked you to add your name after your GitHub username in the CONTRIBUTORS.yaml file, if you didn’t already.

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

Finishing 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, however, there’s no point adding you as a contributor if you don’t plan to contribute! So you have to make a choice - do you plan to contribute now, later, or never?

Hands-on: Choose Your Own Tutorial

This is a "Choose Your Own Tutorial" section, where you can select between multiple paths. Click one of the buttons below to select how you want to follow the tutorial

Your choice impacts how you will continue with your pull request.

Contribute-now Contribute-later Contribute-never

Conclusion

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

Open image in new tab

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 main 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!

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

• 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

You've Finished the Tutorial

Please also consider filling out the Feedback Form as well!

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

• Tutorial FAQs
• Topic FAQs
• Galaxy FAQs
• GTN Matrix Chat
• Galaxy Help Forum

Feedback

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

1. Cyril Monjeaud, Bérénice Batut, Wendi Bacon, Contributing to the Galaxy Training Network with GitHub (Galaxy Training Materials). https://training.galaxyproject.org/training-material/topics/contributing/tutorials/github-contribution/tutorial.html Online; accessed TODAY
2. Hiltemann, Saskia, Rasche, Helena et al., 2023 Galaxy Training: A Powerful Framework for Teaching! PLOS Computational Biology 10.1371/journal.pcbi.1010752
3. Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012

BibTeX

@misc{contributing-github-contribution,
author = "Cyril Monjeaud and Bérénice Batut and Wendi Bacon",
	title = "Contributing to the Galaxy Training Network with GitHub (Galaxy Training Materials)",
	year = "",
	month = "",
	day = "",
	url = "\url{https://training.galaxyproject.org/training-material/topics/contributing/tutorials/github-contribution/tutorial.html}",
	note = "[Online; accessed TODAY]"
}
@article{Hiltemann_2023,
	doi = {10.1371/journal.pcbi.1010752},
	url = {https://doi.org/10.1371%2Fjournal.pcbi.1010752},
	year = 2023,
	month = {jan},
	publisher = {Public Library of Science ({PLoS})},
	volume = {19},
	number = {1},
	pages = {e1010752},
	author = {Saskia Hiltemann and Helena Rasche and Simon Gladman and Hans-Rudolf Hotz and Delphine Larivi{\`{e}}re and Daniel Blankenberg and Pratik D. Jagtap and Thomas Wollmann and Anthony Bretaudeau and Nadia Gou{\'{e}} and Timothy J. Griffin and Coline Royaux and Yvan Le Bras and Subina Mehta and Anna Syme and Frederik Coppens and Bert Droesbeke and Nicola Soranzo and Wendi Bacon and Fotis Psomopoulos and Crist{\'{o}}bal Gallardo-Alba and John Davis and Melanie Christine Föll and Matthias Fahrner and Maria A. Doyle and Beatriz Serrano-Solano and Anne Claire Fouilloux and Peter van Heusden and Wolfgang Maier and Dave Clements and Florian Heyl and Björn Grüning and B{\'{e}}r{\'{e}}nice Batut and},
	editor = {Francis Ouellette},
	title = {Galaxy Training: A powerful framework for teaching!},
	journal = {PLoS Comput Biol}
}

                   

Developing GTN training material

This tutorial is part of a series to develop GTN training material, feel free to also look at:

1. Contributing to the Galaxy Training Network with GitHub
2. Overview of the Galaxy Training Material
3. GTN Metadata
4. Generating PDF artefacts of the website
5. Adding Quizzes to your Tutorial
6. Updating diffs in admin training
7. Tools, Data, and Workflows for tutorials
8. Principles of learning and how they apply to training and teaching
9. Including a new topic
10. Preview the GTN website as you edit your training material
11. Contributing with GitHub via its interface
12. Creating Interactive Galaxy Tours
13. Teaching Python
14. Adding auto-generated video to your slides
15. Design and plan session, course, materials
16. Creating a new tutorial
17. FAIR Galaxy Training Material
18. Single Cell Publication - Data Plotting
19. Single Cell Publication - Data Analysis
20. Creating content in Markdown
21. Creating Slides
22. Updating tool versions in a tutorial

Galaxy Administrators: Install the missing tools

You can use Ephemeris's shed-tools install command to install the tools used in this tutorial.

shed-tools install [-g GALAXY] [-a API_KEY] -t <(curl https://training.galaxyproject.org/training-material/api/topics/contributing/tutorials/github-contribution/tutorial.json | jq .admin_install_yaml -r)

Alternatively you can copy and paste the following YAML

---
install_tool_dependencies: true
install_repository_dependencies: true
install_resolver_dependencies: true
tools: []

Feedback

No feedback has been recieved yet for this training. Be the first one by filling in the feedback form.