[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:50:38 -0400
--001485f03c0616b43a04754631ed
Content-Type: text/plain; charset=ISO-8859-1
On Tue, Oct 6, 2009 at 11:41 AM, Steven Jenkins <steven.jenkins@gmail.com>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?
>
>
I gave you some detail about my objection. that's all i can really quantify
now.
> 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.'
>
>
How about 10/10/10. We can aim to be perfect by that day.
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'.
>
> > 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..
And when we have a good track record of this, that's when I'd want to be
announcing the date, rather than the other way around.
> >> 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.
>
Why? afs3-standardization standardizes network protocol. What's on the disk
is really entirely an implementation issue, and frankly,
afs3-standardization shouldn't care how OpenAFS, or arla, or anyone else,
implements that.
> Are you saying that a patch that modifies that format could get
> accepted without going through that discussion?
>
The discussion of a group that standardizes network protocol of a change
which does not touch the network had better go something like "it changes
nothing, so we don't care". otherwise, there's a problem.
*A* discussion is not *that* discussion. I'm not splitting hairs: the IETF
doesn't standardize how SSL certificates are stored, but they do standardize
HTTPS. Every Apache install would break if the former changed, so it better
be discussed, but venue matters. OpenAFS gets to decide how OpenAFS stores
data.
--
Derrick
--001485f03c0616b43a04754631ed
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
<br><br><div class=3D"gmail_quote">On Tue, Oct 6, 2009 at 11:41 AM, Steven =
Jenkins <span dir=3D"ltr"><<a href=3D"mailto:steven.jenkins@gmail.com">s=
teven.jenkins@gmail.com</a>></span> wrote:<br><blockquote class=3D"gmail=
_quote" style=3D"border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt=
0pt 0.8ex; padding-left: 1ex;">
<div class=3D"im">On Tue, Oct 6, 2009 at 11:25 AM, Derrick Brashear <<a =
href=3D"mailto:shadow@gmail.com">shadow@gmail.com</a>> wrote:<br>
><br>
><br>
>> This point is why I posted to openafs-devel and not just in the<br=
>
>> ticket: what is keeping us from requiring documentation updates fo=
r<br>
>> code submissions? =A0If we're not there yet, how will we deter=
mine when<br>
>> we will start making that requirement.<br>
><br>
> =A0An easy answer would be consensus, since it's obvious we don=
9;t have a<br>
> consensus that we're ready now.<br>
<br>
</div>My query is asking around about consensus. =A0Who is for/against at t=
his<br>
point. =A0And for those against, are the objections/concerns strategic<br>
(i.e., 'I'll never support this idea") vs tactical (i.e., '=
;I'll<br>
support it once X is available/happens/etc'), and what are those<br>
concerns/objections?<br>
<br></blockquote><div><br>I gave you some detail about my objection. that&#=
39;s all i can really quantify now.<br>=A0<br></div><blockquote class=3D"gm=
ail_quote" style=3D"border-left: 1px solid rgb(204, 204, 204); margin: 0pt =
0pt 0pt 0.8ex; padding-left: 1ex;">
Speaking as someone who has helped clean up documentation/write<br>
documentation for 'missing' pages, it would be really, really good =
to<br>
draw a line in the sand and say 'as of this date, if you change a<br>
command interface, we will *not* commit your change without a<br>
corresponding documentation change. =A0But if you need help getting the<br>
documentation change made, then specify that in your gerrit submission<br>
and we'll help you.'<br>
<br></blockquote><div><br>How about 10/10/10. We can aim to be perfect by t=
hat day.<br><br></div><blockquote class=3D"gmail_quote" style=3D"border-lef=
t: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1=
ex;">
That would let Jason and others focus on other areas that are needing<br>
documentation and stay away from the state where we say 'well, I don=
9;t<br>
know if command X's documentation is up to date or not, so someone<br>
needs to look at it and see'.<br>
<div class=3D"im"><br>
> Worse, though, is i've found engineer-types often write very bad<b=
r>
> documentation. So... do we just not take their code?<br>
<br>
</div>If someone submits code and doesn't submit documentation, it'=
s like if<br>
someone submits a partial patch -- the community can work together to<br>
get the required missing pieces assembled, and then get it committed..</blo=
ckquote><div><br>And when we have a good track record of this, that's w=
hen I'd want to be announcing the date, rather than the other way aroun=
d.<br>
=A0</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;"><div cla=
ss=3D"im">
>> 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 thi=
s)<br>
>> - if you are =A0making changes to ondisk formats, you must have th=
e<br>
>> changes reviewed through afs3-standardization (we're already d=
oing<br>
>> this -- I think)<br>
><br>
> it's not an afs3-standardization issue, unless that format hits th=
e wire.<br>
> what happens in my magic black box is none of your business otherwise,=
for<br>
> instance.<br>
<br>
</div>I guess I misunderstood the situation: for example, I thought that if=
<br>
I propose a new on-disk format for the fileserver, that the discussion<br>
would need to go through afs3-standardization.<br></blockquote><div><br>Why=
? afs3-standardization standardizes network protocol. What's on the dis=
k is really entirely an implementation issue, and frankly, afs3-standardiza=
tion shouldn't care how OpenAFS, or arla, or anyone else, implements th=
at.=A0<br>
</div><div>=A0</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=
;">
Are you saying that a patch that modifies that format could get<br>
accepted without going through that discussion?<br></blockquote><div class=
=3D"im"><br>The discussion of a group that standardizes network protocol of=
a change which does not touch the network had better go something like &qu=
ot;it changes nothing, so we don't care".=A0otherwise, there's=
a problem.<br>
<br>*A* discussion is not *that* discussion. I'm not splitting hairs: t=
he IETF doesn't standardize how SSL certificates are stored, but they d=
o standardize HTTPS. Every Apache install would break if the former changed=
, so it better be discussed, but venue matters. OpenAFS gets to decide how =
OpenAFS stores data.<br>
</div></div>-- <br>Derrick<br>
--001485f03c0616b43a04754631ed--