Hacking on darktable

1. Discuss your planned changes (if you want feedback)

• On IRC
• On the developer mailing list

Of course you can start coding without talking to us beforehand but be prepared that you might waste your time that way. We won't accept every patch just because it's there.

2. Create GitHub account

http://www.github.com

3. Fork darktable into your account

https://github.com/darktable-org/darktable

4. Clone your newly forked copy onto your local workspace

$ git clone [email protected]:[your user]/darktable.git
$ cd darktable

5. Add a remote ref to upstream, for pulling future updates

$ git remote add upstream https://github.com/darktable-org/darktable.git

6. As a precaution, disable merge commits to your master

$ git config branch.master.mergeoptions --ff-only

7. Build darktable

$ ./build.sh

8. Pulling later updates from upstream

$ git pull --rebase upstream master

Please note that --rebase is very important if you do have commits. What happens is that when git pull can't fast forward, it does a merge commit, and a merge commit puts the sucked in changes ON TOP of yours whereas a rebase puts them BELOW yours. In other words a merge commit makes the history a graph, and we prefer a cleaner, easier to follow linear history (hence the rebasing). Further once you do a merge commit it will be difficult to rebase the history before that commit (say you want to combine two commits to one later) as described in point 13. Luckily the option set in step 5 will prevent this from happening.

One way to not forget --rebase the rebase option is you may want to create an alias

$ git config --global alias.up "pull --rebase"

and then just use the new alias instead of pull

$ git up upstream master

9. Pushing pulled updates (or local commits if you aren't using topic branches) to your private github repository (origin)

$ git push

You might need to say -f to force the changes. Read the note on 12 though before you do it.

10. Make sure there is an issue for the enhancement/fix

https://github.com/darktable-org/darktable/issues

11. Create a simple topic branch to isolate that work (just a recommendation)

$ git checkout -b my_cool_feature

12. Make the changes and commit one or more times (Don't forget to push)

$ git commit -m '[Issue #XXXX] My Cool Feature'
$ git push origin my_cool_feature

Note that git push references the branch you are pushing and defaults to master, not your working branch.

Please make sure that your commit messages follow the format that is generally considered nice: A short summary in the first line, no more than 50 characters long. When you can't put everything in that one line, then add one empty line and then a more verbose description with lines no longer than 78 characters. The reason for this is that commit messages formated like this can nicely be sent as emails and read in the terminal.

13. Rebase your branch against the latest master (applies your patches on top of master)

$ git fetch upstream
$ git rebase -i upstream/master

# if you have conflicts fix them and rerun rebase
# The -f, forces the push, alters history, see note below

$ git push -f origin my_cool_feature

The -i triggers an interactive update which also allows you to combine commits, alter commit messages etc. It's a good idea to make the commit log very nice for external consumption. Note that this alters history, which while great for making a clean patch, is unfriendly to anyone who has forked your branch. Therefore you want to make sure that you either work in a branch that you don't share, or if you do share it, tell them you are about to revise the branch history (and thus, they will then need to rebase on top of your branch once you push it out).

14. Get your changes merged into upstream

1. Make sure your repo is in sync with other unrelated changes in upstream before requesting your changes be merged into upstream by repeating step 13.

2. Send a github pull request, by clicking the pull request link while in your repo's fork

3. An email will automatically be sent to the committers

4. After review a maintainer will merge your patch, update/resolve issues by request, and reply when complete

5. Don't forget to switch back to master and pull the updates

   $ git checkout master
$ git pull --ff-only upstream master

Then to update the master branch of your github repository (otherwise you will see a message like 'Your branch is ahead of 'origin/master' by XXX commits.' if you use 'git status' on your local master branch):

$ git push origin master

Committers

The committers will make sure that the pull request submitted is rebased against the branch in question, and is up-to-date.

The pull request will be merged using the GitHub pull request merge functionality, the below script or a similar method:

#!/bin/bash

git fetch upstream
git checkout master
git rebase upstream/master

cmd="git fetch upstream "
for var in "$@"
do
cmd="$cmd pull/$var/head:pullRequest$var"
done

$cmd

for var in "$@"
do
echo Merging PR $var
git checkout pullRequest$var
git merge --ff-only pullRequest$var
git branch -D pullRequest$var
done