... | ... | @@ -3,37 +3,55 @@ |
|
|
# Code Development
|
|
|
|
|
|
## Repository Structure
|
|
|
The main branches are:
|
|
|
- `master`: bugfix updates since the last release, should always be runnable/stable code, e.g. could be used in production
|
|
|
|
|
|
The main branches:
|
|
|
- `master`: bugfix updates since the last release, should always be runnable/stable code, e.g. can be used in production
|
|
|
- `develop`: current developments, waiting to be pushed into the `master` prior to a new release.
|
|
|
The code in `develop` is generally quite stable, but occasional regressions may occur.
|
|
|
- `maintenance-v1806`, `maintenance-v1712`, *etc*: bugfix branches for
|
|
|
previous releases. When a new code version is released, `master`
|
|
|
The code in `develop` is generally quite stable, but regressions may occasional occur.
|
|
|
- `maintenance-v1806`, `maintenance-v1712`, _etc_: bugfix branches for previous releases.
|
|
|
When a new code version is released, `master`
|
|
|
is renamed `maintenance-{prevRelease}` and a new `master` is created at release.
|
|
|
|
|
|
In addition, there may be a number of _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, download the OpenFOAM-plus and ThirdParty-plus repositories to your local OpenFOAM installation directory:
|
|
|
|
|
|
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
|
|
|
cd ~/openfoam # Or any other directory
|
|
|
git clone https://develop.openfoam.com/Development/OpenFOAM-plus.git
|
|
|
git clone https://develop.openfoam.com/Development/ThirdParty-plus.git
|
|
|
```
|
|
|
All new features should target the `develop` branch. To set-up 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
|
|
|
All new features should target the `develop` branch.
|
|
|
To set-up 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 ThirdParty-plus
|
|
|
git checkout -b develop --track remotes/origin/develop
|
|
|
|
|
|
cd ../OpenFOAM-plus
|
|
|
git checkout -b develop --track remotes/origin/develop
|
|
|
|
|
|
cd ThirdParty-plus
|
|
|
git checkout -b develop --track remotes/origin/develop
|
|
|
```
|
|
|
|
|
|
For ease of integration and long-term maintenance, developed code
|
|
|
should follow the [OpenFOAM coding style](Coding-Style-Guide).
|
|
|
***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 download 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 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
|
... | ... | @@ -49,14 +67,21 @@ 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 follow the [OpenFOAM coding style](Coding-Style-Guide).
|
|
|
|
|
|
|
|
|
### 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
|
... | ... | @@ -70,4 +95,12 @@ 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. |
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
[foam-repo]: https://develop.openfoam.com/Development/OpenFOAM-plus
|
|
|
[third-repo]: https://develop.openfoam.com/Development/ThirdParty-plus
|
|
|
[third-build]: https://develop.openfoam.com/Development/ThirdParty-plus/blob/develop/BUILD.md |