[gentoo-dev] [GLEP56] USE flag descriptions in metadata

[gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Doug Goldstein]

All,

Here's a GLEP for the addition of USE flag descriptions to package 
metadata. It does not address any future ideas that others may have had 
or suggested. It merely gives developers the necessary "tools" to 
document their USE flag usage it better detail on a per package basis.

An clearly motivation explanation that I didn't add, which I'm going to 
add once I send this is the fact that as per the QA Project, 
use.local.desc can not contain a USE flag that already appears globally 
in use.desc. This would allow a description for that USE flag to be 
contained in the metadata.

http://www.gentoo.org/proj/en/glep/glep-0056.html

I encourage any and all _technical_ feedback.

Thanks.
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Marius Mauch]

On Thu, 05 Jun 2008 15:42:24 -0400
Doug Goldstein <cardoe@gentoo.org> wrote:

> All,
> 
> Here's a GLEP for the addition of USE flag descriptions to package 
> metadata. It does not address any future ideas that others may have
> had or suggested. It merely gives developers the necessary "tools" to 
> document their USE flag usage it better detail on a per package basis.
> 
> An clearly motivation explanation that I didn't add, which I'm going
> to add once I send this is the fact that as per the QA Project, 
> use.local.desc can not contain a USE flag that already appears
> globally in use.desc. This would allow a description for that USE
> flag to be contained in the metadata.
> 
> http://www.gentoo.org/proj/en/glep/glep-0056.html
> 
> I encourage any and all _technical_ feedback.

Doesn't include any statement about compability with existing tools or
how it's related to use.local.desc (replacement, extension, ...)

Marius
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Doug Goldstein]

Marius Mauch wrote:
> On Thu, 05 Jun 2008 15:42:24 -0400
> Doug Goldstein <cardoe@gentoo.org> wrote:
>
>   
>> All,
>>
>> Here's a GLEP for the addition of USE flag descriptions to package 
>> metadata. It does not address any future ideas that others may have
>> had or suggested. It merely gives developers the necessary "tools" to 
>> document their USE flag usage it better detail on a per package basis.
>>
>> An clearly motivation explanation that I didn't add, which I'm going
>> to add once I send this is the fact that as per the QA Project, 
>> use.local.desc can not contain a USE flag that already appears
>> globally in use.desc. This would allow a description for that USE
>> flag to be contained in the metadata.
>>
>> http://www.gentoo.org/proj/en/glep/glep-0056.html
>>
>> I encourage any and all _technical_ feedback.
>>     
>
> Doesn't include any statement about compability with existing tools or
> how it's related to use.local.desc (replacement, extension, ...)
>
> Marius
>   
It purposefully does not. XML is an extensible language that allows for 
this type of expandability. Current tools should be able to validate 
that adding these tags are valid if they appear in the DTD. However, if 
those tools do not handle those tags they should not do anything with 
them, hence the nature of XML.

The replacement of use.local.desc would necessitate a change to any and 
all tools which use that file and require them to support the new XML 
data. This of course introduces a chicken/egg issue. I have mentioned to 
infra the possibility of having a pre-rsync process that condensed all 
metadata.xml's into a use.local.desc that would be part of rsync data 
but not part of CVS. This could be written as a CVS hook to see when a 
metadata.xml was touched and run the utility appropriately.

But again, this is outside the scope of this GLEP, whose purpose merely 
is to provide a way to document this.
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Marius Mauch]

On Thu, 05 Jun 2008 17:01:00 -0400
Doug Goldstein <cardoe@gentoo.org> wrote:

> Marius Mauch wrote:
> > On Thu, 05 Jun 2008 15:42:24 -0400
> > Doug Goldstein <cardoe@gentoo.org> wrote:
> >
> >   
> >> All,
> >>
> >> Here's a GLEP for the addition of USE flag descriptions to package 
> >> metadata. It does not address any future ideas that others may have
> >> had or suggested. It merely gives developers the necessary "tools"
> >> to document their USE flag usage it better detail on a per package
> >> basis.
> >>
> >> An clearly motivation explanation that I didn't add, which I'm
> >> going to add once I send this is the fact that as per the QA
> >> Project, use.local.desc can not contain a USE flag that already
> >> appears globally in use.desc. This would allow a description for
> >> that USE flag to be contained in the metadata.
> >>
> >> http://www.gentoo.org/proj/en/glep/glep-0056.html
> >>
> >> I encourage any and all _technical_ feedback.
> >>     
> >
> > Doesn't include any statement about compability with existing tools
> > or how it's related to use.local.desc (replacement, extension, ...)
> >
> > Marius
> >   
> It purposefully does not. XML is an extensible language that allows
> for this type of expandability. Current tools should be able to
> validate that adding these tags are valid if they appear in the DTD.
> However, if those tools do not handle those tags they should not do
> anything with them, hence the nature of XML.

