FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Gentoo > Gentoo Development

 
 
LinkBack Thread Tools
 
Old 11-29-2007, 07:58 AM
Christian Faulhammer
 
Default Features and documentation

Donnie Berkholz <dberkholz@gentoo.org>:

> The Linux kernel seems to still have contributors, despite its
> requirement.

You have been quoted on LWN:
"'The Linux kernel requires that any needed documentation accompany all
changes requiring said documentation -- part of the source-code patch
must apply to the Documentation/ directory.' -- Donnie Berkholz engages
in some wishful thinking"

V-Li

--
Christian Faulhammer, Gentoo Lisp project
<URL:http://www.gentoo.org/proj/en/lisp/>, #gentoo-lisp on FreeNode

<URL:http://www.faulhammer.org/>
 
Old 11-29-2007, 12:57 PM
"Santiago M. Mola"
 
Default Features and documentation

On Nov 29, 2007 1:43 AM, Alec Warner <antarus@gentoo.org> wrote:
>
> Forcing people to write documentation won't get it written, people
> will continue to act like we just saw and either the rule will get
> ignored, or someone will change the rule, or people will leave because
> the rule is enforced aggressively and it has ruined the ability to
> contribute to the project.
>
> This is why I offered to write the GLEP for Diego and Cardoe, because
> I know they are not interested in writing it themselves. Thats why we
> have a doc-team that for some sick reason enjoy writing and
> maintaining documentation.
>

It would be reasonable to require devs to:
a) Document changes before commiting when it's possible.
b) When a) is not applicable, ask doc project to document it before commiting.
c) When neither a) or b) are possible, file a bug asking for doc
update for the commited changes.

--
Santiago M. Mola
Jabber ID: cooldwind@gmail.com
--
gentoo-dev@gentoo.org mailing list
 
Old 11-29-2007, 01:47 PM
Doug Klima
 
Default Features and documentation

Alec Warner wrote:
> On 11/28/07, Donnie Berkholz <dberkholz@gentoo.org> wrote:
>
>> On 19:10 Tue 27 Nov , Alec Warner wrote:
>>
>>> No, because this is not a realistic requirement, it's an ideal case.
>>> People will just commit changes without documentation anyway.
>>>
>> Here's my understanding of what you said: Because people will break
>> rules and violate standards, we shouldn't have any.
>>
>> Is that accurate?
>>
>>
>
> Kind of.
>
> Most people follow most rules. Most people break a subset of rules.
>
> You are essentially adding an unreasonable (in my view) rule that I
> expect nearly everyone to break or ignore, thereby adding little or no
> value to the project as whole. Most people care about documentation
> in the abstract sense, almost no one cares *enough* to write any
>
> Forcing people to write documentation won't get it written, people
> will continue to act like we just saw and either the rule will get
> ignored, or someone will change the rule, or people will leave because
> the rule is enforced aggressively and it has ruined the ability to
> contribute to the project.
>
> This is why I offered to write the GLEP for Diego and Cardoe, because
> I know they are not interested in writing it themselves. Thats why we
> have a doc-team that for some sick reason enjoy writing and
> maintaining documentation.
>
> -Alec
>
Load of crap. I wrote full documentation and provided patches to the
Developer Handbook, where metadata is documented. A GLEP is a terrible
place to document this since you have to read through 5 different GLEPs
and automatically cross out the parts that are no longer valid or have
been replaced by newer parts of the GLEP. Which is why once again, the
GLEP is stupid and one central location on one topic should be kept up
to date. As I have done.
--
gentoo-dev@gentoo.org mailing list
 
Old 11-29-2007, 05:06 PM
Duncan
 
Default Features and documentation

Donnie Berkholz <dberkholz@gentoo.org> posted
20071129053854.GD11249@supernova, excerpted below, on Wed, 28 Nov 2007
21:38:54 -0800:

> In fact, I believe exactly the opposite. What we want to create are
> basic philosophies to guide us. Nailing down a million tiny details is
> what makes things not fun, and what makes them impossible to learn.
> We're not trying to write a specification here, we're trying to come up
> with a set of guidelines that people could actually learn and remember.

OK, so you are deliberately going for the "big brush strokes" general
guideline approach, and don't /want/ the policy getting into details. I
can respect that and will need to go back and reread the discussion to
date with that in mind.

Meanwhile, you still sidestepped the other question. Maybe it's getting
too detailed also, but if so, directly saying so to that point would be
nice, and if you just missed it, maybe this'll bring it to point:

Something must have motivated you to present this now. What was it, or
to put it a different way, how would have things been different in your
view had this policy been in effect? Point to other examples as well if
you believe they'll help clarify the effect you intend this policy to
have.

(BTW, I'm mailing you directly related to this as well.)

--
Duncan - List replies preferred. No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master." Richard Stallman

--
gentoo-dev@gentoo.org mailing list
 
Old 11-29-2007, 06:29 PM
"Santiago M. Mola"
 
Default Features and documentation

On Nov 29, 2007 7:06 PM, Duncan <1i5t5.duncan@cox.net> wrote:
>
> Something must have motivated you to present this now. What was it, or
> to put it a different way, how would have things been different in your
> view had this policy been in effect? Point to other examples as well if
> you believe they'll help clarify the effect you intend this policy to
> have.
>

I don't know what kind of changes meant Donnie (I hope he clarify
that) but a couple of examples came to my mind when I read his
proposal: bugs #182253 and #181897. I'm sure there are much better
examples, but those are the ones I have right now.

