From 88313b0c51eb508ace33c181397fb24d321f17e9 Mon Sep 17 00:00:00 2001
From: Valentin Haudiquet <valentin.haudiquet@canonical.com>
Date: Wed, 17 Dec 2025 16:49:16 +0100
Subject: [PATCH] readme: added README.md

---
 README.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..220cbf1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,129 @@
+# pkh
+
+`pkh` is a packaging helper for Debian/Ubuntu packages.
+
+## Usage and features
+
+### Basic concepts
+
+`pkh` aims at wrapping the different debian tools and workflows 
+(`git`, `git-ubuntu`, `pull-debian-sources`, `pull-lp-sources`, `pull-ppa-sources`,
+`dch`, `dpkg-buildpackage`, `sbuild`, `dpkg-source`, `quilt`, ...) into one tool, that
+would have the same interface for everything, while being smarter at integrating all workflows.
+
+Thus, `pkh` uses similar options for all subcommands (with very few command-specific options):
+```
+Options:
+  -s, --series <series>    Target package distribution series
+  -d, --dist <dist>        Target package distribution (debian, ubuntu)
+  -v, --version <version>  Target package version
+  -a, --arch <arch>        Target architecture (amd64, arm64, riscv64, ...)
+      --ppa <ppa>          Do the action in/for a specific PPA
+```
+
+Commands and workflows include:
+```
+Commands:
+  pull    Get a source package from the archive or git
+  chlog  Auto-generate changelog entry, editing it, committing it afterwards
+  help   Print this message or the help of the given subcommand(s)
+```
+
+### Examples
+
+A typical workflow to patch an Ubuntu package `hello` on the development release could be:
+```
+# Obtain the package source
+git ubuntu clone hello
+cd hello
+# Apply the patch to the package
+...
+dpkg-source --commit
+# Increment version number
+dch
+# Test that the patch builds
+git ubuntu export-orig
+dpkg-buildpackage -S -I -i -nc -d
+sbuild --dist resolute --arch amd64 ../hello_xxx.dsc
+# Upload the package to a ppa
+dput ppa:user/hello_xxx ../hello_xxx_source.changes
+# Commit the changes to git
+git add debian/patches/xxx.patch
+git commit -m "Applied patch xxx"
+git add debian/changelog
+git commit -m "changelog"
+git checkout -b xxx
+git push xxx user-fork
+```
+
+That is a lot of different tools and operations. With pkh, the same workflow:
+```
+# Obtain the package source (and orig tarball)
+pkh pull hello # needs -d ubuntu if you are not running Ubuntu
+# Apply the patch to the package
+...
+pkh 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
+git push xxx user-fork
+```
+
+## Roadmap: features needed for 1.0
+
+Basically, wrapping the basic debian workflows.
+Missing features:
+- [ ] `pkh pull`
+  - [x] Obtain package sources from git
+  - [x] Obtain package sources from the archive (fallback)
+  - [ ] Obtain package source from PPA (--ppa)
+  - [ ] 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
+  - [ ] Extra flags: backport, non-maintainer upload, no change rebuild, ...
+  - [ ] Commit changelog entry
+- [ ] `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 using sbuild+unshare, with binary emulation (default)
+    - [ ] Cross-compilation
+  - [ ] Async build
+- [ ] `pkh status`
+  - [ ] Show build status
+- [ ] `pkh put`
+  - [ ] Upload the source package to a PPA
+  - [ ] Upload the source package to the archive
+- [ ] `pkh commit`
+  - [ ] Commit the changes to git
+- [ ] `pkh lint`
+  - [ ] Lint the package
+- [ ] `pkh test`
+  - [ ] Run autopkgtest
+  - [ ] Provide options: local (discouraged), sbuild/VM?, ppa
+  - [ ] Async test
+
+## Nice-to-have features
+
+- [ ] 'pkh pull'
+  - [ ] Cache the Sources.gz files, to improve speed
+  - [ ] Work in an already downloaded package, to git pull and re-fetch orig tar gz
+- [ ] 'pkh context'
+  - [x] Select, add, remove, list contexts
+  - [x] Context-scoped command execution
+  - [ ] Context-scoped deb and test commands
+  - [ ] Per-architecture contexts
+  - [ ] Per-series contexts
+  - [x] ssh contexts
+  - [ ] docker, lxc contexts?
+  - [ ] context push, context pop: context stack
+