Hope you update the manuals prior to coding... On Sun, Nov 8, 2009 at 10:11 AM, Simon Wilkinson <[email protected]> wrote:
> > 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<https://developer.mozilla.org/en/Mozilla_Hacker%27s_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 >