I was more talking about tools that process use flag information
(equery, euse, ufed, ...).

> The replacement of use.local.desc would necessitate a change to any
> and all tools which use that file and require them to support the new
> XML data. This of course introduces a chicken/egg issue. I have
> mentioned to infra the possibility of having a pre-rsync process that
> condensed all metadata.xml's into a use.local.desc that would be part
> of rsync data but not part of CVS. This could be written as a CVS
> hook to see when a metadata.xml was touched and run the utility
> appropriately.
> 
> But again, this is outside the scope of this GLEP, whose purpose
> merely is to provide a way to document this.

I disagree. At the very least state that the GLEP does not replace
use.local.desc if that's the intention, and which location is
supposed to take priority if a flag is defined in both. Otherwise
different tools will use different rules and generating inconsistent
results. And there are many tools affected by this ...

Marius

PS: I like the general idea, but as long as compability issues are
completely ignored by the GLEP I have to oppose it.
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Doug Goldstein]

Marius Mauch wrote:
> On Thu, 05 Jun 2008 17:01:00 -0400
> Doug Goldstein <cardoe@gentoo.org> wrote:
>
>   
>> Marius Mauch wrote:
>>     
>>> On Thu, 05 Jun 2008 15:42:24 -0400
>>> Doug Goldstein <cardoe@gentoo.org> wrote:
>>>
>>>   
>>>       
>>>> All,
>>>>
>>>> Here's a GLEP for the addition of USE flag descriptions to package 
>>>> metadata. It does not address any future ideas that others may have
>>>> had or suggested. It merely gives developers the necessary "tools"
>>>> to document their USE flag usage it better detail on a per package
>>>> basis.
>>>>
>>>> An clearly motivation explanation that I didn't add, which I'm
>>>> going to add once I send this is the fact that as per the QA
>>>> Project, use.local.desc can not contain a USE flag that already
>>>> appears globally in use.desc. This would allow a description for
>>>> that USE flag to be contained in the metadata.
>>>>
>>>> http://www.gentoo.org/proj/en/glep/glep-0056.html
>>>>
>>>> I encourage any and all _technical_ feedback.
>>>>     
>>>>         
>>> Doesn't include any statement about compability with existing tools
>>> or how it's related to use.local.desc (replacement, extension, ...)
>>>
>>> Marius
>>>   
>>>       
>> It purposefully does not. XML is an extensible language that allows
>> for this type of expandability. Current tools should be able to
>> validate that adding these tags are valid if they appear in the DTD.
>> However, if those tools do not handle those tags they should not do
>> anything with them, hence the nature of XML.
>>     
>
> I was more talking about tools that process use flag information
> (equery, euse, ufed, ...).
>
>   
>> The replacement of use.local.desc would necessitate a change to any
>> and all tools which use that file and require them to support the new
>> XML data. This of course introduces a chicken/egg issue. I have
>> mentioned to infra the possibility of having a pre-rsync process that
>> condensed all metadata.xml's into a use.local.desc that would be part
>> of rsync data but not part of CVS. This could be written as a CVS
>> hook to see when a metadata.xml was touched and run the utility
>> appropriately.
>>
>> But again, this is outside the scope of this GLEP, whose purpose
>> merely is to provide a way to document this.
>>     
>
> I disagree. At the very least state that the GLEP does not replace
> use.local.desc if that's the intention, and which location is
> supposed to take priority if a flag is defined in both. Otherwise
> different tools will use different rules and generating inconsistent
> results. And there are many tools affected by this ...
>
> Marius
>
> PS: I like the general idea, but as long as compability issues are
> completely ignored by the GLEP I have to oppose it.
>   
Considering Portage and repoman currently require any and all USE flags 
appearing in IUSE to be present in use.local.desc, there should be no 
ambiguity to the compatibility issues currently. I 100% expect different 
tools to provide different results. Writing a GLEP stating that one file 
is preferred over another will not cause those tools to magically 
choose. The tools and their maintainers should be pushed by the 
community to use the best data available. If use.local.desc provides 
this data, then so be it. The initial goal of this GLEP is really to 
allow per-package descriptions of global USE flags [*]. There by 
different tools will provide more detailed information about USE flags 
and some will simply not. That will result in a community push to make 
these tools use newer data available and as such will result in one day 
use.local.desc becoming deprecated. But, we're speaking about something 
which may never happen. Or may happen in another GLEP in the future.

