Debian Package Tags - Editing the vocabulary

Intro

The Debtags vocabulary is the file that describes what are the facets and tags that can be used to categorize Debian packages.

The file contains whatever needs to be stored about facets and tags. At the moment this means:

• a list of facets and their tags
• description of facets and tags
• editorial informations
• comments

Repository

The vocabulary is maintained in the subversion repository svn://svn.debian.org/debtags/vocabulary/trunk. The file inside the repository is called debian-packages.

After substantial editing is done in debian-packages, an automated system triggered by a mail will do a check out of it and make it eventually available to debtags update.

Another file in the repository, facet-classification, is used to store a description of editorial tags that can be assigned to facets to mark their level of maturity.

Checking out the repository

First thing: install the package called 'subversion' using your favourite package manager.

Now, if you type svn help you get some help about subversion's commands:

$ svn help
usage: svn  [options] [args]
Type "svn help " for help on a specific subcommand.

Most subcommands take file and/or directory arguments, recursing
on the directories.  If no arguments are supplied to such a
command, it will recurse on the current directory (inclusive) by
default.

Available subcommands:
   add
[...]

Then decide where you want to have your working copy of the source. In this guide, we assume you want it in the directory "vocabulary" inside your home directory. Don't create the directory: subversion will do it by itself.

Then, get a copy of the repository (this is called checkout):

cd ~
svn checkout svn://svn.debian.org/debtags/vocabulary/trunk vocabulary

This creates a directory ~/vocabulary that contains a copy of the latest development version.

Have a look around the repository. At the time of writing there are just the debian-packages and facet-classification files that were described above.i If you see some directory called .svn, those are used by subversion and should be left alone.

Now you have everything inside the vocabulary directory, and you can work as you please. Don't worry if you break something: whatever you do, you can't break the repository on the server.

A look at debian-packages

Now, try editing the file debian-packages. It starts with something like:

Facet: accessibility
Status: needing-review
Description: Accessibility support provided

Tag: accessibility::input
Description: Alternative input systems

Those are a facet definition and a tag definition. For more informations on faceted classification, you can have a look to this web page or at the links in this e-mail (help is very welcome in integrating faceted.html with the links from that mail and information found on them).

The format of the file is the same format used by various Debian infrastructure, such as package control files. It is documented in the Debian policy, in the section "5.1 Syntax of control files", but simply put, we have a "Field: contents" couple per every line, and long contents can continue in more lines provided that they all start with at least one space. An empty line marks the end of a record.

In the example above, you can see a facet being defined ("accessibility") and a tag "input" being defined as part of "accessibility". Both have a description, and the "accessibility" facet is marked as "needing-review".

Scroll down slowly, you'll easily understand how the file works. If you see something strange, don't hesitate to ask in the Debtags list

Some modifications

Now try to improve a description: find a "Description:" field that could use some work and type something on it. You can easy review descriptions and correct typos this way.

You can add a new tag by adding a new "Tag:" field next to some other. Don't forget to put the facet name in the tag, separated my "::". For many other similar kinds of editing, you can easily guess how the vocabulary works just by looking at what has been written already, as you probably noticed even before reading these lines.

For more complicate things, the Debtags list is there for you.

Sending changes to the Debtags list

Now you made some changes and you want to send them to the Debtags list.

First, double check your work. Here is a good procedure to follow:

TODO: add to debtags a command that checks the syntax of a vocabulary file.  It
should also check that all faceted tags have a corresponding facet, and warn
about tags with no facet.

Now that you have checked your work, you can send them to the list: from the vocabulary directory, type:

svn status

This will show you what files have been changed by you (they will be marked with M). If a file is marked with ?, it means that it does not belong to the repository and it's probably some other file you created during your work.

Now you are ready to send your changes to the list. Type:

svn diff > mypatch.diff

This file is called a patch file and it represents the changes you made. If you have a look inside, you can see them fairly clearly. Patch files are really smart files that can be both reviewed by a person and processed automatically by a program like Subversion, or Patch.

Now that you have the patch file, you can just send it to the list, and Enrico Zini will put it in the repository for you. Patch files are usually quite small (unless you changed really, really, really a lot of things), so sending them to a mailing list is rarely a problem.

After you get used to the vocabulary, Subversion and Debtags, you are very likely to be offered an account so that you can write to the repository as well.

Other miscellaneous tips

If someone makes a change in the repository and you want your repository to be up-to-date, you can go inside the vocabulary directory and issue:

svn up

That will bring your repository up to date, and it's very quick.

Also, locally, subversion is able to revert (using svn revert <filename>) any file to how it was at the time of the last checkout or update.