Home

Welcome to the sailfish-qtcreator wiki!

Branching / committing policy

Please take care to separate any changes touching upstream code. Keep these in separate commits.

You can learn which code is "our" by comparing master branch to mer-x.y. The mer-x.y branch is basically the upstream x.y branch with our changes to upstream code collected on top of it by the mean of cherry-picking (ch-p) appropriate commits from the master branch.

sailfish/master <--merge-- sailfish/mer-x.y <--merge-- qt/x.y
sailfish/master ---ch-p--> sailfish/mer-x.y ---ch-p--> qt/x.y

New upstream is merged by

1. reseting the mer-x.y branch to the newer upstream (utilizing the ours strategy of git-merge),
2. cherry-picking our commits discarded with the reset, resolving possible conflicts and discarding commits which are no more needed
3. then merging the mer-x.y branch back to master, often using next branch as a staging area.

This way we

1. keep our changes to upstream code as a minimal patch set x.y..mer-x.y and
2. avoid conflicts resolution in a single huge merge commit

The following command provides an overview of the process.

gitk --simplify-by-decoration sailfish/master ^v4.0.1 ^sdk-1608

Time has shown that the use of the ours strategy of git-merge for resetting is not ideal. It leads to such order of parent commits that makes the history harder to look at. It would be better done the opposite way, but the opposite theirs strategy was unfortunately removed from git-merge earlier. We continue consistently using this not so ideal approach and use git-replace to correct the order of parents of the concerned commits as in this example:

git replace --graft "$commit" "$commit"^2 "$commit"^1

To see the effect, the replacements must be explicitly fetched e.g. with command:

git fetch sailfish 'refs/replace/*:refs/replace/*'

After that, the following command provides much cleaner overview of the process.

gitk --simplify-by-decoration sailfish/master ^qt/master

(When used without fetching the replace objects, it provides an incomplete view.)

The git-lltb tool is able to provide a transformed view of the mer-x.y branch, with the original commits between each pair of consecutive tags represented as patch files added by single commit. This allows to inspect the commits as an evolving patch set. Use either the version from your platform SDK chroot or download the latest version from https://github.com/sailfishos/sdk-setup/blob/master/sdk-setup/src/git-lltb. (In order to use gitk to visualize the transformed history, run the tool outside the SDK chroot.)

git-lltb patch-view --tool gitk mer-x.y qt/master

The following command helps deciding which changes should be cherry-picked to a mer-x.y branch - we aim to minimize the diff:

git diff mer-X.Y..master -- * ':(exclude)'{\
src/plugins/mer,\
doc,\
src/plugins/qmldesigner/jollaplugin,\
share/qtcreator/sfdk,\
share/qtcreator/templates/wizards/sailfishos-qtquick2app,\
share/qtcreator/translations/sfdk_modules_tr.pro,\
dist/gdb,\
src/tools/{merssh,sdktool/*sfdk*,sfdk},\
src/libs/sfdk,\
tests/manual/mer,\
*.ts\
}