[*] As decided by the Gentoo QA Team, any USE flag that appears in 
use.desc CAN NOT appear in use.local.desc. There by, there is no way for 
a descriptive variation of a global USE flag to officially appear in any 
medium.
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Doug Goldstein]

Doug Goldstein wrote:
> Marius Mauch wrote:
>> On Thu, 05 Jun 2008 17:01:00 -0400
>> Doug Goldstein <cardoe@gentoo.org> wrote:
>>
>>  
>>> Marius Mauch wrote:
>>>    
>>>> On Thu, 05 Jun 2008 15:42:24 -0400
>>>> Doug Goldstein <cardoe@gentoo.org> wrote:
>>>>
>>>>        
>>>>> All,
>>>>>
>>>>> Here's a GLEP for the addition of USE flag descriptions to package 
>>>>> metadata. It does not address any future ideas that others may have
>>>>> had or suggested. It merely gives developers the necessary "tools"
>>>>> to document their USE flag usage it better detail on a per package
>>>>> basis.
>>>>>
>>>>> An clearly motivation explanation that I didn't add, which I'm
>>>>> going to add once I send this is the fact that as per the QA
>>>>> Project, use.local.desc can not contain a USE flag that already
>>>>> appears globally in use.desc. This would allow a description for
>>>>> that USE flag to be contained in the metadata.
>>>>>
>>>>> http://www.gentoo.org/proj/en/glep/glep-0056.html
>>>>>
>>>>> I encourage any and all _technical_ feedback.
>>>>>             
>>>> Doesn't include any statement about compability with existing tools
>>>> or how it's related to use.local.desc (replacement, extension, ...)
>>>>
>>>> Marius
>>>>         
>>> It purposefully does not. XML is an extensible language that allows
>>> for this type of expandability. Current tools should be able to
>>> validate that adding these tags are valid if they appear in the DTD.
>>> However, if those tools do not handle those tags they should not do
>>> anything with them, hence the nature of XML.
>>>     
>>
>> I was more talking about tools that process use flag information
>> (equery, euse, ufed, ...).
>>
>>  
>>> The replacement of use.local.desc would necessitate a change to any
>>> and all tools which use that file and require them to support the new
>>> XML data. This of course introduces a chicken/egg issue. I have
>>> mentioned to infra the possibility of having a pre-rsync process that
>>> condensed all metadata.xml's into a use.local.desc that would be part
>>> of rsync data but not part of CVS. This could be written as a CVS
>>> hook to see when a metadata.xml was touched and run the utility
>>> appropriately.
>>>
>>> But again, this is outside the scope of this GLEP, whose purpose
>>> merely is to provide a way to document this.
>>>     
>>
>> I disagree. At the very least state that the GLEP does not replace
>> use.local.desc if that's the intention, and which location is
>> supposed to take priority if a flag is defined in both. Otherwise
>> different tools will use different rules and generating inconsistent
>> results. And there are many tools affected by this ...
>>
>> Marius
>>
>> PS: I like the general idea, but as long as compability issues are
>> completely ignored by the GLEP I have to oppose it.
>>   
> Considering Portage and repoman currently require any and all USE 
> flags appearing in IUSE to be present in use.local.desc, there should 
> be no ambiguity to the compatibility issues currently. I 100% expect 
> different tools to provide different results. Writing a GLEP stating 
> that one file is preferred over another will not cause those tools to 
> magically choose. The tools and their maintainers should be pushed by 
> the community to use the best data available. If use.local.desc 
> provides this data, then so be it. The initial goal of this GLEP is 
> really to allow per-package descriptions of global USE flags [*]. 
> There by different tools will provide more detailed information about 
> USE flags and some will simply not. That will result in a community 
> push to make these tools use newer data available and as such will 
> result in one day use.local.desc becoming deprecated. But, we're 
> speaking about something which may never happen. Or may happen in 
> another GLEP in the future.
>
> [*] As decided by the Gentoo QA Team, any USE flag that appears in 
> use.desc CAN NOT appear in use.local.desc. There by, there is no way 
> for a descriptive variation of a global USE flag to officially appear 
> in any medium.
Replying to myself is evil, but I'm going to try to clarify a bit more. 
GLEPs are more like RFCs. We can't force any application to do anything 
with a GLEP. We technically can't even force Portage to do anything in a 
GLEP since there's nothing that states Portage is the official package 
manager of Gentoo Linux and must follow all GLEPs. I personally feel any 
GLEP that tries to force any action to be taken by application 
developers and does not include a reference implementation or patches 
for said application(s), is fundamentally flawed (this is something I 
look to address in the future.

For example, take RFC 3514 [1], it might be great on paper if you could 
have everyone follow it. However, go ahead and try to actually force 
every single developer out there to implement it. Similar situation. A 
GLEP being approved isn't going to make truedfx suddenly hop up and 
update ufed to support these new descriptions because a) what's forcing 
him? it's open source. There's no corporate overlord threatening to fire 
him if he doesn't.  b) it's pretty worthless initially since there won't 
be any content for it to consume.

