[mihini-dev] Git workflow

[Fabien Fleutot <fleutot@xxxxxxxxx>]

There are a couple of organizational decisions to make, to transition Mihini into a truly open-source, open-development project. One of them is how to use Git; this post is intended to start the ball rolling.

When Mihini was a closed-source project handled by a small team sharing the same office, we had very few Git usage rules, and that proved to be good enough. The situation is likely to become trickier, though: we'll have to handle external contributions, and external contributors will rely on online docs, including Git history, more than on coffee-machine discussions to figure out how the project works.

There are 3 families of Git workflows: merge, rebase, and pull requests. 

• Merge workflows show branching and merging in the public repository. They represent the way we develop more truthfully, but they tend to turn into an unreadable spaghetti mess. 
• In rebase workflows, before committing a set of changes, we graft them onto the top of the master branch *at commit time*, rather than when the feature's development started. It forces to rewrite history, but rewritten history is more readable. 
• Finally, pull requests is the Linux way: there's only one integrator per authoritative repo, he pulls changes from development repos when he receives pull requests. To me, it seems both over-engineered for a project of our size, and at odds with Eclipse's habits of trusting several committers on a project.

The basic merge workflow is to stay on our local master branch, and to perform "git pull; git push"  whenever the changes are to be published.

For the rebase workflow, all developments must be done on short-lived, local branches ("git checkout -b newfeature"). When the feature or bug fix is completed, we fetch the changes which occurred on master ("git fetch origin"), graft our commits on top of it (in branch newfeature, "git rebase master; git checkout master; git merge newfeature"), and push the resulting linear history back to Eclipse ("git push origin master"). It's often interesting to make the rebase interactive ("git rebase -i master"), to clean-up history before putting it back into master. In the common case where all the feature commits should be squashed into a single one, there's a "git rebase --squash master" option which does that without further questions.

My personal opinion: we want our Git history to be welcoming to other people, i.e. readable. The normal workflow should be the rebase one, and each commit should make sense by itself functionally (fixing one bug, providing one feature). In exceptional cases, where long developments went on in parallel for a long time, as happened e.g. when we switched the Airvantage protocol to M3DA, it makes sense to show the parallelism through a merge, but this should be the exception, not the rule.

I'm sure there are people here with relevant experiences and advices, either on high-level workflows or on Git command details!