How to contribute

Initial fork (required only once)

If you have not forked the repository yet, first of all hit the "fork" button.

That way, you get an identical copy of the public repository in your GitHub space. That copy is yours, you have all the permissions to do anything with it.

If you are worried that this takes a lot of space: it does not. The way Git (and GitHub) organizes data, forks add only minimal overhead.

Contributing small fixes (i.e. without leaving GitHub's website)

If you want to contribute a very small patch, e.g. correcting a typo or clarifying an ambiguous comment, you do not need to leave the web browser. Just follow our mini tutorial for contributing small fixes.

However, if your changes require at least a test build, you should instead follow the instructions below.

Getting the source code onto your computer

Now it is time to clone it:

git clone https://github.com/MY-HANDLE/nar-maven-plugin

(This is not the correct URL; You have to substitute "MY-HANDLE" with your GitHub handle.) There are other ways if you already cloned our repository, but that would be outside the scope of this tutorial; please have a look at the Working with remotes chapter of the Git Book.

Starting a topic branch

After that, you would usually start a new topic branch:

git checkout -b xyz-improvement

Then you would make your changes.

What makes a good commit?

Please note that it is a best practice embraced by us to craft elegant, well-separated commits. Each commit is kind of its own little story, so if you make a typo fix, that is its own commit. If you add documentation about a certain task, that is another commit (even if it adds a new file and at the same time modifies the index.apt so it references the new file). If you have multiple typo fixes, you could consider to put them into the same commit, depending on your taste.

In short, make sure that commits are logical units of changes.

Testing your changes

Once you made those changes, test them. If the changes are in the website part, you would call mvn site and then direct your browser to target/site/index.html. If the changes are in the plugin code, just call mvn. If you add or modify an integration test (which you should, to ensure that the functionality you add will remain intact in the future), you would call mvn -Prun-its.

Opening a Pull Request

When you're satisfied with the result, just push your branch to your GitHub repository:

git push origin HEAD

Then you would direct your browser to your forked repository where you should see a little button "Open Pull Request" next to the name of your just-pushed branch. This is how you open a pull request.

It might be possible that somebody who reviews the changes suggests a couple of changes (we want to produce high quality Open Source software, after all). This is good! It means that somebody is interested in your work, and that that somebody wants to help you make it even better.

Incorporating fixes into the Pull Request (i.e. "Rewriting the topic branch")

Now, the way we like to handle such improvements is to rewrite the topic branch. That means that you use Git to rewrite some of your commits. In short, you would call

git rebase -i origin/master

(very sorry about the unintuitive command, it was called "edit-patch-series" first, but was then renamed to "interactive rebase" for consistency with the already existing "rebase" command). Essentially, this will open a text editor with an "edit script", i.e. a list of the commits you have on top of origin/master. They are all marked with the "pick" command.

If you replace one of them with "edit" before saving and quitting the editor, Git will apply the commits up until that marked commit and then let you do things on the command line, e.g. amending that commit. You would basically edit the files, make sure with "git diff" that the changes look correct, then call "git commit -a --amend" to rewrite the commit, then call "git show" to make sure that the result is correct.

Once the commit is rewritten, you can continue by calling

git rebase --continue

Once your topic branch is rewritten as desired, you have to force push the branch:

git push origin +HEAD

(The little "+" tells Git to go ahead overwriting the branch on the remote side, even if that would result in losing commits: this is okay, those commits are now obsolete because you rewrote them.)

Further reading: http://git-scm.com/book/en/Git-Tools-Rewriting-History (this also includes documentation how to split one commit into two).

Advanced topic branch rewriting

It is very common that some commit in a topic branch needs to be adjusted. For example, if a comment needed clarification, or if some added code's indentation made the code inconsistent with the rest. In that case, all you need is a little change on top of the original commit.

To this end, git commit has a --fixup option. You would make the desired adjusting change, then commit it with git commit --fixup <commit> where <commit> references the commit to rewrite (the most intuitive way to reference a commit is to look at the output of git log and copy the long hexadecimal string above the commit message). This will make a special commit that the --autosquash option of git rebase will interpret correctly and reorder the commits appropriately.

Example:

Let's assume that the commits in the topic branch read like this, from newest to oldest:

01234567 Add Javadocs
cafeca11 Add the --bling option
b7ab7ab7 Fix incorrect author information

Let's assume further that the commit purporting to fix the author had a typo in the fixed author name, and that that was pointed out by that author in a pull request.

To fix this, the developer would fix the author name in the source code and then commit it with git commit --fixup b7ab7ab7 and then rewrite the topic branch with git rebase --autosquash -i origin/master. After force-pushing the branch to update the pull request, the author will be very happy indeed!