Unsupported Contributions Repository

Unsupported Contributions Repository

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 the OpenFOAM Foundation. However, code of sufficient quality, usefulness and maturity may be migrated by the Foundation into the official OpenFOAM code base for distribution.

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.3.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.3.x. Each new repository will contain the following set of directories, with no files:

src
source code for libraries;
applications
source code for applications (solvers and utilities);
tutorials
example cases.

Contributing OpenFOAM Code

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.

How to Contribute

Please follow the steps below to contribute to the Unsupported-Contrib-OpenFOAM repository:

Creating an account (do once)
Create a public, personal account on GitHub (unless you have one already), by going to https://github.com and selecting Sign up for Free.
Configuring SSH on the Account (do once)
In order to be able to contribute code using the instructions below, a secure shell (SSH) connection is required to interact with GitHub. The following instructions explain how to enable GitHub to identify that the contributions are uploaded from a trusted computer.
  1. The instructions below use the SSH and Xclip packages. These packages can be installed, for example, on Debian/Ubuntu by typing the following (if a package already exists, no installation occurs):

    sudo apt-get install ssh xclip
  2. The user can generate a simple RSA key by typing the following command (copy and paste into terminal). If an RSA key already exists, it will not be overwritten by the following command.

    echo 'n' | ssh-keygen -f ~/.ssh/id_rsa -t rsa -N '' -C ''
  3. The user now needs to click this link to SSH Keys of their user account. In the top right of the SSH Keys table, click “Add SSH key”. In order to paste the contents of the user’s id_rsa.pub file into the “Key” text box, the user can first copy the contents into their clipboard by typing the following in a terminal:

    xclip -sel clip < ~/.ssh/id_rsa.pub
    The file contents can now be pasted into the “Key” text box using “Paste” in the browser (can be usually executed by CNTRL-V). The user should then click the green “Add Key” button to add the key.
  4. SSH access can be tested by typing:

    ssh -T git@github.com
    On the first attempt, an authenticity message may appear, which the user should confirm by typing yes. If the user does not see a message saying “You’ve successfully authenticated”, then refer to the SSH Keys Help Page on GitHub and the Error: Permission denied (publickey) page.
Fork and clone the unsupported contributions repository (do once)
  1. Go to the Unsupported-Contrib-OpenFOAM user account at https://github.com/Unsupported-Contrib-OpenFOAM.
  2. From the Repositories tab, select the repository version (e.g. 2.3.x) to which you wish to contribute.
  3. Click the Fork button to create a forked repository in your own user account.
  4. Clone your forked repository onto your local machine, e.g. by the following command (for the account contributor and repository Unsupported-Contrib-OpenFOAM-2.3.x:

    git clone git@github.com:contributor/Unsupported-Contrib-OpenFOAM-2.3.x.git
Modifying your forked repository
  1. Modify your forked repository locally. For example, if your contribution is a new incompressible solver called icoSolver, create the relevant directories (mimicking the OpenFOAM distribution) and copy in the new code, e.g. 

    cd Unsupported-Contrib-OpenFOAM-2.3.x
    mkdir -p applications/solvers/incompressible/icoSolver
    cp <source files> applications/solvers/incompressible/icoSolver
  2. 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). The following commands would add, commit and push the changes in the above example:

    git add applications/solvers/incompressible/icoSolver
    git commit -m "Added new icoSolver"
    git pull
    git push
Migrating your contribution(s) to the unsupported contributions repository
  1. To submit a contribution to the Unsupported-Contrib-OpenFOAM repository, issue a Pull Request to the Unsupported-Contrib-OpenFOAM user account on GitHub.
  2. 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.

Migration to OpenFOAM

Any contributor 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 as a contributor in a release announcement that includes their contribution; details of their contribution(s) will be recognised through the commit log.