Developer Workflow

    Table of contents
    No headers

    Draft content for developer workflow.


    Branches for development

    The GROMACS project maintains multiple long-term branches of code development. A branch from which a release has been made will persist, and further development may occur from it. Generally, three branches will be under active development. Releases will have git tags of the form "vx.y.z" for a version with major/minor/patch version numbers x/y/z. These numbers will generally increase by 1 with each release, and may have multiple digits.

    <diagram of three branches>

    The master branch will be suitable for new features requiring long-term development, perhaps with large-scale changes to the code (e.g. porting to C++, adding multipole method). Versions released from this branch will increment the major release number and reset the other numbers to zero (i.e. x'.0.0). Generally, such a major release will include all the features present in previous releases, and indicate that future development of older feature branches (i.e. with smaller x) will cease.

    The branch that will generally accept new features will be called release-x-y. Versions released from this branch will increment the minor release number to y and reset the patch number to zero (i.e. x.y.0). Activity on this branch will then cease, a new features branch called release-x-(y+1) will be created.

    For any major or minor release, a branch called release-x-y-patches will be created. Any bug fixes, minor changes to documentation, etc. may be accepted here. Changes to user interface, API or functionality that are not bug fixes will be regarded as features and will not be accepted for this branch. Features that were not ready in time for the x.y.0 release will not be accepted in release-x-y-patches, and should be rebased onto release-x-(y+1). In principle, these patches branches are permanently accepting bug fixes; however, in practice, activity dies off as users switch to new minor and major release versions.


    Flow of content between branches

    Periodically, bug fixes from release-x-y-patches will be merged with the next features branch, and similarly from feature branches to master.

    <diagram of merge flow via developer repo and gerrit>

    give example commands

    Such merges will definitely occur prior to minor and major releases, and will also occur at other times to facilitate testing and developer convenience. By definition, there will normally not be flow of content from master to features branches to bug fix branches, but either a cherry-pick or a newly crafted commit can be in order if (for example) it is discovered later that some master commit fixes a bug as a side effect (and in such cases you will want a new Gerrit Change-Id).

    * how do we omit commits that should not be merged upstream? (e.g. because a new feature makes them redundant)


    Workflow for preparing new features

    * decide master or feature branch

    * get source branch

    * check out new local branch with a name that is descriptive to you, and set it up to track the source branch

    * install gerrit hooks

    * code/test/debug cycle, possibly using gerrit draft commit to get easy access to Jenkins testing. Commit often and on any excuse (e.g. before each compilation, before going home). The ability to scroll back through your history (e.g. with git bisect to find where you broke part of your new feature that used to work right) is much more valuable than a clean history. You can search git commit messages and git commits with lots of tools (pickaxe), and you'll be squashing everything down to one commit anyway 

    * share branch with colleagues for group development, possibly by using a gerrit draft (no need to make feature branches in the repo if gerrit will do the admin for you)

    * rebase your feature branch onto the source branch (deal with merging as necessary if your work is colliding with someone else's). The frequency of your rebasing is up to you to decide, but there's no magic way to minimize the pain of merging if you will have it.

    * when you're ready for code review, rebase onto the updated source branch, make a new branch (this lets you keep your old branch if you need to go back and do any detective work later), squash your commits into one commit, describing what you've done and why, making references to any Redmine issues, following the style guide for commit messages, upload to the gerrit branch for your source branch, wait for Jenkins to verify, fix any issues, then nominate reviewers. If you've been using a Gerrit draft commit, you can just use the "Publish" button once you are ready.

    * respond to review comments. If someone has uploaded a new patch on "your" commit (maybe because they could fix an issue faster than you could), go to the gerrit page and download it (there are many reasonable workflows here - note Gerrit clipboard button, etc.)

    * do not mix development and rebasing in the same gerrit patch, because that makes reviewing extremely awkward. If in doubt, use the gerrit "Rebase Change" button, check out the gerrit patch and rebase your new work on top of that (can we set up gerrit to detect and prevent this?)

    * If you wish to preserve your development branch through the reviewing cycle, then you will need to switch between it and your squashed branch, uploading to gerrit only from the squashed branch (e.g. after rebasing the development branch onto the squashed branch, then doing an interactive rebase to squash the new work into the old, then uploading to Gerrit)

    * If your feature doesn't make the next release, rebase on the new features branch (and set up tracking better)



    Preparing to use git, Gerrit and Jenkins

    configure git

    get hooks for use with gerrit


    Making bug-fix commits

    * the commit message should reference or close any relevant Redmine issues

    * the commit message should note if this commit should not be merged



    Future changes

    * name features branch "features" - there is no need to force people to change their workflow just because a release has happened, and we don't want trivia like this biasing us against making releases on schedule

    * bug fix release generally monthly, or sooner for any fix deemed critical

    * features release twice annually

    * major release when ready

    * have a Gerrit hook to automatically give +2 and trigger a rebase-and-merge if there is verify, two separate +1 and a period of time has passed (a day? a week?). Now reviewers can just give a +1 and go do useful things.

    * have a git checkout hook that installs hooks for ChangeID for gerrit upload

    * have gerrit reject commits with messages that don't match the line length settings

    * set gerrit to not show changes in white space?

    * stuff from

    Page last modified 12:47, 22 Oct 2013 by carsten