Features and documentation
 

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?

To sum up: No undocumented changes.

Discuss.

Thanks,
Donnie
--
gentoo-dev@gentoo.org mailing list

Features and documentation
 

On Tue, 27 Nov 2007 11:21:44 -0800
Donnie Berkholz <dberkholz@gentoo.org> wrote:
> To sum up: No undocumented changes.

Define 'change'.

--
Ciaran McCreesh

Features and documentation
 

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?
>
> To sum up: No undocumented changes.
>
> Discuss.
>
> Thanks,
> Donnie
>
I agree that documentation should be provided before anything is committed.

I'd also like to note that documentation was provided with the USE flag
descriptions as well as an example metadata.xml with all the new
features being used was provided.

--
Doug Klima
Gentoo Developer
--
gentoo-dev@gentoo.org mailing list

Features and documentation
 

On 19:25 Tue 27 Nov , Ciaran McCreesh wrote:
> On Tue, 27 Nov 2007 11:21:44 -0800
> Donnie Berkholz <dberkholz@gentoo.org> wrote:
> > To sum up: No undocumented changes.
>
> Define 'change'.

That was the summary, so you should be able to get the information you
want from the paragraph above it.

Thanks,
Donnie
--
gentoo-dev@gentoo.org mailing list

Features and documentation
 

On Tue, 27 Nov 2007 11:36:17 -0800
Donnie Berkholz <dberkholz@gentoo.org> wrote:
> On 19:25 Tue 27 Nov , Ciaran McCreesh wrote:
> > On Tue, 27 Nov 2007 11:21:44 -0800
> > Donnie Berkholz <dberkholz@gentoo.org> wrote:
> > > To sum up: No undocumented changes.
> >
> > Define 'change'.
>
> That was the summary, so you should be able to get the information
> you want from the paragraph above it.

But I can't, hence why I asked. You haven't at any point said what you
mean by 'change'.

--
Ciaran McCreesh

Features and documentation
 

On 11/27/07, Donnie Berkholz <dberkholz@gentoo.org> 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?
>
> To sum up: No undocumented changes.

No, because this is not a realistic requirement, it's an ideal case.
People will just commit changes without documentation anyway.

>
> Discuss.
>
> Thanks,
> Donnie
> --
> gentoo-dev@gentoo.org mailing list
>
>
--
gentoo-dev@gentoo.org mailing list

Features and documentation
 

Alec Warner wrote:
> On 11/27/07, Donnie Berkholz <dberkholz@gentoo.org> 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?
>>
>> To sum up: No undocumented changes.
>
> No, because this is not a realistic requirement, it's an ideal case.
> People will just commit changes without documentation anyway.

What if Donnie had used s/changes/new features/ ? Then his proposal
makes much more sense.

For bugfix, we already have ChangeLogs.

My 2 euro ¢

Cheers,
Rémi
--
gentoo-dev@gentoo.org mailing list

Features and documentation
 

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

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?

Marijn

- --
Marijn Schouten (hkBst), Gentoo Lisp project, Gentoo ML
<http://www.gentoo.org/proj/en/lisp/>, #gentoo-{lisp,ml} on FreeNode
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.7 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHTVPKp/VmCx0OL2wRAoMqAJ4zkrWMSmthzxNNjc+/syiz4EMq2wCcCnSE
CA8fiI/lq716rIV5+i9r4lI=
=ypdc
-----END PGP SIGNATURE-----
--
gentoo-dev@gentoo.org mailing list

Features and documentation
 

"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.

Donnie, I'm sure you have the scope of what you intend to apply this to
firmly in your mind, but it's not at all clear from your post what it
is. Ebuilds? Doesn't make sense with changelog already there and
generally used (when folks don't forget or screw the format and therefore
the parsing thereof). Eclasses? OK, that makes more sense, but is that
what you intended? Gentoo sponsored projects such as portage? Isn't
that stepping on the various project's toes and don't most of them have
such requirements in place formally or not as it is? Something else?
Some combination of the above?

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.

--
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

Features and documentation
 

Rémi Cardona wrote:
> Alec Warner wrote:
>> On 11/27/07, Donnie Berkholz <dberkholz@gentoo.org> 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?
>>>
>>> To sum up: No undocumented changes.
>> No, because this is not a realistic requirement, it's an ideal case.
>> People will just commit changes without documentation anyway.
>
> What if Donnie had used s/changes/new features/ ? Then his proposal
> makes much more sense.

I agree that new features makes more sense here. USE flag description in
metadata.xml is just an example of new feature, IMO.

My 2 HK$, ;)

--
Zhang Le, Robert
GPG key ID: 1E4E2973
Fingerprint: 0260 C902 B8F8 6506 6586 2B90 BC51 C808 1E4E 2973
--
gentoo-dev@gentoo.org mailing list