Could you expand a bit on the “number of issues” that remain if it’s
functionally complete? Is there a published list of things that need
to be in place for something to be mainlined, in general, or are
these issues only for Rxk5?
Marcus has pointed out that you were asking a more general question,
and it occurred to me that, whilst I've talked about these issues at
both the Stanford and Rome Workshops, there are folks who won't have
been to either. So, here's a rough summary of what I think the process
of getting code upstream is. Bear in mind that I'm very much a single
voice here, and what I say has no more weight they anyone else - but
I've said this lot a few times now without getting shouted down...
Firstly, any changes to the protocol have to go past the afs3-
standardisation list. This effectively means anything on the wire, but
may also extend to (for example) the pioctl interfaces when there are
multiple implementations of these. Proposals should be presented in
the form of an internet draft. We're still coming up to speed on how
these get dealt with - at present, the level of comment generally
depends on the scale of the change. If the proposal is for a minor
tweak to a debugging interface, it's likely to get through easily. If
it's a wholescale change to a fundamental bit of AFS, then things will
take longer, and probably involve actively soliciting responses.
Secondly, any major changes should be discussed before they're
implemented. The openafs-devel list is the best place to do this. It
is of course up to an author what to do with the feedback they
receive. My general advice would be to listen carefully if there are
suggestions that the fundamental approach is wrong, but to be cautious
of demands for feature creep. One key point is that the people
commenting now are the people who'll be reviewing the finished code.
If nobody agrees that an approach is the best solution now, finding
reviewers when it comes to getting it into the tree is likelyto be
difficult. It's at this point that it'll also be possible to get an
idea of when merge windows are available for this kind of change.
Typically, large scale changes won't be accepted, even into the
development branch, around branch points for stable releases.
Thirdly, code gets written, with steps one and two repeating as
required. If it's a large project, please keep the community informed,
especially if you are significantly changing previously discussed
designs. When coding, bear in mind that the tree has a documented
coding style, which should be followed as far as possible. Try and
keep your code as small modular chunks. Consider, as you write it, how
it would make sense to split it for an upstream contribution. If your
code requires interface changes, then split off these changes, and
make them separate commits. Avoid bundling unrelated changes in with
your core work - if you need to fix bugs in existing code, then make
those changes as separate patches, and contribute them as you work.
Cutting down the size of you main code drop will make the final
integration steps much much easier.
At the end of all of this, there will be a collection of code to
contribute as a set of patches. The rough guidance here is that there
should be one patch per change, and one change per patch - but good
judgement is necessary as 10,000 individual 10 line patches are no
more manageable than a single 100,000 line patch.
The key thing to consider when splitting code into patches is that the
people who review them are volunteering their time to do so - there's
no commitment upon them to spend time evaluating any code, so
contributors should make it as easy for them as possible. This is one
reason why breaking large changes up makes life easier - it's a lot
easier for reviewers to find spare hours here and there, than it is to
contemplate looking at something that's obviously going to take days
to get through. Also, a set of sensibly created patches is far easier
to review, and to test, than a single monolithic change. Providing
reviewers with a guide to the code is hugely helpful - either through
commit comments, in-tree design documentation, or a separate document.
Contributors should expect that their code won't be accepted first
time round. There are likely to be nits picked up by the review
process, although the more communication that's occurred at the
beginning, the less significant those nits are likely to be.
The final issue I'd like to address is that of _when_ code should make
its way into the development branches. Maintaining code out of tree is
hard - keeping it up to date is a pain - and people will often break
code that's not in the tree (or even that is in the tree, but on a
different branch) simply because they don't realise its there, or
don't test against it. This leads to a general desire by contributors
to get code in as quicky as possible. However, there is a flip side.
There are a lot of developers working off the main branch, and
committing code that breaks the tree or the build is a bad thing. Once
code has gone in, the longer it remains in the tree, the harder it
becomes to remove it. This is a real problem when a new 'stable'
branch is required - if the development branch is broken, how do you
create the new stable branch. This is exactly the state of affairs
that demand attach left us in - with a development branch that was too
broken to even consider creating a 1.6 from, but with a set of changes
that it would be hugely timeconsuming to unpick from the rest of the
code. There is, of course, the question of branching earlier - you
have 'stable', 'development' and 'very bleeding edge'. But this just
shifts the problem slightly sideways. Additionally, each new branch
creates significantly more work for everyone - as patches need to be
created, tested, and committed against each new branch.
So, I think the best answer is 'when its ready' and 'not near proposed
branch points'. Lots of projects have clearer answers to these
particular questions - for example, Linux has its merge windows, and
Mozilla has code freezes around releases, where no feature commits are
permitted. I'd argue that OpenAFS probably wants to adopt something
along these lines too, along with a clearer set of data driven targets
for stable release. But that's an argument for another email.
I should round off by saying that absolutely none of this is specific
to OpenAFS - they're all just part of a functioning Open Source eco
system. If you're interested, I'd highly recommend reading:
How to Participate in the Linux Community (A Guide to the Kernel
Development Process)
http://ldn.linuxfoundation.org/how-participate-linux-community
Mozilla Hacker's Getting Started Guide
https://developer.mozilla.org/en/Mozilla_Hacker's_Getting_Started_Guide
or any other big projects' developer guidelines - we're all struggling
with the same problems!
Hope that helps,
Simon.
_______________________________________________
OpenAFS-info mailing list
[email protected]
https://lists.openafs.org/mailman/listinfo/openafs-info
