How to create a new branch and a Pull Request

GIT : Getting Started

New branch

To create a new branch:

• Base your branch on the development branch: git checkout dev (if your not already on dev)
• Be sure your dev branch is up to date with the remote : git pull
• Then create a new branch yi/feature/learn-git : git checkout -b yi/feature/learn-git
• Branch name rule: your-initial/type/name-of-the-branch (branch type: feature | fix | refactoring)

Your work

• Do your work on that branch
• Your branch should be related to a trello card and your work also.
• One card = One branch. Do not do multiple card on a same branch. Do not do multiple branch for a single card (the card is probably too big and must be split)

Commit your work often (at least every day, several time a day is better)

• git add .
• git commit -m "wip: what I did since last commit"

Push your work on the repository at least every day:

• git push -u origin yi/feature/learn-git (for the 1st push of your new branch)
• git push yi/feature/learn-git (if not the 1st push of this branch)

Submit your work

The procedure to submit your work (ie your branch) to a Pull Request is detailed here. The idea is to rebase your branch on the dev branch before submitting the Pull Request. A rebase is needed to updated your branch with all the modifications done the dev branch since your branch was created. It will put your branch ahead of dev (or master on the diagram below) so that you can perform an auto merge from the Pull Request.

TLDR

0. git checkout dev && git pull
1. git checkout your_branch ; git add . ; git commit -m "your message" ; git push
2. git rev-list --left-right --count dev...branch_name
3. git rebase -i HEAD~${number-of-commits-on-your-branch}
4. git push -f
5. git fetch --all
6. git rebase origin/dev
7. Resolve conflicts if any
8. git add . && git rebase --continue
9. When the rebase is completed : git push -f

Detailed version :

0. Update the dev branch : git checkout dev and then git pull

1. Checkout on your branch and push your latest changes (in case something go wrong during the rebase...) :

   • git checkout your_branch
   • git add .
   • git commit -m "your message"
   • git push

2. Check where your branch is compare to the dev branch:
   git rev-list --left-right --count dev...branch_name
   You will get something like this:
   13 2
   This output means: "Compared to dev, your-branch is 2 commits ahead and 13 commit behind". In other word, the dev branch has been changed by 13 commits since you created (or last rebased) your branch. If your branch is 0 commit behind dev (output would be like 0 2) then you can directly create the Pull Request (go to the next chapter). Otherwise, you can't auto merge into dev. You have to first rebase your branch on dev and then create the pull request.

3. Squash your commits into one with the interactive rebase: git rebase -i HEAD~${number-of-commits-on-your-branch}. It will make the rebase on the dev branch easier. The number-of-commit-on-your-branch is provided by the output of the previous step (2 in this example).
   You will have something like this:
   
   Pick the last commit and replace pick by squash or s on all other commit

4. Then: git push -f to rewrite your remote commit history.
   It's ok to push force since it's your branch: no one else is working on this branch. There is no alternative to push force, if you try a normal git push, you will get an error saying that the tip of your branch is behind. Which is normal since you squashed your commit into one.

5. Fetch the commits done on dev that are ahead of your branch: git fetch --all

6. Then rebase your branch on the tip of the dev branch: git rebase origin/dev

7. Resolves your conflicts if you have some. This is where it can be tricky. If you don't know how to solve git conflicts, RTFM BUT do not git commit once conflicts are solved (see next steps). If there is conflict to resolve you will get something like this:
   Here the file race.py has conflict that needs to be resolved.
   If at some points you are not sure if you have resolved all conflict, you can git status anytime during the rebase:

8. Once all conflict are solved :git add . && git rebase --continue (Do not git commit after git add, never git commit in the middle of a rebase!). There is no specific message to tell you that the rebase is completed, if you have no error or conflict after the git rebase --continue, then all is good. (See picture below).
   

9. When all is done you do a last git push -f

10. You can run again a the git rev-list ... command from step 1. to check all is good. You should the following output : 0 1

Some additional remarks:

• Why did we use the interactive rebase at step 2. ? If you don't, you will have to resolve the conflict for every commits of your branch. Trust me, when you have lot of commits, you don't want to do that.
• NEVER PUSH FORCE ON ANY BRANCH THAT IS NOT 100% YOURS !

Pull Request

Now that your branch is rebased and ahead of dev you can create the Pull Request. Please refer to github documentation for how to create a Pull Request.

When you create the PR, be sure that the target branch is dev and not master.

That's all folks