[Soc-coordination] Declarative Diversions - Report 1

[Sam Dunne]

The following is the design spec so far for this project. It has to be
fleshed out a bit more but most of the basic structure is there. Anyone who
cares to give input is more than welcome.
A further update will be posted on Monday to my blog, planet debian, the
wiki page and to the dpkg mailing list.

DECLARATIVE DIVERSIONS
======================
------------
Introduction
------------
A diversion is when it is possible to have dpkg not overwrite a file when
it
reinstalls the package it belongs to, and to have it put the file from the
package somewhere else instead.

Declarative diversions involves a new control file with a declarative
syntax which dpkg will parse and process directly as part of the package
unpack
and removal phases, eliminating the problems resulting from non-atomic
handling of diversions.


------
Topics
------
There are a number of topics involved in implementing this kind of project

 * What syntax do we use for the new control file?
 * What dpkg does with the control file
 * How do we handle diversions to a non-existant directory?
 * How do we order unpacking a new package which adds a diversion?
 * How do we order removing a package which had a diversion?
 * How do we handle errors?
 * What happens to dpkg-divert?


-----------------------------
Details - Control File Syntax
-----------------------------
It will conform to RFC2822 style with the following format:
 * Divert-From:
 * Divert-To:
 * Blank lines and lines beginning with '#' will be comments

'Divert-To' will be optional and if it is ommitted then files being
diverted
will have their filename changed to 'file.distrib'

The above style has it's advantages, one of the main ones being that there
is
no need to escape whitespace within filenames.


-------------------------------
Details - Control File Handling
-------------------------------
Within control.tar.gz the file should be named 'diversions'
This file is then copied to /var/lib/info/$package.diversions
This is ensuring we have a copy of the control file just in case it is
needed.
Any input on this subject would be appreciated.


---------------------------------------------------------
Details - Handling Diversions to non-existant directories
---------------------------------------------------------
Diverting files to directories that don't exist can cause a number of
problems.
If the package does not 'own' the directory it may be left orphaned on
removal of the package
The package is responsible for ensuring the availability of the target
directory in the unpack phase.


-------------------------------
Details - Ordering Requirements
-------------------------------
 =>Unpacking a new package that adds a diversion
   *1. Unpack folders
   *2. Add diversions
   *3. Unpack files
   ==Notes==
   Performing diversions this way avoids trouble with creating folders and
   accidentally overwrtiting the wrong version of files.
   If we don't use this method the problems that can occur include creating
   folders before the package itself would create them which may cause
   permission errors.
   Another major problem would be extracting a new version of the file and
   overwriting the old one.
   This might cause the wrong version of the file to be diverted and the
   package to break.


 =>Removing a package which had a diversion
   *1. Remove files
   *2. Remove diversions
   *3. Remove folders
   ==Notes==
   This ensures that all files, diversions and folders are removed correctly


------------------------
Details - Error handling
------------------------
Errors in diversions will have to handled with a great deal of care due to
the fact that if they are not the package could be broken.
This means that a great deal of checks must be done to ensure that all the
files
can be diverted properly before any actual diverting takes place. If they
can't
the package installation/update must be stopped and rolled back to avoid
the
package being installed incorrectly or broken.


-----------------------
Details - 'dpkg-divert'
-----------------------
When we impliment the new diversion method we should keep the current
dpkg-divert. This allows maintainers to catch up with the new method
without
breaking their packages. It also allows maintainers to perform some
operations
that aren't support by the new method.


----------------
Example Usage #1
----------------
The file to be diverted is '/usr/share/foo'
It needs to be moved to '/usr/share/bar'

The syntax of the control file would be:

#Start File
Divert-From: /usr/share/foo
Divert-To: /usr/share/bar
#End File


----------------
Example Usage #2
----------------
In this example the maintainer doesn't want to move the file to any specific
folder

The syntax of the control file would be:

#Start File
Divert-From: /usr/share/foo
#End File

This would divert the file to '/usr/share/foo.distrib'


---------
Footnotes
---------
RFC2822 Guide:
 * http://www.faqs.org/rfcs/rfc2822.html

First Email Thread on Declarative Diversions (First Message in Thread):
 * http://lists.debian.org/debian-dpkg/2011/05/msg00102.html

Declarative Diversions Wiki:
 * http://wiki.debian.org/SummerOfCode2011/DeclarativeDiversions

My Blog for this Project:
 * http://blog.sam-dunne.com

-- 
Sam Dunne

BSc Computer Science, UCD Dublin.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.alioth.debian.org/pipermail/soc-coordination/attachments/20110603/f82c20b9/attachment.html>