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 #549490 obsolete.
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 <gokt...@binghamton.edu>
---
ebuild-writing/misc-files/metadata/text.xml | 408 ++++++++++++++++------------
1 file changed, 227 insertions(+), 181 deletions(-)
diff --git a/ebuild-writing/misc-files/metadata/text.xml
b/ebuild-writing/misc-files/metadata/text.xml
index 2324f53..9d0dc19 100644
--- a/ebuild-writing/misc-files/metadata/text.xml
+++ b/ebuild-writing/misc-files/metadata/text.xml
@@ -10,20 +10,13 @@ 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>
-A <path>metadata.xml</path> file can contain a number of tags:
+A metadata file follows the syntax defined in
+<uri link="https://www.gentoo.org/dtd/metadata.dtd";>
+metadata.dtd</uri> and can contain a number of tags:
</p>
<table>
@@ -39,13 +32,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 +52,21 @@ 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. A package may contain zero or more
+ <brite><maintainer></brite> tags. 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>. 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>.
</ti>
</tr>
<tr>
@@ -108,7 +93,9 @@ A <path>metadata.xml</path> file can contain a number of
tags:
<ti><brite><longdescription></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
+ DESCRIPTION field in the ebuilds themselves. If a long description
+ in any language is provided, an English long description must be
+ present. This tag has two optional
subtags: <brite><pkg></brite> and <brite><cat></brite>.
</ti>
</tr>
@@ -207,8 +194,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 +221,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 +230,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>
@@ -286,208 +267,273 @@ optional:
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: "person" and "project". 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>
+<title>Package Metadata</title>
+<body>
+<p>
+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>
+
+<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>
+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>
+
<subsection>
-<title>First Example</title>
+<title>Package Metadata Examples</title>
+<body>
+
+<p>
+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>
+
+<subsubsection>
+<title>Projects as Maintainers</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>:
+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 <c>app-office/libreoffice</c>. The package maintainer is
+identified by the email address <c>off...@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>openoffice</herd>
+ <maintainer type="project">
+ <email>off...@gentoo.org</email>
+ <name>Gentoo Office Project</name>
+ </maintainer>
<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.
+ 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>
<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>:
+The email address <c>off...@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>
-<note>
-This example may be outdated when you read it. It's just an example!
-</note>
-
<codesample lang="sgml">
-<herd>
- <name>openoffice</name>
- <email>openoff...@gentoo.org</email>
- <description>Openoffice related packages</description>
-
<maintainer><email>pau...@gentoo.org</email></maintainer>
-
<maintainer><email>s...@gentoo.org</email></maintainer>
-</herd>
+<project>
+ <email>off...@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>dilfri...@gentoo.org</email>
+ <name>Andreas K. Hüttel</name>
+ <role>member</role>
+ </member>
+ <member>
+ <email>scarab...@gentoo.org</email>
+ <name>Tomáš Chvátal</name>
+ <role>member</role>
+ </member>
+</project>
</codesample>
-<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="so...@gentoo.org">so...@gentoo.org</mail>) and add yourself to the
-alias (by editing <path>/var/mail/alias/misc/<alias name></path> on
-dev.gentoo.org).
-</p>
-
</body>
-</subsection>
-<subsection>
-<title>Second Example</title>
+</subsubsection>
+<subsubsection>
+<title>Local USE Flag Descriptions</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.
+The second example is formed after the <path>metadata.xml</path> of
+<c>sys-apps/portage</c>. 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">
-<?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>jo...@gentoo.org</email>
- <name>John Mylchreest</name>
+ <upstream>
+ <bugs-to>mailto:dev-port...@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>la...@gentoo.org</email>
+ <name>Larry the Cow</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.
- </longdescription>
+ <maintainer type="project">
+ <email>dev-port...@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>
-<subsection>
-<title>Third Example</title>
+</subsubsection>
+<subsubsection>
+<title>Split Maintainership</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.
+This example splits the maintainership based on package versions using
+the attribute <c>restrict</c>. According to the
+<path>metadata.xml</path> of <c>sys-boot/grub</c>, the ebuilds for
+version 2 and above are maintained by flop...@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>. The example also uses the <pkg> tag in USE flag
+descriptions and the <remote-id> tag in the upstream
+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>gentopia</herd>
-<maintainer>
- <email>compn...@gentoo.org</email>
-</maintainer>
-<maintainer>
- <email>st...@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>
+ <maintainer restrict="&gt;=sys-boot/grub-2" type="person">
+ <email>flop...@gentoo.org</email>
+ </maintainer>
+ <maintainer type="project">
+ <email>base-sys...@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:0</pkg>
and
+ <pkg>sys-boot/grub:2</pkg> 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>Fourth Example</title>
+<title>Maintainer-Needed</title>
<body>
<p>
-This example demonstrates the usage of the upstream element:
+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 "maintainer-needed"
+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-nee...@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">
-<upstream>
- <maintainer status="inactive">
- <email>f...@bar.bar</email>
- <name>Foo Bar</name>
- </maintainer>
- <maintainer status="active">
- <email>f...@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>
+ <!-- maintainer-needed -->
+ <upstream>
+ <maintainer status="active">
+ <email>ras...@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>
-
-
-<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.
-</p>
-
-<p>
-If a package has no maintainer, <c>maintainer-nee...@gentoo.org</c>
-should be listed as the maintainer.
-</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>.
-</p>
-
-<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.
-</p>
-
+</body>
</section>
<section>
--
2.7.3
