Project Guidelines

From OpenFOAMWiki

This is the preliminary version of the Project Guidelines for the foam-extend project. They are based on the draft guidelines and their discussion on cfd-online.


1 Project mission

Develop a free and open-source framework for numerical simulation in continuum mechanics and related fields under an open and collaborative development model with a global community. Allow all parties to contribute source code, validation examples, training material and documentation.

The foam-extend project is a framework for numerical simulation of continuum mechanics with special emphasis on Computational Fluid Dynamics (CFD) and, more generally Computational Continuum Mechanics (CCM). To offer the broadest possible amount of methods, models and applications, the project intends to enable and encourage contributions from all parties. High quality of the code is achieved through peer-review of contribution and thorough code testing.

2 Roles

  1. User
  2. Contributor
  3. Maintainer
  4. Admin
  • Contributor: The two types of contributors are Code contributor and Documentation contributor.
    • Code contributor (CodeC): Contributes bugfixes and new source code. Only requires to register a SourceForge account to create an own fork to put changes into.
    • Documentation contributor (DocC): Creates and peer-reviews documentation. Has write access to documentation repository.
  • Maintainer: Appointed by unanimous decision of all admins.
    • Code maintainers (CodeMs): Experienced contributor. Reviews and merges branches into "master" and "nextRelease". Has admin rights on bugtracker (can change status etc.).
    • Webpage maintainer (WebM): Creates and updates the foam-extend.org landing page.
    • FAQ maintainer (FaqM): Creates and update foam-extend FAQ.
    • Wiki maintainer (WikiM): In charge of administration of foam-extend wiki.
    • Documentation maintainer(DocM): Maintains documentation system with special regard to low-entry level effort for DocC.
    • Guidelines maintainer(GuideM): Creates and updates web-pages "guidelines" and "get-involved".
    • Packages maintainer (PackM): Creates and updates source code and binary packages.
    • Bugtracker maintainer(BugM): Takes care of issues that have not been picked up by maintainers after 1 week. Notifies individual CodeCs or CodeMs of suitable issues.
    • Test loop maintainer (TestM): Configures and operates the nightly build system.
    • Forum maintainer (ForumM): Moderates the foam-extend specific discussion (sub-)forum.
  • Admin: Appointed by unanimous decision of all current admins.
    • Project admins(PA): Have full access to sourceforge page. Grant permissions for other roles (git, mantis)
    • Project head(PH): The benevolent dictator of the project. Resolves disputes (only) if necessary, has right of veto.

3 Communication

All project related communication is done on discussion forums:

  1. devel (for merge descriptions, posts only by admins and code maintainers)
  2. discussion: everything else that is related to foam-extend project.

Everything related to installation, running, etc. has to be posted on relevant foam-extend (cfd-online OpenFOAM) forums and will be deleted from the devel and discussion forums. For communication style, reference http://apache.org/dev/contrib-email-tips.html

4 Decision making

  1. The Maintainer does the work. The Maintainer decides how it is done.
  2. In case of dispute:
  • Public discussion on forum listing pros and cons
  • Attempt to find best solution based on pros and cons
  • If anything else fails, decision by PH.

5 Bugtracker rules

  • First, make sure it's a bug. Search the relevant foam-extend (cfd-online) forums and the bugtracker, whether this problem is new.
  • Make a recipe for reproducing the bug, possibly including a test case. See [1].
  • Post the bug on http://sourceforge.net/apps/mantisbt/openfoam-extend/. The post should include:
    • Operating system
    • Compiler version
    • foam-extend version, including git-commit (or binary package name and version)
    • Additional information, rather too much than too little :)

6 Submitting procedure: Extend-bazaar

Extend-bazaar on openfoamwiki.

  • Review your code:
    • Fulfils coding style?
    • Compiles on fresh installation?
  • Create user account for openfoamwiki
  • Create wiki page based on Bazaar template

7 Submitting procedure: Core code

7.1 Git and Email based Workflow

Actions by CodeC:

  • Create fork from latest foam-extend code on SourceForge.
    • If not done yet, register as SourceForge user
    • Commit code to fork
  • Review your code:
    • Fulfills coding style?
    • Compiles on fresh installation?
  • Contact sourceforge admins admins@.... :
    • Describe bugfix or new feature
    • Request merge

Merging procedure for CodeM: Review code:

  • Fulfills coding style?
  • Code looks reasonable?

If not, contact contributor and request change.

  • Test merge using fresh foam-extend installation:
    • Compilation ./Allwmake.firstinstall runs without error
    • Run test-loop (with FOAM_SETNAN, FOAM_ABORT, FOAM_SIGFPE all =1)
    • In the future, this will be supplemented with a validation-loop that checks simulation results for consistency.

If bugfix, merge into master and nextRelease If feature, merge into nextRelease

  • Notify CodeC to post short description on foam-extend devel-announce-list


8 Actions required

  • Appoint PH by PA
  • Approval of draft by PA and PH
  • Recruit maintainers
  • Create guidelines pages (by GuideM)
  • Create (forwarded) email adresses for maintainers and admins
  • Create private mailing lists: admins@... , maintainers@..., code.maintainers@..., developers@...
  • Create public mailing list/forum: devel, discussion

9 References

For some inspiration and background information about FOSS project guidelines, please have a look at these ressources: