SuperPOM - Making a contribution

Copyright

In case you are want to submit code, you have to agree to the licensing terms of this project. Do so by using gpg to sign the WAIVER file included in this project:

$ gpg --no-version --armor --sign AUTHORS/WAIVER

After that, add the signed file into the AUTHORS folder. Rename it to WAIVER-signed-by-YOUR_NAME.asc.

$ mv AUTHORS/WAIVER.asc AUTHORS/WAIVER-signed-by-YOUR_NAME.asc

Branches

Branch names are called issue-ISSUE_NUMBER, e.g. issue-123.

# good
$ git checkout -b issue-123

# bad - no reference to the actual issue
$ git checkout -b login_fix

When several people are working on the same feature, it might be convenient to have personal feature branches and a team-wide feature branch. In that case, suffix the name of branch with a slash, followed by the person’s name for the personal branches and master for the team-wide branch:

# team-wide branch
$ git checkout -b issue-123/master

# Adam's branch
$ git checkout -b issue-123/adam

# Eve's branch
$ git checkout -b issue-123/eve

Merge at will the personal branches to the team-wide branch after rebasing onto it (in order to maintain a simple history). Eventually, the team-wide branch will be merged to master.
Delete your branch from the upstream repository after it’s merged (unless there is a specific reason not to). Tip: Use the following command to list merged branches:

$ git branch --merged master | grep -v "\* master"

Commits

Each commit should be a single logical change. Don’t make several logical changes in one commit. For example, if a patch fixes a bug and optimizes the performance of a feature, split it into two separate commits.
Don’t split a single logical change into several commits. For example, the implementation of a feature and the corresponding tests should be in the same commit.
Commit early and often. Small, self-contained commits are easier to understand and revert when something goes wrong.
Commits should be ordered logically. For example, if commit X depends on changes done in commit Y, then commit Y should come before commit X.

Messages

The summary line should look like this:

#ISSUE_NUMBER - ISSUE_TITLE

After that should come a blank line following by a more thorough description. It should be wrapped to 72 characters and explain why the change is needed, how it addresses the issue and what side-effects it might have.
After that the following reference to the issue is expected:

Task-Url: https://github.com/sebhoss/superpom/issues/issue/ISSUE_NUMBER

Finally, the signed-off line is expected to look like this:

Signed-off-by: FIRST_NAME LAST_NAME <email@address.com>

Ultimately, when writing a commit message, think about what you would need to know if you run across the commit in a year from now.
If a commit A depends on another commit B, the dependency should be stated in the message of commit A. Use the commit’s hash when referring to commits.
Similarly, if commit A solves a bug introduced by commit B, it should be stated in the message of commit A.
If a commit is going to be squashed to another commit use the --squash and --fixup flags respectively, in order to make the intention clear:

$ git commit --squash f387cab2

Tip: Use the --autosquash flag when rebasing. The marked commits will be squashed automatically.

Merging

Do not rewrite published history. The repository’s history is valuable in its own right and it is very important to be able to tell what actually happened. Altering published history is a common source of problems for anyone working on the project.
However, there are cases where rewriting history is legitimate. These are when:
- You are the only one working on the branch and it is not being reviewed.
- You want to tidy up your branch (eg. squash commits) and/or rebase it onto the "master" in order to merge it later.
That said, never rewrite the history of the "master" branch or any other special branches (ie. used by production or CI servers).
Keep the history clean and simple. Just before you merge your branch:
- Make sure it conforms to the style guide and perform any needed actions if it doesn’t (squash/reorder commits, reword messages etc.)
- Rebase it onto the branch it’s going to be merged to and do the merge after:

[my-branch] $ git fetch
[my-branch] $ git rebase origin/master

This results in a branch that can be applied directly to the end of the "master" branch and results in a very simple history.
Note: This strategy is better suited for projects with short-running branches. Otherwise it might be better to occassionally merge the "master" branch instead of rebasing onto it.
All merges are expected to be handled by GitHubs pull request feature.

Misc.

Test before you push. Do not push half-done work.
Use annotated tags for marking releases or other important points in the history.
Prefer lightweight tags for personal use, such as to bookmark commits for future reference.
Keep your repositories at a good shape by performing maintenance tasks occasionally, in your local and remote repositories:

Making a contribution

Table of contents

Copyright

Branches

Commits

Messages

Merging

Misc.