This is excellent advice, Pascal.
I've added a slightly modified version of this to the New Committer
Handbook.
http://wiki.eclipse.org/Development_Resources/New_Commmitter_Handbook#Lower_the_Barriers
Thanks,
Wayne
On 03/09/2013 08:56 PM, Pascal
Rapicault wrote:
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".
Regards,
Pascal
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
mihini-dev@xxxxxxxxxxx
http://dev.eclipse.org/mailman/listinfo/mihini-dev
_______________________________________________
mihini-dev mailing list
mihini-dev@xxxxxxxxxxx
http://dev.eclipse.org/mailman/listinfo/mihini-dev
|