1 files changed, 85 insertions, 0 deletions
diff --git a/debian/README.source b/debian/README.source
new file mode 100644
index 0000000..6f9bd61
--- /dev/null
+++ b/debian/README.source
@@ -0,0 +1,85 @@
+Patching happens as usual. This document just explains some more
+complex aspects of the packaging.
+
+For details on how to get the build environment after checking out
+from Subversion, see README.svn.
+
+The following are notes by J.M. Roth <jmroth@iip.lu> (Mar 2010)
+
+The database
+============
+
+Upgrading
+---------
+
+Upgrading is easy: modify the upstream database_update.php file (strip
+output-generating stuff, see patches) and put it into
+dbconfig-common/scripts/phpbb3/upgrade/...
+
+Installing
+----------
+
+A new install is the hard part. One has to distinguish between:
+
+- the schema, and
+
+- the schema data.
+
+For each version of phpBB, the schema file itself is at the newest
+state. Still, the install script would do things that are not in the
+schema (data).
+
+Even if one would simply import generic schema data and then ran the
+updater somehow, this does not work because dbconfig-common FIRST runs
+script and only then imports (custom) SQL data.
+
+Therefore, one has to generate a new dump of an UPGRADED database at
+each version (either manually via database_update.php or via the
+upgrade functionality already implemented in a new package). The
+debianization here only needs to occur initially, except for the
+dynamic stuff added in postinst. To that end:
+
+- run the installer of the first version from which an update is
+possible to the new version (this one performs the debianizations),
+
+- update the install using the new version to provide (this runs the
+update script),
+
+- extract the data using some tool like mysqldump or phpmyadmin,
+e.g. mysqldump --compatible=ansi --skip-opt --compact
+--complete-insert --no-create-info --skip-quote-names, so this data
+requires the least postprocessing necessary to import into all
+supported db types, and make sure that indexes/sequences are
+generated/updated on the fly during import, i.e. for postgres we use
+postgres_update_seqs.sh,
+
+- use this extracted data to produce the files for
+dbconfig-common/data/phpbb3/install/,
+
+- replace the he data that would usually contain '@DEB_...' and be
+dynamically replaced during postinst (e.g. captcha obfuscation),
+
+- save these files as database_update_debian.php and
+  schema_data_debian.sql, respectively.
+
+Testing the package
+===================
+
+When testing the package in a chroot (e.g. man schroot) the following
+cleanup script might come in handy when things get really broken
+
+#!/bin/sh -x
+#rm -rf /var/lib/phpbb3 /usr/share/phpbb3 /etc/phpbb3 /etc/dbconfig-common/phpbb* /usr/share/dbconfig-common/data/phpbb* /usr/share/dbconfig-common/scripts/phpbb* /var/lib/dpkg/info/phpbb*
+#for i in $(debconf-get-selections | grep ^phpbb | awk '{print $2}' | cut -d/ -f1 | sort | uniq); do
+#    echo purge | debconf-communicate $i
+#    u=$(echo $i | cut -d_ -f2)
+#    for j in $(rgrep $u /var/lib/ucf); do
+#        ucf --purge $(echo j | awk '{print $2}')
+#    done
+#done
+#for i in $(rgrep phpbb /var/lib/ucf | awk '{print $2}'); do
+#    ucf --purge $i
+#done
+#aptitude -y purge phpbb3
+
+This is not an issue when using pbuilder/pdebuild.