Difference between revisions of "Project Guidelines"

From OpenFOAMWiki
Line 1: Line 1:
 
This is the preliminary version of the Project Guidelines for {{-Extend}}. They are based on the draft guidelines and their discussion on [http://www.cfd-online.com/Forums/openfoam/132133-discussion-project-guidelines-draft.html cfd-online].
 
This is the preliminary version of the Project Guidelines for {{-Extend}}. They are based on the draft guidelines and their discussion on [http://www.cfd-online.com/Forums/openfoam/132133-discussion-project-guidelines-draft.html cfd-online].
 
 
  
  
 
== Project mission ==
 
== 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.
+
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.
 
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.
Line 15: Line 13:
 
# Admin
 
# Admin
  
Contributor: Appointed by getting write access to repository by Project Admin (source code) or documentation maintainer (documentation).
+
* Contributor: The two types of contributors are Code contributor and Documentation contributor.
Code contributor (CodeC): Contributes bugfixes and new source code. Has write access to git repository.
+
** 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.
+
** Documentation contributor (DocC): Creates and peer-reviews documentation. Has write access to documentation repository.
  
Maintainer: Appointed by unanimous decision of all admins.  
+
* 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.).
+
** 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.
+
** Webpage maintainer (WebM): Creates and updates the foam-extend.org landing page.
FAQ maintainer (FaqM): Creates and update foam-extend FAQ.
+
** FAQ maintainer (FaqM): Creates and update foam-extend FAQ.
Wiki maintainer (WikiM): In charge of administration of foam-extend wiki.
+
** 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.
+
** 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".
+
** Guidelines maintainer(GuideM): Creates and updates web-pages "guidelines" and "get-involved".
Packages maintainer (PackM): Creates and updates source code and binary packages.
+
** 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.
+
** 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.
+
** Test loop maintainer (TestM): Configures and operates the nightly build system.
Forum maintainer (ForumM): Moderates the foam-extend discussion forum.
+
** Forum maintainer (ForumM): Moderates the foam-extend specific discussion (sub-)forum.
  
Admin: Appointed by unanimous decision of all current admins.
+
* 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 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.
+
** Project head(PH): The benevolent dictator of the project. Resolves disputes (only) if necessary, has right of veto.
  
 
== Communication ==
 
== Communication ==
Line 40: Line 38:
 
# discussion: everything else that is related to foam-extend project.
 
# 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.
+
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
 
+
We need full access to re-direct/delete/stickify posts. Is this possible with cfd-online? Other platform?
+
For communication style, reference http://apache.org/dev/contrib-email-tips.html
+
  
 
== Decision making ==
 
== Decision making ==
Line 54: Line 49:
 
== Bugtracker rules ==
 
== 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.
 
* 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.  
+
* Make a recipe for reproducing the bug, possibly including a test case. See [http://www.sscce.org/].
 
* Post the bug on http://sourceforge.net/apps/mantisbt/openfoam-extend/. The post should include:
 
* Post the bug on http://sourceforge.net/apps/mantisbt/openfoam-extend/. The post should include:
 
** Operating system
 
** Operating system
Line 64: Line 59:
 
[[Extend-bazaar]] on openfoamwiki.
 
[[Extend-bazaar]] on openfoamwiki.
 
* Review your code:
 
* Review your code:
** Fulfills coding style?
+
** Fulfils coding style?
 
** Compiles on fresh installation?
 
** Compiles on fresh installation?
 
* Create user account for openfoamwiki
 
* Create user account for openfoamwiki
Line 74: Line 69:
  
 
Actions by CodeC:
 
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:
 
* Review your code:
 
** Fulfills coding style?
 
** Fulfills coding style?
Line 80: Line 79:
 
* Contact sourceforge admins admins@.... :
 
* Contact sourceforge admins admins@.... :
 
** Describe bugfix or new feature
 
** Describe bugfix or new feature
** Request writing permission to repository (if you don't have it already)
+
** Request merge
 
+
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:
 
Merging procedure for CodeM:
Line 90: Line 85:
 
* Fulfills coding style?
 
* Fulfills coding style?
 
* Code looks reasonable?
 
* Code looks reasonable?
If not, contact contributor and request change
+
If not, contact contributor and request change.
  
If bugfix, merge into master and nextRelease
+
* Test merge using fresh foam-extend installation:
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
 
** Compilation ./Allwmake.firstinstall runs without error
 
** Run test-loop (with FOAM_SETNAN, FOAM_ABORT, FOAM_SIGFPE all =1)
 
** Run test-loop (with FOAM_SETNAN, FOAM_ABORT, FOAM_SIGFPE all =1)
* Push merged branch: git push origin nextRelease
+
** In the future, this will be supplemented with a validation-loop that checks simulation results for consistency.
* 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
+
 
+
=== 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.  
+
 
+
==== Relying on the gihub pull request system ====
+
 
+
The pull request workflow is described here [https://help.github.com/articles/using-pull-requests].
+
 
+
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?
+
  
 +
If bugfix, merge into master and nextRelease
 +
If feature, merge into nextRelease
  
==== Using Bitbucket ====
+
* Notify CodeC to post short description on foam-extend devel-announce-list
  
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.
 
  
 
== Actions required ==
 
== Actions required ==
* Create final draft of project guidelines
 
 
* Appoint PH by PA
 
* Appoint PH by PA
 
* Approval of draft by PA and PH
 
* Approval of draft by PA and PH
* Appoint maintainers
+
* Recruit maintainers
 
* Create guidelines pages (by GuideM)
 
* Create guidelines pages (by GuideM)
 
* Create (forwarded) email adresses for maintainers and admins
 
* Create (forwarded) email adresses for maintainers and admins

Revision as of 13:48, 13 May 2014

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: 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-bazzar

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: