[gentoo-dev] [RFC] Allow SLOT documentation in metadata.xml

[gentoo-dev] [RFC] Allow SLOT documentation in metadata.xml

[Julian Ospald]

The following patch tries to address the lack of slot
documentation, since getting the slots of a dependency
right seems like a common problem.

Things that I was particularly not sure about: the 'subslots'
element. Having a sub-element for 'slot' seemed even more
messy, so I tried to make this as simple as possible, so
that maintainers don't get angry and give up when trying
to document their slots. However, this is a little bit
at the expense of correctness, because you cannot
document different subslot naming schemes if they differ
between slots of a single package (does such thing even exist
in the tree?).

[gentoo-dev] [PATCH] metadata: add slots element

[Julian Ospald]

There seems to be some general confusion about specific package SLOTs
and their meaning, since there can be several naming schemes applied
and documentation is either non-existent or is inside the ebuild via
comments.
Because of that it should be part of metadata.xml.

An example use case for media-libs/libpng would be:
<slots>
    <slot name="0">For building against. This is the only slot
        that provides headers and command line tools.</slot>
    <slot name="1.2">For binary compatibility, provides libpng12.so.0.</slot>
    <slot name="1.5">For binary compatibility, provides libpng15.so.15.</slot>
    <subslots>Represent ABI compatibility for libpng.so.</subslots>
</slots>

For packages like x11-libs/wxGTK one could write:
<slots>
    <slot name="*">Major versions.</slot>
</slots>
---
 metadata.dtd | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/metadata.dtd b/metadata.dtd
index ff2649c..4b29f3b 100644
--- a/metadata.dtd
+++ b/metadata.dtd
@@ -5,7 +5,7 @@
 <!ATTLIST catmetadata pkgname CDATA "">
 
 <!-- Metadata for a package -->
-<!ELEMENT pkgmetadata ( (herd|maintainer|natural-name|longdescription|use|upstream)* )>
+<!ELEMENT pkgmetadata ( (herd|maintainer|natural-name|longdescription|slots|use|upstream)* )>
 <!ATTLIST pkgmetadata pkgname CDATA "">
 
   <!-- One tag for each herd this package is assigned to. -->
