The OpenFOAM Foundation hosts a public source code repository for users who wish to share their code modifications of OpenFOAM with the wider community. This repository code is not part of the official OpenFOAM distribution and is known as the Unsupported Contributions Repository. The code is not endorsed or supported by ESI-OpenCFD, the producers of OpenFOAM. However, code of sufficient quality, usefulness and maturity may be migrated by ESI-OpenCFD into the official OpenFOAM code base for distribution by the OpenFOAM Foundation.
The OpenFOAM Foundation distributes the official OpenFOAM code base via GitHub through a user account called OpenFOAM, as described in the Repository Release page. The Foundation creates a new repository for each major release of OpenFOAM, with names such as OpenFOAM-2.1.x.
The Unsupported Contributions Repository resides on GitHub under the user account Unsupported-Contrib-OpenFOAM. Like the official code, a separate repository is created for each major release of OpenFOAM, e.g. Unsupported-Contrib-OpenFOAM-2.1.x. Each new repository will contain the following set of directories, with no files:
- source code for libraries;
- source code for applications (solvers and utilities);
- example cases.
The contribution process is managed through GitHub. A contributor first forks the Unsupported-Contrib-OpenFOAM repository, adds their own code, then requests that their developments are merged back into the unsupported repository. Each merge request will be assessed by the repository administrators against the following criteria:
- Where possible, contributions should take the form of fully encapsulated libraries, applications and example cases; the contributed files should fit within the repository directory structure described above.
- Submitted code must follow the coding style guidelines to ensure consistency with existing code.
- All new source files must begin with a banner including a copyright statement with the relevant year and author name(s) inserted, see example banner.
- All modified source files must retain the original copyright statement, and include a notice stating the modification(s), including author name and date, see example notices.
- All files must be distributed under the General Public License (GPL) version 3, and therefore must include an appropriate license notice, see example license notice.
- The Foundation will not accept any OpenFOAM code that is known to have been distributed elsewhere in a manner that violates the terms of the GPL.
- The Foundation will not accept code from any person known to have distributed any OpenFOAM code in a manner that violates the terms of the GPL.
Please follow the steps below to contribute to the Unsupported-Contrib-OpenFOAM repository:
- Create a public, personal account on GitHub (unless you have one already), by going to https://github.com and selecting Sign up for Free.
- Log into your account, and go to the Unsupported-Contrib-OpenFOAM user account at https://github.com/Unsupported-Contrib-OpenFOAM.
- From the Repositories tab, select the repository version (e.g. 2.1.x) to which you wish to contribute.
- Click the Fork button to create a forked repository in your own user account.
- Clone your forked repository onto your local machine, e.g. by the
following command (for the account contributor and repository
Unsupported-Contrib-OpenFOAM-2.1.x: git clone firstname.lastname@example.org:contributor/Unsupported-Contrib-OpenFOAM-2.1.x.git
- Modify your forked repository locally.
- Push your changes to your repository on GitHub. Note that this will place your code in the public domain so any pushed files should conform to the GPL as described in Contributing OpenFOAM Code (above).
- To submit a contribution to the Unsupported-Contrib-OpenFOAM repository, issue a Pull Request to the Unsupported-Contrib-OpenFOAM user account.
- The contribution will be assessed against the criteria described in Contributing OpenFOAM Code (above). The pull request will be accepted if those criteria are satisfied; otherwise the reasons for rejection will be provided.
ESI-OpenCFD and any Contributor(s) may agree to migrate their code from the Unsupported Contributions Repository to the official OpenFOAM release, for distribution by the OpenFOAM Foundation. The Foundation maintain the sole copyright of all OpenFOAM code it distributes, to be able to enforce the GPL effectively, as advocated by the Free Software Foundation. Therefore, migration of code is conditional on the authors transferring copyright to the OpenFOAM Foundation (or signing a licence agreement to the Foundation in countries where copyright cannot be transferred from the author). Contributing authors will be duly acknowledged in the source code files to which they contributed.