dev.git

Git usage

Fork on me GitHub!

If you don’t have an account on GitHub, create one now and fork your own copy of Ehcache to your account;
git clone that fork to your computer, by default that remote’s name will be origin;
git remote add ehcache \git@github.com:ehcache/ehcache3.git;
You’ll have to keep your master branch in sync (both on your computer and the one on your GitHub account) with the one from ehcache (see §2.1.1 below)
git checkout -b issue-'<id>', where '<id>' of issue-'<id>' is the number of the issue you will work on (command that both creates the branch and switches to it). Commit as you see fit on each of these branches (we recommend small commits often;
You can have as many parallel branches as issues you might be working on;
Once done, you may want to re-organize you commits by doing a git rebase -i HEAD~'<n>' where '<n>' is how many commits you’d be ahead when done;

Initiate a pull request

Now that Ehcache 3.0 has releases out there, bug fixes may apply to both the release branches and/or master.

Given this, the development team has decided on the following development strategy.

Feature development

This happens on master only, using a rebase model described below. We strive on keeping a clean and very linear history for feature development.

Right before sharing your changes, make sure your issue-'<id>' branch is based of ehcache/master's current HEAD, e.g.:
```
git pull ehcache
git checkout master
git rebase ehcache/master
git checkout issue-<id>
git rebase master
```
Finally, git push origin issue-'<id>' to push your branch to your account;
You then need to create a pull request, using the UI on GitHub;
Someone from our team is then going to review it.

Bug fixing

If what you are working on is a bug fix, we want to be able to merge the fix commits on all impacted release branches and master. In order to do that, we use a strategy inspired from DaggyFixes.

Picking the base commit

The base commit for your fix must be at the earliest a parent of all branches it will need to be merged to, it can also be at the latest the commit that introduced the bug as describe in DaggyFixes.

Such a commit can be found using the following (presented here as an alias definiton):

alias.oldest-ancestor=!bash -c 'diff --old-line-format='' --new-line-format='' <(git rev-list --first-parent ${1:-master}) <(git rev-list --first-parent ${2:-HEAD}) | head -1' -

Developing the fix

That’s you doing the work - nothing specific there but the usual commit recommendations.

Pull requests

As the fix developer, integrating the fix in the different target branches is your responsibility. So unless your fix can directly be merged in the different branches, you will have to merge the branches into the fix to resolve conflicts.

The idea behind this strategy is that the commits that were created on branch issue-1048 in this example are now part of the history of the different releases and tracking which fix exists where is vastly simplified over the different strategies that are cherry-pick based.

Create the pull requests

The easiest way is to use GitHub’s compare across forks feature when creating the pull request. Use the Ehcache repo as the base fork and your own repo as the head fork, then pick your branch containing the fix as the compare branch.

Now you just need to select the Ehcache branches you want to target (every necessary release/3.x ones, plus master) as the base branch. GitHub will tell you if these branches can be automatically merged. If they can, just create the pull requests as-is. If all branches can be automatically merged, you’re done after you created all the pull requests.

If GitHub reports some branches as having conflicts, you have to read on to create special pull requests containing the merge work.

When manually merging is necessary

I will use the release/3.0 branch as the target in the example below and assume your fix branch is issue-1048. These names should be replaced by the one applicable to your context.

On your fix branch

git checkout -b issue-1048-release-3.0
git merge release/3.0
// Resolve conflicts
git merge --continue

Open a pull request from that, making sure it is against release/3.0
Repeat for each target branch, including master

Have it reviewed

The pull request will be reviewed for:
1. 'Correctness': the pull request should wholly and only be about the related issue;
2. 'Style': which needs to match the style of the project;
3. 'Testing': all changes need to have appropriate test coverage, without breaking existing tests.
4. You can look up general developer guidelines as well
There could be some back and forth between you and the 'reviewer' in that process. Keep in mind that during that time ehcache/master may drift, you’d then need to follow §2.1.1 above, but finally git push --force origin issue-<id> to keep the pull request updated.

Merging a pull request

If you are a reviewer (i.e. have commit rights to the ehcache/ehcache3 repo), the way we are looking at this is:

When working on an issue, you are the author of a contribution, but you don’t have commit rights on the main repo;
When you are code reviewing someone else’s contribution, you do have commit rights.

As a reviewer, you are expected to verify the following:

Branch to be merged is up-to-date with master
Branch to be merged is pristine - it has not been used in a previous pull request

As such, every contribution gets reviewed by a committer, that effectively commits the changes to Ehcache’s repository for the author. As a reviewer/committer, you do the following:

git remote add '<contributor>' '<url'> the contributor’s ehcache3 repository;
git fetch '<contributor>' issue-'<id>';
git checkout -b issue-'<id>' '<contributor>'/issue-'<id>';
'do the actual review';

— THEN —

Use the GitHub UI to do the merge

— OR —

git checkout master;
git merge --no-ff issue-'<id>';
- If this results in something else than having to edit a commit comment - something’s wrong, you need to STOP
git push ehcache master to the main repository.

Both of these methods will create a merge commit, indicating who accepted the change in the main code line. It will also make sure the resulting history is linear equivalent. Always use a reference to the issue id in the commit message of the merge.