[OpenAFS] rxk5 Mainline Issues?

[Simon Wilkinson]

> Could you expand a bit on the =93number of issues=94 that remain if =
it=92s =20
> functionally complete? Is there a published list of things that need =20=

> to be in place for something to be mainlined, in general, or are =20
> these issues only for Rxk5?

Marcus has pointed out that you were asking a more general question, =20
and it occurred to me that, whilst I've talked about these issues at =20
both the Stanford and Rome Workshops, there are folks who won't have =20
been to either. So, here's a rough summary of what I think the process =20=

of getting code upstream is. Bear in mind that I'm very much a single =20=

voice here, and what I say has no more weight they anyone else - but =20
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-=20
standardisation list. This effectively means anything on the wire, but =20=

may also extend to (for example) the pioctl interfaces when there are =20=

multiple implementations of these. Proposals should be presented in =20
the form of an internet draft. We're still coming up to speed on how =20
these get dealt with - at present, the level of comment generally =20
depends on the scale of the change. If the proposal is for a minor =20
tweak to a debugging interface, it's likely to get through easily. If =20=

it's a wholescale change to a fundamental bit of AFS, then things will =20=

take longer, and probably involve actively soliciting responses.

Secondly, any major changes should be discussed before they're =20
implemented. The openafs-devel list is the best place to do this. It =20
is of course up to an author what to do with the feedback they =20
receive. My general advice would be to listen carefully if there are =20
suggestions that the fundamental approach is wrong, but to be cautious =20=

of demands for feature creep. One key point is that the people =20
commenting now are the people who'll be reviewing the finished code. =20
If nobody agrees that an approach is the best solution now, finding =20
reviewers when it comes to getting it into the tree is likelyto be =20
difficult. It's at this point that it'll also be possible to get an =20
idea of when merge windows are available for this kind of change. =20
Typically, large scale changes won't be accepted, even into the =20
development branch, around branch points for stable releases.

Thirdly, code gets written, with steps one and two repeating as =20
required. If it's a large project, please keep the community informed, =20=

especially if you are significantly changing previously discussed =20
designs. When coding, bear in mind that the tree has a documented =20
coding style, which should be followed as far as possible. Try and =20
keep your code as small modular chunks. Consider, as you write it, how =20=

it would make sense to split it for an upstream contribution. If your =20=

code requires interface changes, then split off these changes, and =20
make them separate commits. Avoid bundling unrelated changes in with =20
your core work - if you need to fix bugs in existing code, then make =20
those changes as separate patches, and contribute them as you work. =20
Cutting down the size of you main code drop will make the final =20
integration steps much much easier.

At the end of all of this, there will be a collection of code to =20
contribute as a set of patches. The rough guidance here is that there =20=

should be one patch per change, and one change per patch - but good =20
judgement is necessary as 10,000 individual 10 line patches are no =20
more manageable than a single 100,000 line patch.

The key thing to consider when splitting code into patches is that the =20=

people who review them are volunteering their time to do so - there's =20=

no commitment upon them to spend time evaluating any code, so =20
contributors should make it as easy for them as possible. This is one =20=

reason why breaking large changes up makes life easier - it's a lot =20
easier for reviewers to find spare hours here and there, than it is to =20=

contemplate looking at something that's obviously going to take days =20
to get through. Also, a set of sensibly created patches is far easier =20=

to review, and to test, than a single monolithic change. Providing =20
reviewers with a guide to the code is hugely helpful - either through =20=

commit comments, in-tree design documentation, or a separate document.

Contributors should expect that their code won't be accepted first =20
time round. There are likely to be nits picked up by the review =20
process, although the more communication that's occurred at the =20
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 =20=

its way into the development branches. Maintaining code out of tree is =20=

hard - keeping it up to date is a pain - and people  will often break =20=

code that's not in the tree (or even that is in the tree, but on a =20
different branch) simply because they don't realise its there, or =20
don't test against it. This leads to a general desire by contributors =20=

to get code in as quicky as possible. However, there is a flip side. =20
There are a lot of developers working off the main branch, and =20
committing code that breaks the tree or the build is a bad thing. Once =20=

code has gone in, the longer it remains in the tree, the harder it =20
becomes to remove it. This is a real problem when a new 'stable' =20
branch is required - if the development branch is broken, how do you =20
create the new stable branch. This is exactly the state of affairs =20
that demand attach left us in - with a development branch that was too =20=

broken to even consider creating a 1.6 from, but with a set of changes =20=

that it would be hugely timeconsuming to unpick from the rest of the =20
code. There is, of course, the question of branching earlier - you =20
have 'stable', 'development' and 'very bleeding edge'. But this just =20
shifts the problem slightly sideways. Additionally, each new branch =20
creates significantly more work for everyone - as patches need to be =20
created, tested, and committed against each new branch.

So, I think the best answer is 'when its ready' and 'not near proposed =20=

branch points'. Lots of projects have clearer answers to these =20
particular questions - for example, Linux has its merge windows, and =20
Mozilla has code freezes around releases, where no feature commits are =20=

permitted. I'd argue that OpenAFS probably wants to adopt something =20
along these lines too, along with a clearer set of data driven targets =20=

for stable release. But that's an argument for another email.

I should round off by saying that absolutely none of this is specific =20=

to OpenAFS - they're all just part of a functioning Open Source eco =20
system. If you're interested, I'd highly recommend reading:

How to Participate in the Linux Community (A Guide to the Kernel =20
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 =20=

with the same problems!

Hope that helps,

Simon.