Some explanations about dh_config_model_upgrade

[Dominique Dumont <dominique.dumont@hp.com>]

Hello

Since dh_config_model_upgrade and the associated template is not easy to 
understand, I've written a README.debian file in libconfig-model-perl.

Could you review this text (pasted below) and provide comments or suggestions?

Thanks

===============

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.

===========

Thanks

Dominique
--
http://config-model.wiki.sourceforge.net/ -o- http://search.cpan.org/~ddumont/
http://www.ohloh.net/accounts/ddumont