[1837] in BarnOwl Developers
barnowl development workflows
daemon@ATHENA.MIT.EDU (Nelson Elhage)
Thu Oct 29 18:22:59 2009
Resent-From: nelhage@mit.edu
Resent-To: barnowl-dev-mtg@charon.mit.edu
X-Original-To: nelhage@lunatique.mit.edu
Date: Sat, 24 Oct 2009 12:45:31 -0400
From: Nelson Elhage <nelhage@MIT.EDU>
To: barnowl-dev@mit.edu
BarnOwl development has picked up a bunch recently, and we've started
to get a broader community of contributors working on the project.
In light of this increased development, I think it'd be useful to try
to somewhat better define procedures for contributing to barnowl,
reviewing code, merging code to master, and doing builds and releases.
What follows is my suggestion for a workflow for how development
should work. I hope to see some discussion of these suggestions, and
that we will settle on some more-or-less consistent pattern. I don't
necessarily want to establish an absolute policy that must be followed
at all costs. My main hope in this email is to start discussion, so we
can figure out workflows that work for all of us.
That said, here's my rough ideas:
* We should try to keep master fairly stable at all times. This will
improve the utility of doing regular builds, and git should make it
easy for development of more risky features to happen on a different
branch.
QUESTION: Should we always have two "stable" and "less stable"
branches, instead of only when stabilizing for a locker build? If
so, what should the workflow there look like?
* In part to this end, nearly all code that goes to master should be
reviewed and acked by at least one other developer.
I don't think it's important at this point to define who is allowed
to ACK what. If the author and the reviewer both feel confident in
their ability to assess the change, that's fine.
Larger changes, such as significant refactorings or design of
non-trivial features, should, whenever possible, be informed by
broader discussion.
* An important part of code review is explicit communication from
the reviewer. If you are reviewing a piece of code, it's very
important to be clear when you are happy with the code. If you
have comments, state them. If you don't have comments, and feel
qualified to ack the code, say so clearly so that the author knows
so.
I will generally reply to review requests with some comments, and
either an Acked-by: or Signed-of-by: line. The former means that I
agree with the idea of the code, but either want to see changes
before I'm totally happy, or don't feel qualified to review
it. The latter means I would be happy to see it go to master.
QUESTION: Is it useful or worthwhile to have an explicit
convention of sign-offs, and including them in commits or merges
to track code review?
* Code review should not excessively increase the activation energy
of getting code to master, or overly delay the process. Reviewers
are encouraged to, in general, prefer finding solutions to
problems that can get code in sooner rather than later, and avoid
blocking bugfixes and features on excessively picky aesthetic or
design issues when possible.
* While Zephyr is a very convenient forum for discussion, discussion
of larger design decisions or review of non-trivial branches should,
in general, happen at least largely over email (to
barnowl-dev@mit.edu). Conclusions reached on Zephyr in response to
discussion on email should be communicated back to the list in a
timely fashion.
In addition, developers should not be required to read Zephyr logs,
in general. In particular, I will tend to ignore review requests on
zephyr unless I am free to process them at the moment they come in,
whereas I will make an effort to ensure that any requests to email
get handled eventually.
I see two related reasons for this preference, all related to the
fact that email tends to be more persistent than zephyr.
(1) It is harder for review requests or discussion to get dropped
and forgotten about over email, since, in general, I think most
of us have better workflows for ensuring that email is not
drooped.
(2) Email discussions tend to be somewhat more structured and easy
to follow after the fact. This is important both so that
developers who are not on zephyr all the time can effectively
follow discussion, and so that developers can refer to past
discussion. I intend to request a discuss archive for
barnowl-dev to help with this.
A third, less significant but still relevant issue, is that I would
like to work towards a future in which barnowl is generally useful
as an IM client outside of Zephyr, which means that developers not
on Zephyr would need to be able to participate in the development
process.
QUESTION: These points are based in part on my own preferences and
workflows around Zephyr and email. Do other people agree with them,
or do you feel that the convenience and immediacy of zephyr counts
for more?
* I hope to soon set up weekly builds into the locker (probably under
the barnowl-beta name), in order to get better testing of barnowl
development, and to get features to our users faster.
* In conjunction with the weekly builds, roughly once a month or so
I plan to move the previous week's build, plus any bugfixes and
small changes since then to the 'barnowl' name in the locker. I
have not decided whether this will also always be accompanied by a
release to the website, or not.
* I don't care, in general, whether you merge branches to master or
rebase them on top of master. However, it is worth noting that if a
branch is to be developed on by more than one person, it is
important that it not be rebased in order for life not to suck
horribly.
If we do decide to make a regular policy of having release or
stabilization branches, however, I will want to consider using
merges more often.
I think that's it, for my thoughts for now. I would appreciate
comments on any of this.
- Nelson
