git workflow

Repository structure
Prerequisites
- Cautionary note
Workflow
- Submitting for code review
- Direct addition to the repository
Code merging

Repository structure

OpenFOAM follows a branching workflow with the following main branches:

Branch name	Description
`master`	Bugfix updates since the last release, should always be stable and runnable (suitable for production)
`develop`	Current developments, slated for the next release. The code in develop is generally quite stable, but minor regressions may occasionally occur.
`maintenance-v1912` ...	Bugfix branches for previous releases, should always be stable and runnable (suitable for production)

When a new code version is released, master is renamed maintenance-{prevRelease} and a new master is created at release.

There may be additional feature or bugfix branches, which are not of interest for the casual user. Note that these branches are subject to change or removal at any time.

Prerequisites

If not already installed, clone the OpenFOAM and ThirdParty repositories to your local OpenFOAM installation directory:

cd ~/openfoam       # Or any other directory
git clone https://develop.openfoam.com/Development/openfoam.git
git clone https://develop.openfoam.com/Development/ThirdParty-common.git

All new features should target the develop branch. To setup your environment, start from the develop branches inside both the main code and third-party repositories, e.g. to create local develop branches in each repository that track the develop branches from upstream at https://develop.openfoam.com

cd openfoam
git checkout -b develop --track remotes/origin/develop

cd ../ThirdParty-common
git checkout -b develop --track remotes/origin/develop

Cautionary note

The ThirdParty repository only contains configuration and build scripts (and patches) for integrating third-party software. It does not include any third-party sources. For convenience, these can either be reused from a recent release pack or simply downloaded directly. The more detailed ThirdParty build guide lists the locations and versions used. This file is structured with the relevant links near the bottom of its content, where they are readily accessible with grep/tail etc from the command-line.

Workflow

All new code/features/bug-fixes should be created on their own branch, e.g. starting from the develop branch

git checkout develop

Create and move to a new feature branch feature-ABC

git checkout -b feature-ABC

or a bugfix branch bugfix-ABC

git checkout -b bugfix-ABC

Add functionality in the usual way, e.g. adding and committing code changes.

For ease of integration and long-term maintenance, developed code should observe the OpenFOAM coding style.
It may also be useful to note various coding patterns during development.

Submitting for code review

When ready for review, push the branch upstream

git push -u origin feature-ABC

On logging in to this service, you will be able to submit a merge request, and assign a user from the list of developers. Most merge requests will target the develop branch, unless e.g. hot-fixes which will target the master branch directly.

Direct addition to the repository

If you have the necessary permissions and no code review is required, the feature branch can be merged in the local repository directly and pushed upstream to the relevant branch, e.g.

git checkout develop
git merge feature-ABC

If the branch is no longer needed, delete it!

git branch -d feature-ABC

Code merging

The master branch should only be updated by features that do not break backwards compatibility with the latest release typically comprising bugfixes, and occasional small/modular components that are near release-ready. All new capabilities should reside on their own branch until ready to be merged into the develop branch. At release the develop branch is frozen and tested prior to merging into the master branch.