[1] http://www.faqs.org/rfcs/rfc3514.html

-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Marius Mauch]

On Fri, 06 Jun 2008 09:51:22 -0400
Doug Goldstein <cardoe@gentoo.org> wrote:

> Replying to myself is evil, but I'm going to try to clarify a bit
> more. GLEPs are more like RFCs. We can't force any application to do
> anything with a GLEP. We technically can't even force Portage to do
> anything in a GLEP since there's nothing that states Portage is the
> official package manager of Gentoo Linux and must follow all GLEPs. I
> personally feel any GLEP that tries to force any action to be taken
> by application developers and does not include a reference
> implementation or patches for said application(s), is fundamentally
> flawed (this is something I look to address in the future.

It's not about "forcing" anyone to do something but giving people enough
information on how to implement it _if they choose to do so_. With the
current GLEP they'd have to make arbitrary decisions if e.g. a flag is
defined in both use.local.desc and metadata.xml, or some people might
think that it replaces use.local.desc completely.
Really, all I'm looking for is something like

"This proposal does not intend to replace the existing use.local.desc
format. If a flag is defined for a package in both use.local.desc and
metadata.xml the latter should be preferred by tools"

Do you really consider that to be such a huge deal?

Marius
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Vlastimil Babka]

[-- Attachment #1: Type: text/plain, Size: 1014 bytes --]

Doug Goldstein wrote:
> An clearly motivation explanation that I didn't add, which I'm going to 
> add once I send this is the fact that as per the QA Project, 
> use.local.desc can not contain a USE flag that already appears globally 
> in use.desc. This would allow a description for that USE flag to be 
> contained in the metadata.

What reason does the QA Project have to disallow such thing? Is it just 
so that package-specific info does not concentrate in one huge file? Or 
is it the danger that the meaning of package-specific flags would drift 
too far from the global flag's meaning and lead to confusion?
If it's the first, then metadata.xml seems like a good place. If the 
latter, then it wouldn't make much sense to approve the syntax and then 
disallowing it by QA :)

> I encourage any and all _technical_ feedback.

Technically, I think linking to blogs, especially outside of g.o domain 
is not the best thing durability-wise :)
-- 
Vlastimil Babka (Caster)
Gentoo/Java


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Vlastimil Babka]

[-- Attachment #1: Type: text/plain, Size: 836 bytes --]

Marius Mauch wrote:
> It's not about "forcing" anyone to do something but giving people enough
> information on how to implement it _if they choose to do so_. With the
> current GLEP they'd have to make arbitrary decisions if e.g. a flag is
> defined in both use.local.desc and metadata.xml, or some people might
> think that it replaces use.local.desc completely.
> Really, all I'm looking for is something like
> 
> "This proposal does not intend to replace the existing use.local.desc
> format. If a flag is defined for a package in both use.local.desc and
> metadata.xml the latter should be preferred by tools"

++ I suppose you want people to read the package-specific information 
and not e.g. fill bug reports caused by wrong assumptions about the 
flag's meaning.

-- 
Vlastimil Babka (Caster)
Gentoo/Java


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 1123 bytes --]

On Sat, 07 Jun 2008 01:40:36 +0200
Vlastimil Babka <caster@gentoo.org> wrote:
> Doug Goldstein wrote:
> > An clearly motivation explanation that I didn't add, which I'm
> > going to add once I send this is the fact that as per the QA
> > Project, use.local.desc can not contain a USE flag that already
> > appears globally in use.desc. This would allow a description for
> > that USE flag to be contained in the metadata.
> 
> What reason does the QA Project have to disallow such thing? Is it
> just so that package-specific info does not concentrate in one huge
> file? Or is it the danger that the meaning of package-specific flags
> would drift too far from the global flag's meaning and lead to
> confusion? If it's the first, then metadata.xml seems like a good
> place. If the latter, then it wouldn't make much sense to approve the
> syntax and then disallowing it by QA :)

As I recall, the logic was that global use flags have a single, well
defined global meaning. Using use.local.desc for *refinements* wouldn't
go against that, but it's a fairly badly defined line.

