Project Guidelines

From OpenFOAMWiki
Revision as of 13:24, 13 May 2014 by Dchrist (Talk | contribs)

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 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 or Bitbucket

Mainstream web based solutions for version control already support organization in teams and collaborative work + planning, and their services are *free* for open source software.

7.2.1 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?

7.2.2 Using Bitbucket

Atlassian, the company behind Bitbucket provides web based solutions for project organization. Teams can be organized as well, like on github. Systems like Jira allow an easy overview of what is being worked on and by whom, and again, the best thing there is that such systems are proven to work by companies in the software industries, as well as Open Source projects, since the services are hosted *for free* for OS projects.

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

9 References

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