How to contribute

Introduction

The NAR project is completely driven by user contributions, from people like you!

The NAR project uses GitHub's Issue Tracker and Pull Request (PR) features for managing known issues and contributions in a community-driven way. In some cases, frequent contributors may earn direct commit rights to expedite their workflow.

Open issues are classified into three types:

• New issues have not yet been assigned a milestone, and await maintainer review.
• Active issues have an assignee and are being actively discussed and/or developed. They typically are PRs, or become PRs as soon as possible.
• Dormant issues are known defects, feature requests, etc., but on which there is no active development or discussion. They belong to the "unscheduled" milestone.

The NAR project closes issues only when they reach a final resolution (e.g.: fixed, wontfix or invalid).

With this approach:

• Community members can:
  • Check open issues to avoid filing duplicates.
  • Look at dormant issues to browse potential contribution points.
• Project developers can:
  • Track their current work as active PRs.
  • Track and discuss possible future work as dormant issues.
• Project maintainers can:
  • Browse issues needing attention without clutter from old passive issues.

Workflow guide

This section describes the mechanics of working with Git and GitHub.

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.

When it comes to the commit message, it is good practice to avoid repeating what is easily deduced from the code changes. Instead, try to describe aspects of the solved problem, or the added feature, that the reader might not be aware of, or that do not come to mind easily when reading the code change. For example, you might want to describe why different ways to solve the issue are not complete, or to link to further information. Please use e8851c83 and b82186847 for inspiration.

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

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. Example:

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

If you replace one of them with "edit" before saving and quitting the editor, Git will apply the commits up until, and including, that marked commit and then let you do things on the command line, e.g. amending that commit. The files in question then need to be edited, the changes verified with "git diff", and then the commit needs to be rewritten using git commit -a --amend. You should then call "git show" to make sure that the result is correct (if not, rinse and repeat).

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!