/[dep]/web/deps/dep4.mdwn

Diff of /web/deps/dep4.mdwn

Parent Directory | Revision Log | View Patch Patch

-revision 49 by codehelp,
Tue Apr 14 09:25:44 2009 UTC
+revision 50 by codehelp,
Tue Apr 14 10:26:33 2009 UTC
 Line 10
      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]]
-Line 35 
 packages.
+Line 36 
 packages.
 . 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 &copy; 2008
  * Neil Williams <email>codehelp@debian.org</email>,
-Line 60 
 Debian (possibly with automated TDeb gen
+Line 59 
 Debian (possibly with automated TDeb gen
  ## 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
+ package format. It has the same structure as deb, but the (single) data
- is replaced by bzip2-compressed members for each LOCALE_ROOT supported.
+ 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 !&lt;arch&gt;.
-Line 165 
 the rest.
+Line 210 
 the rest.
  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
-Line 184 
 Patches for current tools are handled in
+Line 338 
 Patches for current tools are handled in
  * <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
-Line 194 
 be NO support for Architecture-dependent
+Line 350 
 be NO support for Architecture-dependent
  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
  ## Avoiding changes to the source package
-Line 266 
 If tdebs are revised by the translation
+Line 424 
 If tdebs are revised by the translation
  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
-Line 286 
 There is no need to unpack in order to o
+Line 446 
 There is no need to unpack in order to o
  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
  apt-extracttemplates is used by debconf's dpkg-preconfigure to extract
-Line 294 
 This needs to take tdebs into account. N
+Line 456 
 This needs to take tdebs into account. N
  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/
-Line 302 
 all templates files under the original n
+Line 466 
 all templates files under the original n
  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
  ## PO translations
-Line 326 
 can be reused)
+Line 495 
 can be reused)
  * 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
-Line 333 
 languages, coordinate builds of tdebs to
+Line 504 
 languages, coordinate builds of tdebs to
  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)
+ # TDeb implementation
- * 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
-Line 362 
 Automation in uscan should be possible
+Line 528 
 Automation in uscan should be possible
  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).
-Line 373 
 merged in new versions of the source pac
+Line 541 
 merged in new versions of the source pac
  i18n.debian.net needs to help "Localisation Assistants" in gathering the new
  translations before the preparation of a new tdeb
- # Timeline
+ ---
+ ## Timeline
- ## What needs to be done still?
+ ### 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
+ * any remaining debconf packages not yet using TDebs
- of it in squeeze+1.
+ * remaining native packages using gettext
+ * non-native packages with a Debian maintainer on upstream team
+ * starting support for non-gettext packages
+ ---
  # Changes
  -----
 -03-08 - [Neil Williams]
-Line 410 
 of it in squeeze+1.
+Line 605 
 of it in squeeze+1.
 -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.

 Legend:



Removed from v.49
 


changed lines


 
Added in v.50
 Legend:



Removed from v.49
 


changed lines


 
Added in v.50
-Removed from v.49
+Added in v.50

	ViewVC Help
Powered by ViewVC 1.1.5