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

[Jeffrey Altman]

Steven Jenkins wrote:
> 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?  If we're not there yet, how will we determine when
>>> we will start making that requirement.
>>  An 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?

You appear to be contradicting yourself with what you say below.
On one hand you want the person who submitted the code change to
be responsible for submitting the docs.  On the other you want the
community to collaborate to fill in the missing pieces.

You can't have it both ways.

In the case in question, Hartmut was told that he would not have to
submit docs for his contribution.  Why?  Because the change to fs setacl
to add -cmd was trivial and fs setacl -cmd had to be implemented for
Windows which we weren't requiring of him either.

Now, I would much rather draw a line in the sand that says "if you
contribute a change for Unix that you must also contribute it for
Windows or we won't talk to you" but that is as unrealistic as telling
someone that writes code and doesn't speak English as a primary language
that they must submit usable end user documentation for their wiz bang
new gizmo.

> 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.'

The fact that there is no documentation is indication that the person
needs help writing it.  If it is coming from another entity, then it
should be submitted in a separate commit.  Otherwise, we cannot
distinguish the authorship properly.

The correct thing to do is to create the ticket in the openafs-docs RT
indicating that the change needs to be implemented.  Most of the
documentation contributors are not going to follow the rapid fire
source code changes that traverse through gerrit.

> 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'.

The way you make sure that these types of questions have definitive
answers is to track the changes in RT if there is not documentation
update.

>> 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..

Bingo!  A patch was received.  It had no documentation.  It had no
Windows implementation.  The community came together to address the needs.

Now if you wanted the documentation in German I'm sure that we could
have found someone involved in the code development to submit it.


>>> 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  making 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, for
>> 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.

afs3-stds is for discussing the wire protocols that are required
for independent implementations of the AFS3 protocols to interoperate.

An on-disk format (unless it is exposed as part of a wire protocol)
is a private implementation detail.

> Are you saying that a patch that modifies that format could get
> accepted without going through that discussion?

Yes.  Provided that it didn't impact the wire protocols.

> ...
>>> - 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. but
>> faster."
>>
> 
> Heh.  Yeah, like that.

This level of documentation is part of the commit message.  We already
do require it.

Jeffrey Altman