@@ -20,6 +20,15 @@
   <!-- A long description of the package in freetext-->
   <!ELEMENT longdescription (#PCDATA|pkg|cat)* >
 
+  <!-- A description of the packages SLOTs -->
+  <!ELEMENT slots ((slot)*,subslots?) >
+    <!-- A particular SLOT -->
+    <!ELEMENT slot (#PCDATA)* >
+      <!-- name attribute holds the name of the SLOT, for sub-SLOTS use the subslots element -->
+      <!ATTLIST slot name CDATA #REQUIRED >
+    <!-- The meaning of sub-SLOTs for the whole package -->
+    <!ELEMENT subslots (#PCDATA)* >
+
   <!-- The changelog of the package-->
   <!-- Please note that #PCDATA is mentioned only for the upstream changelog
     element, where the content is a URL. This is due to limitations of the DTD -->
@@ -79,6 +88,7 @@
   language "C" or "en", which is equivalent -->
   <!ATTLIST description lang CDATA "C" >
   <!ATTLIST longdescription lang CDATA "C" >
+  <!ATTLIST slots lang CDATA "C" >
   <!ATTLIST use lang CDATA "C" >
 
 <!-- The restrict attribute, this attribute specifies restrictions on 
-- 
2.6.1

Re: [gentoo-dev] [PATCH] metadata: add slots element

[Alexis Ballier]

On Mon, 12 Oct 2015 19:19:33 +0200
Julian Ospald <hasufell@gentoo.org> wrote:

> There seems to be some general confusion about specific package SLOTs
> and their meaning, since there can be several naming schemes applied
> and documentation is either non-existent or is inside the ebuild via
> comments.
> Because of that it should be part of metadata.xml.


Why not, but what's the advantage of xmlizing it vs comments in the
ebuilds?

Re: [gentoo-dev] [PATCH] metadata: add slots element

[hasufell]

On 10/12/2015 07:49 PM, Alexis Ballier wrote:
> On Mon, 12 Oct 2015 19:19:33 +0200
> Julian Ospald <hasufell@gentoo.org> wrote:
> 
>> There seems to be some general confusion about specific package SLOTs
>> and their meaning, since there can be several naming schemes applied
>> and documentation is either non-existent or is inside the ebuild via
>> comments.
>> Because of that it should be part of metadata.xml.
> 
> 
> Why not, but what's the advantage of xmlizing it vs comments in the
> ebuilds?
> 

Because metadata.xml is the place for metadata and has a defined,
verifiable and useful (in terms of actual processing/parsing data) form.

Even if you want those things to be in the ebuild, it would definitely
not be comments, but actual syntax (like exheres).

So basically the same arguments for not having random comments for USE
flags in the ebuilds apply.

Re: [gentoo-dev] [PATCH] metadata: add slots element

[Alexis Ballier]

On Mon, 12 Oct 2015 20:01:15 +0200
hasufell <hasufell@gentoo.org> wrote:

> On 10/12/2015 07:49 PM, Alexis Ballier wrote:
> > On Mon, 12 Oct 2015 19:19:33 +0200
> > Julian Ospald <hasufell@gentoo.org> wrote:
> >   
> >> There seems to be some general confusion about specific package
> >> SLOTs and their meaning, since there can be several naming schemes
> >> applied and documentation is either non-existent or is inside the
> >> ebuild via comments.
> >> Because of that it should be part of metadata.xml.  
> > 
> > 
> > Why not, but what's the advantage of xmlizing it vs comments in the
> > ebuilds?
> >   
> 
> Because metadata.xml is the place for metadata and has a defined,
> verifiable and useful (in terms of actual processing/parsing data)
> form.
> 
> Even if you want those things to be in the ebuild, it would definitely
> not be comments, but actual syntax (like exheres).
> 
> So basically the same arguments for not having random comments for USE
> flags in the ebuilds apply.
> 

makes sense

*clicks like*

Re: [gentoo-dev] [PATCH] metadata: add slots element

[Ian Delaney]

On Mon, 12 Oct 2015 20:01:15 +0200
hasufell <hasufell@gentoo.org> wrote:

> On 10/12/2015 07:49 PM, Alexis Ballier wrote:
> > On Mon, 12 Oct 2015 19:19:33 +0200
> > Julian Ospald <hasufell@gentoo.org> wrote:
> > 
> >> There seems to be some general confusion about specific package
> >> SLOTs and their meaning, since there can be several naming schemes
> >> applied and documentation is either non-existent or is inside the
> >> ebuild via comments.
> >> Because of that it should be part of metadata.xml.
> > 
> > 

Oh that word should.
You appear to state this as fact.
> > Why not, but what's the advantage of xmlizing it vs comments in the
> > ebuilds?
> > 
> 
> Because metadata.xml is the place for metadata and has a defined,
> verifiable and useful (in terms of actual processing/parsing data)
> form.
> 
> Even if you want those things to be in the ebuild, it would definitely
> not be comments, but actual syntax (like exheres).
> 
> So basically the same arguments for not having random comments for USE
> flags in the ebuilds apply.
> 

random? RANDOM? How about a carefully thought out and pertinent one
then? While use of xmlizing appears fine, I fail to see anything wrong
with entering a commented line in an ebuild as developers do all the
time as standard 'workflow'.
Just my 2 phennigs worth.

-- 
kind regards

Ian Delaney

Re: [gentoo-dev] [PATCH] metadata: add slots element

[Alexis Ballier]

On Tue, 13 Oct 2015 08:11:44 +0800
Ian Delaney <idella4@gentoo.org> wrote:

> On Mon, 12 Oct 2015 20:01:15 +0200
> hasufell <hasufell@gentoo.org> wrote:
> 
> > On 10/12/2015 07:49 PM, Alexis Ballier wrote:  
> > > On Mon, 12 Oct 2015 19:19:33 +0200
> > > Julian Ospald <hasufell@gentoo.org> wrote:
> > >   
> > >> There seems to be some general confusion about specific package
> > >> SLOTs and their meaning, since there can be several naming
> > >> schemes applied and documentation is either non-existent or is
> > >> inside the ebuild via comments.
> > >> Because of that it should be part of metadata.xml.  
> > > 
> > >   
> 
> Oh that word should.
> You appear to state this as fact.
> > > Why not, but what's the advantage of xmlizing it vs comments in
> > > the ebuilds?
> > >   
> > 
> > Because metadata.xml is the place for metadata and has a defined,
> > verifiable and useful (in terms of actual processing/parsing data)
> > form.
> > 
> > Even if you want those things to be in the ebuild, it would
> > definitely not be comments, but actual syntax (like exheres).
> > 
> > So basically the same arguments for not having random comments for
> > USE flags in the ebuilds apply.
> >   
> 
> random? RANDOM? How about a carefully thought out and pertinent one
> then? While use of xmlizing appears fine, I fail to see anything wrong
> with entering a commented line in an ebuild as developers do all the
> time as standard 'workflow'.
> Just my 2 phennigs worth.
> 

that would work too, but dtd provides standardization, and avoids
duplicating package-wide information (meaning of slot/subslot) in every
single ebuild.

Re: [gentoo-dev] [PATCH] metadata: add slots element

[hasufell]

On 10/13/2015 09:51 AM, Alexis Ballier wrote:
> 
> that would work too, but dtd provides standardization, and avoids
> duplicating package-wide information (meaning of slot/subslot) in every
> single ebuild.
> 

Yeah, the only thing that I wasn't sure about is the subslots part. With
the proposed patch we don't document a subslot for a specific slot, but
for the whole package. Everything else looked too complicated/ugly in
xml and I'm not sure we even need it. If someone has a better idea,
please speak up.
I think it should be kept simple, because we want devs to fill in this
kind of information, not confuse them.

Re: [gentoo-dev] [PATCH] metadata: add slots element

[Alexis Ballier]

On Tue, 13 Oct 2015 11:39:04 +0200
hasufell <hasufell@gentoo.org> wrote:

> On 10/13/2015 09:51 AM, Alexis Ballier wrote:
> > 
> > that would work too, but dtd provides standardization, and avoids
> > duplicating package-wide information (meaning of slot/subslot) in
> > every single ebuild.
> >   
> 
> Yeah, the only thing that I wasn't sure about is the subslots part.
> With the proposed patch we don't document a subslot for a specific
> slot, but for the whole package. Everything else looked too
> complicated/ugly in xml and I'm not sure we even need it. If someone
> has a better idea, please speak up.
> I think it should be kept simple, because we want devs to fill in this
> kind of information, not confuse them.

This looks fine as-is. Technically, subslot can be seen as a slot I
think, so we can bikeshed if you'd like :)

I see the subslots part only as extra information for subslots in case
they can be factored.
If some slot differs from the rest, it can be documented in its slot
part. If all slots differ, just describe subslot meaning in slot part
and skip subslot part.

Re: [gentoo-dev] [PATCH] metadata: add slots element

[Manuel Rüger]

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

On 13.10.2015 11:39, hasufell wrote:
> On 10/13/2015 09:51 AM, Alexis Ballier wrote:
>>
>> that would work too, but dtd provides standardization, and avoids
>> duplicating package-wide information (meaning of slot/subslot) in every
>> single ebuild.
>>
> 
> Yeah, the only thing that I wasn't sure about is the subslots part. With
> the proposed patch we don't document a subslot for a specific slot, but
> for the whole package. Everything else looked too complicated/ugly in
> xml and I'm not sure we even need it. If someone has a better idea,
> please speak up.
> I think it should be kept simple, because we want devs to fill in this
> kind of information, not confuse them.
> 

Should we extend the definition, so it can optionally
include a number of libraries the subslot is created from?

<subslot files>libfoo.so libbar.so libbaz.so</subslot files>

This would enable us to write a tool that checks for changed sonames
automatically (by using some command like find ${DESTDIR} -name
"libsoname.so" and run objdump on it.

Cheers

Manuel





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

Re: [gentoo-dev] [PATCH] metadata: add slots element

[Ian Stakenvicius]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 13/10/15 05:39 AM, hasufell wrote:
> On 10/13/2015 09:51 AM, Alexis Ballier wrote:
>> 
>> that would work too, but dtd provides standardization, and
>> avoids duplicating package-wide information (meaning of
>> slot/subslot) in every single ebuild.
>> 
> 
> Yeah, the only thing that I wasn't sure about is the subslots
> part. With the proposed patch we don't document a subslot for a
> specific slot, but for the whole package. Everything else looked
> too complicated/ugly in xml and I'm not sure we even need it. If
> someone has a better idea, please speak up. I think it should be
> kept simple, because we want devs to fill in this kind of
> information, not confuse them.
> 

Subslots are set to indicate changes from one ebuild to another,
that is loosely independent of $PV.  I see it as a per-package
description, so the way it's been described here in the XML syntax
makes a lot of sense.

+1 from me for all of it, too.

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iF4EAREIAAYFAlYel/UACgkQAJxUfCtlWe1vwQD9EW09+ofh270hbLTakjuXKSA+
ESyphRNg0pjJx6rfJ8gBANglXSYVnOM+eqryldoIlbSVgIHs+zOoBJR4YsZ/eRD6
=RUdR
-----END PGP SIGNATURE-----

Re: [gentoo-dev] [PATCH] metadata: add slots element

[Andreas K. Huettel]

Am Montag, 12. Oktober 2015, 19:19:33 schrieb Julian Ospald:
> An example use case for media-libs/libpng would be:
> <slots>
>     <slot name="0">For building against. This is the only slot
>         that provides headers and command line tools.</slot>
>     <slot name="1.2">For binary compatibility, provides
> libpng12.so.0.</slot> <slot name="1.5">For binary compatibility, provides
> libpng15.so.15.</slot> <subslots>Represent ABI compatibility for
> libpng.so.</subslots> </slots>
> 
> For packages like x11-libs/wxGTK one could write:
> <slots>
>     <slot name="*">Major versions.</slot>
> </slots>

+1

-- 
Andreas K. Huettel
Gentoo Linux developer (council, perl, libreoffice)
dilfridge@gentoo.org
http://www.akhuettel.de/

Re: [gentoo-dev] [PATCH] metadata: add slots element

[NP-Hardass]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Mon, 12 Oct 2015 23:49:11 +0200
"Andreas K. Huettel" <dilfridge@gentoo.org> wrote:

> There seems to be some general confusion about specific package SLOTs
> and their meaning, since there can be several naming schemes applied
> and documentation is either non-existent or is inside the ebuild via
> comments.
> Because of that it should be part of metadata.xml.
> 
> An example use case for media-libs/libpng would be:
> <slots>
>     <slot name="0">For building against. This is the only slot
>         that provides headers and command line tools.</slot>
>     <slot name="1.2">For binary compatibility, provides
> libpng12.so.0.</slot> <slot name="1.5">For binary compatibility,
> provides libpng15.so.15.</slot> <subslots>Represent ABI compatibility
> for libpng.so.</subslots> </slots>
> 
> For packages like x11-libs/wxGTK one could write:
> <slots>
>     <slot name="*">Major versions.</slot>
> </slots>
> ---
>  metadata.dtd | 12 +++++++++++-
>  1 file changed, 11 insertions(+), 1 deletion(-)
> 
> diff --git a/metadata.dtd b/metadata.dtd
> index ff2649c..4b29f3b 100644
> --- a/metadata.dtd
> +++ b/metadata.dtd
> @@ -5,7 +5,7 @@
>  <!ATTLIST catmetadata pkgname CDATA "">
>  
>  <!-- Metadata for a package -->
> -<!ELEMENT pkgmetadata
> ( (herd|maintainer|natural-name|longdescription|use|upstream)* )>
> +<!ELEMENT pkgmetadata
> ( (herd|maintainer|natural-name|longdescription|slots|use|upstream)*
> )> <!ATTLIST pkgmetadata pkgname CDATA ""> <!-- One tag for each herd
> this package is assigned to. --> @@ -20,6 +20,15 @@
>    <!-- A long description of the package in freetext-->
>    <!ELEMENT longdescription (#PCDATA|pkg|cat)* >
>  
> +  <!-- A description of the packages SLOTs -->
> +  <!ELEMENT slots ((slot)*,subslots?) >
> +    <!-- A particular SLOT -->
> +    <!ELEMENT slot (#PCDATA)* >
> +      <!-- name attribute holds the name of the SLOT, for sub-SLOTS
> use the subslots element -->
> +      <!ATTLIST slot name CDATA #REQUIRED >
> +    <!-- The meaning of sub-SLOTs for the whole package -->
> +    <!ELEMENT subslots (#PCDATA)* >
> +
>    <!-- The changelog of the package-->
>    <!-- Please note that #PCDATA is mentioned only for the upstream
> changelog element, where the content is a URL. This is due to
> limitations of the DTD --> @@ -79,6 +88,7 @@
>    language "C" or "en", which is equivalent -->
>    <!ATTLIST description lang CDATA "C" >
>    <!ATTLIST longdescription lang CDATA "C" >
> +  <!ATTLIST slots lang CDATA "C" >
>    <!ATTLIST use lang CDATA "C" >
>  
>  <!-- The restrict attribute, this attribute specifies restrictions
> on 

+1
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJWHGj/AAoJEBzZQR2yrxj7KWcQAJXawG1eTgdJZx1shunzk1QN
xLgHs0dKvsmvnutDkqxcdJ3p2OzbdHlJpZQn88htdfj3c2vYqEMCnORPYtdmqAUD
HzdnSdcXnfCIPGVcOy+uFftndW1A+AXDqouLDOh0AAbZ0loQKNvrbqlk6IB85p9d
yq3f/0oWYdE989BqRiljFWmDbCLvFe1D7oH3CAORzcZenOA5OpPxLfpR9dwpQrO1
1NHf+7HyvMK1LWABmGPySQgh12kCZWMri7F1epr1jepeuUtAormlAFG8I6fc0p6C
KPS21Oqu8ejHTL0ekL+0YDfjJtGbyZ0EexGrhPZwBA7X3E4R0bHxQxOYHc41jO3L
3owOk6nKkBT8iUClxz1uaS7IuhgpyPcGhrjnyzH5HP6K2Dr/FQCz9QS9RERnnFBu
HShFOttmVK4rvDUcsWcVx1SHnGWGonESsyjjRw6jGV7sbXD1kEsGjjf5JuYNMk6/
45tOP23HbIxj6eyMACXoQpXS3N+4nsBLHwZyLunGYd7RM7lLG7/byS3GXXweornr
MK9GYaPAxyyYPqt60UTJqfeFjNps30KuNgPeQva0ooRBPCS/GPt+N3PLdGWJ68mq
45Lne/c6JcD67wqsCllxg0IlsiNpnltq68Ky7mVir6eHo9RU1bhfoOLgZNxVUll9
uCMVDFG3047ynEMTV2Mj
=9URl
-----END PGP SIGNATURE-----

[gentoo-dev] Re: [PATCH] metadata: add slots element

[Michael Palimaka]

On 13/10/15 04:19, Julian Ospald wrote:
> There seems to be some general confusion about specific package SLOTs
> and their meaning, since there can be several naming schemes applied
> and documentation is either non-existent or is inside the ebuild via
> comments.
> Because of that it should be part of metadata.xml.
> 
> An example use case for media-libs/libpng would be:
> <slots>
>     <slot name="0">For building against. This is the only slot
>         that provides headers and command line tools.</slot>
>     <slot name="1.2">For binary compatibility, provides libpng12.so.0.</slot>
>     <slot name="1.5">For binary compatibility, provides libpng15.so.15.</slot>
>     <subslots>Represent ABI compatibility for libpng.so.</subslots>
> </slots>
> 
> For packages like x11-libs/wxGTK one could write:
> <slots>
>     <slot name="*">Major versions.</slot>
> </slots>
> ---
>  metadata.dtd | 12 +++++++++++-
>  1 file changed, 11 insertions(+), 1 deletion(-)
> 
> diff --git a/metadata.dtd b/metadata.dtd
> index ff2649c..4b29f3b 100644
> --- a/metadata.dtd
> +++ b/metadata.dtd
> @@ -5,7 +5,7 @@
>  <!ATTLIST catmetadata pkgname CDATA "">
>  
>  <!-- Metadata for a package -->
> -<!ELEMENT pkgmetadata ( (herd|maintainer|natural-name|longdescription|use|upstream)* )>
> +<!ELEMENT pkgmetadata ( (herd|maintainer|natural-name|longdescription|slots|use|upstream)* )>
>  <!ATTLIST pkgmetadata pkgname CDATA "">
>  
>    <!-- One tag for each herd this package is assigned to. -->
> @@ -20,6 +20,15 @@
>    <!-- A long description of the package in freetext-->
>    <!ELEMENT longdescription (#PCDATA|pkg|cat)* >
>  
> +  <!-- A description of the packages SLOTs -->
> +  <!ELEMENT slots ((slot)*,subslots?) >
> +    <!-- A particular SLOT -->
> +    <!ELEMENT slot (#PCDATA)* >
> +      <!-- name attribute holds the name of the SLOT, for sub-SLOTS use the subslots element -->
> +      <!ATTLIST slot name CDATA #REQUIRED >
> +    <!-- The meaning of sub-SLOTs for the whole package -->
> +    <!ELEMENT subslots (#PCDATA)* >
> +
>    <!-- The changelog of the package-->
>    <!-- Please note that #PCDATA is mentioned only for the upstream changelog
>      element, where the content is a URL. This is due to limitations of the DTD -->
> @@ -79,6 +88,7 @@
>    language "C" or "en", which is equivalent -->
>    <!ATTLIST description lang CDATA "C" >
>    <!ATTLIST longdescription lang CDATA "C" >
> +  <!ATTLIST slots lang CDATA "C" >
>    <!ATTLIST use lang CDATA "C" >
>  
>  <!-- The restrict attribute, this attribute specifies restrictions on 
> 

+1

Re: [gentoo-dev] [RFC] Allow SLOT documentation in metadata.xml

[Alexis Ballier]

On Mon, 12 Oct 2015 19:19:32 +0200
Julian Ospald <hasufell@gentoo.org> wrote:

> The following patch tries to address the lack of slot
> documentation, since getting the slots of a dependency
> right seems like a common problem.
> 
> Things that I was particularly not sure about: the 'subslots'
> element. Having a sub-element for 'slot' seemed even more
> messy, so I tried to make this as simple as possible, so
> that maintainers don't get angry and give up when trying
> to document their slots. However, this is a little bit
> at the expense of correctness, because you cannot
> document different subslot naming schemes if they differ
> between slots of a single package (does such thing even exist
> in the tree?).
> 


btw, once this is committed, please consider adding or asking for a
repoman warning when subslot is defined but metadata.xml is not filled

Re: [gentoo-dev] [RFC] Allow SLOT documentation in metadata.xml

[hasufell]

On 10/18/2015 08:21 PM, Alexis Ballier wrote:
> 
> 
> btw, once this is committed, please consider adding or asking for a
> repoman warning when subslot is defined but metadata.xml is not filled
> 

Almost forgot: it has been committed yesterday:
https://gitweb.gentoo.org/data/dtd.git/commit/?id=551e00fc42ed21f6a6ff6129b5b85e64725d9665