On Tue, Oct 6, 2009 at 9:55 AM, Jeffrey Altman <[email protected]> wrote: ... >> Is there a man page update for this change or any tests/examples for >> the new interface? I 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=Take&id=125470 >
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? There would be much, much less >> documentation-drift that way. > > In general we would like to see documentation updates for all > commits. However, 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. A 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 _______________________________________________ OpenAFS-devel mailing list [email protected] https://lists.openafs.org/mailman/listinfo/openafs-devel
