# How to create a pull request
Step by step instructions that will guide you through the code contribution process. We will be using `ataiya` as an example GitHub username here, as it will allow us to show some "live" examples of pull requests.
Further information is also available [here](https://github.com/tensorflow/graphics/blob/master/CONTRIBUTING.md).


## Sign the [Contributor License Agreement](https://cla.developers.google.com/clas).

## Fork the tensorflow_graphics repository on [GitHub](https://help.github.com/en/github/getting-started-with-github/fork-a-repo)
![fork](images/fork.png)

## Clone your fork locally
```
~/: git clone git@github.com:ataiya/graphics.git ~/tfg
~/: cd ~/tfg
~/tfg:
```

Above we use [SSH authentication](https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh), but you can use classical HTTPS too:
```
~/: git clone https://github.com/ataiya/graphics.git ~/tfg
~/: cd ~/tfg
~/tfg:
```

## Setup upstream branch of your repo
You will want to keep your fork up-to-date with the main codebase.
To do so, we will add an `official` remote:
```
~/tfg: git remote add official https://github.com/tensorflow/graphics.git
```

You can inspect the remotes you will be using:
```
~/tfg: git remote -v
official	https://github.com/tensorflow/graphics.git (fetch)
official	https://github.com/tensorflow/graphics.git (push)
origin	  https://github.com/ataiya/graphics.git (fetch)
origin	  https://github.com/ataiya/graphics.git (push)
```

## Create a contribution branch

If you are planning to make multiple isolated contributions, it is a good idea to use different branches, one per contributions you plan to perform. You can do so via [git commands](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging):

```

~/tfg: git checkout -b contribution1
Switched to a new branch 'contribution1'
~/tfg: git push -u origin contribution1
Branch 'contribution1' set up to track remote branch 'contribution1' from 'origin'.
~/tfg: git branch
* contribution1
  master
```

The published branch is now visible [https://github.com/ataiya/graphics/tree/contribution1](https://github.com/ataiya/graphics/tree/contribution1).

You could omit `git push -u` if you only wanted local branch, but we will need it to be public to be able to create a **pull request**.

## Keeping your branch up to date
You will want to update your branch often with the (master branch of the) official repo to minimize the chance of conflicts, or at least make them easier/faster to resolve:
```
~/tfg: git pull official master
 * branch            master     -> FETCH_HEAD
Already up to date.
```
As we just forked the official repository, our branch is already up to date.

## Setting your branch to be a pristine copy of the official repo
**WARNING: this will erase any local changes**
```
~/tfg: git fetch official
~/tfg: git reset --hard official/master
HEAD is now at 0593f0d [...]
```

## Make changes and publish them to your fork
```
~/tfg: echo "Simple test change" >> simple_test_change.txt
~/tfg: git add simple_test_change.txt
~/tfg: git commit -m "A simple test change"
~/tfg: git push
```
And now our simple "A simple test change" is visible on the public fork:
[https://github.com/ataiya/graphics/commit/cdb1eae62febf7850871aa5efd466165d03fcdf4](https://github.com/ataiya/graphics/commit/cdb1eae62febf7850871aa5efd466165d03fcdf4)

## Creating a pull request
We can now visit the `branches` page of your fork
[https://github.com/ataiya/graphics/branches](https://github.com/ataiya/graphics/branches)
and press **New pull request**:

![createpr](images/createpr.png)

Make sure to choose a good name for your PR (pull request) and fill out a description of your work.
Also ensure you are creating a PR against `base repository: tensorflow/graphics` and `base: master`.

![createpr2](images/createpr2.png)

Pressing "Create pull request" created [Pull Request #360](https://github.com/tensorflow/graphics/pull/360) in the official repo. The important bits to notice here is that the CLA check has passed, and that the `Github Actions / Build` continuous integration has started executing (this can take a few minutes).
You can press on `Details` to see the progress of the Build action, and check how to replicate the execution of these tests locally by inspecting [//.github/workflows/build.yml](https://github.com/tensorflow/graphics/blob/master/.github/workflows/build.yml). Once these checks have completed successfully, the orange dot to the left will be changed to a green checkmark.

**WARNING: we will not be notified about your pull request until all checks have passed.**

![pr360](images/pr360.png)


## Modifying your PR until it is approved

Once the pull request is created, one of the official contributors will perform a code review of your  pull request, and *likely* require a few changes. To make any change, you can simply push to that branch, as **Github automatically syncs a pull request with the branch it originated from**; let us see this with an example:
```
~/tfg: echo "Another simple test change" >> another_simple_test_change.txt
~/tfg: git add another_simple_test_change.txt
~/tfg: git commit -m "A change that was required by a reviewer"
~/tfg: git push
```

Note that the page of [Pull Request #360](https://github.com/tensorflow/graphics/pull/360) has now been updated with the changes you just made, and, as you updated your code, a new continuous integration test was launched by GitHub actions.

![pr360_edit](images/pr360_edit.png)


**WARNING:** do not modify the code in the PR branch after the branch has been approved, as this will result in you losing these changes.

## Merging an accepted PR with the official master branch

Once your PR is fully approved, the pull request is transferred to the Google side, where one of the Google software engineers will perform another round of code review, and apply any necessary fine-tuning changes. Your PR will be merged with the master without you having to take any further action, but it might take a few days for your changes to become visible. As a rule of thumb, smaller PRs are approved *significantly* faster. So try to breakdown your project into smaller, self-contained, and independent contributions.