HowToContribute

How to contribute

Following the spirit of a true open source effort, we invite the community to contribute with new features and bug fixes. Such contributions can be shared directly through the foam-extend source code, or through the extend-bazaar. While contributions to the foam-extend source code must go through a thorough review process that guarantees the quality of the code, the extend-bazaar has been created to minimize the effort for sharing your code. The procedures for the different ways of contributing are given below.

Why should I share my code?

Depending on your background, your motivation for contributing to foam-extend 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. 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.

How to contribute to the foam-extend source code:

First of all it is important to know that bug fixes go both into both the master and nextRelease branches, and new features go only into the nextRelease branch. The master branch should thus be considered as a stable branch with continous bug fixes. The nextRelease branch is the development branch, which gets all the bug fixes but also all new features that will ultimately go into the next release.

First, make sure to have an account on SourceForge.Net. You will need to be logged-on on SourceForge.Net for completing some of the next following steps.

For small contributions, such as bug fixes, the simplest way to share is to post a patch through the bug-tracker:

• First, decide if the bug fix should be based on the master or nextRelease branch. Do either of:

  git checkout master
  git checkout nextRelease

• Create and switch to a new branch:

  git checkout -b fixOfBug

• Implement the bug fix or small feature addition
• Create a patch using git command, depending on the base branch:

  git format-patch master --stdout > fixOfBug.patch
  git format-patch nextRelease --stdout > fixOfBug.patch

• Go to the bug-tracker: http://sourceforge.net/p/openfoam-extend/ticketsfoamextendrelease/
• Click on Create Ticket
• Enter title
• Enter category "Bug" or "Feature request"
• Enter "Version" - e.g. foam-extend-3.1
• Write a description
• Add your patch as part of the description, or as an attached file.
• Preferrably, go back to the branch you are following:

  git checkout master
  git checkout nextRelease

• When the bug fix has been merged, you can pull an update and delete your branch:

  git pull
  git branch -d fixOfBug

For larger contributions, you should follow these instructions:

• Browse to http://sourceforge.net/p/openfoam-extend/foam-extend-3.1/ci/master/tree/
• Click on the “Fork” button to create your own fresh fork of foam-extend-3.1
  Just accept the default settings at the next page (just take a note of the Project label) and click on “Fork” again.
  Wait a little while to make sure that everything is forked completely before proceeding (otherwise you may get an error message saying “possible repository corruption” in the next stage)
• At http://sourceforge.net/p/openfoam-extend/foam-extend-3.1/ci/master/tree/, click on “Forks” (note the “s”!), and you should be able to browse to your fork (the Project label you took a note of above) and get instructions on how to clone it.
• Go to your working copy and switch to the nextRelease branch, (this is the platform for which your code must work!)

  cd ~/foam/foam-extend-3.1
  git checkout nextRelease

• Compile foam-extend-3.1 as usual
• Copy you contribution to the appropriate location of the directory structure, and do the modifications you need. Make sure that the code is bug-free, that it works in the nextRelease branch, and that you did not break anything in the nextRelease branch. Check your code, especially regarding coding style and trailing whitespace
• Create and checkout a feature branch. In the example below, ‘feature’ should be a one-word short description of your contribution. Of course, your name will be added to the long list of contributors of this great piece of software. So please no nicknames, only real names for posterity.

  git checkout -b nr/YourfirstnameYourfamilyname_feature

• Clean up your files so that only source files will be added! I.e. remove files that are generated when compiling your contribution, or running tutorial cases that you have added.
• Add, commit and push your contribution to your new feature branch.
  Use “git add” to add your contributions to your local repository.
  Use ‘git commit -m “Descriptive commit message”’ to commit it to your local repository. The descriptive commit message is very important, since it will be the basis of the release notes.
  Push your contribution to the remote repository:

  git push origin nr/YourfirstnameYourfamilyname_feature

• At http://sourceforge.net/p/openfoam-extend/foam-extend-3.1/ci/master/tree/, click on “Forks” and browse to your fork. Make sure that your new branch is there (under “Branches”, click on “More Branches”).
• Request a merge by clicking on “Merge Request”. Write descriptive “Summary” and “Description”. Select your newly created branch as “Source Branch”, and select the nextRelease branch as the “Target Branch”. Then click on “Save” and the administrators will be notified of your request.
• It is preferable if you use the OpenFOAM Wiki for a more detailed description of your accepted contributions.
• 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

If your fork becomes obsolete, you can delete it:

• Go to your fork at SourceForge
• Click on “Admin”
• Click on “Tools”
• Under “Installed Tools”, find your branch and click on “Delete”.

How to contribute to the extend-bazaar:

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:

• 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. A template exists 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 or github. 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