HowToContribute

Guide to contribute code to OpenFOAM-extend project

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 OpenFOAM® communinity.


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 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 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 LINK. Contributing gives the code visibility in the 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.  We do not require contributors to give up the rights to their work.

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

The \BOLD{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 experiened OpenFOAM®-extend maintainer. The code must adhere to OpenFOAM® coding style guideline LINK. The contribution procedure is:
* Check your code, especially regarding coding style and trailing whitespace
* Contact the maintainers of FOAM-extend repository to get write access , ???@???.org.
* 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 FOAM-extend branching model LINK and git usage LINK.
* Contact the maintainers and ask for review and merge of your code. Experience shows this involves a few iterative steps.
* Your code is merged and becomes part of FOAM-extend. You are added to the list of contributors FOAM-extend.
* Maintainance of your case is now part of the general development

The \BOLD{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:

* Create a user account on the OpenFOAM® Wiki.
* Go to the extend-bazaar page and find a category for your contribution.
* Create a new sub-page in the category and write a brief description/documentation for your contribution. Templates LINK exist that you can re-use.
* 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 LINK or github LINK. Add a link to the repository on the wiki page.
* Implementing bug fixes, new features or ports to a new FOAM-extend release is at your discretion







 

http://www.openfoam.org/contrib/code-style.php