Git Guidelines and Best Practices

In general we should follow the Git guidelines for the fcrepo project since they are sensible. They go into a lot of detail about line endings which we don't need to worry about as much at the moment. Specifically we should try and do the following, however:

Commit Messages

Commit messages should follow the guidelines described in detail at http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html.

In summary:

• First line: JIRA issue ID in all caps (if applicable), followed by a brief description (~ 50 characters)
• Second line: blank
• Following lines: more detailed description, line-wrapped at 72 characters. May contain multiple paragraphs, separated by blank lines. Link to the JIRA issue, if applicable. Use the present tense when writing messages, i.e. "Fix bug, apply patch", not "Fixed bug, applied patch."

Using the git command line tool you can add multi-line commit messages by typing a \ at the end of a line and continuing to type. E.g.,

$ git commit -m "ISLANDORA-110 Cannot delete content model when there is only one left.\
\
Remove logic that prevents delete widget from being drawn."
$ 

Branches

Main Project Branches

Many of our projects are dependent on Drupal, and we have projects with multiple master branches, one for each supported version of Drupal, the main branches for each projects repository are named after the version of Drupal that is supported by that version of the project. For example Islandora has 6.x for Drupal 6 and 7.x for Drupal 7. These branches should be treated as the master branch for each version, and not developed on top of as is mentioned above. All of our projects should follow this naming convention for their master branch for consistency.

There are also release branches associated with each of the master branches. These are named after the master branch they correspond to. For example: 6.x-release and 7.x-release. These branches are are an archive of the "blessed" released code. They exist mainly so that we can do things like modify the module.info files for releases and cherry-pick commits from the master branch to backport bugfixes into a release.

Issue / Topic Branches

All JIRA issues should be worked on in separate git branches. The branch name should be the same as the JIRA issue number, including all-caps, so ISLANDORA-153, ISLANDORA-118, etc.

When working on a branch, before committing and merging it's best to pull updates from the master branch into your own branch. This makes for more graceful merge logic and more intuitive-looking github graphs. This is discussed extensively in the Development in a local branch section of the fcrepo git guidelines.

Before merging changes in a branch into master, which should be done as agreed upon in the weekly committers call, the JIRA ticket should be resolved with a status of 'Ready to test'. After merging with master, the local git and github branches are no longer needed. To delete the branches run the following commands

pc044:islandora aoneill$ git branch -d ISLANDORA-153
Deleted branch ISLANDORA-153 (was 06fcef3).
pc044:islandora aoneill$ git push islandora-master :ISLANDORA-153
To [email protected]:Islandora/islandora.git
 - [deleted]         ISLANDORA-153

Once the merge with master is complete, change the fix status of the JIRA ticket to 'Fixed'.