-- 
Ciaran McCreesh

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 850 bytes --]

On Thu, 05 Jun 2008 15:42:24 -0400
Doug Goldstein <cardoe@gentoo.org> wrote:
> Here's a GLEP for the addition of USE flag descriptions to package 
> metadata. It does not address any future ideas that others may have
> had or suggested. It merely gives developers the necessary "tools" to 
> document their USE flag usage it better detail on a per package basis.

There should also be a way of referring to a use flag owned by either
this or another package. For example:

<flag name="foo">Enables support for fooing. Ignored unless <flagref
name="bar">plugin</flagref> support is enabled for this package and
<flagref restrict="app-misc/foo" name="bindings">bindings</flagref> is
enabled for <pkg>app-misc/foo</pkg>.</flag>

But that's rather ugly... There's probably a nicer way of marking it up
using XML.

-- 
Ciaran McCreesh

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Steve Dibb]

Ciaran McCreesh wrote:
> On Thu, 05 Jun 2008 15:42:24 -0400
> Doug Goldstein <cardoe@gentoo.org> wrote:
>> Here's a GLEP for the addition of USE flag descriptions to package 
>> metadata. It does not address any future ideas that others may have
>> had or suggested. It merely gives developers the necessary "tools" to 
>> document their USE flag usage it better detail on a per package basis.
> 
> There should also be a way of referring to a use flag owned by either
> this or another package. For example:
> 
> <flag name="foo">Enables support for fooing. Ignored unless <flagref
> name="bar">plugin</flagref> support is enabled for this package and
> <flagref restrict="app-misc/foo" name="bindings">bindings</flagref> is
> enabled for <pkg>app-misc/foo</pkg>.</flag>
> 
> But that's rather ugly... There's probably a nicer way of marking it up
> using XML.
> 

What about just nesting them?

<flag name foo>
	<flag name bar>Turns on hawt chicks</flag>
	<flag name baz>Turns on welp</flag>
</flag>

Of course, you probably couldn't tell that just by looking at them, but 
it's an idea.

Steve
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Donnie Berkholz]

On 17:11 Fri 06 Jun     , Marius Mauch wrote:
> It's not about "forcing" anyone to do something but giving people enough
> information on how to implement it _if they choose to do so_. With the
> current GLEP they'd have to make arbitrary decisions if e.g. a flag is
> defined in both use.local.desc and metadata.xml, or some people might
> think that it replaces use.local.desc completely.
> Really, all I'm looking for is something like
> 
> "This proposal does not intend to replace the existing use.local.desc
> format. If a flag is defined for a package in both use.local.desc and
> metadata.xml the latter should be preferred by tools"
> 
> Do you really consider that to be such a huge deal?

From a council perspective, I think that we should have GLEPs that 
promote a certain solution as one that should be preferred and should 
deprecate another. We need to take a stand on the best way to do things 
and to have GLEPs that do the same, choosing the better direction to 
motivate people to do things that way. If that stand turns out to be 
wrong after people have spent some time doing the work, we can revert 
the GLEP and unapprove it.

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

Re: [gentoo-dev] [GLEP56] USE flag descriptions in metadata

[Petteri Räty]

[-- Attachment #1: Type: text/plain, Size: 1411 bytes --]

Doug Goldstein kirjoitti:
> All,
> 
> Here's a GLEP for the addition of USE flag descriptions to package 
> metadata. It does not address any future ideas that others may have had 
> or suggested. It merely gives developers the necessary "tools" to 
> document their USE flag usage it better detail on a per package basis.
> 
> An clearly motivation explanation that I didn't add, which I'm going to 
> add once I send this is the fact that as per the QA Project, 
> use.local.desc can not contain a USE flag that already appears globally 
> in use.desc. This would allow a description for that USE flag to be 
> contained in the metadata.
> 
> http://www.gentoo.org/proj/en/glep/glep-0056.html
> 
> I encourage any and all _technical_ feedback.
> 
> Thanks.

As asked in the last council meeting here are my thoughts.

1. Rather than linking to the PMS repo it should refer to the devmanual 
on CPV http://devmanual.gentoo.org/ebuild-writing/file-format/index.html

2. "Each <flag> XML tag requires a 'name' attribute which is the full 
USE flag name as it would appear in the IUSE section of the ebuild."

Shouldn't this rather be as it appears. If the use flag is not used in 
all versions I would rather see that the

3. It should clarify the meaning of the pkg and cat tags as links to 
other places in the tree. IMHO it doesn't hurt to be explicit.

Regards,
Petteri


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 260 bytes --]