r50 - /web/deps/dep4.mdwn
codehelp at users.alioth.debian.org
codehelp at users.alioth.debian.org
Tue Apr 14 10:26:33 UTC 2009
Author: codehelp
Date: Tue Apr 14 10:26:33 2009
New Revision: 50
URL: http://svn.debian.org/wsvn/dep/?sc=1&rev=50
Log:
Fold in the results of the discussions so far on -devel.
Modified:
web/deps/dep4.mdwn
Modified: web/deps/dep4.mdwn
URL: http://svn.debian.org/wsvn/dep/web/deps/dep4.mdwn?rev=50&op=diff
==============================================================================
--- web/deps/dep4.mdwn (original)
+++ web/deps/dep4.mdwn Tue Apr 14 10:26:33 2009
@@ -10,7 +10,8 @@
Abstract: This document provides an overview of the TDeb format, TDeb
design and usage. This specification should be considered as a work in
progress.
- Source: http://svn.debian.org/viewsvn/dep/web/deps/dep4.mdwn?revision=45&view=markup
+ Source: http://svn.debian.org/viewsvn/dep/web/deps/dep4.mdwn?view=markup
+ Version 0.0.3
[[!toc levels=2]]
@@ -34,8 +35,6 @@
packages.
3. Translators should have a common interface for getting updates into
Debian (possibly with automated TDeb generation after i18n team review).
-
-## Version 0.0.2
## Copyright © 2008
@@ -60,8 +59,54 @@
## Summary
The tdeb binary package format is a variation of the deb binary
-package format. It has the same structure as deb, but the (single) data member
-is replaced by bzip2-compressed members for each LOCALE_ROOT supported.
+package format. It has the same structure as deb, but the (single) data
+member is replaced by bzip2-compressed members for each LOCALE_ROOT
+supported.
+
+## Locale-root members
+
+The new locale root data members are designed to support easier
+management of the translations, including allowing
+users to only install the translations that are needed for one
+particular installation.
+
+e.g. a standard .deb contains debian-binary, control.tar.gz and
+data.tar.gz whereas a typical TDeb could contain:
+
+ $ ar -t ../pilot-qof-tdeb_0.1.7-1_all.tdeb
+ debian-binary
+ control.tar.gz
+ t.de.tar.bz2
+ t.en.tar.bz2
+ t.fr.tar.bz2
+ t.pt.tar.bz2
+ t.ru.tar.bz2
+ t.sv.tar.bz2
+ t.vi.tar.bz2
+
+t.pt.tar.bz2 would contain translations for pt and pt_BR:
+
+ ./usr/share/locale/pt/LC_MESSAGES/pilot-qof.mo
+ ./usr/share/locale/pt_BR/LC_MESSAGES/pilot-qof.mo
+
+This allows later tools to extract only the requested translations from
+the TDeb upon installation.
+
+TDebs are based on the .deb format, it is only a small change in the
+organisation of the data.tar.gz but it simplifies various stages of
+handling the resulting packages in the repository, in upload rules and
+in other support tools.
+
+## Use of the .tdeb suffix
+
+Various file-based tools exist to handle .deb files and it will be easier
+for such tools to be able to reliably tell the difference between a .deb
+and a .tdeb from the filename rather than having to add new support in
+the codebase to detect the absence of data.tar.gz and work out how to
+handle the t.$root.bz2 members. The suffix also makes it easier to manage
+TDebs in various repository situations. Although closely related to the
+.deb format, the .tdeb format is sufficiently different to merit a subtle
+change to the suffix in a similar manner to .udeb.
## Format specification
The file is an ar archive with a magic number of !<arch>.
@@ -165,6 +210,115 @@
The regular deb will need to contain a untranslated copy of the
templates file, too. See "TDebs and Debconf" below.
+# TDeb uploads
+
+## Initial uploads - +t0
+
+The initial TDeb will be generated by the maintainer, effectively
++t0, containing whatever translations are currently supported. The
+TDeb is uploaded alongside the binary and .dsc. It is up to the
+maintainer to incorporate any +t1.diff.gz containing updated or new
+translations that may exist already into each new Debian version.
+
+If the new version has changed translated strings then those will only
+available in English until the +t1 TDeb can be prepared.
+
+Maintainers are advised to always seek translation updates
+prior to the upload of the initial TDeb. If maintainers implement a
+string freeze and wait for translation updates before uploading, the
+chances of a +t1.diff.gz being required by time of the next release
+by the maintainer are lower.
+
+See also Timeline.
+
+Maintainers will be creating TDebs in Squeeze+1, using debian/rules,
+using debhelper calls and uploading TDebs each time they would
+currently upload any package that contains /usr/share/locale/LC_*/ etc.
+Those TDebs are, effectively, +t0 - only updates by translators start
+the +t1 sequence.
+
+Maintainer uploads (non-native package example):
+foo_1.2.3-4_amd64.deb
+foo-tdeb_1.2.3-4_all.tdeb
+foo-bar_1.2.3-4_amd64.deb
+foo_1.2.3-4.diff.gz
+foo_1.2.3.orig.tar.gz
+foo_1.2.3-4.dsc
+foo_1.2.3-4_amd64.changes
+
+Maintainer uploads (native package example):
+foo_1.2.3_amd64.deb
+foo-tdeb_1.2.3_all.tdeb
+foo-bar_1.2.3_amd64.deb
+foo_1.2.3.tar.gz
+foo_1.2.3.dsc
+foo_1.2.3_amd64.changes
+
+The foo-tdeb package will be listed in the .changes anyway so existing
+tools will simply add it to the list of files to be uploaded to
+ftp-master or wherever. foo-tdeb_1.2.3-4_all.tdeb is, effectively,
+foo-tdeb_1.2.3-4+t0_all.tdeb
+
+When the maintainer makes a new release, foo_1.2.3-5, which incorporates
+the TDeb changes, it is done in a similar manner to how an NMU is
+included. All files matching foo*1.2.3-4* are removed by dak when the
+new version is uploaded. The updated translations now exist in
+foo-tdeb_1.2.3-5_all.tdeb - uploaded by the maintainer and there is no
++t1.diff.gz or +t1_all.tdeb until the package translations need to be
+touched again.
+
+## Translator updates
+
+Updates to translations will update the existing TDeb, creating
++t2.diff.gz and +t3.diff.gz etc. All supported languages go into the
+existing TDeb, organised by locale root.
+
+Unless a package needs more than one TDeb for the debconf plus large
+amounts of translated documentation corner case, each source package
+should only expect to have one TDeb for all binary packages and all
+locales.
+
+Translation teams can work together to make uploads in a coordinated
+manner - similar to the current method of requesting deadlines for i18n
+bugs, a nominated person can collate the various translations prior to
+a deadline chosen by the teams themselves, according to the needs of
+that particular package.
+
+Translator updates of TDebs do not necessarily need to use typical
+package building tools like 'dpkg-buildpackage'. All that is needed
+is to put the .mo files into the relevant directory hierarchy (or use
+dh_gentdeb) and then call dpkg-deb --tdeb -b:
+
+ dpkg-deb --tdeb -b debian/pilot-qof-tdeb ../pilot-qof-tdeb_0.1.7-1_all.tdeb
+
+This means that translators can build updated TDebs without needing the
+full dependency chain needed for a source rebuild - only dpkg (at a version
+that includes the TDeb support) is strictly necessary.
+
+Translator update uploads would contain:
+foo-tdeb_1.2.3-4+t1_all.tdeb
+foo_1.2.3-4+t1.diff.gz
+foo_1.2.3-4+t1.dsc
+foo_1.2.3-4+t1_all.changes
+
+The key point is that a +t1 revision can happen *during a release
+freeze* without touching the source, without changing any of the
+binaries. Once the release is out and unstable is accessible again, the
+maintainer adds +t1.diff.gz to their next upload.
+
+## dpkg source formats
+
+Format 3.0 should not be any more difficult than 1.0 or anything that
+follows. 3.0 has to deal with incorporating patches and changes from
+the Debian Bug Tracking System, so +t1.diff.gz is no different.
+
+What matters is that the maintainer gets the +t1.diff.gz and applies it
+onto the source package prior to the next upload. It's no different to
+how the same maintainer would handle a patch or new translations
+file sent to the BTS.
+
+---
+
# TDeb resources.
## Packages and patches
@@ -184,6 +338,8 @@
* <http://git.debian.org/?p=users/codehelp/debhelper.git;a=summary>
* <http://git.debian.org/?p=users/codehelp/dpkg.git;a=summary>
+---
+
# TDeb Architectures
## TDebs are architecture-independent
@@ -193,6 +349,8 @@
Any translation system that does not use gettext can choose to use
TDebs as long as the translation files are architecture-independent.
+
+---
# TDebs and LINGUAS
@@ -266,6 +424,8 @@
must be used and all tdebs for the source package must be revised
at the same time.
+---
+
# TDebs and package managers
Package managers can find out whether a package has a base tdeb by examining
@@ -285,6 +445,8 @@
There is no need to unpack in order to obtain the debconf templates - the
tdeb merely has to be locatable by debconf which will call apt-extracttemplates
and load the translated debconf strings into memory. See TDebs and debconf:
+
+---
# TDebs and debconf
@@ -294,6 +456,8 @@
are per-binary while tdebs are per-source. Also, the .deb should
have non-translated templates.
+---
+
# TDebs and multiple templates files
If a source package builds multiple binaries that use debconf, the debian/
@@ -302,9 +466,14 @@
will need to work together to ensure that all templates files are available to
debconf so that debconf can selectively load only the templates files required.
+---
+
# Tdebs and usr/share/doc
+
A tdeb needs usr/share/doc/copyright and changelog.Debian and dpkg will create
the necessary files, just as with a normal .deb.
+
+---
# Lintian support
@@ -326,6 +495,8 @@
* Name of the manpages in the binary packages (tdeb). An english
manpage shall remain, with the same name, in the original binary package.
+---
+
# TDeb maintainers
Rather than allow repeat uploads of the same change in multiple
@@ -333,16 +504,11 @@
many changes as possible at one time. Translation-Maintainers: in
debian/control and Localisation Assistants.
+---
+
# TDeb implementation
-## What needs to be done and when?
-
-* Archive and tools support (Squeeze)
-* Debconf translation will form the first TDebs (Squeeze + 1)
-* Native packages with program translations next
-* Non-native packages with Debian maintainers who are also the upstream
-
-# Incorporation of the tdiff in the next source package
+## Incorporation of the tdiff in the next source package
A process will be needed to help maintainers including the tdiff when they
prepare a new source package (kind of NMU acknowledgement?) Automated so that
@@ -362,7 +528,9 @@
This issue can be postponed until tdebs appear for non-native packages (squeeze+1)
-# L10N Infrastructure
+---
+
+## L10N Infrastructure
i18n.debian.net gathers the translation material from the packages. It needs
to support tdebs too (tdiff).
@@ -373,32 +541,59 @@
i18n.debian.net needs to help "Localisation Assistants" in gathering the new
translations before the preparation of a new tdeb
-# Timeline
-
-## What needs to be done still?
+---
+
+## Timeline
+
+### Sequence
+
+* Archive and tools support (Squeeze)
+* Debconf translation will form the first TDebs (Squeeze + 1)
+* Native packages with program translations next
+* Non-native packages with Debian maintainers who are also the upstream
+
+### What needs to be done for Squeeze ?
* tdeb binary file definition - (ratification and review)
* tdeb source file definition - (development and testing)
-* dpkg class support - (make it easier to selectively install translations
-for specific locale roots).
* dpkg-source building support - (partially implemented in git)
+
+There will be no TDebs in Squeeze.
+
+### What needs to be done for Squeeze + 1?
+
* debhelper support for both tdebs explicitly, and also marking files into
classes in general (partially implemented via dh_gentdeb in git)
* provide a patch to cdbs for running dh_gentdeb in the right place.
-(Done - only remains for the patch to be filed and applied, after Lenny).
+(Done - only remains for the patch to be filed and applied).
* apt/aptitude support for pulling in and removing tdebs
* lintian support
* debdiff support
* devscripts support (debc)
* dak support (run away, run away) run faster
+
+First generation of TDebs:
+
+* packages using debconf
+* native packages using gettext (optional)
+
+### What will be done for Squeeze + 2 or later?
+
+* dpkg class support - (make it easier to selectively install translations
+for specific locale roots).
* support for packages using non-gettext translations. Packages using
non-gettext mechanisms include OOo, mozilla, Qt or Java properties, menus,
desktop.)
-We do need the toolchain changes in squeeze so we can enable use
-of it in squeeze+1.
+* any remaining debconf packages not yet using TDebs
+* remaining native packages using gettext
+* non-native packages with a Debian maintainer on upstream team
+* starting support for non-gettext packages
+
+---
# Changes
+
-----
2009-03-08 - [Neil Williams]
@@ -410,3 +605,4 @@
2009-04-14 - [Neil Williams]
* Tweak some of the links to become active.
* Update the URL
+* Fold in the results of the discussions so far on -devel.
More information about the dep-commits
mailing list