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 <gokt...@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>openoff...@gentoo.org</email>
- <description>Openoffice related packages</description>
-
<maintainer><email>pau...@gentoo.org</email></maintainer>
-
<maintainer><email>s...@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="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).
+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>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>tools-portage</herd>
- <maintainer>
- <email>jo...@gentoo.org</email>
- <name>John Mylchreest</name>
+ <maintainer type="project">
+ <email>off...@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>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>
<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>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>
-</pkgmetadata>
+<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>
</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>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>
+ <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>
+ <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>
-
+</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 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>.
</p>
<p>
-If a package has no maintainer, <c>maintainer-nee...@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>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</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-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">
+<?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>
+</body>
</section>
<section>
--
2.7.3
