Make parts of generic packaging conditional

This should allow to rebuild old releases from before Debian packages,
Arch ppackages, manpages, or even the HTML manual were added

.gitignore

@@ -1,17 +1,26 @@
-# Temporary files and dependencies
+# Temporary files
 
-/vendor/
-/vendor-bin/*/vendor
-/node_modules
+/release/
 /documentation/
 /manual/
 /tests/coverage/
+/dist/arch/arsse/
+/dist/arch/src/
+/dist/arch/pkg/
+/dist/man/
 /arsse.db*
 /config.php
 /.php_cs.cache
-/yarn-error.log
 /tests/.phpunit.result.cache
 
+# Dependencies
+
+/vendor/
+/vendor-bin/*/vendor
+/node_modules
+/yarn.lock
+/yarn-error.log
+
 
 # Windows files
 
@@ -26,7 +35,6 @@ $RECYCLE.BIN/
 .DS_Store
 .AppleDouble
 .LSOverride
-Icon
 ._*
 .Spotlight-V100
 .Trashes
@@ -37,6 +45,7 @@ Icon
 *.zip
 *.7z
 *.tar.gz
+*.tar.xz
 *.tgz
 *.deb
 *.rpm

CHANGELOG

@@ -1,9 +1,66 @@
+Version 0.10.0 (2021-07-11)
+===========================
+
+New features:
+- Complete Unix manual page
+- Support for running service as a forking daemon
+- Respond to TERM and HUP signals when possible
+
+Changes:
+- Packages for Debian and related are now available (see manual for details)
+
+Version 0.9.2 (2021-05-25)
+==========================
+
+Bug fixes:
+- Do not fail adding users to an empty database (regression since 0.9.0)
+- Cleanly ignore unknown configuration properties
+- Set access mode to rw-r---- when creating SQLite databases
+
+Changes:
+- Packages for Arch Linux are now available (see manual for details)
+- Numerous improvements to the manual
+
+Version 0.9.1 (2021-03-18)
+==========================
+
+Bug fixes:
+- Respond to PUT requests with 201 rather than 200 in Miniflux
+
+Changes:
+- Correct Web server configuration in manual
+
+Version 0.9.0 (2021-03-06)
+==========================
+
+New features:
+- Support for the Miniflux protocol (see manual for details)
+- Support for API level 15 of Tiny Tiny RSS
+- Support for feed icons in Fever
+- Command-line functionality for managing user metadata
+- Command-line functionality for managing Miniflux login tokens
+
+Bug fixes:
+- Further relax Fever HTTP correctness, to fix more clients
+- Use icons specified in Atom feeds when available
+- Do not return null as subscription unread count
+- Explicitly forbid U+003A COLON and control characters in usernames, for 
+  compatibility with RFC 7617
+- Never return 401 in response to an OPTIONS request
+- Accept "t" and "f" as booleans in Tiny Tiny RSS
+
+Changes:
+- Administrator account requirements for Nextcloud News functionality are
+  now enforced
+- E_DEPRECATED is now suppressed for compatibility with PHP 8 until affected
+  dependencies can be replaced
+
 Version 0.8.5 (2020-10-27)
 ==========================
 
 Bug fixes:
 - Relax Fever HTTP correctness, to fix some clients
-- Added the QUERY_STRING FastCGI paramater to the sample Nginx configuration
+- Add the QUERY_STRING FastCGI parameter to the sample Nginx configuration
 
 Version 0.8.4 (2020-09-09)
 ==========================
@@ -84,7 +141,7 @@ Bug fixes:
 Version 0.6.1 (2019-01-23)
 ==========================
 
-Bug Fixes:
+Bug fixes:
 - Unify SQL timeout settings
 - Correctly escape shell command in subprocess service driver
 - Correctly allow null time intervals in configuration when appropriate
@@ -204,4 +261,5 @@ Bug fixes:
 Version 0.1.0 (2017-08-29)
 ==========================
 
-Initial release
+New features:
+- Initial release

README.md

