[OpenAFS-devel] Re: OpenAFS Master Repository branch, master, updated. openafs-devel-1_5_65-15-ge5cf14b

[Steven Jenkins]

On Tue, Oct 6, 2009 at 11:25 AM, Derrick Brashear <shadow@gmail.com> wrote:
>
>
>> This point is why I posted to openafs-devel and not just in the
>> ticket: what is keeping us from requiring documentation updates for
>> code submissions? =A0If we're not there yet, how will we determine when
>> we will start making that requirement.
>
> =A0An easy answer would be consensus, since it's obvious we don't have a
> consensus that we're ready now.

My query is asking around about consensus.  Who is for/against at this
point.  And for those against, are the objections/concerns strategic
(i.e., 'I'll never support this idea") vs tactical (i.e., 'I'll
support it once X is available/happens/etc'), and what are those
concerns/objections?

Speaking as someone who has helped clean up documentation/write
documentation for 'missing' pages, it would be really, really good to
draw a line in the sand and say 'as of this date, if you change a
command interface, we will *not* commit your change without a
corresponding documentation change.  But if you need help getting the
documentation change made, then specify that in your gerrit submission
and we'll help you.'

That would let Jason and others focus on other areas that are needing
documentation and stay away from the state where we say 'well, I don't
know if command X's documentation is up to date or not, so someone
needs to look at it and see'.

> Worse, though, is i've found engineer-types often write very bad
> documentation. So... do we just not take their code?

If someone submits code and doesn't submit documentation, it's like if
someone submits a partial patch -- the community can work together to
get the required missing pieces assembled, and then get it committed..

> That seems like a recipe to ensure we only take stuff from companies. Ick=
.
>

I don't follow that logic at all, but I'm not sure it's your main point...

>> There are certain things we might not be ready to say with respect to
>> documentation, but I think that now is a good time to say:
>>
>> - if you are making protocol changes, you must have the changes
>> reviewed through afs3-standardization (we're already doing this)
>> - if you are =A0making changes to ondisk formats, you must have the
>> changes reviewed through afs3-standardization (we're already doing
>> this -- I think)
>
> it's not an afs3-standardization issue, unless that format hits the wire.
> what happens in my magic black box is none of your business otherwise, fo=
r
> instance.

I guess I misunderstood the situation: for example, I thought that if
I propose a new on-disk format for the fileserver, that the discussion
would need to go through afs3-standardization.

Are you saying that a patch that modifies that format could get
accepted without going through that discussion?
...
>> - documentation for enhancements that do not result in interface
>> changes (either command interface, wire interface, or on-disk
>> interface)
>>
> "before, it served the AFS3 protocol. now, it serves the AFS3 protocol. b=
ut
> faster."
>

Heh.  Yeah, like that.

>>
>> >> As for tests, well, tests are appreciated.
>> >
>> > Tests are certainly appreciated but again we do not require them
>> > for minor contributions such as this.
>> >
>>
>> Agreed. =A0However, I'd =A0like to see what movement and momentum we can
>> get around testing (again, not directly related to this commit but
>> rather in general with submissions). =A0I think gerrit is helping here;
>> I'm not sure what other good, solid wins are on the table.
>>
> My take would be "provide a submission with tests, and let's see how it
> goes, instead of talking theoretically about things that would be nice."
>
> I don't mean you, particularly. Until we have a framework better than the
> one contributed 7 years ago for testing, it's all in flux, and while I co=
uld
> elaborate suggestions for implementing a new one, unless someone's actual=
ly
> promising to do it, there are more pressing and useful things I could do
> *now* with the time.
>

/me nods.  I don't know where a good, solid win is there either, but
if someone *does* know where we could make some solid improvements
(i.e., stuff we could get done in the short term, not pie-in-the-sky
stuff), I'd like to hear it.

Thanks,
Steven