[gentoo-dev] GLEP 34: Per-Category metadata.xml Files

[Ciaran McCreesh <ciaranm@gentoo.org>]

[-- Attachment #1.1: Type: text/plain, Size: 500 bytes --]

Attached is an updated GLEP 34 (Per-Category metadata.xml Files) draft.
Changes since the last posting are:

* clarified the wording and purpose of the catmetadata element
* clarified maintainer information elements at category level
* wording fixes

If there are no further comments, I'd like this to be voted upon on
Monday.

-- 
Ciaran McCreesh : Gentoo Developer (Vim, Fluxbox, shell tools)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #1.2: glep-0034.txt --]
[-- Type: text/plain, Size: 4376 bytes --]

GLEP: 34
Title: Per-Category metadata.xml Files
Version: $Revision: 1.1 $
Author: Ciaran McCreesh <ciaranm@gentoo.org>
Last-Modified: $Date: 2005/03/11 19:07:16 $
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 11-March-2005
Post-Date: 11-March-2005, 13-March-2005

Abstract
========

A ``metadata.xml`` file [1]_ is currently used to provide extra metadata
(long descriptions, herd and maintainer information) about a package. It
is proposed that these files also be used to describe the purpose of a
category.

Motivation
==========

Category names are short and not entirely clear. Adding arbitrary length
long descriptions to categories would provide several advantages:

* It would clarify the meaning of categories for users, who may not be
  aware of some of the abbreviations or acronyms we use.

* With the use of XML ``lang=""`` attributes, it would allow for
  additional non-English descriptions (simply using longer category names
  would not allow this).

* It would help developers better select a relevant category for their
  package, rather than dumping everything into ``sys-apps`` and
  ``app-misc`` as is done currently.

* It would help illustrate which categories are too broad or badly defined
  in scope, making any future category splits easier.

Specification
=============

It is proposed that the existing ``metadata.xml`` format [1]_ be used.
Even though XML sucks, there is already a framework in place for these
files.  The filename will be ``blah-misc/metadata.xml``. The character set
used shall be UTF-8 for consistency with GLEP 31 [2]_.

A new top level ``<catmetadata>`` element shall be added to the DTD. This
is necessary because the existing ``<pkgmetadata>`` element is not
appropriately named, and doing a global rename would be impractical. Using
a different element would also permit additional category-specific data to
be added at a later date.

The existing ``<longdescription>`` elements shall be used for
descriptions. The ``lang`` attribute shall be used to indicate the human
language of the description -- all categories must have at least an
English (``en``) description.

The ``<herd>`` and ``<maintainer>`` elements are not generally relevant at
the category level. They may be specified as a fall-back "assume that
everything in this category is maintained by these people", but this must
not be used as a replacement for proper per-package metadata.


Examples
--------

The ``app-vim`` category could use a ``metadata.xml`` file like the
following: ::

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE catmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
    <catmetadata>
            <longdescription lang="en">
                The app-vim category contains plugins and syntax file
                packages for the Vim text editor.
            </longdescription>
            <longdescription lang="de">
                Die Kategorie app-vim enthält Plugins und Syntax-Pakete
                für den Vim Texteditor.
            </longdescription>
    </catmetadata>

Implementation Requirements
---------------------------

The DTD file would need to be updated to include the ``<catmetadata>``
element.

A metadata file would have to be added to every category in the tree. This
could be done over a period of time.

``repoman`` would need a few small changes to be able to handle
per-category metadata files.

The "packages.gentoo.org metadata" bug [3]_ would need to be
updated to ask for category descriptions as well.

The metadata documentation [1]_ would require some additions.

Backwards Compatibility
=======================

The metadata DTD will remain backwards compatible.

The category metadata files will need to be considered "optional until
implemented" rather than immediately becoming mandatory.

References
==========

.. [1] Gentoo Metadata,
       (http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4)
.. [2] GLEP 31: Character Sets for Portage Tree Items
       (http://www.gentoo.org/proj/en/glep/glep-0031.html)
.. [3] Gentoo bug 66917
       (http://bugs.gentoo.org/show_bug.cgi?id=66917)

Copyright
=========

This document has been placed in the public domain.

.. vim: set tw=74 fileencoding=utf-8 :


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]