[OpenAFS-devel] Re: OpenAFS Master Repository branch, master,
updated. openafs-devel-1_5_65-15-ge5cf14b
Derrick Brashear
shadow@gmail.com
Tue, 6 Oct 2009 11:25:34 -0400
--001485f725786db966047545d7d8
Content-Type: text/plain; charset=ISO-8859-1
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.
--001485f725786db966047545d7d8
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
<br><br>
<div class=3D"gmail_quote"><blockquote class=3D"gmail_quote" style=3D"borde=
r-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-le=
ft: 1ex;">This point is why I posted to openafs-devel and not just in the<b=
r>
ticket: what is keeping us from requiring documentation updates for<br>
code submissions? =A0If we're not there yet, how will we determine when=
<br>
we will start making that requirement.<br></blockquote><div><br>=A0An easy =
answer would be consensus, since it's obvious we don't have a conse=
nsus that we're ready now.<br>Worse, though, is i've found engineer=
-types often write very bad documentation. So... do we just not take their =
code? <br>
That seems like a recipe to ensure we only take stuff from companies. Ick.<=
br><br></div><blockquote class=3D"gmail_quote" style=3D"border-left: 1px so=
lid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
There are certain things we might not be ready to say with respect to<br>
documentation, but I think that now is a good time to say:<br>
<br>
- if you are making protocol changes, you must have the changes<br>
reviewed through afs3-standardization (we're already doing this)<br>
- if you are =A0making changes to ondisk formats, you must have the<br>
changes reviewed through afs3-standardization (we're already doing<br>
this -- I think)<br></blockquote><div><br>it's not an afs3-standardizat=
ion issue, unless that format hits the wire. what happens in my magic black=
box is none of your business otherwise, for instance. <br>=A0<br></div>
<blockquote class=3D"gmail_quote" style=3D"border-left: 1px solid rgb(204, =
204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
- if you change an interface to a command (e.g., add a new command,<br>
add/modify/remove existing commands), you need to provide the<br>
corresponding documentation change.<br>
<br></blockquote><div>See above.<br>=A0</div><blockquote class=3D"gmail_quo=
te" style=3D"border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt=
0.8ex; padding-left: 1ex;">
What we're not requiring:<br>
<br>
- implementation specifications<br></blockquote><div><br>we're not in a=
position to do it yet, but it would be nice.<br>=A0<br></div><blockquote c=
lass=3D"gmail_quote" style=3D"border-left: 1px solid rgb(204, 204, 204); ma=
rgin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
- documentation changes for bug fixes<br></blockquote><div><br>goes to the =
above.<br>=A0<br></div><blockquote class=3D"gmail_quote" style=3D"border-le=
ft: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: =
1ex;">
- documentation for enhancements that do not result in interface<br>
changes (either command interface, wire interface, or on-disk<br>
interface)<br>
<div class=3D"im"><br></div></blockquote><div>"before, it served the A=
FS3 protocol. now, it serves the AFS3 protocol. but faster."<br>=A0<br=
></div><blockquote class=3D"gmail_quote" style=3D"border-left: 1px solid rg=
b(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div class=3D"im">
>> As for tests, well, tests are appreciated.<br>
><br>
> Tests are certainly appreciated but again we do not require them<br>
> for minor contributions such as this.<br>
><br>
<br>
</div>Agreed. =A0However, I'd =A0like to see what movement and momentum=
we can<br>
get around testing (again, not directly related to this commit but<br>
rather in general with submissions). =A0I think gerrit is helping here;<br>
I'm not sure what other good, solid wins are on the table.<br>
<br></blockquote><div>My take would be "provide a submission with test=
s, and let's see how it goes, instead of talking theoretically about th=
ings that would be nice."<br><br>I don't mean you, particularly. U=
ntil we have a framework better than the one contributed 7 years ago for te=
sting, it's all in flux, and while I could<br>
elaborate suggestions for implementing a new one, unless someone's actu=
ally promising to do it, there are more pressing and useful things I could =
do *now* with the time.<br><br><br>
</div></div>
--001485f725786db966047545d7d8--