|
|
|
<!-- --- title: Code Development -->
|
|
|
|
|
|
|
|
[](/home)
|
|
|
|
[][code-patterns]
|
|
|
|
[][code-style]
|
|
|
|
|
|
|
|
[[_TOC_]]
|
|
|
|
|
|
|
|
## Repository Structure
|
|
|
|
|
|
|
|
OpenFOAM follows a
|
|
|
|
[branching workflow](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows)
|
|
|
|
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-v1906` ... | 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][foam-repo] and [ThirdParty][third-repo] 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](https://www.openfoam.com/download/install-source.php)
|
|
|
|
or simply downloaded directly.
|
|
|
|
The more detailed [ThirdParty build guide][third-build] 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][code-style].
|
|
|
|
|
|
|
|
- It may also be useful to note various [coding patterns][code-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.
|
|
|
|
|
|
|
|
|
|
|
|
[code-patterns]: /coding/patterns/patterns
|
|
|
|
[code-style]: /coding/style/style
|
|
|
|
|
|
|
|
[foam-repo]: https://develop.openfoam.com/Development/openfoam
|
|
|
|
[third-repo]: https://develop.openfoam.com/Development/ThirdParty-common
|
|
|
|
[third-build]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/BUILD.md |
