Project Guidelines

From OpenFOAMWiki
Revision as of 20:41, 26 March 2014 by Tomislav-maric (Talk | contribs)

This is a list of ideas for the new foam-extend project guidelines. Please add your ideas and include new points and sections as necessary. Since the aim is to collect ideas first, please do not delete any text written by someone else. In cases, where we have several alterternatives, these will be discussed online to achieve concensus. If for a certain point, no concensus can be achieved, the decision is with the current admins of the openfoam-extend sourceforge project, with a veto right by the project head.

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

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 the user community. 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: Appointed by getting write access to repository by Project Admin (source code) or documentation maintainer (documentation). Code contributor (CodeC): Contributes bugfixes and new source code. Has write access to git repository. 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): Reviews and merges branches into "master" and "nextRelease". Has admin rights on bugtracker (can change status etc.). Webpage maintainer (WebM): Creates and updates the 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 CodeMs of suitable issues. Test loop maintainer (TestM): Configures and operates the nightly build system. Forum maintainer (ForumM): Moderates the foam-extend discussion 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.

We need full access to re-direct/delete/stickify posts. Is this possible with cfd-online? Other platform? For communication style, reference

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.
  • Post the bug on 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-bazzar

Extend-bazaar on openfoamwiki.

  • Review your code:
    • Fulfills 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:

  • Review your code:
    • Fulfills coding style?
    • Compiles on fresh installation?
  • Contact sourceforge admins admins@.... :
    • Describe bugfix or new feature
    • Request writing permission to repository (if you don't have it already)

Create local git branch that branches of latest "master" (for bugfixes) or "nextRelease" (for new features): git checkout master git checkout -b bugfix/

Merging procedure for CodeM: Review code:

  • Fulfills coding style?
  • Code looks reasonable?

If not, contact contributor and request change

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

  • Create a fresh temporary foam installation directory (e.g. in virtual machine)
  • Merge into local master: git merge --no-ff BRANCHNAME
  • Test merge:
    • Compilation ./Allwmake.firstinstall runs without error
    • Run test-loop (with FOAM_SETNAN, FOAM_ABORT, FOAM_SIGFPE all =1)
  • Push merged branch: git push origin nextRelease
  • Post short description on foam-extend devel-announce-list
  • Create a fresh temporary foam installation directory (e.g. in virtual machine)
  • Merge into local nextRelease: git checkout nextRelease; git merge --no-ff BRANCHNAME
  • Test merge:
    • Compilation: ./Allwmake.firstinstall runs without error
    • Run test-loop (with FOAM_SETNAN, FOAM_ABORT, FOAM_SIGFPE all set to true)
  • Push merged branch: git push origin nextRelease
  • Post short description on devel-announce-list

7.2 Using github pull requests

Relying on the gihub pull request system.

The pull request workflow is described here [1].

The benefits of such approach:

  • clear communication during the review process - the system interacts very well with the code
  • decisions are easily tracked because they are coupled to the code and not burried in cc-ed emails
  • multiple CdeM-s can collaborate easily and clearly on a signle pull-request with a CodeC
  • the entire process is open : a first successful pull request can be used as a model for other CodeM / CodeC teams
  • thousands of other open source projects are using it, including the boost C++ library - why re-invent the wheel?

8 Actions required

  • Create final draft of project guidelines
  • Appoint PH by PA
  • Approval of draft by PA and PH
  • Appoint 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