HowToContribute

   1 How to Contribute
   2 ~~~~~~~~~~~~~~~~~
   3
   4 Contacts:
   5
   6 Release Committee:    Hrvoje Jasak (h.jasak@wikki.co.uk)
   7 SourceForge Accounts: Bernhard Gschaider (Bernhard.Gschaider@ice-sf.at)
   8                       Martin Beaudoin (beaudoin.martin@ireq.ca)
   9 git Repository:       Henrik Rusche (h.rusche@wikki.co.uk)
  10                       Martin Beaudoin (beaudoin.martin@ireq.ca)
  11
  12 1. SourceForge Access
  13    ~~~~~~~~~~~~~~~~~~
  14
  15    To make contributions to the -extend project, you should first obtain an
  16    account at SourceForge.net. (SourceForge will suggest a username
  17    of firstnamelastname, but a username of firstname_lastname may
  18    be a better choice.) After you obtain your account at SourceForge, you will
  19    still need to be granted specific access to the -extend project. Make a request
  20    to the "SourceForge Accounts" contact at the top of this document for access to
  21    the project.
  22
  23
  24 2. Access to the git Repository
  25    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  26
  27    For a read-only copy of the repository, use the following command:
  28    + git clone git://openfoam-extend.git.sourceforge.net/gitroot/openfoam-extend/OpenFOAM-1.6-ext
  29
  30    To obtain a copy of the repository with write access, use the following command:
  31    + git clone ssh://username@openfoam-extend.git.sourceforge.net/gitroot/openfoam-extend/OpenFOAM-1.6-ext
  32
  33    Also see:
  34    http://openfoam-extend.git.sourceforge.net/git/gitweb.cgi?p=openfoam-extend
  35
  36
  37 3. git Commit Policies and Workflow (Introduction)
  38    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  39
  40    A formal procedure for contributions has been established for the project with
  41    regard to branching and commits in the git repository. The workflow proposed
  42    by Hrv Jasak and Henrik Rusche for contributing to the git repository is described
  43    in the following document:
  44
  45    http://nvie.com/posts/a-successful-git-branching-model/
  46
  47    The article listed above should be considered mandatory reading material
  48    for those planning to make contributions to the repository. Some links about
  49    the general usage of GIT can be found in Section 8.
  50
  51    Please do not hesitate to ask one of the "git Repository" contacts at the top
  52    of this document if you are not sure about specific operation relative to the git
  53    repository.
  54
  55
  56 4. git Commit Policies and Workflow (User Perspective)
  57    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  58
  59    The document listed in Section 3 above from nvie.com provides an excellent conceptual
  60    description of the policies that will be used for the -extend repository. More
  61    detailed instructions for users who wish to make contributions are spelled out in
  62    this section.
  63
  64    Before making any commits to the git repository, be sure to configure git with your
  65    username and e-mail address, which helps to ensure that you receive proper credit
  66    in the git repository for work you contribute.
  67
  68    The author's name and e-mail address can be provided to git using commands such
  69    as these:
  70
  71    + git config --global user.name "John Doe"
  72    + git config --global user.email john.doe@xxx.com
  73
  74    Afterwards, the provided information will be contained in a file named .gitconfig
  75    in the user's home directory.
  76
  77    All contributions to the project repository will be contained in a new feature branch
  78    created by the contributor. The recommended way of creating branches is to create one
  79    branch for each new specific fix or feature using a command such as this:
  80
  81    + git checkout -b my-feature-branch
  82
  83    Feature branches should be named after the fix or feature that they contain,
  84    *not* named after the author. There may be more than one author, after all, and
  85    this information is recorded in the commit anyway. As an example, a bug fix
  86    to the mesquite package should be committed to a branch named "hotfix/mesquite".
  87
  88    Carefully organized commits and branches, clear commit messages, and well-chosen
  89    branch names will make it easier for the release committee to review and merge
  90    each contribution.
  91
  92    When you have a feature branch that is ready to be merged, push it to the server
  93    using a command such as this:
  94
  95    + git push origin my-feature-branch
  96
  97    Next, notify the "Release Committee" point-of-contact listed at the top of this
  98    document that the feature branch has been pushed to the server and is ready to be
  99    merged. A release committee member will review your contribution, merge your
 100    branch, and then delete the branch from the server, as it is no longer needed once
 101    it has been merged.
 102
 103    If you need to delete the branch from the server or are requested to do so, the proper
 104    command is
 105
 106    + git push origin :my-feature-branch
 107
 108    To delete the same branch from your local repository requires the command
 109
 110    + git branch -d my-feature-branch
 111
 112    Finally, to clean your local repository of tracking branches that have been deleted
 113    from the server requires the command
 114
 115    + git remote prune origin
 116
 117 5. git Commit Policies and Workflow (Committee Perspective)
 118    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 119
 120    The -extend project "release committee" (initially comprised of Hrv Jasak) will be
 121    solely responsible for merging user contributions into the master and nextRelease branches.
 122
 123    User contributions will be contained in feature branches, with a new feature branch for
 124    each new fix or feature, as described in Section 4 above.
 125
 126    The feature branches provided by users will be merged by the release committee
 127    into an integration branch called "nextRelease", and then both the local
 128    and remote copy of the feature branch will be deleted. The merge will be performed
 129    using a "git merge --no-ff" command, which forces the creation of a merge commit
 130    even in the case where the merge could be accomplished by fast-forward.
 131    Note that the automated test loop will be run off of this integration branch.
 132
 133    When the next release is ready, the release committee will merge the
 134    integration branch into the master branch, again using a "git merge --no-ff" command.
 135    Consistent with the proposed workflow, the master branch will only contain releases
 136    and hotfixes.
 137
 138    Note that hotfixes should be branched off of the master branch and should be merged
 139    twice - once into the integration branch and once into the master branch - in order to
 140    guarantee that a merge of the integration branch into the master branch can be
 141    accomplished by a fast-forward.
 142
 143
 144 6. Specific Usage Instructions
 145    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 146
 147    In case you find out that something that should be a hotfix ended up in
 148    your local feature branch, follow the steps below to ensure that the hotfix is
 149    properly committed to the integration and master branches:
 150
 151    a. Single out the SHA-1 of the commit that contains the hotfix (e.g. 13e5d2f)
 152
 153    c. Create a new hotfix branch; e.g.
 154
 155       + git checkout master
 156       + git checkout -b hotfix/my-hotfix-topic
 157
 158    b. Single out the commit and base it on the master branch; e.g.
 159
 160       # The fix is in a single commit, but localBranch has advanced
 161       + git cherry-pick commitID
 162
 163       OR
 164
 165       # The fix is small, but the commit contains other changes
 166       + git checkout localBranch file
 167       + git commit
 168
 169    d. Contact the "Release Committee" point-of-contact at the top of this document
 170       and request that the hotfix be merged into the integration and master branches.
 171
 172
 173 7. Acknowledgements & Copyright
 174    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 175
 176    Your authorship is tracked by the version control system (git). You may also document
 177    your authorship in the header of the files. Furthermore, the release committee will
 178    update the list of contributors in the README file with every release.
 179
 180
 181 8. Background Reading on git
 182    ~~~~~~~~~~~~~~~~~~~~~~~~~
 183
 184    http://openfoamwiki.net/index.php/Starting_points_for_using_GIT
 185