Contributing with GitHub via command-line

name: inverse
layout: true
class: center, middle, inverse

</span></div>

</span></div>

---

# Contributing with GitHub via command-line

<div class="contributors-line">
		Authors: 
<a href="/training-material/hall-of-fame/cmonjeau/" class="contributor-badge contributor-cmonjeau"><img src="https://avatars.githubusercontent.com/cmonjeau?s=27" alt="Avatar">Cyril Monjeaud</a>

<a href="/training-material/hall-of-fame/bebatut/" class="contributor-badge contributor-bebatut"><img src="/training-material/assets/images/orcid.png" alt="orcid logo"/><img src="https://avatars.githubusercontent.com/bebatut?s=27" alt="Avatar">Bérénice Batut</a>

</div>

<div class="footnote" style="bottom: 8em;"><i class="far fa-calendar" aria-hidden="true"></i><span class="visually-hidden">last_modification</span> Updated: Jul 26, 2021</div>

<div class="footnote" style="bottom: 6em;">

<i class="fas fa-file-alt" aria-hidden="true"></i><span class="visually-hidden">text-document</span><a href="slides-plain.html"> Plain-text slides</a>
</div>

<div class="footnote" style="bottom: 2em;">
    <strong>Tip: </strong>press <kbd>P</kbd> to view the presenter notes
    | <i class="fa fa-arrows" aria-hidden="true"></i><span class="visually-hidden">arrow-keys</span> Use arrow keys to move between slides

</div>

???
Presenter notes contain extra information which might be useful if you intend to use these slides for teaching.

Press `P` again to switch presenter notes off

Press `C` to create a new window where the same presentation will be displayed.
This window is linked to the main window. Changing slides on one will cause the
slide to change on the other.

Useful when presenting.

---

### <i class="far fa-question-circle" aria-hidden="true"></i><span class="visually-hidden">question</span> Questions

- How can I contribute to an open-source project with GitHub?

- What is the GitHub flow?

---

### <i class="fas fa-bullseye" aria-hidden="true"></i><span class="visually-hidden">objectives</span> 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

---

### Steps

- Fork (copy) a GitHub repository in your GitHub space

- Clone your GitHub repository on your system

- Create a new branch (one branch = one new feature)

- Make your changes on this branch

- Push your branch on your GitHub repository

- Merge your branch on the original GitHub repository

---

## 1. Fork a repository

---

### Fork from a GitHub repository

![Screenshot of github repository header with watch, star and fork buttons. The fork button highlighted](../../images/PR_fork.jpg)

---

### Welcome on your fork repository

![Screenshot for a fork of the training material repository. It shows that it is username/training-material and it has been forked from the upstream.](../../images/PR_fork_repo.png)

---

### Welcome on your fork repository

![Cartoon of two github repositories, upstream and fork. Both have branches like main, feature1 and feature2.](../../images/PR_schema_01.png)

---

## 2. Clone your GitHub repository

---

### Get your GitHub URL

![A subset of the github interface is shown with the green code button clicked. A popup is shown with options to clone from https or ssh, open in github desktop, or download a zip file.](../../images/clone_code_button.png)

---

### Clone your GitHub repository

On your terminal:

- clone your repository

```bash
$ git clone your_fork_github_url
```

- go into your repository

```bash
$ cd training-material
```

---

### Clone your GitHub repository

![The cartoon from before with repositories upstream and fork are now shown to exist on github, and an arrow labelled clone is drawn to a local copy that exists locally.](../../images/PR_schema_02.png)

---

## 3. Make your changes

---

### Create your branch

List your branches

```bash
$ git branch

* main
```
![a line with dots on it representing commits is labelled main has an arrow pointing to the end where there are no dots.](../../images/PR_branch_main.png)

Create a new branch

```bash
$ git checkout -b my_new_branch

Switched to a new branch 'my_new_branch'
```

---

### Make your changes

List your branches

```bash
$ git branch

main
	* my_new_branch
```

![The line with dots or commits is labelled main, now a different line comes out of the right most (i.e. latest) commit. this is labelled my new branch.](../../images/PR_branches_01.png)

Make changes and commits

```bash
$ git add newfile1 newfile2 ...
$ git commit -m "my contribution"
```

![The cartoon from above, however now there are commits shown on my new branch.](../../images/PR_branches_02.png)

---

### Make changes and commits

![The cartoons of the three github repositories are back, upstream, fork, and local. Now local shows a new branch, my new branch.](../../images/PR_schema_03.png)

---

### Push your branch on *your* GitHub repository

```bash
$ git push origin my_new_branch
```

![The same cartoon of the three repositories, an arrow labelled push is shown from the local copy to the fork, and now the my new branch is present in the fork, as well as locally like before.](../../images/PR_schema_04.png)

---

## 4. The pull request

---

### Can't push on the *original* GitHub repository

![The same cartoon, but now two arrows are shown between the upstream and fork repositories on github. One arrow is labelled push and has an X over it, indicating a push cannot happen. However an arrow labelled pull request is shown in colour like it can happen.](../../images/PR_schema_05.png)

---

### Create your pull request

![Screenshot of the github interface showing a yellow popup labelled "your recently pushed branches" with my new branch shown in the list. A green button reads compare and pull request.](../../images/PR_button.png)

---

### Select the branches and write a description

![The pull request form is shown titled "Open a Pull Request", the user is busy filling out the title of the pull request. A button at the bottom reads create pull request.](../../images/PR_form.png)

---

### Automated tests can be executed

![A screenshot of the training material on github, the pull request tab is highlighted. A number of pull requests appear below, some with green check marks, some with red crosses.](../../images/PR_list.png)

- Green check mark = OK
 - Red cross = **not** OK
---

### Your pull request is accepted (congrats)

- Automated tests are ok

- Authors have accepted your feature

- Branches are merged

![line with dots on it representing commits is shown, the line is labelled main as before, but now the commits from my new branch appear directly on the main branch.](../../images/PR_merged_branche.png)

---

### Your feature is now in the original code

![The same 3 repository cartoon as before, both the fork and local copy include my new branch, it looks like the author intended that upstream did too but it is missing from the graphic.](../../images/PR_schema_06.png)

---

### Your pull request need modifications (oops)

- Automated tests are non ok

- Authors have not accepted your feature

You have to make modifications on your branch and push it

---

### Summary

![A final version of the three repository graphic is shown, fork and upstream are on github, the local copy is local. There are several arrows: 1 fork, creating fork from upstream; 2 clone, creating local from fork; 3 push, pushing my new branch to fork; 4 pull request, starting the process of getting my new branch into upstream.](../../images/PR_global_schema.png)

---
### <i class="fas fa-key" aria-hidden="true"></i><span class="visually-hidden">keypoints</span> 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

---

## Thank You!

This material is the result of a collaborative work. Thanks to the [Galaxy Training Network](https://training.galaxyproject.org) and all the contributors!

</div>

</div>

<a rel="license" href="https://creativecommons.org/licenses/by/4.0/">
This material is licensed under the Creative Commons Attribution 4.0 International License</a>.