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.

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).