[Debtags-devel] Tag patch + question regarding langdevel

[Enrico Zini]

On Sun, Nov 06, 2005 at 02:02:28PM +0100, Torsten Marek wrote:

> > Reading this I had a closer look and yes, the two categories aren't too
> > big.  If noone has arguments against the merge, I could go on and do it.
> I do not;-)
> If you don't have time to do that, please tell me and I'm going to do it (I
> suggested it, so I might as well bear the consequences). Is there anything else
> to do apart from patching the vocabulary and sending one really big patch to the
> tag database?

On Mon, Nov 07, 2005 at 01:55:07PM +0900, Sanghyeon Seo wrote:

> As this renames a tag, I guess mass update of tag database is also necessary.
> How does one do that?

I'm glad you both asked: I was waiting for an opportunity to write and
post a small tutorial about it.  I'll take Sanghyeon Seo's case as the
example to begin with, because it's simpler.


Tag reorganization tutorial
===========================

Suppose we want to rename a tag, say uitoolkit::wxwindows into
uitoolkit::wxwidgets.  This involves a change in the vocabulary and a
change in the tag database.

Step 1: add the new tag to the vocabulary
-----------------------------------------

The first thing to do is adding the new tag to the vocabulary:

 1. Check out the vocabulary from 
    svn+ssh://svn.debian.org/svn/debtags/debian-packages
 2. Add the new tags, *without removing the old ones*
 3. Commit

Then you need to tell the central database to reload the vocabulary
data, so that it will accept the tag in new tag patches:

 4. Send an empty mail to "qnfu purpxbhg qnfu ibpnohynel ng ivgnibaav qbg
    qr".  I encoded it with rot13 to keep it out of spam harvesting
    tools.  Also note that this address will change after the central
    database will be completely moved to Alioth.

Lastly, let your local debtags installation know about the tag as well,
so that it can properly submit patches to the central database:

 5. Update the vocabulary downloadable on Alioth by 'debtags update'::

      gzip -c9 debian-packages | \
        ssh alioth.debian.org \
	"/org/alioth.debian.org/chroot/home/groups/debtags/bin/writevoc"

 6. Run 'debtags update' on your system.

I created a script to automate 4 and 5.  I haven't committed it because
it would show on viewsvn and make the update email address harvestable,
however, it's trivially two lines that you can easily figure out.

The `writevoc` script on Alioth just writes the standard input to the
right place and with the right umask.

Note that you will need to change your /etc/debtags/sources.list for
this to work.  Use this tag source:

  tags http://debtags.alioth.debian.org/tags/

It is updated just like the one on people.debian.org/~enrico.  Next
upload of debtags will use this one by default.


Step 2: Create the tag patch
----------------------------

Here's a quick way of generating the renaming patch automatically::

  # Create a file with the renames you want to do.
  # The syntax is a bit awkward:
  #   new-name: oldname1, oldname2
  #   new-name1: oldname3
  #   new-name2: oldname4, oldname5, oldname6
  #   ...and so on...
  echo "uitoolkit::wxwidgets: uitoolkit::wxwindows" > renames.list
  # Create a modified tag database using the rename list
  debtags cat | tagcoll copy --rename-from=renames.list  > tags.renamed
  # Create a patch
  debtags mkpatch tags.renamed > tags.patch
  # Check that everything is ok
  less tags.patch

Note that if you didn't do debtags update to get the new tag vocabulary,
the patch will remove the old tag but not add the new one, and this
would be dangerous.  Luckily, it's easy to create a reverse patch if
needed.


Step 3: Activate the tag patch
------------------------------

First, submit it to the central database::

  debtags submit tags.patch

Then, commit it to the hand-checked tag database that goes into the
packages file::

  svn co svn+ssh://svn.debian.org/svn/debtags/tagdb/tags
  tagcoll copy --patch-with=tags.patch tags > tags.patched
  mv tags.patched tags
  svn commit -m "Renamed uitoolkit::wxwindows into uitoolkit::wxwidgets"


Step 4: Remove the old tags from the vocabulary
-----------------------------------------------

At this point, this should be trivial:

 1. Check out the vocabulary from 
    svn+ssh://svn.debian.org/svn/debtags/debian-packages
 2. Remove the old tags
 3. Commit


Done
----

This should be all.  With the next update of the tag repository (happens
once a day), the system should get updated.  Don't forget to annouce
your changes in the debtags-devel mailing list, so that people stay up
to date.


Wow!  It's finally documented, which is the first step towards improving
it :)

To rename more tags (merging two facets is just a long list of
renamings) one can just put more things in the renames.list.  On more
complex reorganizations (such as one tag split in two), one can use
debtags-edit, tagcolledit or other tools, instead of the 'renames'
feature of tagcoll, to generate the patch.

I'll be of course at your disposal for more clarifications.


Ciao,

Enrico

--
GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini <enrico at debian.org>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.alioth.debian.org/pipermail/debtags-devel/attachments/20051107/f0a2f134/attachment.pgp