title¶
Recommended Patch development process¶
- Git clone the repository, checking out
develop
- Make sure it builds and tests, following the instructions.
- Create a feature branch
feature/<JIRA-NAME>
for the feature. Examplefeature/SLIDER-149-registry
- Develop your code.
- Check in your code as you go along, including the relevant JIRA value in the commit message, e.g. "SLIDER-149 patch pom"
- 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
- Tag the current version of the branch, something like
tag_<JIRA-NAME>_<DATE>_rebasing
. Exampletag_SLIDER-149_2014-08-14_rebasing
. This ensures the pre-rebase commit tree is still retained somewhere. - Fetch the latest version of
develop
- check out your feature branch, then rebase it with
git rebase develop
. - Fix any conflicts.
Generating Patches¶
There's two ways you can create patches.
-
However you do it check in all your code first. The command
git status
MUST show no outstanding changes/additions, etc. -
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.
- Every time you create a new patch, update the patch revision number.
- 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.