Regards,
Santiago

--
Santiago M. Mola
Jabber ID: cooldwind@gmail.com
--
gentoo-dev@gentoo.org mailing list
 
Old 11-30-2007, 09:42 AM
Steve Long
 
Default Features and documentation

Duncan wrote:
> "Marijn Schouten (hkBst)" <hkBst@gentoo.org> posted
> 474D53CA.7060101@gentoo.org, excerpted below, on Wed, 28 Nov 2007
> 12:40:58 +0100:
>
>> Donnie Berkholz wrote:
>>> How the recent changes happened to allow USE flag descriptions in
>>> metadata.xml (which I'm not taking any position on now) gave me an
>>> idea. The Linux kernel requires that any needed documentation accompany
>>> all changes requiring said documentation -- part of the source-code
>>> patch must apply to the Documentation/ directory. Should we require
>>> that before you commit any changes, you (or someone) write the
>>> documentation for them and commit it or submit a patch at the same
>>> time?
>>
>> We're not talking about ebuilds here, are we? So what ARE we talking
>> about?
>
> Agreed with hkBst and Ciaranm on this one.
<snip>
> It's kinda hard to discuss such a proposal without knowing where it is
> going to be applied, or to read such discussion without being sure
> everybody has the same target in mind (maybe it was discussed on IRC and
> since I don't normally do that I missed it... seems I'm not the only one,
> tho), and what it may be.
>
I took it to mean anything which changes something already documented on a
gentoo doc website (including the devmanual but not individual dev space)
or in a man page. That isn't so hard to define, while covering all the
changes users or devs need to know about. One would hope devs would be
aware of the docs relevant to the software they're changing, so I don't see
that as onerous.

Additions would count too; I'd imagine someone adding a new feature would
want others to know about it. In that regard, asking them to talk to the
doc team before it gets committed makes sense; often that process helps
development. In the case of core software, or larger projects it might make
sense for a point of contact in the doc team (although portage manpages
seem to be updated pretty frequently.)

While not privy to the prior (if any) discussion, I saw it as an attempt to
make the development team aware of documentation responsibility, and asking
them to bear that in mind when they change or add stuff (which we want them
to do as that's how stuff improves) helps them to become more useful devs,
imo. It doesn't have to mean sanctions at any point, but rather that
someone would be put in touch with docs if they needed help to document
stuff. I'd think new people would welcome that.


--
gentoo-dev@gentoo.org mailing list
 
Old 11-30-2007, 04:42 PM
Duncan
 
Default Features and documentation

Steve Long <slong@rathaus.eclipse.co.uk> posted fiop46$9o$1@ger.gmane.org,
excerpted below, on Fri, 30 Nov 2007 10:42:03 +0000:

> Duncan wrote:

>> It's kinda hard to discuss such a proposal without knowing where it is
>> going to be applied

> I took it to mean anything which changes something already documented on
> a gentoo doc website (including the devmanual but not individual dev
> space) or in a man page. [...] Additions would count too; I'd imagine
> someone adding a new feature would want others to know about it.

> I saw [this] as an attempt to make the development team aware of
> documentation responsibility, and asking them to bear that in mind when
> they change or add stuff [...] It doesn't have to mean sanctions at any
> point, but rather that someone would be put in touch with docs if they
> needed help to document stuff. I'd think new people would welcome that.

OK. That makes sense, and the last part agrees with the reply I got from
the private inquiry I mentioned. Quoting a single though from Donnie's
reply:

> This isn't about punishing people. But it could be about
> reverting their commit until it comes back with documentation.

IMO people are (unfortunately correctly, given history) afraid of
something being used to clobber them over the head. If the above thought
were included virtually verbatim in whatever is ultimately hard-proposed,
I believe it'd go a LONG way to avoiding that, since the "clobber limits"
are now clearly defined and (IMO) reasonable.

I guess I've been concerned that neither the reach of nor the weight of
the "clobber stick" seemed limited in any way, and I think we've seen
that an unlimited "clobber stick" isn't a good thing. I was trying to
limit the reach; Donnie didn't want that, but now I see his point that
limiting the weight is equally abuse preventative, while less crippling
to the effectiveness of the tool.

So provided a substantively similar "clobber limit" appears in the final
proposal, I'm now supportive.

--
Duncan - List replies preferred. No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master." Richard Stallman

--
gentoo-dev@gentoo.org mailing list
 
Old 11-30-2007, 04:50 PM
Duncan
 
Default Features and documentation

"Santiago M. Mola" <coldwind@gentoo.org> posted
3c32af40711291129m24b886edu24092291efac2281@mail.g mail.com, excerpted
below, on Thu, 29 Nov 2007 20:29:31 +0100:

> I don't know what kind of changes meant Donnie (I hope he clarify that)
> but a couple of examples came to my mind when I read his proposal: bugs
> #182253 and #181897.

Good examples. Thanks. =8^)

--
Duncan - List replies preferred. No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master." Richard Stallman

--
gentoo-dev@gentoo.org mailing list
 

Thread Tools




All times are GMT. The time now is 09:59 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright 2007 - 2008, www.linux-archive.org