[gentoo-dev] [PATCH v2 2/4] ebuild-writing/misc-files/metadata: rewrite the section per GLEP 67 #572144

2016-05-14 Thread Göktürk Yüksek 
A major rewrite of the section. Here is a brief summary of changes:
- Remove the information about the  tag per GLEP 67
- Restructure the section in the following order:
  - metadata.xml syntax
  - package metadata
- metadata examples
- maintainer-needed
  - category metadata
- Update the tables for metadata.xml syntax per GLEP 67
- Rewrite the package metadata examples to reflect better on GLEP 67
  and enhance with more explanations
- Assign meaningful titles to package metadata examples instead of
  using "First Example", "Second Example" etc.
- Add a subsection for handling maintainer-needed in metadata.xml
  per GLEP 67 and provide an example

This commit also makes #545272 obsolete.

Gentoo-Bug: https://bugs.gentoo.org/show_bug.cgi?id=572144
Gentoo-Bug: https://bugs.gentoo.org/show_bug.cgi?id=545272
Signed-off-by: Göktürk Yüksek 
---
 ebuild-writing/misc-files/metadata/text.xml | 418 
 1 file changed, 238 insertions(+), 180 deletions(-)

diff --git a/ebuild-writing/misc-files/metadata/text.xml 
b/ebuild-writing/misc-files/metadata/text.xml
index 2324f53..31ec926 100644
--- a/ebuild-writing/misc-files/metadata/text.xml
+++ b/ebuild-writing/misc-files/metadata/text.xml
@@ -10,16 +10,7 @@ package or category.
 
 
 
-Package Metadata
-
-
-For packages, metadata.xml can specify a long description and
-maintainer information. If a long description in any language is
-provided, an English long description must be present. A typical
-example might look like:
-
-
-
+Syntax
 
 
 
@@ -39,13 +30,10 @@ A metadata.xml file can contain a number of 
tags:
 This is the root element of the metadata.xml file for
 packages. It has no attributes. The following subtags are
 allowed:
-,
 ,
 ,
 , and
 .
-There should be at least one  or
- subtag.
   
 
 
@@ -62,26 +50,16 @@ A metadata.xml file can contain a number of 
tags:
 
 
   
-
-  
-  
-If a package is maintained by one or more herds, names of these herds
-can be specified with the  tag. The names
-used in this tag must be the same as specified in the https://sources.gentoo.org/viewcvs.py/*checkout*/gentoo/xml/htdocs/proj/en/metastructure/herds/herds.xml?content-type=text/plain&rev=HEAD";>herds.xml
-file.
-  
-
-
-  
 
   
   
-Besides being part of a herd, a package can also be maintained directly. 
-The maintainers of a package can be specified with the 
- tag. This tag has one required subtag: 
+This tag specifies the persons and/or projects responsible for
+the maintenance of a package. The type attribute must
+be specified and can be either "person" or
+"project". There is one required subtag:
 . It has two optional subtags:
-, and .
+ and
+.
   
 
 
@@ -207,8 +185,7 @@ A metadata.xml file can contain a number of 
tags:
 
 
 
-There are also some attributes that can be used with these tags. They are all
-optional:
+There are also some attributes that can be used with these tags:
 
 
 
@@ -235,7 +212,7 @@ optional:
 
   restrict
   
-, , 
+,
 , 
   
   
@@ -244,12 +221,7 @@ optional:
 without this attribute must also exist. That tag without the restrict 
 attribute will serve as the default. The format of the restrict attribute 
 is that of the DEPEND flag, except that "<" and 
-">" need to be specified by < and >.
-
-For example, in the sys-libs/db package, 
-restrict=">=sys-libs/db-3.2.9-r5"  on the
-maintainer tag shows that I'm currently maintaining all
-versions greater then 3.2.9-r5.
+">" need to be specified by "<" and ">".
   
 
 
@@ -282,212 +254,298 @@ optional:
 
   
   
-A string identifying the type of upstream source. A list of valid strings 
are kept in metadata.dtd.
+A string identifying the type of upstream source. A list of valid strings 
are kept in
+https://www.gentoo.org/dtd/metadata.dtd";>metadata.dtd.
 Developers should email the gentoo-dev mailing list before using a new 
