Hacking on darktable¶
- Table of contents
- Hacking on darktable
- 1. Discuss your planned changes (if you want feedback)
- 2. Create GitHub account
- 3. Fork darktable into your account
- 4. Clone your newly forked copy onto your local workspace
- 5. Add a remote ref to upstream, for pulling future updates
- 6. As a precaution, disable merge commits to your master
- 7. Build darktable
- 8. Pulling later updates from upstream
- 9. Pushing pulled updates (or local commits if you aren't using topic branches) to your private github repository (origin)
- 10. Make sure there is an issue for the enhancement/fix
- 11. Create a simple topic branch to isolate that work (just a recommendation)
- 12. Make the changes and commit one or more times (Don't forget to push)
- 13. Rebase your branch against the latest master (applies your patches on top of master)
- 14. Get your changes merged into upstream
1. Discuss your planned changes (if you want feedback)¶
- On the developer mailing list
- On IRC
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¶
3. Fork darktable into your account¶
4. Clone your newly forked copy onto your local workspace¶
$ git clone firstname.lastname@example.org:[your user]/darktable.git $ cd darktable
5. Add a remote ref to upstream, for pulling future updates¶
$ git remote add upstream git://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¶
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¶
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¶
- 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.
- Send a github pull request, by clicking the pull request link while in your repo's fork
- An email will automatically be sent to the committers
- After review a maintainer will merge your patch, update/resolve issues by request, and reply when complete
- Don't forget to switch back to master and pull the updates
$ git checkout master $ git pull --ff-only upstream master
- 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 are use 'git status' on your local master branch.
$ git push origin master
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