Guidelines for maintainers

This page consists of several important guidelines for maintaining javaee-samples repository.

Dealing with pull requests

tl;dr; Do not use "Merge Pull Request" button. Squash and rebase instead.

Merging pull requests (what is exposed in GitHub through this magic "Merge pull request" button) is making more harm than good. Each time you hit this button the new merge commit is created and instead of having streamlined and simple history we are slowly ending up with polluted repository full of small micro-merge commits.

From now on usage of this feature is strongly discouraged.

Instead, consider following approach:

1. Rebase pull request instead (using interactive mode if needed - see next point)
2. If there are more than one commit we can squashed them, as we are not really interested in all changes contributor did (which can be also a result of the discussion / code review). The only thing interesting for us is the whole change, so can be one commit for my taste. And he will still get all the credits.

Obviously it is not as straightfoward and easy like clicking the button, but there is tiny little wrapper around git which simplifies this process when dealing with GitHub repositories.

I hope we all agree on this approach.

Several people already covered this concern, so if you would like to learn more why is it handy, have a look at those posts:

• http://blog.spreedly.com/2014/06/24/merge-pull-request-considered-harmful/
• http://mislav.uniqpath.com/2013/02/merge-vs-rebase/
• http://blogs.atlassian.com/2013/10/git-team-workflows-merge-or-rebase/

We already have too many railway tracks

Pulling the changes

Note: As we work with fork & pull-request strategy this is not really that relevant, but still worth mentioning

When team members work on the single branch and sync it regularly by using git pull, with the default git strategy we will end up with tons of unnecessary merge commits. This make the history quite messy. By using rebase we ensure that the commits are always re-applied so that the history stays linear and there is no pollution. The simplest way to apply this approach is to use git pull --rebase flag. However it's quite tedious when needed all the time. So instead we can ensure that git pull on master always use rebase:

$ git config branch.master.rebase true

Or make it a default for every tracking branch strategy :

$ git config --global branch.autosetuprebase always