Guide for contributing code to foam-extend

You have developed a new top-level solver or utility. You have implemented a further turbulence model, interface to a material properties library or created a really useful boundary condition?

This guide shows the ways to share this code with the foam-extend and OpenFOAM® community.

Why should I share my code?

Depending on your background, motivations for contributing code to OpenFOAM® via the foam-extend project will differ.

With an industrial background you may find it a cost-advantage compared to keeping everything in-house. Code contributed to the source-core will be maintained along with the complete project source code. This saves you the cost of porting your code to each new release. Furthermore, your code will be reviewed by experts with relevant foam-extend and OpenFOAM® experience, who will be able to spot design improvements that lead to increased speed of execution, better convergence, improved robustness, stability or all of the above. If you plan to deploy your code to clients, the extend-bazaar gives you a unified platform that is simple to use, easy to access and gives you maximum freedom in presenting your code.

In academia, many foam-extend and OpenFOAM® developments are carried out within publicly funded projects, often as part of PhD studies. Unfortunately, much of this work is not re-used and developed further. A time-saving option to share this work is the extend-bazaar, where working code and example cases can be simply uploaded with a brief description. This can be expanded and may even form the base for a journal publication; a good example for this is the waves2Foam package by Niels Jacobsen. Contributing gives the code visibility in the foam-extend and OpenFOAM® community and harvests public recognition long after the project has been completed.

In both cases, the credit for your work, its authorship, and copyright remains with you. You are not required to give up the rights to your work.

What is the difference between contributing to source-core and to extend-bazaar?

The source-core of foam-extend meets the high quality standards of a software package that is deployed for production use. A contribution will be therefore reviewed by an experienced foam-extend maintainer. The code must adhere to the coding style guidelines. The contribution procedure is:

1. Check your code, especially regarding coding style and trailing whitespace.
2. Contact the maintainers of foam-extend repository to get write access , ???@???.org.
3. Use git to make a local feature branch, move your contribution into this branch and push the branch to the repository. See details of the branching model employed for foam-extend and git usage.
4. Contact the maintainers and ask for review and merge of your code. Experience shows this involves a few iterative steps.
5. Your code is merged and becomes part of foam-extend. You are added to the list of contributors foam-extend.
6. Maintenance of your case is now part of the general development.

The extend-bazaar has been created to minimize the effort for sharing your code. It is ideal for solvers and utilities that can live in the user-directory. The required steps are:

1. Create a user account on the OpenFOAM Wiki.
2. Go to the extend-bazaar page and find a category for your contribution.
3. Create a new sub-page in the category and write a brief description/documentation for your contribution. Templates exist that you can re-use.
4. Upload your code. Options are:
   • For small packages that will not change much in the future, you can upload a .tgz archive to your wiki page directly.
   • For larger packages that contain for example big meshes, use a file-hoster and add a link to your wiki page.
   • If your contribution is under active development, create a repository for example on SourceForge.net or GitHub or Bitbucket. Add a link to the repository on the wiki page.
5. Implementing bug fixes, new features or ports to a new foam-extend release is at your discretion.