|The git workflow is one thing but in the end this is of very little relevance to the success of the project.|
Through my involvement at Eclipse and other OSS communities, I think that the most critical aspect is to "lower the barrier of entry" for both contributors and users.
- For contributors:
- Make it easy for people to find the starting point. Where is the code, how to build it, running the tests, etc.
- Make the contribution process clear. How to contribute patches (patch attached, gerrit, ...), etc.
- Make the schedule clear. Build schedule, delivery schedule, etc.
- Take the important decision in the open. Of course this is not about having every single chit/chat to be captured on the ML or a bug report (after all you don't want to sacrifice the efficiency of your tightly knit team) but rather make sure that decisions and the reasoning are captured somewhere. For example in p2 even when we took a decision over lunch, we would always make sure that the final resolution and the whys were captured in a bug report so people could interject (we mostly did all of our activity tracking in bugzilla).
- Team meeting phone calls. I don't know if many project do that, but it definitely is a great way to all get on the same page. From the beginning of p2 and for about 3y, we had a weekly phone call where we would discuss the schedule, the on-going work, but also the more complex / controversial technical things which would have not been easy to take care of by email (e.g. p2 QL, API review).
- For users:
- I think a 5min tutorial is of great use and help captures the audience.
- Where to go to ask question (btw, you probably want to decide whether you want to separate the user ML from the dev one)
- Great documentation, with a lot of ready to go example (monkey see, monkey do :))
All of this may sound pompous, and I'm sure you knew most of it, but I just hope it helps. And as the saying goes "do as I say, don't do what I do".
On 2013-03-08, at 1:04 PM, Fabien Fleutot wrote:
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.f
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!
mihini-dev mailing list