docs: refresh command list, workflow example, roadmap and install

The command block is now the actual pkh --help output (new, lint and
prune were missing). The example workflow used pkh commit, a
subcommand that does not exist; commits go through git until
chlog/pkh commit land. The roadmap now reflects what is implemented
(pull -v, deb --mode local, lint, prune, new) and an installation
section documents the source build and its system dependencies.

README.md

@@ -2,6 +2,22 @@
 
 `pkh` is a packaging helper for Debian/Ubuntu packages.
 
+## Installation
+
+No distribution channel is published yet; build from source:
+
+```
+sudo apt install pkg-config libssl-dev libgpg-error-dev libgpgme-dev
+git clone https://git.vhaudiquet.fr/vhaudiquet/pkh.git
+cd pkh
+cargo install --path .
+```
+
+At runtime pkh shells out to the Debian packaging toolchain (git,
+dpkg-dev, quilt, mmdebstrap, lintian, pristine-tar, ...): install the
+ones your workflows use, or build the classic snap from
+`snap/snapcraft.yaml` (`snapcraft pack`), which carries them.
+
 ## Usage and features
 
 ### Basic concepts
@@ -25,12 +41,19 @@ Options:
 Commands and workflows include:
 ```
 Commands:
+  new    Scaffold a new Debian source package (buildable right away)
   pull   Pull a source package from the archive or git
   chlog  Auto-generate changelog entry, editing it, committing it afterwards
   build  Build the source package (into a .dsc)
-  deb    Build the source package into binary package (.deb)
   put    Upload the built source package to a PPA
+  deb    Build the source package into binary package (.deb)
+  lint   Lint the package (lintian wrapper + pkh-native checks)
+  prune  Prune residual pkh build artifacts and caches
   help   Print this message or the help of the given subcommand(s)
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
 ```
 
 ### Examples
@@ -66,14 +89,15 @@ That is a lot of different tools and operations. With pkh, the same workflow:
 pkh pull hello # needs -d ubuntu if you are not running Ubuntu
 # Apply the patch to the package
 ...
-pkh commit -m "Applied patch xxx"
+git add debian/patches/xxx.patch
+git commit -m "Applied patch xxx"
 pkh chlog
 # Test that the package builds
 pkh build
 pkh deb
 # Upload the package to a ppa
 pkh put --ppa user/hello_xxx
-# Push previously commited changes
+# Push the commits to your fork
 git push xxx user-fork
 ```
 
@@ -85,20 +109,22 @@ Missing features:
   - [x] Obtain package sources from git
   - [x] Obtain package sources from the archive (fallback)
   - [x] Obtain package source from PPA (--ppa)
-  - [ ] Obtain a specific version of the package
+  - [x] Obtain a specific version of the package
   - [x] Fetch the correct git branch for series on Ubuntu
   - [ ] Try to fetch the correct git branch for series on Debian, or fallback to the archive
 - [ ] `pkh chlog`
   - [x] Auto-generate changelog entry
   - [x] Extra flags: backport, non-maintainer upload, no change rebuild, ...
   - [ ] Commit changelog entry
+- [x] `pkh new`
+  - [x] Scaffold a new Debian source package (interactive, multiple languages)
 - [ ] `pkh build`
   - [x] Build the source package
 - [ ] `pkh deb`
   - [x] Build the binary package
   - [x] Build for a specific architecture
   - [ ] Three build modes:
-    - [ ] Build locally (discouraged)
+    - [x] Build locally (discouraged)
     - [x] Build using unshare chroot, with binary emulation (default)
     - [x] Cross-compilation
   - [ ] Async build
@@ -109,8 +135,10 @@ Missing features:
   - [ ] Upload the source package to the archive
 - [ ] `pkh commit`
   - [ ] Commit the changes to git
-- [ ] `pkh lint`
-  - [ ] Lint the package
+- [x] `pkh lint`
+  - [x] Lint the package
+- [x] `pkh prune`
+  - [x] Prune residual pkh build artifacts and caches
 - [ ] `pkh test`
   - [ ] Run autopkgtest
   - [ ] Provide options: local (discouraged), chroot, VM?, ppa