Workflow

Basic Workflow

If you want to work on a new feature, this is the basic workflow. It can be summarised as:

1. Fork
2. Branch
3. Commit
4. Pull Request
5. Code Review
6. Merge (for maintainers)

See GitHub flow for more about the generic GitHub workflow.

1 Fork

GitHub users who are not a member of the TIA organisation do not have permission to add a branch to the repository. Therefore, you must create a fork first to make a copy which you have permission to add branches to. To do this, go to the GitHub page for the toolbox repository and click the 'Fork' button.

After you have forked, clone the fork to your local computer by clicking the green 'Code' button and copying the URL in the git clone command:

git clone <url-to-your-fork> 

cd into the cloned repo and add the upstream repository (this will let you push changes back to GitHub):

cd tiatoolbox 
git remote add upstream <url-to-your-fork> 

Now you should see two remotes:

• upstream, which refers to the tiatoolbox repository
• origin, which refers to your personal fork

$ git remote -v 
<output here> 

If you already have a cloned fork and want to update it to be in line with upstream before working on a new feature use git fetch:

git fetch upstream 

See Also

• GitHub Guides Forking for more on forking.
• GitHub Docs: Cloning and forking repositories from GitHub Desktop for instructions on forking from the GitHub desktop application.

2 Branch

Now you need to make a new branch to work on your feature. This should be a branch off of the develop branch in most cases. See Branching and Branch Naming for more information on branching.

There are two common ways to do this:

1. Via the GitHub web UI.
2. Locally via the command line.

Via GitHub Web UI

See the GitHub Help pages for more detail.

1. In the top left of the repo page click on the Current Branch.
2. Click New Branch.
3. Under Name, type the name of the branch. See Branch Naming for branch naming convention.
4. Select the branch to base this new branch on, usually this will be 'develop'.
5. Click Create Branch.

Via Command Line

1. Checkout with the -b option.

git checkout –b feature-example develop

2. Push your new branch to origin

From step 1 you have a branch on your local copy of the repo. However, your fork on GitHub doesn't yet know that it exists. You have to tell the remote (in this case called origin, AKA your fork on GitHub) that it exists. To do this push with -u / --set-upstream to set the upstream for the branch.

git push -u origin feature-example

3 Commit (Work on Your Contribution)

Make sure to commit changes as you go.

Checklist

A few things to remember while developing your feature:

1. Follow the commit message format, see Commit Messages.
2. Use Black to format your code, see Code Formatting.
3. Use clear variable names i.e. avoid 'x', 'r', 'acc', or similar.
4. Tidy up commit history before opening a pull request.

4 Pull Request

1. Push changes to origin.

Before you can open a pull request make sure that origin (your fork on GitHub) is aware of the changes you have committed.

git push origin feature-example

2. Open a pull request.

Go to GitHub and find the branch on your fork. To the right of the branch menu click New pull request.

Insert image here

3. On the Compare page, click compare across forks.
4. In the "base branch" drop-down menu, select the branch of the upstream repository you'd like to merge changes into. This should be tiatoolbox and the develop branch.
5. In the "head fork" drop-down menu, select your fork, then use the "compare branch" drop-down menu to select the branch you made your changes in.
6. Type a title and description for your pull request. To create a pull request that is ready for review, click Create Pull Request. To create a draft pull request, use the drop-down and select Create Draft Pull Request, then click Draft Pull Request.

Insert image here

See Also

• GitHub Docs: Pull Requests.
• GitHub Docs: Creating a pull request from a fork for more on forking.

5 Code Review

At least two people should review a pull request (PR).

When doing the code review via GitHub it is preferred that you add comments to the code across all changed files and create a summary message as a single review rather than creating many standalone comments or a separate review for each file. This creates a cleaner discussion page and prevents the maintainers for receiving an email for every single comment.

6 Merging (For Maintainers)

TLDR: If in doubt, squash and merge for a feature branch.

There are several ways to merge. Some common ways are: merge and no fast-forward (called merge and commit on GitHub), squash and merge, rebase and merge. For this project we usually squash and merge the feature branch into develop. The other options are currently disabled, simply to prevent accidentally choosing a different option.

We chose squash and merge because most of the time a single commit for a new feature will be sufficient and keep the history of the project clean.

For contributing large features you could consider using a rebase interactive command on the feature branch† to tidy up before doing a regular merge and commit / merge no fast-forward. See Tidying Commit History before merge for more. This is similar to a squash and merge but allows for the merged feature to be broken up into a small number of commits instead of squashing into one.

† Note that rebase interactive is onto the same branch and so is simply being used here for squashing commits together and editing commit messages conveniently rather than actually changing the base of the branch at all. Mixing rebasing and merging is to be avoided for reasons.