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

[Steven Jenkins]

On Tue, Oct 6, 2009 at 9:55 AM, Jeffrey Altman
<jaltman@secure-endpoints.com> wrote:
...
>> Is there a man page update for this change or any tests/examples for
>> the new interface? =A0I don't see either in this commit, but there is a
>> comment that an RT ticket can be opened up to request the
>> documentation.
>
> http://gerrit.openafs.org/586
> http://rt.central.org/rt/Ticket/Display.html?Action=3DTake&id=3D125470
>

Thanks for opening these -- I'll take a look.

>> Wouldn't it be better to require documentation updates for all patches
>> that change command interfaces? =A0There would be much, much less
>> documentation-drift that way.
>
> In general we would like to see documentation updates for all
> commits. =A0However, we are far from the point where we can demand
> that we either obtain a documentation or will refuse to accept
> code when a contribution has been requested from a developer.
>

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.

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)
- if you change an interface to a command (e.g., add a new command,
add/modify/remove existing commands), you need to provide the
corresponding documentation change.

What we're not requiring:

- implementation specifications
- documentation changes for bug fixes
- documentation for enhancements that do not result in interface
changes (either command interface, wire interface, or on-disk
interface)

>> 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.  However, I'd  like to see what movement and momentum we can
get around testing (again, not directly related to this commit but
rather in general with submissions).  I think gerrit is helping here;
I'm not sure what other good, solid wins are on the table.

Does anyone have any suggestions?

> Please review the pending gerrit patch. =A0A ticket was created in
> the openafs-docs RT a well since most of the documentation contributors
> are not hard core developers and have not created accounts in gerrit.
>

Will do.

Thanks,
Steven