Branching Strategy

Branches

• Master branch: branch used for producing releases. Commits in this branch should not break compilation or introduce bugs.
• Feature branches: short-lived branches used e.g. for Pull Requests

git checkout -b my-new-feature-branch
<edit as you need>
git stage <files>
git commit
git push --set-upstream origin my-new-feature-branch

• Maintenance branches, named after the stable release series e.g. "0.15". They are used to maintain older series of Stellarium, mostly to fix bugs

Try to keep a linear git history on master

• merge commits to master should be avoided. Rebase your feature branches before pushing them to master
• some branches take long to develop. Rebase them occasionally to let them "grow out of the current master".

git checkout mybranch
git rebase master
<fix issues>
git push -f origin HEAD:mybranch

This rebasing is OK on branches developed by single team members. Else beware of "changing history" too much.

• You may need to exit QtCreator before starting a rebase, else there may be directory permission conflicts.
• if you need to merge some fixes from a maintenance branch to master, it is better to cherry pick the patches instead of merging

Various tips and tricks

I keep rebasing, and run into the same merge conflicts each time.

Use git's rerere feature:

git config --global rerere.enabled true

This will cache your merge resolution and can automatically apply it next time you rebase.

Oops - forgot branching

Sometimes it can happen that you start to add some changes in your master without making a branch first. "Just try out something". Then you are interrupted and should continue elsewhere. You can stash your work and unstash it into a new branch.

git stash
git stash branch my_little_changes_which_need_more_thoughts

This also switches to the new branch. To continue in the master branch (just to compile it cleanly), git checkout master again. You will also see the new branch listed via git branch.

I am coming from the older BZR repository. What are critical differences?

In BZR we usually had one complete Checkout per branch. Before committing into a commonly developed branch, we did

bzr update                        [ update from Launchpad, auto-merge with currently edited files ]
<maybe resolve merge conflicts>
bzr commit -m "fixed bug LP:4563" [ send changes to Launchpad ]

With git, we commit our changes into the local repository, and only then pull in updates from the remote repository. In order to achieve a clean history, we must rebase our local changes.

git stage
git commit 
git pull --rebase
<resolve any merge conflicts>
git push