@@ -8,7 +8,7 @@ Information on how to install and use the software can be found in [the manual](
 
 The main repository for The Arsse can be found at [code.mensbeam.com](https://code.mensbeam.com/MensBeam/arsse/), with a mirror also available [at GitHub](https://github.com/mensbeam/arsse/). The GitHub mirror does not accept bug reports, but the two should otherwise be equivalent.
 
-[Composer](https://getcomposer.org/) is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running `composer install` will download all the required dependencies, and will advise if any PHP extensions need to be installed. If not installing as a programming environment, running `composer install --no-dev` is recommended.
+[Composer](https://getcomposer.org/) is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running `composer install` will download all the required dependencies, and will advise if any PHP extensions need to be installed. If not installing as a programming environment, running `composer install -o --no-dev --no-scripts` is recommended.
 
 # Repository structure
 
@@ -34,13 +34,15 @@ Also necessary to the functioning of the application is the `/vendor/` directory
 
 The `/locale/` and `/sql/` directories contain human-language files and database schemata, both of which are occasionally used by the application in the course of execution. The `/www/` directory serves as a document root for a few static files to be made available to users by a Web server.
 
-The `/dist/` directory, on the other hand, contains samples of configuration for Web servers and init systems. These are not used by The Arsse itself, but are merely distributed with it for reference.
+The `/dist/` directory, on the other hand, contains general and system-specific build files, and samples of configuration for Web servers and other system integration. These are not used by The Arsse itself, but are used during the process of preparing new releases for supported operating systems.
 
 ## Documentation
 
 The source text for The Arsse's manual can be found in `/docs/`, with pages written in [Markdown](https://spec.commonmark.org/current/) and converted to HTML [with Daux](#building-the-manual). If a static manual is generated its files will appear under `/manual/`.
 
-In addition to the manual the files `/README.md` (this file), `/CHANGELOG`, `/UPGRADING`, `/LICENSE`, and `/AUTHORS` also document various things about the software, rather than the software itself.
+The Arsse also has a UNIX manual page, also written in Markdown, which can be found under `/manpages/`. [Pandoc](https://pandoc.org/) is needed to convert it to the appropriate format, with the results stored under `/dist/man/`.
+
+In addition to the manuals the files `/README.md` (this file), `/CHANGELOG`, `/UPGRADING`, `/LICENSE`, and `/AUTHORS` also document various things about the software, rather than the software itself.
 
 ## Tests
 
@@ -50,7 +52,7 @@ The `/tests/` directory contains everything related to automated testing. It is
 |--------------------|------------------------------------------------------------------------------------|
 | `cases/`           | The test cases themselves, organized in roughly the same structure as the code     |
 | `coverage/`        | (optional) Generated code coverage reports                                         |
-| `docroot/`         | Sample documents used in some tests, to be returned by the PHP's basic HTTP server |
+| `docroot/`         | Sample documents used in some tests, to be returned by PHP's basic HTTP server |
 | `lib/`             | Supporting classes which do not contain test cases                                 |
 | `bootstrap.php`    | Bootstrap script, equivalent to `/arsse.php`, but for tests                        |
 | `phpunit.dist.xml` | PHPUnit configuration file                                                         |
@@ -74,7 +76,7 @@ The `/vendor-bin/` directory houses the files needed for the tools used in The A
 | `/robo`           | Simple wrapper for executing Robo on POSIX systems       |
 | `/robo.bat`       | Simple wrapper for executing Robo on Windows             |
 
-In addition the files `/package.json`, `/yarn.lock`, and `/postcss.config.js` as well as the `/node_modules/` directory are used by [Yarn](https://yarnpkg.com/) and [PostCSS](https://postcss.org/) when modifying the stylesheet for The Arsse's manual.
+In addition the files `/package.json` and `/postcss.config.js` as well as the `/node_modules/` directory are used by [Yarn](https://yarnpkg.com/) and [PostCSS](https://postcss.org/) when modifying the stylesheet for The Arsse's manual.
 
 # Common tasks
 
@@ -105,15 +107,20 @@ The Arsse's user manual, made using [Daux](https://daux.io/), can be compiled by
 
 The manual employs a custom theme derived from the standard Daux theme. If the standard Daux theme receives improvements, the custom theme can be rebuilt by running `./robo manual:theme`. This requires that [NodeJS](https://nodejs.org) and [Yarn](https://yarnpkg.com/) be installed, but JavaScript tools are not required to modify The Arsse itself, nor the content of the manual.
 
+## Building the man page
+
+The Arsse's UNIX manual page is authored in Markdown, and must be converted to the native roff format using [Pandoc](https://pandoc.org/). This can be done by running `./robo manpage`, which will output appropriate files to `/dist/man/`. The conversion should not be done manually as there is post-processing required for optimal output.
+
 ## Packaging a release
 
-Producing a release package is done by running `./robo package`. This performs the following operations:
+Producing release packages is done by running `./robo package`. This performs the following operations:
 
-- Duplicates a working tree with the commit (usually a release tag) to package
-- Generates the manual
+- Duplicates a [Git](https://git-scm.com/) working tree with the commit (usually a release tag) to package
+- Generates UNIX manual pages with [Pandoc](https://pandoc.org/)
+- Generates the HTML manual
 - Installs runtime Composer dependencies with an optimized autoloader
 - Deletes numerous unneeded files
 - Exports the default configuration of The Arsse to a file
 - Compresses the remaining files into a tarball
-
-Due to the first step, [Git](https://git-scm.com/) is required to package a release.
+- Produces a binary package for Arch Linux, if possible
+- Produces source and binary packages for Debian using [pbuilder](https://pbuilder-team.pages.debian.net/pbuilder/), if possible

RoboFile.php

@@ -1,11 +1,14 @@
 <?php
 
+use Robo\Collection\CollectionBuilder;
 use Robo\Result;
 
 const BASE = __DIR__.\DIRECTORY_SEPARATOR;
 const BASE_TEST = BASE."tests".\DIRECTORY_SEPARATOR;
 define("IS_WIN", defined("PHP_WINDOWS_VERSION_MAJOR"));
 define("IS_MAC", php_uname("s") === "Darwin");
+define("IS_LINUX", !IS_WIN && !IS_MAC);
+error_reporting(0);
 
 function norm(string $path): string {
     $out = realpath($path);
@@ -96,11 +99,11 @@ class RoboFile extends \Robo\Tasks {
         if (extension_loaded("pcov")) {
             return "$php -d pcov.enabled=1 -d pcov.directory=$code";
         } elseif (extension_loaded("xdebug")) {
-            return $php;
+            return "$php -d xdebug.mode=coverage";
         } elseif (file_exists($dir."pcov.$ext")) {
             return "$php -d extension=pcov.$ext -d pcov.enabled=1 -d pcov.directory=$code";
-        } elseif (file_exists($dir."pcov.$ext")) {
-            return "$php -d zend_extension=xdebug.$ext";
+        } elseif (file_exists($dir."xdebug.$ext")) {
+            return "$php -d zend_extension=xdebug.$ext -d xdebug.mode=coverage";
         } else {
             if (IS_WIN) {
                 $dbg = dirname(\PHP_BINARY)."\\phpdbg.exe";
@@ -144,62 +147,295 @@ class RoboFile extends \Robo\Tasks {
         return $this->taskExec($executor)->option("-d", "zend.assertions=1")->arg($execpath)->option("-c", $confpath)->args(array_merge($set, $args))->run();
     }
 
+    protected function commitVersion(?string $commit): array {
+        $target = $commit ?? $this->askDefault("Reference commit:", "HEAD");
+        $base = escapeshellarg(BASE);
+        $blackhole = $this->blackhole();
+        // get useable version strings from Git
+        $version = trim(`git -C $base describe --tags $target $blackhole`);
+        if (!$version) {
+            throw new \Exception("Commit reference invalid");
+        }
+        return [$target, $version];
+    }
+
+    protected function toolExists(string ...$binary): bool {
+        $blackhole = $this->blackhole(IS_WIN);
+        foreach ($binary as $bin) {
+            if (
+                (IS_WIN && (!exec(escapeshellarg($bin)." --help $blackhole", $junk, $status) || $status))
+                || (!IS_WIN && (!exec("which ".escapeshellarg($bin)." $blackhole", $junk, $status) || $status))
+             ) {
+                    return false;
+            }
+        }
+        return true;
+    }
+
     /** Packages a given commit of the software into a release tarball
      *
-     * The version to package may be any Git tree-ish identifier: a tag, a branch,
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
      * or any commit hash. If none is provided on the command line, Robo will prompt
-     * for a commit to package; the default is "head".
+     * for a commit to package; the default is "HEAD".
      *
      * Note that while it is possible to re-package old versions, the resultant tarball
      * may not be equivalent due to subsequent changes in the exclude list, or because
      * of new tooling.
      */
-    public function package(string $version = null): Result {
+    public function packageGeneric(string $commit = null): Result {
+        if (!$this->toolExists("git", "pandoc")) {
+            throw new \Exception("Git and Pandoc are required in PATH to produce generic release tarballs");
+        }
         // establish which commit to package
-        $version = $version ?? $this->askDefault("Commit to package:", "HEAD");
-        $archive = BASE."arsse-$version.tar.gz";
+        [$commit, $version] = $this->commitVersion($commit);
+        $archVersion = preg_replace('/^([^-]+)-(\d+)-(\w+)$/', "$1.r$2.$3", $version);
+        // name the generic release tarball
+        $tarball = BASE."release/$version/arsse-$version.tar.gz";
         // start a collection
         $t = $this->collectionBuilder();
         // create a temporary directory
         $dir = $t->tmpDir().\DIRECTORY_SEPARATOR;
         // create a Git worktree for the selected commit in the temp location
-        $t->taskExec("git worktree add ".escapeshellarg($dir)." ".escapeshellarg($version));
-        // perform Composer installation in the temp location with dev dependencies
-        $t->taskComposerInstall()->dir($dir);
-        // generate the manual
-        $t->taskExec(escapeshellarg($dir."robo")." manual")->dir($dir);
-        // perform Composer installation in the temp location for final output
-        $t->taskComposerInstall()->dir($dir)->noDev()->optimizeAutoloader()->arg("--no-scripts");
-        // delete unwanted files
-        $t->taskFilesystemStack()->remove([
-            $dir.".git",
-            $dir.".gitignore",
-            $dir.".gitattributes",
-            $dir."composer.json",
-            $dir."composer.lock",
-            $dir.".php_cs.dist",
-            $dir."phpdoc.dist.xml",
-            $dir."build.xml",
-            $dir."RoboFile.php",
-            $dir."CONTRIBUTING.md",
-            $dir."docs",
-            $dir."tests",
-            $dir."vendor-bin",
-            $dir."vendor/bin",
-            $dir."robo",
-            $dir."robo.bat",
-            $dir."package.json",
-            $dir."yarn.lock",
-            $dir."postcss.config.js",
-        ]);
-        // generate a sample configuration file
-        $t->taskExec(escapeshellarg(\PHP_BINARY)." arsse.php conf save-defaults config.defaults.php")->dir($dir);
-        // package it all up
-        $t->taskPack($archive)->addDir("arsse", $dir);
-        // execute the collection
+        $result = $this->taskExec("git worktree add ".escapeshellarg($dir)." ".escapeshellarg($version))->dir(BASE)->run();
+        if ($result->getExitCode() > 0) {
+            return $result;
+        }
+        try {
+            if (file_exists($dir."dist/debian")) {
+                // generate the Debian changelog; this also validates our original changelog
+                $debianChangelog = $this->changelogDebian($this->changelogParse(file_get_contents($dir."CHANGELOG"), $version), $version);
+                // save the Debian-format changelog
+                $t->addTask($this->taskWriteToFile($dir."dist/debian/changelog")->text($debianChangelog));
+            }
+            if (file_exists($dir."dist/arch")) {
+                // patch the Arch PKGBUILD file with the correct version string
+                $t->addTask($this->taskReplaceInFile($dir."dist/arch/PKGBUILD")->regex('/^pkgver=.*$/m')->to("pkgver=$archVersion"));
+                // patch the Arch PKGBUILD file with the correct source file
+                $t->addTask($this->taskReplaceInFile($dir."dist/arch/PKGBUILD")->regex('/^source=\("arsse-[^"]+"\)$/m')->to('source=("'.basename($tarball).'")'));
+            }
+            // save commit description to VERSION file for reference
+            $t->addTask($this->taskWriteToFile($dir."VERSION")->text($version));
+            // perform Composer installation in the temp location with dev dependencies
+            $t->addTask($this->taskComposerInstall()->arg("-q")->dir($dir));
+            if (file_exists($dir."manpages")) {
+                // generate manpages
+                $t->addTask($this->taskExec("./robo manpage")->dir($dir));
+            }
+            if (file_exists($dir."docs")) {
+                // generate the HTML manual
+                $t->addTask($this->taskExec("./robo manual -q")->dir($dir));
+            }
+            // perform Composer installation in the temp location for final output
+            $t->addTask($this->taskComposerInstall()->dir($dir)->noDev()->optimizeAutoloader()->arg("--no-scripts")->arg("-q"));
+            // delete unwanted files
+            $t->addTask($this->taskFilesystemStack()->remove([
+                $dir.".git",
+                $dir.".gitignore",
+                $dir.".gitattributes",
+                $dir."dist/debian/.gitignore",
+                $dir."composer.json",
+                $dir."composer.lock",
+                $dir.".php_cs.dist",
+                $dir."phpdoc.dist.xml",
+                $dir."build.xml",
+                $dir."RoboFile.php",
+                $dir."CONTRIBUTING.md",
+                $dir."docs",
+                $dir."manpages",
+                $dir."tests",
+                $dir."vendor-bin",
+                $dir."vendor/bin",
+                $dir."robo",
+                $dir."robo.bat",
+                $dir."package.json",
+                $dir."yarn.lock",
+                $dir."postcss.config.js",
+            ]));
+            $t->addCode(function() use ($dir) {
+                // Remove files which lintian complains about; they're otherwise harmless
+                $files = [];
+                foreach (new \CallbackFilterIterator(new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($dir."vendor", \FilesystemIterator::CURRENT_AS_PATHNAME | \FilesystemIterator::SKIP_DOTS)), function($v, $k, $i) {
+                    return preg_match('/\/\.git(?:ignore|attributes|modules)$/D', $v);
+                }) as $f) {
+                    $files[] = $f;
+                }
+                return $this->taskFilesystemStack()->remove($files)->run();
+            });
+            // generate a sample configuration file
+            $t->addTask($this->taskExec(escapeshellarg(\PHP_BINARY)." arsse.php conf save-defaults config.defaults.php")->dir($dir));
+            // remove any existing archive
+            $t->addTask($this->taskFilesystemStack()->remove($tarball));
+            // package it all up
+            $t->addTask($this->taskFilesystemStack()->mkdir(dirname($tarball)));
+            $t->addTask($this->taskPack($tarball)->addDir("arsse", $dir));
+            // execute the collection
+            $result = $t->run();
+        } finally {
+            // remove the Git worktree
+            $this->taskFilesystemStack()->remove($dir)->run();
+            $this->taskExec("git worktree prune")->dir(BASE)->run();
+        }
+        return $result;
+    }
+
+    /** Packages a given commit of the software into an Arch package
+     *
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
+     * or any commit hash. If none is provided on the command line, Robo will prompt
+     * for a commit to package; the default is "HEAD".
+     * 
+     * The Arch base-devel group should be installed for this.
+     */
+    public function packageArch(string $commit = null): Result {
+        if (!$this->toolExists("git", "makepkg", "updpkgsums")) {
+            throw new \Exception("Git, makepkg, and updpkgsums are required in PATH to produce Arch packages");
+        }
+        // establish which commit to package
+        [$commit, $version] = $this->commitVersion($commit);
+        $tarball = BASE."release/$version/arsse-$version.tar.gz";
+        $dir = dirname($tarball).\DIRECTORY_SEPARATOR;
+        // start a collection
+        $t = $this->collectionBuilder();
+        // build the generic release tarball if it doesn't exist
+        if (!file_exists($tarball)) {
+            $t->addTask($this->taskExec(BASE."robo package:generic $commit"));
+        }
+        // extract the PKGBUILD from the tarball
+        $t->addCode(function() use ($tarball, $dir) {
+            // because Robo doesn't support extracting a single file we have to do it ourselves
+            (new \Archive_Tar($tarball))->extractList("arsse/dist/arch/PKGBUILD", $dir, "arsse/dist/arch/", false);
+            // perform a do-nothing filesystem operation since we need a Robo task result
+            return $this->taskFilesystemStack()->chmod($dir."PKGBUILD", 0644)->run();
+        })->completion($this->taskFilesystemStack()->remove($dir."PKGBUILD"));
+        // build the package
+        $t->addTask($this->taskExec("makepkg -Ccf")->dir($dir));
+        return $t->run();
+    }
+
+    /** Packages a given commit of the software a binary Debian package
+     *
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
+     * or any commit hash. If none is provided on the command line, Robo will prompt
+     * for a commit to package; the default is "HEAD".
+     * 
+     * The pbuilder tool should be installed for this.
+     */
+    public function packageDeb(string $commit = null): Result {
+        if (!$this->toolExists("git", "sudo", "pbuilder")) {
+            throw new \Exception("Git, sudo, and pbuilder are required in PATH to produce Debian packages");
+        }
+        // establish which commit to package
+        [$commit, $version] = $this->commitVersion($commit);
+        $tarball = BASE."release/$version/arsse-$version.tar.gz";
+        // define some more variables
+        $tgz = BASE."release/pbuilder-arsse.tgz";
+        $bind = dirname($tarball);
+        $script = BASE."dist/debian/pbuilder.sh";
+        $user = trim(`id -un`);
+        $group = trim(`id -gn`);
+        // start a task collection
+        $t = $this->collectionBuilder();
+        // check that the pbuilder base exists and create it if it does not
+        if (!file_exists($tgz)) {
+            $t->addTask($this->taskFilesystemStack()->mkdir(BASE."release"));
+            $t->addTask($this->taskExec('sudo pbuilder create --basetgz '.escapeshellarg($tgz).' --mirror http://ftp.ca.debian.org/debian/ --extrapackages "debhelper devscripts lintian"'));
+        }
+        // build the generic release tarball if it doesn't exist
+        if (!file_exists($tarball)) {
+            $t->addTask($this->taskExec(BASE."robo package:generic $commit"));
+        }
+        // build the packages
+        $t->addTask($this->taskExec('sudo pbuilder execute --basetgz '.escapeshellarg($tgz).' --bindmounts '.escapeshellarg($bind).' -- '.escapeshellarg($script).' '.escapeshellarg("$bind/".basename($tarball))));
+        // take ownership of the output files
+        $t->addTask($this->taskExec("sudo chown -R $user:$group ".escapeshellarg($bind)));
+        return $t->run();
+    }
+
+    /** Packages a release tarball into a Debian source package
+     *
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
+     * or any commit hash. If none is provided on the command line, Robo will prompt
+     * for a commit to package; the default is "HEAD".
+     */
+    public function packageDebsrc(string $commit = null): Result {
+        // establish which commit to package
+        [$commit, $version] = $this->commitVersion($commit);
+        $tarball = BASE."release/$version/arsse-$version.tar.gz";
+        // determine the base version (i.e. x.y.z) and the Debian version (i.e. x.y.z-a)
+        preg_match('/^(\d+(?:\.\d+)+)(?:-(\d+))?/', $version, $m);
+        $baseVersion = $m[1];
+        $debVersion = $m[1]."-".($version === $baseVersion ? "1" : $m[2]);
+        // start a task collection and create a temporary directory
+        $t = $this->collectionBuilder();
+        $dir = $t->tmpDir().\DIRECTORY_SEPARATOR;
+        // build the generic release tarball if it doesn't exist
+        if (!file_exists($tarball)) {
+            $t->addTask($this->taskExec(BASE."robo package:generic $commit"));
+        }
+        $base = $dir."arsse-$version".\DIRECTORY_SEPARATOR;
+        // start by extracting the tarball
+        $t->addCode(function() use ($tarball, $dir, $base) {
+            // Robo's extract task is broken, so we do it manually
+            (new \Archive_Tar($tarball))->extract($dir, false);
+            return $this->taskFilesystemStack()->rename($dir."arsse", $base)->run();
+        });
+        // re-pack the tarball using a specific name special to Debian
+        $t->addTask($this->taskPack($dir."arsse_$baseVersion.orig.tar.gz")->addDir("arsse-$baseVersion", $base));
+        // pack the debian tarball
+        $t->addTask($this->taskPack($dir."arsse_$debVersion.debian.tar.gz")->addDir("debian", $base."dist"));
+        // generate the DSC file
+        $t->addCode(function() use ($t, $debVersion, $baseVersion, $dir, $base) {
+            try {
+                $dsc = $this->generateDebianSourceControl($base."dist/debian/", $debVersion, [$dir."arsse_$baseVersion.orig.tar.gz", $dir."arsse_$debVersion.debian.tar.gz"]);
+            } catch (\Exception $e) {
+                return new Result($t, 1, $e->getMessage());
+            }
+            // write the DSC file
+            return $this->taskWriteToFile($dir."arsse_$debVersion.dsc")->text($dsc)->run();
+        });
+        // delete any existing files
+        $t->AddTask($this->taskFilesystemStack()->remove(BASE."release/$version/arsse_$baseVersion.orig.tar.gz")->remove(BASE."release/$version/arsse_$debVersion.debian.tar.gz")->remove(BASE."release/$version/arsse_$debVersion.dsc"));
+        $t->addTask($this->taskFilesystemStack()->copy($dir."arsse_$baseVersion.orig.tar.gz", BASE."release/$version/arsse_$baseVersion.orig.tar.gz")->copy($dir."arsse_$debVersion.debian.tar.gz", BASE."release/$version/arsse_$debVersion.debian.tar.gz")->copy($dir."arsse_$debVersion.dsc", BASE."release/$version/arsse_$debVersion.dsc"));
+        return $t->run();
+    }
+
+    /** Generates all possible package types for a given commit of the software
+     *
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
+     * or any commit hash. If none is provided on the command line, Robo will prompt
+     * for a commit to package; the default is "HEAD".
+     * 
+     * Generic release tarballs will always be generated, but distribution-specific
+     * packages are skipped when the required tools are not available
+     */
+    public function package(string $commit = null): Result {
+        if (!$this->toolExists("git")) {
+            throw new \Exception("Git is required in PATH to produce packages");
+        }
+        [$commit,] = $this->commitVersion($commit);
+        // determine whether the distribution-specific packages can be built
+        $dist = [
+            'Arch'   => $this->toolExists("git", "makepkg", "updpkgsums"),
+            'Deb' => $this->toolExists("git", "sudo", "pbuilder"),
+        ];
+        // start a collection
+        $t = $this->collectionBuilder();
+        // build the generic release tarball
+        $t->addTask($this->taskExec(BASE."robo package:generic $commit"));
+        // build other packages
+        foreach ($dist as $distro => $run) {
+            if ($run) {
+                $subcmd = strtolower($distro);
+                $t->addTask($this->taskExec(BASE."robo package:$subcmd $commit"));
+            }
+        }
         $out = $t->run();
-        // clean the Git worktree list
-        $this->_exec("git worktree prune");
+        // note any packages which were not built
+        foreach ($dist as $distro => $run) {
+            if (!$run) {
+                $this->say("Packages for $distro skipped");
+            }
+        }
         return $out;
     }
 
@@ -229,6 +465,9 @@ class RoboFile extends \Robo\Tasks {
      * Daux's theme changes
      */
     public function manualTheme(array $args): Result {
+        if (!$this->toolExists("yarn")) {
+            throw new \Exception("Yarn is required in PATH to update the Daux theme");
+        }
         $postcss = escapeshellarg(norm(BASE."node_modules/.bin/postcss"));
         $themesrc = norm(BASE."docs/theme/src/").\DIRECTORY_SEPARATOR;
         $themeout = norm(BASE."docs/theme/arsse/").\DIRECTORY_SEPARATOR;
@@ -246,4 +485,270 @@ class RoboFile extends \Robo\Tasks {
         // execute the collection
         return $t->run();
     }
+
+    /** Generates the "arsse" command's manual page (UNIX man page)
+     *
+     * This requires that the Pandoc document converter be installed and
+     * available in $PATH.
+     */
+    public function manpage(): Result {
+        if (!$this->toolExists("pandoc")) {
+            throw new \Exception("Pandoc is required in PATH to generate manual pages");
+        }
+        $t = $this->collectionBuilder();
+        $man = [
+            'en' => "man1/arsse.1",
+        ];
+        foreach ($man as $src => $out) {
+            $src = BASE."manpages/$src.md";
+            $out = BASE."dist/man/$out";
+            $t->addTask($this->taskFilesystemStack()->mkdir(dirname($out), 0755));
+            $t->addTask($this->taskExec("pandoc -s -f markdown-smart -t man -o ".escapeshellarg($out)." ".escapeshellarg($src)));
+            $t->addTask($this->taskReplaceInFile($out)->regex('/\.\n(?!\.)/s')->to(". "));
+        }
+        return $t->run();
+    }
+
+    protected function changelogParse(string $text, string $targetVersion): array {
+        $lines = preg_split('/\r?\n/', $text);
+        $version = "";
+        $section = "";
+        $out = [];
+        $entry = [];
+        $expected = ["version"];
+        for ($a = 0; $a < sizeof($lines);) {
+            $l = rtrim($lines[$a++]);
+            if (in_array("version", $expected) && preg_match('/^Version (\d+(?:\.\d+)*) \(([\d\?]{4}-[\d\?]{2}-[\d\?]{2})\)\s*$/D', $l, $m)) {
+                $version = $m[1];
+                if (!preg_match('/^\d{4}-\d{2}-\d{2}$/D', $m[2])) {
+                    // uncertain dates are allowed only for the top version, and only if it does not match the target version (otherwise we have forgotten to set the correct date before tagging)
+                    if (!$out && $targetVersion !== $version) {
+                        // use today's date; local time is fine
+                        $date = date("Y-m-d");
+                    } else {
+                        throw new \Exception("CHANGELOG: Date at line $a is incomplete");
+                    }
+                } else {
+                    $date = $m[2];
+                }
+                if ($entry) {
+                    $out[] = $entry;
+                }
+                $entry = ['version' => $version, 'date' => $date, 'features' => [], 'fixes' => [], 'changes' => []];
+                $expected = ["separator"];
+            } elseif (in_array("separator", $expected) && preg_match('/^=+/', $l)) {
+                $length = strlen($lines[$a - 2]);
+                if (strlen($l) !== $length) {
+                    throw new \Exception("CHANGELOG: Separator at line $a is of incorrect length");
+                }
+                $expected = ["blank line"];
+                $section = "";
+            } elseif (in_array("blank line", $expected) && $l === "") {
+                $expected = [
+                    ''         => ["features section", "fixes section", "changes section"],
+                    'features' => ["fixes section", "changes section", "version"],
+                    'fixes'    => ["changes section", "version"],
+                    'changes'  => ["version"],
+                ][$section];
+                $expected[] = "end-of-file";
+            } elseif (in_array("features section", $expected) && $l === "New features:") {
+                $section = "features";
+                $expected = ["item"];
+            } elseif (in_array("fixes section", $expected) && $l === "Bug fixes:") {
+                $section = "fixes";
+                $expected = ["item"];
+            } elseif (in_array("changes section", $expected) && $l === "Changes:") {
+                $section = "changes";
+                $expected = ["item"];
+            } elseif (in_array("item", $expected) && preg_match('/^- (\w.*)$/D', $l, $m)) {
+                $entry[$section][] = $m[1];
+                $expected = ["item", "continuation", "blank line"];
+            } elseif (in_array("continuation", $expected) && preg_match('/^  (\w.*)$/D', $l, $m)) {
+                $last = sizeof($entry[$section]) - 1;
+                $entry[$section][$last] .= "\n".$m[1];
+            } else {
+                if (sizeof($expected) > 1) {
+                    throw new \Exception("CHANGELOG: Expected one of [".implode(", ", $expected)."] at line $a");
+                } else {
+                    throw new \Exception("CHANGELOG: Expected ".$expected[0]." at line $a");
+                }
+            }
+        }
+        if (!in_array("end-of-file", $expected)) {
+            if (sizeof($expected) > 1) {
+                throw new \Exception("CHANGELOG: Expected one of [".implode(", ", $expected)."] at end of file");
+            } else {
+                throw new \Exception("CHANGELOG: Expected ".$expected[0]." at end of file");
+            }
+        }
+        $out[] = $entry;
+        return $out;
+    }
+
+    protected function changelogDebian(array $log, string $targetVersion): string {
+        $latest = $log[0]['version'];
+        $baseVersion = preg_replace('/^(\d+(?:\.\d+)*).*/', "$1", $targetVersion);
+        if ($baseVersion !== $targetVersion && version_compare($latest, $baseVersion, ">")) {
+            // if the changelog contains an entry for a future version, change its version number to match the target version instead of using the future version
+            $log[0]['version'] = $targetVersion;
+            $log[0]['distribution'] = "UNRELEASED";
+        } elseif ($baseVersion !== $targetVersion) {
+            // otherwise synthesize a changelog entry for the changes since the last tag
+            array_unshift($log, ['version' => $targetVersion, 'date' => date("Y-m-d"), 'features' => [], 'fixes' => [], 'changes' => ["Unspecified changes"], 'distribution' => "UNRELEASED"]);
+        }
+        $out = "";
+        foreach ($log as $entry) {
+            // normalize the version string
+            preg_match('/^(\d+(?:\.\d+)*)(?:-(\d+)-.+)?$/D', $entry['version'], $m);
+            $version = $m[1]."-".($m[2] ?: "1");
+            // output the entry
+            $out .= "arsse ($version) ".($entry['distribution'] ?? "unstable")."; urgency=low\n";
+            if ($entry['features']) {
+                $out .= "\n";
+                foreach ($entry['features'] as $item) {
+                    $out .= "  * ".trim(preg_replace("/^/m", "    ", $item))."\n";
+                }
+            }
+            if ($entry['fixes']) {
+                $out .= "\n";
+                foreach ($entry['fixes'] as $item) {
+                    $out .= "  * ".trim(preg_replace("/^/m", "    ", $item))."\n";
+                }
+            }
+            if ($entry['changes']) {
+                $out .= "\n";
+                foreach ($entry['changes'] as $item) {