Git branching strategy¶

The general workflow is to branch off from the latest version's branch, perform your changes, open a pull request, and merge your updates. An open pull request can finalise a version, or patch it with updates.

Branching strategy¶

For new versions, branch off from the latest version. This is usually done by maintainers. Call the branch as vX, where X is the new version number, the successor of the latest version. To find the latest version, check the VERSION file in the repository root. For example, if the latest version is v1, the new version branch will be v2, and the git graph will look like:

%%{init: { 'theme': 'neutral' } }%%
gitGraph:
    commit
    branch v1
    checkout v1
    commit
    branch your-name/issue-identifier
    checkout your-name/issue-identifier
    commit
    checkout v1
    merge your-name/issue-identifier
    commit
    commit tag: "v1"
    branch v2
    checkout v2
    commit
    commit id:"still in development"

Info

The branch vX is the base branch for all new features and patches for the version X. That means that, even when there are new versions, the branch vX can still be used for patches and minor updates to the version X.

Merging finalised versions¶

To merge a finalised version:
Open a pull request against the version in development.
Pass all CI checks.
Tag it with the vX label.
Merge the pull request.

Adding new features to the current version¶

For patches or minor updates, again, branch off from the latest version. Name your branch prefixing your name and an issue identifier, like your-name/issue-identifier. Short descriptive labels are recommended, like fix-typo, or new-solver-engine. So, the steps are:

Fetch the latest changes:
```
git fetch --all
```

Create a new branch:

git checkout vX # Replace vX with the current version
git checkout -b your-name/issue-identifier

Open a pull request against the version in development. If you are using gh, after pushing your changes, you can create a pull request with:
```
gh pr create
```

Rebasing your work¶

Every once in a while, you should rebase your branch onto the base branch, if the current version has been updated. This will incorporate the latest changes from the base branch into your branch. The steps to rebase are usually the following.

Switch to your working branch:

git checkout your-name/issue-identifier

Initiate the rebase onto the target branch:
```
git pull origin vX --rebase
```
Or merge the changes from the base branch:
```
git merge vX
```

Resolve conflicts¶

Git will pause for conflict resolution.
After resolving each conflict:
```
git rebase --continue
```
To stop the rebase process:
```
git rebase --abort
```

Push your changes¶

Once rebase is complete, push changes:

git push origin your-name/issue-identifier

A force push may be required:

git push origin your-name/issue-identifier --force-with-lease

Important notes¶

Ensure you are on the correct branch before making changes.
Regularly update your branch to minimise conflicts.
Ask for help if you encounter any issues to the maintainers.