* [gentoo-dev] [PATCH v2 1/4] general-concepts/herds-and-projects: update per GLEP 67 #572144 #549490
2016-05-15 0:57 [gentoo-dev] [PATCH v2 0/4] devmanual: update the docs per GLEP 67 and 68 Göktürk Yüksek
@ 2016-05-15 0:57 ` Göktürk Yüksek
2016-05-15 0:57 ` [gentoo-dev] [PATCH v2 2/4] ebuild-writing/misc-files/metadata: rewrite the section per GLEP 67 #572144 Göktürk Yüksek
` (2 subsequent siblings)
3 siblings, 0 replies; 7+ messages in thread
From: Göktürk Yüksek @ 2016-05-15 0:57 UTC (permalink / raw
To: devmanual; +Cc: gentoo-dev
The changes are:
- Rename the title to "Projects and Herds" to put the emphasis
on projects
- Explain projects and subprojects in a new "Projects" section
- Add a subsection for starting new projects
- Add a subsection for joining/leaving a project
- Put a warning label at the beginning of the "Herds" section,
declare it obsolete, and preserve it for historical reasons
Gentoo-Bug: https://bugs.gentoo.org/show_bug.cgi?id=572144
Gentoo-Bug: https://bugs.gentoo.org/show_bug.cgi?id=549490
Signed-off-by: Göktürk Yüksek <gokturk@binghamton.edu>
---
general-concepts/herds-and-projects/text.xml | 101 ++++++++++++++++++++++++++-
1 file changed, 100 insertions(+), 1 deletion(-)
diff --git a/general-concepts/herds-and-projects/text.xml b/general-concepts/herds-and-projects/text.xml
index e030150..81b1885 100644
--- a/general-concepts/herds-and-projects/text.xml
+++ b/general-concepts/herds-and-projects/text.xml
@@ -1,10 +1,106 @@
<?xml version="1.0"?>
<guide self="general-concepts/herds-and-projects/">
<chapter>
-<title>Herds and Projects</title>
+<title>Projects and Herds</title>
<body>
+<section>
+<title>Projects</title>
+<body>
+
+<p>
+The management structure of Gentoo, called the "metastructure", is
+defined in
+<uri link="https://wiki.gentoo.org/wiki/GLEP:39#Specification">
+GLEP 39</uri>. In Gentoo, a project is a group of developers working
+towards a common goal in various different areas. For example, the
+<uri link="https://wiki.gentoo.org/wiki/Project:Devmanual">
+Devmanual</uri> project focuses on maintaining this document. Many
+others are responsible for maintaining packages. Projects spanning a
+large area of topics can have multiple subprojects specializing in
+particular fields within the domain of the parent project and thus
+form a project hierarchy.
+</p>
+
+<p>
+A package maintained by a project needs to have the
+project explicitly listed as a maintainer in its
+<uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri>.
+The full listing of all the projects can be found on
+<uri link="https://api.gentoo.org/metastructure/projects.xml">
+api.gentoo.org</uri> or on the
+<uri link="https://wiki.gentoo.org/wiki/Project:Gentoo">wiki</uri>.
+</p>
+
+<subsection>
+<title>Starting New Projects</title>
+<body>
+
+<p>
+According to the metastructure any developer may create a new
+project. There are two procedures involved in starting a new project:
+
+<ol>
+ <li>
+ Create a new project page <uri
+ link="https://wiki.gentoo.org/wiki/Gentoo_Wiki:Developer_Central/Project_pages">
+ through the wiki</uri>.
+ </li>
+ <li>
+ Post a Request For Comments (RFC) email to the gentoo-dev
+ mailing list.
+ </li>
+</ol>
+
+There is no approval required for the RFC and negative comments do not
+block a developer from creating a project. Competing projects are
+allowed to co-exist in Gentoo; existence of another project with
+similar goals do not block another developer from starting a new
+project with the same goals.
+</p>
+
+</body>
+</subsection>
+<subsection>
+<title>Joining and Leaving a Project</title>
+<body>
+
+<p>
+Members of a project are managed through the project's page on the
+Gentoo Wiki. Each page has a "Project" template in its source which
+lists the members of the project. Simply modifying the list is
+sufficient for adding or removing a developer. Note that different
+projects have different requirements and procedures for recruiting
+developers, which may require prior arrangements to be made before
+modifying the member list.
+</p>
+
+<p>
+Developers should remember to add themselves to the alias by editing
+<c><path>/var/mail/alias/misc/<alias name></path></c> on
+dev.gentoo.org. For example, the alias for the Devmanual project is
+located at <c>/var/mail/alias/misc/devmanual</c>, which corresponds to
+the project's email address <c>devmanual@gentoo.org</c>.
+</p>
+
+</body>
+</subsection>
+
+</body>
+</section>
+
+<section>
+<title>Herds</title>
+<body>
+
+<warning>
+Herds have been declared obsolete as per the Gentoo Council's <uri
+link="https://projects.gentoo.org/council/meeting-logs/20160110-summary.txt">
+decision on January 10, 2016</uri>. The following section is preserved
+for historical purposes.
+</warning>
+
<p>
A <e>herd</e> is a collection of packages with an associated set of maintainers.
It can happen for example because of retirement that a herd has no developers
@@ -27,6 +123,9 @@ as the <c>silo</c> bootloader). This is <e>not</e> always the case.
</p>
</body>
+</section>
+
+</body>
</chapter>
</guide>
--
2.7.3
^ permalink raw reply related [flat|nested] 7+ messages in thread* [gentoo-dev] [PATCH v2 2/4] ebuild-writing/misc-files/metadata: rewrite the section per GLEP 67 #572144
2016-05-15 0:57 [gentoo-dev] [PATCH v2 0/4] devmanual: update the docs per GLEP 67 and 68 Göktürk Yüksek
2016-05-15 0:57 ` [gentoo-dev] [PATCH v2 1/4] general-concepts/herds-and-projects: update per GLEP 67 #572144 #549490 Göktürk Yüksek
@ 2016-05-15 0:57 ` Göktürk Yüksek
2016-05-15 7:54 ` Michał Górny
2016-05-15 0:57 ` [gentoo-dev] [PATCH v2 3/4] ebuild-writing/misc-files/metadata: update wrt slotting and per GLEP 68 Göktürk Yüksek
2016-05-15 0:57 ` [gentoo-dev] [PATCH v2 4/4] ebuild-writing/misc-files/metadata: add an example for slots and subslots Göktürk Yüksek
3 siblings, 1 reply; 7+ messages in thread
From: Göktürk Yüksek @ 2016-05-15 0:57 UTC (permalink / raw
To: devmanual; +Cc: gentoo-dev
A major rewrite of the section. Here is a brief summary of changes:
- Remove the information about the <herd> 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 <gokturk@binghamton.edu>
---
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.
</p>
<section>
-<title>Package Metadata</title>
-<body>
-<p>
-For packages, <c>metadata.xml</c> 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:
-</p>
-
-<subsection>
+<title>Syntax</title>
<body>
<p>
@@ -39,13 +30,10 @@ A <path>metadata.xml</path> file can contain a number of tags:
This is the root element of the <path>metadata.xml</path> file for
packages. It has no attributes. The following subtags are
allowed:
- <brite><herd></brite>,
<brite><maintainer></brite>,
<brite><longdescription></brite>,
<brite><use></brite>, and
<brite><upstream></brite>.
- There should be at least one <brite><herd></brite> or
- <brite><maintainer></brite> subtag.
</ti>
</tr>
<tr>
@@ -62,26 +50,16 @@ A <path>metadata.xml</path> file can contain a number of tags:
</tr>
<tr>
<ti>
- <brite><herd></brite>
- </ti>
- <ti>
- If a package is maintained by one or more herds, names of these herds
- can be specified with the <brite><herd></brite> tag. The names
- used in this tag must be the same as specified in the <uri
- link="https://sources.gentoo.org/viewcvs.py/*checkout*/gentoo/xml/htdocs/proj/en/metastructure/herds/herds.xml?content-type=text/plain&rev=HEAD">herds.xml</uri>
- file.
- </ti>
-</tr>
-<tr>
- <ti>
<brite><maintainer></brite>
</ti>
<ti>
- Besides being part of a herd, a package can also be maintained directly.
- The maintainers of a package can be specified with the
- <brite><maintainer></brite> tag. This tag has one required subtag:
+ This tag specifies the persons and/or projects responsible for
+ the maintenance of a package. The <c>type</c> attribute must
+ be specified and can be either <c>"person"</c> or
+ <c>"project"</c>. There is one required subtag:
<brite><email></brite>. It has two optional subtags:
- <brite><name></brite>, and <brite><description></brite>.
+ <brite><name></brite> and
+ <brite><description></brite>.
</ti>
</tr>
<tr>
@@ -207,8 +185,7 @@ A <path>metadata.xml</path> file can contain a number of tags:
</table>
<p>
-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:
</p>
<table>
@@ -235,7 +212,7 @@ optional:
<tr>
<ti>restrict</ti>
<ti>
- <brite><herd></brite>, <brite><maintainer></brite>,
+ <brite><maintainer></brite>,
<brite><longdescription></brite>, <brite><flag></brite>
</ti>
<ti>
@@ -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 &lt; and &gt;.<br />
- <br />
- For example, in the <c>sys-libs/db</c> package,
- <c>restrict="&gt;=sys-libs/db-3.2.9-r5"</c> on the
- <brite>maintainer</brite> tag shows that I'm currently maintaining all
- versions greater then 3.2.9-r5.
+ ">" need to be specified by "&lt;" and "&gt;".
</ti>
</tr>
<tr>
@@ -282,212 +254,298 @@ optional:
<brite><remote-id></brite>
</ti>
<ti>
- 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
+ <uri link="https://www.gentoo.org/dtd/metadata.dtd">metadata.dtd</uri>.
Developers should email the gentoo-dev mailing list before using a new type value.
</ti>
</tr>
+<tr>
+ <ti>type</ti>
+ <ti>
+ <brite><maintainer></brite>
+ </ti>
+ <ti>
+ Defines the type of the maintainer for a package. There are only
+ two valid values: <c>"person"</c> and <c>"project"</c>. The latter
+ denotes an official
+ <uri link="::general-concepts/herds-and-projects">
+ Gentoo project</uri>.
+ </ti>
+</tr>
</table>
</body>
-</subsection>
-
-</body>
</section>
-
<section>
-<title>Metadata Examples</title>
-<subsection>
-<title>First Example</title>
+<title>Package Metadata</title>
<body>
-
<p>
-In this first example we provide you with the <path>metadata.xml</path> for
-OpenOffice of which the ebuilds are completely managed by a herd called
-<c>openoffice</c>:
+All packages <b>must</b> include a <c>metadata.xml</c> file which
+provides information about package description, maintainers, local USE
+flags, upstream etc.
</p>
-<codesample lang="sgml">
-<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd">
-<pkgmetadata>
- <herd>openoffice</herd>
- <longdescription>
- OpenOffice is the opensource version of staroffice.
- This ebuild allows you to compile it yourself. Unfortunately this
- compilation can take up to a day depending on the speed of your
- computer. It will however make a snappier openoffice than the binary
- version.
- </longdescription>
-</pkgmetadata>
-</codesample>
+<p>
+For developers' convenience, a skeleton file is provided in the
+Gentoo tree with the name
+<uri link="https://gitweb.gentoo.org/repo/gentoo.git/tree/skel.metadata.xml">
+skel.metadata.xml</uri>. The metadata file can also be created
+using the <c>app-portage/metagen</c> tool.
+</p>
<p>
-The <c>openoffice</c> herd is defined in <path>herds.xml</path> by the
-<uri link="https://www.gentoo.org/proj/en/metastructure">Gentoo Metastructure Project</uri>:
+Commits of package metadata files are handled by <c>repoman</c>. In
+order for metadata checks to be performed, <c>dev-libs/libxml2</c>
+must be installed on the system.
</p>
-<note>
-This example may be outdated when you read it. It's just an example!
-</note>
+<p>
+Unless specified otherwise, the maintainer who is listed in the
+metadata first shall be the assignee for the bugs for that package as
+per <uri link="https://wiki.gentoo.org/wiki/GLEP:67#Bug_assignment">
+GLEP 67</uri>.
+</p>
-<codesample lang="sgml">
-<herd>
- <name>openoffice</name>
- <email>openoffice@gentoo.org</email>
- <description>Openoffice related packages</description>
- <maintainer><email>pauldv@gentoo.org</email></maintainer>
- <maintainer><email>suka@gentoo.org</email></maintainer>
-</herd>
-</codesample>
+<subsection>
+<title>Package Metadata Examples</title>
+<body>
<p>
-If you want to add (or remove) yourself from a herd, edit <path>herds.xml</path>
-located in <path>[gentoo]/xml/htdocs/proj/en/metastructure/herds</path> in Gentoo's CVS repository. Make sure you
-know the e-mail alias the herd listens to (for instance the "sound" herd has
-<mail link="sound@gentoo.org">sound@gentoo.org</mail>) and add yourself to the
-alias (by editing <path>/var/mail/alias/misc/<alias name></path> on
-dev.gentoo.org).
+In the following sections, various examples of metadata.xml are
+provided. These examples are based on actual package metadata files to
+keep things as realistic as possible. However, they may not include
+these files verbatim and should be taken as hypothetical examples.
</p>
-</body>
-</subsection>
-<subsection>
-<title>Second Example</title>
+<subsubsection>
+<title>Projects as Maintainers</title>
<body>
<p>
-For the second example, we will examine the <path>metadata.xml</path> of
-<c>app-portage/mirrorselect</c>. This ebuild is maintained by the
-<c>tools-portage</c> herd, but has a separate maintainer.
+For the first example, a package maintained by a single project is
+presented. It is a simplified version of <path>metadata.xml</path> for
+the package <path>app-office/libreoffice</path>. The package
+maintainer is identified by the email address <c>office@gentoo.org</c>
+with the name <c>Gentoo Office Project</c> as specified in the
+optional <name> subtag. It also provides a long package
+description.
</p>
<codesample lang="sgml">
-<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd">
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
<pkgmetadata>
- <herd>tools-portage</herd>
- <maintainer>
- <email>johnm@gentoo.org</email>
- <name>John Mylchreest</name>
+ <maintainer type="project">
+ <email>office@gentoo.org</email>
+ <name>Gentoo Office Project</name>
</maintainer>
<longdescription>
- This utility is used to select the fastest mirror (distfiles) and provide a
- nicer front-end for mirror selection (both rsync + distfiles) to a user.
+ LibreOffice is the successor of OpenOffice.org. This ebuild
+ allows you to compile it yourself. Unfortunately this compilation can
+ take up to a day depending on the speed of your computer. It will
+ however make a snappier LibreOffice than the binary version.
</longdescription>
</pkgmetadata>
</codesample>
-</body>
-</subsection>
-<subsection>
-<title>Third Example</title>
-<body>
-
<p>
-For the third example, we will describe the <path>metadata.xml</path> of
-<c>sys-apps/hal</c>. This ebuild is maintained by the <c>gentopia</c> herd
-and contains USE flag descriptions.
+The email address <c>office@gentoo.org</c> corresponds to the
+<c>Gentoo Office Project</c> as defined in
+<uri link="https://api.gentoo.org/metastructure/projects.xml">
+projects.xml</uri>. This file lists all the projects in Gentoo and it
+is generated from the
+<uri link="https://wiki.gentoo.org/wiki/Project:Gentoo">
+projects listing</uri> available on the Gentoo Wiki:
</p>
<codesample lang="sgml">
-<?xml version="1.0" encoding="UTF-8">
-<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd">
-<pkgmetadata>
-<herd>gentopia</herd>
-<maintainer>
- <email>compnerd@gentoo.org</email>
-</maintainer>
-<maintainer>
- <email>steev@gentoo.org</email>
-</maintainer>
-<use>
- <flag name='acpi'>Enables HAL to attempt to read from
- /proc/acpi/event, if unavailable, HAL will read events from
- <pkg>sys-power/acpid</pkg>. If you need multiple acpi
- readers, ensure acpid is in your default runlevel along with HAL. This
- will also enable HAL to read Toshia and IBM acpi events which do not
- get sent via /proc/acpi/event</flag>
- <flag name='crypt'>Allows HAL to mount volumes that are encrypted using
- LUKS. <pkg>sys-fs/cryptsetup-luks</pkg> which has recently been renamed
- to <pkg>sys-fs/cryptsetup</pkg> allows you to create such encrypted
- volumes. HAL will be able to handle volumes that are removable or
- fixed.</flag>
- <flag name='dell'>Builds an installs the Dell addon, which reads data from
- the Dell SM BIOS via <pkg>sys-libs/libsmbios</pkg>. It will read your
- service tag information and your hardware backlight data as well as
- allow you to modify the backlight settings on a Dell laptop.</flag>
- <flag name='disk-partition'>Allows HAL to use libparted from
- <pkg>sys-apps/parted</pkg> to read raw partition data from your disks
- and process that data. Future versions of HAL (possibly 0.5.11 and
- higher) will allow you to create, modify, delete and format partitions
- from a GUI interface agnostic of your desktop environment.</flag>
- <flag name='doc'>Generates documentation that describes HAL's fdi
- format.</flag>
- <flag name='pcmcia'>Allows HAL to process PCMCIA/CardBus slot data which
- includes inserts and removals and act on these events.</flag>
- <flag name='selinux'>Installs SELinux policies and links HAL to the SELinux
- libraries.</flag>
-</use>
-</pkgmetadata>
+<project>
+ <email>office@gentoo.org</email>
+ <name>Gentoo Office Project</name>
+ <url>https://wiki.gentoo.org/wiki/Project:Office</url>
+ <description>
+ The Office project manages the office implementations
+ and related packages in Gentoo.
+ </description>
+ <member>
+ <email>dilfridge@gentoo.org</email>
+ <name>Andreas K. Hüttel</name>
+ <role>member</role>
+ </member>
+ <member>
+ <email>scarabeus@gentoo.org</email>
+ <name>Tomáš Chvátal</name>
+ <role>member</role>
+ </member>
+</project>
</codesample>
</body>
-</subsection>
-<subsection>
-<title>Fourth Example</title>
+</subsubsection>
+<subsubsection>
+<title>Local USE Flag Descriptions</title>
<body>
<p>
-This example demonstrates the usage of the upstream element:
+The second example is formed after the <path>metadata.xml</path> of
+<path>sys-apps/portage</path>. It lists multiple maintainers where one
+is a developer and the other is a project. It illustrates how local
+USE flag descriptions are specified and also contains an upstream
+element. It is also worth pointing out the use of <c>mailto:</c>
+prefix in <bugs-to> tag due to the presence of an email address
+as opposed to a URL. Conversely, email addresses specified in the
+<email> tags require no such prefix.
</p>
<codesample lang="sgml">
-<upstream>
- <maintainer status="inactive">
- <email>foo@bar.bar</email>
- <name>Foo Bar</name>
- </maintainer>
- <maintainer status="active">
- <email>foo@gentoo.org</email>
- <name>Foo Gentoo</name>
- </maintainer>
- <changelog>http://foo.bar/changelog.txt</changelog>
- <doc lang="en">http://foo.bar/doc/index.html</doc>
- <doc lang="de">http://foo.bar/doc/index.de.html</doc>
- <bugs-to>https://bugs.foo.bar</bugs-to>
- <remote-id type="freshmeat">foobar</remote-id>
- <remote-id type="sourceforge">foobar</remote-id>
-</upstream>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+<pkgmetadata>
+ <upstream>
+ <bugs-to>mailto:dev-portage@gentoo.org</bugs-to>
+ <changelog>https://gitweb.gentoo.org/proj/portage.git/plain/RELEASE-NOTES</changelog>
+ <doc>https://wiki.gentoo.org/wiki/Handbook:AMD64/Working/Portage</doc>
+ </upstream>
+ <maintainer type="person">
+ <email>larry@gentoo.org</email>
+ <name>Larry the Cow</name>
+ </maintainer>
+ <maintainer type="project">
+ <email>dev-portage@gentoo.org</email>
+ </maintainer>
+ <use>
+ <flag name="epydoc">Build html API documentation with epydoc.</flag>
+ <flag name="ipc">Use inter-process communication between portage and running ebuilds.</flag>
+ <flag name="pypy2_0">Use pypy-c2.0 as Python interpreter.</flag>
+ <flag name="python2">Use python2 as Python interpreter.</flag>
+ <flag name="python3">Use python3 as Python interpreter.</flag>
+ <flag name="xattr">
+ Preserve extended attributes (filesystem-stored metadata) when
+ installing files. Usually only required for hardened systems.
+ </flag>
+ </use>
+</pkgmetadata>
</codesample>
</body>
-</subsection>
-
+</subsubsection>
+<subsubsection>
+<title>Split Maintainership</title>
+<body>
<p>
-All new packages <b>must</b> include a <c>metadata.xml</c> file. That file
-should specify at least one herd or one maintainer. It is however recommended,
-if at all possible, to find a herd willing to be listed.
+This example splits the maintainership based on package versions using
+the attribute <c>restrict</c>. According to the
+<path>metadata.xml</path> of <path>sys-boot/grub</path>, the ebuilds
+for version 2 and above are maintained by floppym@gentoo.org whereas
+earlier versions are maintained by the Gentoo Base System
+project. Note the use of "&gt;" as opposed to ">" in
+<c>restrict</c>.
</p>
<p>
-If a package has no maintainer, <c>maintainer-needed@gentoo.org</c>
-should be listed as the maintainer.
+The example also uses the <c><pkg></c> tag in USE flag
+descriptions. Slot operators are not allowed inside <pkg>,
+therefore the notation <pkg>sys-boot/grub</pkg><c>:2</c>
+is adopted as opposed to
+<pkg>sys-boot/grub<c>:2</c></pkg>.
</p>
<p>
-To easily create <c>metadata.xml </c>files, you can use
-<c>app-portage/metagen</c>. There is also a skeleton file, see
-<c>/usr/portage/skel.metadata.xml</c>.
+Lastly, the <c><remote-id></c> tag in the upstream description
+is demonstrated.
</p>
+<codesample lang="sgml">
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+<pkgmetadata>
+ <maintainer restrict="&gt;=sys-boot/grub-2" type="person">
+ <email>floppym@gentoo.org</email>
+ </maintainer>
+ <maintainer type="project">
+ <email>base-system@gentoo.org</email>
+ <name>Gentoo Base System</name>
+ </maintainer>
+ <use>
+ <flag name="device-mapper">
+ Enable support for device-mapper from <pkg>sys-fs/lvm2</pkg>
+ </flag>
+ <flag name="efiemu">
+ Build and install the efiemu runtimes
+ </flag>
+ <flag name="fonts">Build and install fonts for the gfxterm module</flag>
+ <flag name="mount">
+ Build and install the grub-mount utility
+ </flag>
+ <flag name="libzfs">
+ Enable support for <pkg>sys-fs/zfs</pkg>
+ </flag>
+ <flag name="multislot">
+ Allow concurrent installation of <pkg>sys-boot/grub</pkg>:0 and
+ <pkg>sys-boot/grub</pkg>:2 by renaming all programs.
+ </flag>
+ <flag name="themes">Build and install GRUB themes (starfield)</flag>
+ <flag name="truetype">
+ Build and install grub-mkfont conversion utility
+ </flag>
+ </use>
+ <upstream>
+ <remote-id type="sourceforge">dejavu</remote-id>
+ </upstream>
+</pkgmetadata>
+</codesample>
+
+</body>
+</subsubsection>
+</body>
+</subsection>
+<subsection>
+<title>Maintainer-Needed</title>
+<body>
+
<p>
-Commits of package metadata files are handled by <c>repoman</c>. You
-should ensure that you have <c>dev-libs/libxml2</c> installed so that
-the XML can be validated.
+Maintainer-needed, or orphaned, packages have no maintainers
+responsible for them. Per
+<uri link="https://wiki.gentoo.org/wiki/GLEP:67#Case_of_maintainer-needed_packages">
+GLEP 67</uri>, these packages must not contain any <maintainer>
+subtags under <pkgmetadata> in their <c>metadata.xml</c>. By
+convention, a comment line containing the string <c>maintainer-needed</c>
+is inserted. Other tags which are relevant to the package may be
+present in the metadata. Bugs for these packages must be assigned to
+<c>maintainer-needed@gentoo.org</c>. The QA team periodically generates the
+<uri link="https://qa-reports.gentoo.org/output/maintainer-needed.html">
+orphaned packages list</uri> along with their corresponding bugs as
+part of the QA reports.
</p>
+<codesample lang="sgml">
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+<pkgmetadata>
+ <!-- maintainer-needed -->
+ <upstream>
+ <maintainer status="active">
+ <email>rasmus@alum.mit.edu</email>
+ <name>Matt Rasmussen</name>
+ </maintainer>
+ <doc lang="en">http://keepnote.org/manual/</doc>
+ <bugs-to>https://code.google.com/p/keepnote/issues/list</bugs-to>
+ </upstream>
+ <longdescription lang="en">
+ KeepNote is a note taking application. With KeepNote, you can
+ store your class notes, TODO lists, research notes, journal entries,
+ paper outlines, etc in a simple notebook hierarchy with rich-text
+ formatting, images, and more. Using full-text search, you can
+ retrieve any note for later reference.
+ </longdescription>
+</pkgmetadata>
+</codesample>
+
+</body>
+</subsection>
+</body>
</section>
<section>
--
2.7.3
^ permalink raw reply related [flat|nested] 7+ messages in thread* Re: [gentoo-dev] [PATCH v2 2/4] ebuild-writing/misc-files/metadata: rewrite the section per GLEP 67 #572144
2016-05-15 0:57 ` [gentoo-dev] [PATCH v2 2/4] ebuild-writing/misc-files/metadata: rewrite the section per GLEP 67 #572144 Göktürk Yüksek
@ 2016-05-15 7:54 ` Michał Górny
2016-05-16 2:23 ` Göktürk Yüksek
0 siblings, 1 reply; 7+ messages in thread
From: Michał Górny @ 2016-05-15 7:54 UTC (permalink / raw
To: Göktürk Yüksek; +Cc: devmanual, gentoo-dev
[-- Attachment #1: Type: text/plain, Size: 1035 bytes --]
On Sat, 14 May 2016 20:57:48 -0400
Göktürk Yüksek <gokturk@binghamton.edu> 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 &lt; and &gt;.<br />
> - <br />
> - For example, in the <c>sys-libs/db</c> package,
> - <c>restrict="&gt;=sys-libs/db-3.2.9-r5"</c> on the
> - <brite>maintainer</brite> tag shows that I'm currently maintaining all
> - versions greater then 3.2.9-r5.
> + ">" need to be specified by "&lt;" and "&gt;".
> </ti>
> </tr>
> <tr>
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
<http://dev.gentoo.org/~mgorny/>
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 949 bytes --]
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [gentoo-dev] [PATCH v2 2/4] ebuild-writing/misc-files/metadata: rewrite the section per GLEP 67 #572144
2016-05-15 7:54 ` Michał Górny
@ 2016-05-16 2:23 ` Göktürk Yüksek
0 siblings, 0 replies; 7+ messages in thread
From: Göktürk Yüksek @ 2016-05-16 2:23 UTC (permalink / raw
To: Michał Górny; +Cc: devmanual, gentoo-dev
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
Michał Górny:
> On Sat, 14 May 2016 20:57:48 -0400 Göktürk Yüksek
> <gokturk@binghamton.edu> 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 &lt; and &gt;.<br /> - <br /> - For
>> example, in the <c>sys-libs/db</c> package, -
>> <c>restrict="&gt;=sys-libs/db-3.2.9-r5"</c> on the -
>> <brite>maintainer</brite> tag shows that I'm currently
>> maintaining all - versions greater then 3.2.9-r5. + ">"
>> need to be specified by "&lt;" and "&gt;". </ti> </tr>
>> <tr>
>
> 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-----
^ permalink raw reply [flat|nested] 7+ messages in thread
* [gentoo-dev] [PATCH v2 3/4] ebuild-writing/misc-files/metadata: update wrt slotting and per GLEP 68
2016-05-15 0:57 [gentoo-dev] [PATCH v2 0/4] devmanual: update the docs per GLEP 67 and 68 Göktürk Yüksek
2016-05-15 0:57 ` [gentoo-dev] [PATCH v2 1/4] general-concepts/herds-and-projects: update per GLEP 67 #572144 #549490 Göktürk Yüksek
2016-05-15 0:57 ` [gentoo-dev] [PATCH v2 2/4] ebuild-writing/misc-files/metadata: rewrite the section per GLEP 67 #572144 Göktürk Yüksek
@ 2016-05-15 0:57 ` Göktürk Yüksek
2016-05-15 0:57 ` [gentoo-dev] [PATCH v2 4/4] ebuild-writing/misc-files/metadata: add an example for slots and subslots Göktürk Yüksek
3 siblings, 0 replies; 7+ messages in thread
From: Göktürk Yüksek @ 2016-05-15 0:57 UTC (permalink / raw
To: devmanual; +Cc: gentoo-dev
Add information about specifying slots and subslots in the
metadata.
Also, update the section according to the specifications in GLEP 68,
clarify some of the tags better, and reorder the tags to improve the
flow of the text.
Signed-off-by: Göktürk Yüksek <gokturk@binghamton.edu>
---
ebuild-writing/misc-files/metadata/text.xml | 140 ++++++++++++++++++----------
1 file changed, 93 insertions(+), 47 deletions(-)
diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml
index 31ec926..3d135a6 100644
--- a/ebuild-writing/misc-files/metadata/text.xml
+++ b/ebuild-writing/misc-files/metadata/text.xml
@@ -14,7 +14,15 @@ package or category.
<body>
<p>
-A <path>metadata.xml</path> file can contain a number of tags:
+A metadata file follows the syntax defined in
+<uri link="https://wiki.gentoo.org/wiki/GLEP:68">GLEP 68</uri>.
+The character set <b>must</b> be UTF-8 as specified by
+<uri link="https://wiki.gentoo.org/wiki/GLEP:31">GLEP 31</uri>.
+</p>
+
+<p>
+The following table summarizes the tags that may appear in a
+metadata.xml:
</p>
<table>
@@ -24,28 +32,41 @@ A <path>metadata.xml</path> file can contain a number of tags:
</tr>
<tr>
<ti>
+ <brite><catmetadata></brite>
+ </ti>
+ <ti>
+ This is the root element of the <path>metadata.xml</path> file for
+ categories. It has no attributes. It contains a number of
+ <brite><longdescription></brite> tags, each for a different
+ language.
+ </ti>
+</tr>
+<tr>
+ <ti>
<brite><pkgmetadata></brite>
</ti>
<ti>
This is the root element of the <path>metadata.xml</path> file for
packages. It has no attributes. The following subtags are
allowed:
- <brite><maintainer></brite>,
<brite><longdescription></brite>,
+ <brite><maintainer></brite>,
+ <brite><slots></brite>,
<brite><use></brite>, and
<brite><upstream></brite>.
+ While all the subtags are optional, <upstream> may
+ appear at most once.
</ti>
</tr>
<tr>
+ <ti><brite><longdescription></brite></ti>
<ti>
- <brite><catmetadata></brite>
- </ti>
- <ti>
- This is the root element of the <path>metadata.xml</path> file for
- categories as per <uri link="https://wiki.gentoo.org/wiki/GLEP:34">GLEP 34</uri>.
- It has no attributes. It contains a number of
- <brite><longdescription></brite> tags, each for a different
- language.
+ This tag contains a description for a category or a package. For
+ packages, it is used to augment the
+ <uri link="::ebuild-writing/variables#ebuild-defined-variables">
+ DESCRIPTION</uri> field in the ebuilds themselves. This tag has
+ two optional subtags: <brite><pkg></brite> and
+ <brite><cat></brite>.
</ti>
</tr>
<tr>
@@ -83,11 +104,25 @@ A <path>metadata.xml</path> file can contain a number of tags:
</ti>
</tr>
<tr>
- <ti><brite><longdescription></brite></ti>
+ <ti><brite><slots></brite></ti>
+ <ti>
+ This tag describes the
+ <uri link="::general-concepts/slotting">slots</uri> of a package.
+ It has two optional subtags: <slot> and <subslots>.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><slot></brite></ti>
+ <ti>
+ This contains information for a particular slot. The <c>name</c>
+ attribute is mandatory and specifies the name of the slot.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><subslots></brite></ti>
<ti>
- This tag contains a description of the package. This is to augment the
- DESCRIPTION field in the ebuilds themselves. This tag has two optional
- subtags: <brite><pkg></brite> and <brite><cat></brite>.
+ Describes the meaning of subslots for the whole package. This
+ tag may appear at most once.
</ti>
</tr>
<tr>
@@ -113,25 +148,30 @@ A <path>metadata.xml</path> file can contain a number of tags:
<ti><brite><upstream></brite></ti>
<ti>
This tag contains information about the upstream developers/project.
+ It supports multiple optional subtags: <maintainer>,
+ <changelog>, <doc>, <bugs-to>,
+ and <remote-id>.
</ti>
</tr>
<tr>
<ti><brite><maintainer></brite></ti>
<ti>
- Name and e-mail of an upstream maintainer. May appear more than once.
+ Provides information about the upstream maintainer. It requires a
+ <name> subtag to be specified, supports an optional
+ <email> subtag and an optional <c>status</c> attribute.
</ti>
</tr>
<tr>
- <ti><brite><email></brite></ti>
+ <ti><brite><name></brite></ti>
<ti>
- The email address of an upstream may appear only once and must appear in first place.
+ The name of an upstream maintainer should contain a block of text with upstream's name.
+ This element is mandatory for an upstream maintainer and must appear exactly once.
</ti>
</tr>
<tr>
- <ti><brite><name></brite></ti>
+ <ti><brite><email></brite></ti>
<ti>
- The name of an upstream maintainer should contain a block of text with upstream's name.
- This element is mandatory for an upstream maintainer and must appear only once.
+ The email address of an upstream maintainer. May appear only once.
</ti>
</tr>
<tr>
@@ -141,7 +181,7 @@ A <path>metadata.xml</path> file can contain a number of tags:
The URL must be version independent and must point to a changelog which is only
updated on new releases of the corresponding package. (This also implies that
one can link to an automatically updated changelog in case of vcs snapshots
- only.)
+ only). May appear at most once.
</ti>
</tr>
<tr>
@@ -151,14 +191,14 @@ A <path>metadata.xml</path> file can contain a number of tags:
found. The link must not point to any third party documentation and must be
version independent. If the documentation is available in more than one language,
a lang attribute can be used which follows the same rules as the one for
- longdescription.
+ <longdescription>.
</ti>
</tr>
<tr>
<ti><brite><bugs-to></brite></ti>
<ti>
Should contain a place where bugs can be filed, a URL or an e-mail address prefixed
- with mailto:.
+ with <c>mailto:</c>. May appear at most once.
</ti>
</tr>
<tr>
@@ -167,12 +207,14 @@ A <path>metadata.xml</path> file can contain a number of tags:
Should specify a type of package identification tracker and the identification that
corresponds to the package in question. remote-id should make it easier to index
information such as its Freshmeat ID or its CPAN name.
+ It has a mandatory attribute <c>type</c> which identifies the type
+ of upstream source.
</ti>
</tr>
<tr>
<ti><brite><pkg></brite></ti>
<ti>
- This tag contains a valid package name in the format of a DEPEND.
+ This tag contains a valid qualified package name.
</ti>
</tr>
<tr>
@@ -198,6 +240,7 @@ There are also some attributes that can be used with these tags:
<ti>lang</ti>
<ti>
<brite><description></brite>, <brite><longdescription></brite>,
+ <brite><slots></brite>,
<brite><use></brite>, <brite><doc></brite>
</ti>
<ti>
@@ -216,25 +259,29 @@ There are also some attributes that can be used with these tags:
<brite><longdescription></brite>, <brite><flag></brite>
</ti>
<ti>
- The restrict attribute allows one to restrict the application of certain
- tags to certain versions of a package. When this attribute is used, a tag
- 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 "&lt;" and "&gt;".
+ The restrict attribute allows one to restrict the application of
+ certain tags to certain versions of a package. When this attribute
+ is used, other tags with or without the restrict attribute must be
+ present to cover all the versions of the package. A tag without
+ 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
+ ">" need to be specified using "&lt;" and "&gt;".
</ti>
</tr>
<tr>
<ti>name</ti>
<ti>
- <brite><flag></brite>
+ <brite><flag></brite>, <brite><slot></brite>
</ti>
<ti>
- This attribute is required on the <brite><flag></brite> tag. It
- simply contains the USE flag.
- <br /><br />
- For example, in the <c>sys-apps/hal</c> package, <c><flag name='acpi'>
- Enables ACPI</flag></c>
+ When this attribute is required on the <flag> tag, it
+ simply contains the name of the USE flag. For the
+ <slot> tag, it specifies the
+ <uri link="::general-concepts/slotting#slot-names">
+ slot name</uri> to which it applies. A slot name of <c>"*"</c>
+ allows for a single <slot> tag to match all the slots of a
+ package, in which case no other slot tags may be present.
</ti>
</tr>
<tr>
@@ -243,9 +290,12 @@ There are also some attributes that can be used with these tags:
<brite><maintainer></brite>
</ti>
<ti>
- The upstream maintainer element has a status attribute, which is one of active or inactive.
- This attribute is not mandatory. The absence of it shall be interpreted as unknown.
- Please note: This attribute is only allowed in the <upstream> <maintainer> element!
+ The upstream maintainer element has a status attribute, which is
+ one of <c>"active"</c> or <c>"inactive"</c>. This attribute is not
+ mandatory. The absence of it shall be interpreted as
+ <c>"unknown"</c>. Please note that this attribute is only allowed
+ for the <maintainer> subtags of the <upstream>
+ element!
</ti>
</tr>
<tr>
@@ -446,9 +496,9 @@ project. Note the use of "&gt;" as opposed to ">" in
<p>
The example also uses the <c><pkg></c> tag in USE flag
-descriptions. Slot operators are not allowed inside <pkg>,
-therefore the notation <pkg>sys-boot/grub</pkg><c>:2</c>
-is adopted as opposed to
+descriptions. Slot dependency specifiers are not allowed inside
+<pkg>, therefore the notation
+<pkg>sys-boot/grub</pkg><c>:2</c> is adopted as opposed to
<pkg>sys-boot/grub<c>:2</c></pkg>.
</p>
@@ -553,11 +603,7 @@ part of the QA reports.
<body>
<p>
For categories, <c>metadata.xml</c> specifies a long description (in
-English and optionally in other languages). The format is specified
-formally in <uri link="https://wiki.gentoo.org/wiki/GLEP:34">
-GLEP 34</uri>, and the character set <b>must</b> be UTF-8 as specified
-by <uri link="https://wiki.gentoo.org/wiki/GLEP:31">GLEP
-31</uri>. A typical example:
+English and optionally in other languages). A typical example:
</p>
<codesample lang="sgml">
--
2.7.3
^ permalink raw reply related [flat|nested] 7+ messages in thread* [gentoo-dev] [PATCH v2 4/4] ebuild-writing/misc-files/metadata: add an example for slots and subslots
2016-05-15 0:57 [gentoo-dev] [PATCH v2 0/4] devmanual: update the docs per GLEP 67 and 68 Göktürk Yüksek
` (2 preceding siblings ...)
2016-05-15 0:57 ` [gentoo-dev] [PATCH v2 3/4] ebuild-writing/misc-files/metadata: update wrt slotting and per GLEP 68 Göktürk Yüksek
@ 2016-05-15 0:57 ` Göktürk Yüksek
3 siblings, 0 replies; 7+ messages in thread
From: Göktürk Yüksek @ 2016-05-15 0:57 UTC (permalink / raw
To: devmanual; +Cc: gentoo-dev
Signed-off-by: Göktürk Yüksek <gokturk@binghamton.edu>
---
ebuild-writing/misc-files/metadata/text.xml | 50 +++++++++++++++++++++++++++++
1 file changed, 50 insertions(+)
diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml
index 3d135a6..486af11 100644
--- a/ebuild-writing/misc-files/metadata/text.xml
+++ b/ebuild-writing/misc-files/metadata/text.xml
@@ -549,6 +549,56 @@ is demonstrated.
</body>
</subsubsection>
+<subsubsection>
+<title>Slots and Subslots</title>
+<body>
+
+<p>
+The main focus of this example is to demonstrate how slots and
+subslots are specified, by examining the metadata of
+<path>media-libs/libpng</path>. There may be multiple reasons for
+slotting depending on the nature of the package. For this particular
+package, it can be seen that the slots are used to provide different
+versions of the library with varying binary compatibility and that
+developers are advised to build against the slot 0. Furthermore,
+different versions of this package with the same subslot provide the
+same Application Binary Interface (ABI), according to the description
+specified in the <c><subslots></c> tag.
+</p>
+
+<codesample lang="sgml">
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+<pkgmetadata>
+ <maintainer type="project">
+ <email>base-system@gentoo.org</email>
+ <name>Gentoo Base System</name>
+ </maintainer>
+ <use>
+ <flag name="apng">support unofficial APNG (Animated PNG) spec</flag>
+ </use>
+ <upstream>
+ <remote-id type="cpe">cpe:/a:libpng:libpng</remote-id>
+ <remote-id type="sourceforge">apng</remote-id>
+ </upstream>
+ <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 only.
+ </slot>
+ <slot name="1.5">
+ For binary compatibility, provides libpng15.so.15 only.
+ </slot>
+ <subslots>Reflect ABI compatibility for libpng.so.</subslots>
+ </slots>
+</pkgmetadata>
+</codesample>
+
+</body>
+</subsubsection>
</body>
</subsection>
<subsection>
--
2.7.3
^ permalink raw reply related [flat|nested] 7+ messages in thread