Branching Strategy

Branches

There exist a few important branches in the Stellarium repository.

• master branch: branch used for producing releases. Commits in this branch should not break compilation or introduce bugs.
• release branch: (to explain)
• 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 and remember that you must re-test a rebased branch before pushing.
• 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 and commit as needed>
git push -f origin HEAD:mybranch

This rebasing is OK on branches developed by single or closely coordinated team members. In general, beware of "changing history" too much.

• you should always close all applications (such QtCreator) before starting a rebase, otherwise directory permission conflicts and incomplete disc synchronisation issues are very likely to occur. This also holds true when committing.
• if you need to merge some fixes from a maintenance branch to master, it is better to cherry pick the patches instead of merging
• be aware that files managed by some applications (XML and the like, config, JSON, ...) can be very tricky to merge/rebase due to their "pseudo-binary" nature. It is exceptional that such applications provide features to perform merging. Sometimes the only solution to merging/rebasing is to manually perform the three-way merge by opening all required instances of the objects in separate instances of the editor application, and carefully reapply and recombine all edit actions. This is a far from trivial process that is likely to produce bugs.

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), commit these changes and 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

# update from Launchpad, auto-merge with currently edited files
bzr update                        

<maybe resolve merge conflicts>

# send changes to Launchpad
bzr commit -m "fixed bug LP:4563" 

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

Note: try to avoid making git pull a habit, because pull can create a mess when attempting the automatic merge. The recommended way of working it to first run a git fetch and then decide if merging, rebasing or cherry picking is the way forward.

Friendlier remote names

Git uses default names for repositories, such as origin. This is an unfortunate default value, as it can be confusing and can be a problem when you routinely push to different repositories within a project.

When you track several repositories (of course including stellarium, the main one), it can help to rename repositories using folder names.

git remote # lists all you repositories

# rename the official repo to a friendlier name

git remote rename origin stellarium

# rename your public repo

git remote rename <whatever> my-github

# group all remote user repositories

git remote add user/abalkin 	https://github.com/abalkin/stellarium.git
git remote add user/ray		https://github.com/rayw000/stellarium.git
git remote add user/ultrapre	https://github.com/ultrapre/stellarium.git

# now the listing becomes far more nice
git remote

my-github
stellarium
user/abalkin
user/ray
user/ultrapre

Note: upstream is also a good suggestion to replace origin.

Manage branch names

You will soon discover that you will be submerged by local as well as remote branches. Git offers a powerful feature to manage this namespace, by allowing to move branch names (as well as remotes) into subdirectories

Here is an example.

git branch --remotes | grep "stellarium/"

...
  stellarium/SH_AlmagestSkyculture
  stellarium/african-sky-cultures
  stellarium/android-port
  stellarium/astrocalc-ephemeris-refactoring
  stellarium/avoid-sun-streak
  stellarium/aw_svgTextureSupport
  stellarium/catalan-sc
  stellarium/coverity_scan
  stellarium/debian-packaging
  stellarium/dynamic-mgr-plugins
  stellarium/fix-orbit-lines
  stellarium/fix-orbits
  stellarium/fix-orbits2
  stellarium/fix_telrad
  stellarium/gz_AtmosphereTweaks
  stellarium/gz_aberration
  stellarium/gz_curvatureFix
  stellarium/gz_reduceOpenGLstateChanges
...

# by moving branch names into "subdirectories" one can achieve a better overview:

git branch rename stellarium/SH_AlmagestSkyculture stellarium/feature/SH_AlmagestSkyculture
git branch rename stellarium/gz_aberration stellarium/user/gz/feature/aberration
...

# Here is what can be achieved:
# notice that even in this example, improvements are possible!

git branch

...
  contrib/1315/comet-icon
  contrib/algol-types
  contrib/astrocalc/iprove-graph-label
  contrib/astrocalc/notes
  contrib/dbl-click-shortcut
  contrib/dlg
  contrib/general/startpage
...
  user/ajk-alex
  user/ajk/navstar
  vendor/etwright/almagest
...

This approach allows you to keep a high level overview by grouping branches that logically belong together (eg contributor branchess, main branches such as master and release, tests, maintenance branches, vendor branches, etc). This also applies to names of remotes and tags.

Such approaches will prevent a explosion of names in the namespaces of remotes, branches and tags.

In some Git clients (such as e.g. SourceTree), using subdirectories in names will produce a nice tree of remotes, branches and tags.

Note: Git implements this tree by physically using subdirectories; this means that you cannot create objects (names of remotes, branches, tags) that exist as a directory. Take a look at .git/ to discover this.

Clean up!

From time to time, perform some cleanup, get rid of old branches, etc:

git fetch --prune --prune-tags --verbose
git prune --verbose
git gc