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. Worse, though, is i've found engineer-types often write very bad documentation. So... do we just not take their code? That seems like a recipe to ensure we only take stuff from companies. Ick. 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. > - 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. > > See above. > What we're not requiring: > > - implementation specifications > we're not in a position to do it yet, but it would be nice. > - documentation changes for bug fixes > goes to the above. > - 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." > >> 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. > > 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 could elaborate suggestions for implementing a new one, unless someone's actually promising to do it, there are more pressing and useful things I could do *now* with the time.
