IDEA Development Collaboration Best Practices

Introduction

This document attempts to standardize the collaboration procedures when contributing to IDEAconsult's repositories on GitHub. The main goal is to ensure efficiency and consistency in the work process and the overall quality of the final product.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

TL;DR

• Use pull requests whenever possible. Direct commits to master are acceptable only for trivial changes.
• Use separate branches for each enhancement or fix you're working on, unless the circumstances dictate otherwise.
• Give the branches appropriate names, e.g. fix/238 (where 238 is the issue number) or ehn/my-awesome-feature.
• DO NOT merge new commits from master to your branches: either rebase your branches to master or wait till the final merge into master. See Avoiding automatic merges on pull below.
• Once the branch is ready to be merged, rebase it again, preferably interactively. It SHOULD be able to be fast forwarded (--ff-only) even if a merge commit (--no-ff) is planned.

Short step-by-step

1. Fork the repo you want to contribute to into your account.
2. git clone https://github.com/youraccount/forkedrepo (q.v. git clone)
3. git remote add upstream https://github.com/ideaconsult/forkedrepo (optional, see Rebase below, q.v. git remote)
4. git checkout -b enh/coolfeature (q.v. git checkout, git branch, in GitHub)
5. Make your commits.
6. Rebase (optional, but highly desirable unless circumstances dictate to use merge):
   1. git fetch upstream master
   2. git rebase -i upstream/master
   3. Use the appropriate commands for each of your commits. In particular, you may want to squash/fixup commits that had only been intermediate stages. Remember that rebase rewrites the branch history! (q.v. git rebase, squash et al.)
   4. git push -u origin enh/coolfeature (note that you MUST push to your forked repo, not to the original one you forked from; q.v. git push, git remote)
   5. Create a pull request for the original repo from your newly pushed branch.
   6. If necessary, continue pushing commits to that branch, while rebasing if master is updated, until the pull request is accepted.

Advanced topics

Keeping your fork up-to-date

For more detailed information, see Syncing a fork.

1. git fetch upstream
2. git checkout master (or whatever branch you want to sync)
3. git merge upstream/master (remember that in general you MUST keep your own commits in separate branches!)
4. git push origin master (remember that origin is the remote name of your fork; see git remote -v)

Avoiding automatic merges on pull

To avoid the undesired automatic merge and attempt automatic rebase instead, set the following Git option in one of the two ways:

• for this repo only:

git config pull.rebase true

• for all Git repos:

git config --global pull.rebase true

After setting the option, if are remote commits that you don't have locally the automatic rebase may fail. In these cases you'll need to resolve the conflicts by yourself. See git rebase for further details.

Notes

If the above steps aren't carried out, recent versions of Git produce the following warning:

hint: Pulling without specifying how to reconcile divergent branches is
hint: discouraged. You can squelch this message by running one of the following
hint: commands sometime before your next pull:
hint:
hint:   git config pull.rebase false  # merge (the default strategy)
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.