title

  1. Git clone the repository, checking out develop
  2. Make sure it builds and tests, following the instructions.
  3. Create a feature branch feature/<JIRA-NAME> for the feature. Example feature/SLIDER-149-registry
  4. Develop your code.
  5. Check in your code as you go along, including the relevant JIRA value in the commit message, e.g. "SLIDER-149 patch pom"
  6. Rebase before the final patch submission, and ideally regularly

Rebasing

Patches will be applied to the head of the develop branch, so need to be submitted as diffs against that. This is best done during development by rebasing your commit history provided you are not collaborating with others on that branch

  1. Tag the current version of the branch, something like tag_<JIRA-NAME>_<DATE>_rebasing. Example tag_SLIDER-149_2014-08-14_rebasing. This ensures the pre-rebase commit tree is still retained somewhere.
  2. Fetch the latest version of develop
  3. check out your feature branch, then rebase it with git rebase develop.
  4. Fix any conflicts.

Generating Patches

There's two ways you can create patches.

  1. However you do it check in all your code first. The command git status MUST show no outstanding changes/additions, etc.

  2. The patch file must be named with the name of the JIRA, the two/three digit revision number (with leading zeros as needed), and the suffix .patch.

Example: SLIDER-149-002.patch

The numbering system makes it easy to see which is the latest version in the JIRA issue.

  1. Every time you create a new patch, update the patch revision number.
  2. Consider tagging your branch whenever you create a patch, including the patch filename in the tag, e.g. tag_patch_SLIDER-149-002. This makes the work history easier to trace.

Simple git diff

Create a diff between the develop branch and your latest commit

git diff develop...HEAD > <PATCH_FILENAME>

example

git diff develop...HEAD > SLIDER-149-002.patch

formatted patches

A git formatted patch includes all the commits applied during the development process. This must be called against a branch which has either been rebased, or had its patch history squashed to a single patch. The process of doing that is documented on stackoverflow

git format-patch --stdout  develop > <PATCH_FILENAME>

Example:

git format-patch --stdout  develop > SLIDER-149-003.patch

Submitting Patches

Add the patch to the JIRA to which it is related.

Applying patches

Patches MUST be applied to a new feature branch created off the latest commit of develop; if a long-lived branch is being developed, it MUST be rebased first.

simple patches

Before applying a patch, check it actually works:

git apply -p0 --check --verbose --whitespace=fix <PATH-TO-PATCH>

If happy, apply the patch

git apply -p0 --verbose --whitespace=fix <PATH-TO-PATCH>

Then: clean build, test.

Formatted patches

Formatted patches, with the commit history, are applied with git am

git am --whitespace=fix <  <PATH-TO-PATCH>

Example:

git am --whitespace=fix <  SLIDER-149-003.patch

Reviewing patches

After being applied, the feature branch must be committed. This ensures that there is a history of the submitted patch. The commit message must include the patch filename.

As well as reviewing the code and its style, all tests that it patch must be run before attempting to merge the code back into the develop branch.

Ideally, the full test run, minicluster and functional should be performed. A less-reliable shortcut is to run all the tests that are changed in the patch, and all tests which are known to depend on the expected feature. As an example, if a client command is changed, search for uses of that command and execute those tests.

If a submission is to changed before committing build a formatted patch from it and include it in the JIRA as a final log of what went in.