r47854 - in /trunk/libconfig-model-perl/debian: README.debian dh/dh_config_model_upgrade

[ddumont-guest at users.alioth.debian.org]

Author: ddumont-guest
Date: Fri Nov 27 16:31:48 2009
New Revision: 47854

URL: http://svn.debian.org/wsvn/pkg-perl/?sc=1&rev=47854
Log:
add README.debian

Added:
    trunk/libconfig-model-perl/debian/README.debian
Modified:
    trunk/libconfig-model-perl/debian/dh/dh_config_model_upgrade

Added: trunk/libconfig-model-perl/debian/README.debian
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libconfig-model-perl/debian/README.debian?rev=47854&op=file
==============================================================================
--- trunk/libconfig-model-perl/debian/README.debian (added)
+++ trunk/libconfig-model-perl/debian/README.debian Fri Nov 27 16:31:48 2009
@@ -1,0 +1,49 @@
+The aim of dh_config_model_upgrade is to provide an easy way for a
+debian developer to add better configuration upgrade to the packages
+they maintain.
+
+Let's assume that Joe, debian developer, wants to add smooth upgrade
+capability to his foobar package.
+
+What will the end user see ?
+
+The end user may have to answer a medium debconf question asking him
+whether to upgrade foobar package with Config::Model. Hopefully,
+that's all the end user will see.
+
+What does Joe, debian developer, has to do ?
+
+- ensure that a proper configuration model for the application
+  contained in foobar exists.
+- ensure that foobar.postinst and foobar.config have a #DEBHELPER#
+  line (if these files exist)
+- ensure that foobar.control has a dependency on ${misc:Depends}
+- call dh_config_model_upgrade during package build. See
+  dh_config_model_upgrade man page for more details
+
+
+How does this work ?
+
+When called, dh_config_model_upgrade will setup foobar package to ask
+whether to upgrade the configuration with Config::Model or not.
+
+This requires to:
+- add a dependency on libconfig-model-perl in foobar control file
+- add or update foobar.config file so that the question is raised by
+  debconf. This file is generated from config-config-model delivered
+  by libconfig-model-perl package
+- add or update foobar.postinst file so that the configuration is
+  upgraded if the user answered yes to the question above This file is
+  generated from postinst-config-model delivered by libconfig-model-perl
+  package
+- last but not least, both foobar.config and foobar.postinst will use
+  a template delivered by libconfig-model-perl
+  (libconfig-model-perl.templates) to ask the question to user. This
+  template contains a ${pkg_name} substitution that will be replaced
+  with 'foobar' by foobar.config and foobar.postinst (See SUBST
+  debconf command in debconf-devel(7))
+
+All these operations are handled by dh_config_model_upgrade.
+
+Feel free to contact the package maintainer if more explanations are
+needed.

Modified: trunk/libconfig-model-perl/debian/dh/dh_config_model_upgrade
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libconfig-model-perl/debian/dh/dh_config_model_upgrade?rev=47854&op=diff
==============================================================================
--- trunk/libconfig-model-perl/debian/dh/dh_config_model_upgrade (original)
+++ trunk/libconfig-model-perl/debian/dh/dh_config_model_upgrade Fri Nov 27 16:31:48 2009
@@ -132,6 +132,22 @@
 
 =back
 
+=head1 REQUIREMENTS
+
+For this program to work, package maintainer must ensure that:
+
+=over
+
+=item *
+
+ensure that *.postinst and *.config have a #DEBHELPER#  line (if these files exist)
+
+=item *
+
+ensure that control file has a dependency on ${misc:Depends}
+
+=back
+
 =head1 OPTIONS
 
 =head2 --model_name XX