Developer's Guide

Drop in #coinium-dev channel in freenode for dev-talk.

git configuration

Line endings

In your .gitconfig, you need to set core.autocrlf to input, like so:

git config --global core.autocrlf input

This will convert line endings to LF when committing (the standard) and back to whatever your system uses when you pull. Also, GitHub's help page lies to you about this; it is actually correct to use input on all OSes.

If you don't want this to be the top-level configuration for git, just remove the --global bit (but make sure you change it when your current directory is in a/the coinium repository). If you choose to do it this way, you must make sure it is set on your copy of all coinium repositories (main/documentation/site/etc.)

Forking

See here for help. Once you've made a fork, add a remote repository pointing to the primary upstream repository with:

git remote add upstream git://github.com/CoiniumServ/CoiniumServ.git

Then you can continually use git pull upstream master to keep in-sync with the changes made upstream.

Only after you pull upstream into your master should you push to your fork and open a pull request. This is to prevent giving us a bunch of extra work having to ensure that you didn't screw something up. It also makes it easier to see what you've changed.

If you are going to delete your fork, you must delete or close any pending pull requests (or wait for them to be merged). GitHub doesn't like it when you do that.

Conflicting merge commits

When merging a conflicting branch with upstream, do not remove the automatically-inserted list (in the commit message) of conflicting files.

Pull requests

A pull request (PR) is the primary way to push your changes upstream. We encourage you to send us anything that you deem appropriate for the master branch. We do not accept requests from a fork that is not up-to-date with upstream, so please don't send them unless you're fully up-to-date (this is to prevent rogue merges where one branch breaks something upstream, due to conflicting with upstream or (more often) in some other obtuse, generally unexplainable cases). If you need help sending a PR, see here.

We will typically only merge a PR when it is described adequately and follows the design and coding style of the repository.

Commits/PRs we will (typically) not merge:

• With commit message(s) "Edited ... via GitHub": because we're not going to test or traverse your diff in an attempt to understand your commits without a summary - unless we feel like yelling expletives at our monitors. There is a text box for the commit message below the edit box: use it. Or get a proper git client and make proper commits like the rest of us. These kinds of commits are explicitly refused due to not being able to tell what the commit does in commands like git log (without consulting the diff).
• With no or inadequate descriptions (sometimes you may pass by being descriptive enough in commit messages, but it is best to properly describe a PR. Even a summary of the commits will suffice, though this does not exclude you from writing proper commit messages in the first place).

A proper commit or PR will:

• Reference any issues (#XYZ in the commit or PR description, where XYZ is the issue number) that have been fixed (or for other reasons).
• Aptly describe what has been fixed/changed rather than, for example, "ponies weren't working right", where "ponies weren't working right" has presumably been 'fixed'.

A PR's description is best kept as a summary of the commits therein. Rule of thumb is:

• PR descriptions are verbosely descriptive summarisations.
• PR titles are a conciser version of the description.

If you want to avoid an active PR from picking up all of your commits to your master branch, you should work in a separate branch and only merge back to your master when the PR is closed (or if you want to include the commits from the branch in the PR). This can also be prevented by setting the PR's range to end at the last commit made, though in that setup you can't put any more commits in the PR since the range stops at a specific commit rather than the entire master branch.