type value. 
   
 
+
+  type
+  
+
+  
+  
+Defines the type of the maintainer for a package. There are only
+two valid values: "person" and "project". The latter
+denotes an official
+
+Gentoo project.
+  
+
 
 
 
 
-
-
-
 
-
 
-Metadata Examples
-
-First Example
+Package Metadata
 
-
 
-In this first example we provide you with the metadata.xml for 
-OpenOffice of which the ebuilds are completely managed by a herd called
-openoffice:
+All packages must include a metadata.xml file which
+provides information about package description, maintainers, local USE
+flags, upstream etc.
 
 
-
-
-;
-

Re: [gentoo-dev] [PATCH v2 2/4] ebuild-writing/misc-files/metadata: rewrite the section per GLEP 67 #572144

2016-05-15 Thread Michał Górny 
On Sat, 14 May 2016 20:57:48 -0400
Göktürk Yüksek  wrote:

> @@ -244,12 +221,7 @@ optional:
>  without this attribute must also exist. That tag without the restrict 
>  attribute will serve as the default. The format of the restrict 
> attribute 
>  is that of the DEPEND flag, except that "<" and 
> -">" need to be specified by < and >.
> -
> -For example, in the sys-libs/db package, 
> -restrict=">=sys-libs/db-3.2.9-r5"  on the
> -maintainer tag shows that I'm currently maintaining all
> -versions greater then 3.2.9-r5.
> +">" need to be specified by "<" and ">".
>
>  
>  

I'm sorry for coming late to the party but could you mention that it
must be an EAPI 0 package dependency? There were more than a few
packages where people put slot- or USE-dependencies there.

-- 
Best regards,
Michał Górny



pgpdrcEhILP4Q.pgp
Description: OpenPGP digital signature

Re: [gentoo-dev] [PATCH v2 2/4] ebuild-writing/misc-files/metadata: rewrite the section per GLEP 67 #572144

2016-05-15 Thread Göktürk Yüksek 
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA512

Michał Górny:
> On Sat, 14 May 2016 20:57:48 -0400 Göktürk Yüksek
>  wrote:
> 
>> @@ -244,12 +221,7 @@ optional: without this attribute must also
>> exist. That tag without the restrict attribute will serve as the
>> default. The format of the restrict attribute is that of the
>> DEPEND flag, except that "<" and -">" need to be
>> specified by < and >. - -For
>> example, in the sys-libs/db package, -
>> restrict=">=sys-libs/db-3.2.9-r5"  on the -
>> maintainer tag shows that I'm currently
>> maintaining all -versions greater then 3.2.9-r5. +">"
>> need to be specified by "<" and ">".   
>> 
> 
> I'm sorry for coming late to the party but could you mention that
> it must be an EAPI 0 package dependency? There were more than a
> few packages where people put slot- or USE-dependencies there.
> 

The purpose of this change was to remove the example inside the table
since I've added a complete example with restrict under the metadata
examples section.

PATCH 3/4 accomplishes what you ask:
+the restrict attribute serves as the default. The format of the
+restrict attribute is that of a EAPI=0 package dependency
+specification. Due to the limitations of XML, the "<" and

-BEGIN PGP SIGNATURE-

iQEcBAEBCgAGBQJXOS8RAAoJEIT4AuXAiM4z21sH+wWVlhYAZpGTIaBJydWWnynI
zuF1CmHxb4dlLh9zbwMcMuRavbxYbKsI3P0D2p4h1kNI6a9jZzAAvHF99eTC6o54
+PjwgxroxtTHKrp147Jmubrj+u70EWvj2JGxIprRkS5A0ZW+zE24n37IA/8AtwEL
XV24dB1HSs98WkfJbnhYmS6nxyQHz0fiFRM4o1syxtHyu9bS1zXE+fEevqeTOo4i
PlqJCgyepvyPdcYeDHVOz7b9MqXy19+GTPFxHzfoHMBWB4/X/6umYE+1n9CRIjeX
THhiCZ/6uXVvXJgUcaoLlWE984wbgEzt9j4zp2CJqG0FgyndtCuW9QZrY8gWW4I=
=kmMC
-END PGP SIGNATURE-