diff --git a/data/skill/SKILL.md b/data/skill/SKILL.md new file mode 100644 index 0000000..54030c3 --- /dev/null +++ b/data/skill/SKILL.md @@ -0,0 +1,130 @@ +--- +name: pkh +description: 'Drive pkh, a Debian/Ubuntu packaging helper: pull source packages, generate changelog entries, build .dsc/.deb, lint, and upload to a PPA. Use it whenever the task touches Debian or Ubuntu packaging: patching an existing package, preparing an SRU, backport or NMU, scaffolding a new .deb, rebuilding for a PPA, or uploading a source package. Trigger on "update the changelog", "package this", or a bare package name, even when the user never mentions Debian.' +--- + +# pkh + +`pkh` wraps the Debian packaging toolchain (`dch`, `dpkg-buildpackage`, +`sbuild`, `dpkg-source`, `quilt`, `lintian`, PPA uploads) in one CLI. +The subcommands share one set of option names, so `-s` always targets +the series and `--ppa` always names the PPA. Each step also does more +than the raw tool it replaces: `pull` fetches the orig tarball with the +source, `chlog` commits the entry it writes, `deb` sets up a chroot and +installs the build dependencies. + +Check the install with `pkh --version`. Each command lists its flags +with `pkh --help`, so check there instead of guessing. pkh +shells out to host tools (git, dpkg-dev, quilt, mmdebstrap, lintian, +pristine-tar, schroot, ...). Install the ones your workflow uses, or +use the classic snap, which carries them. + +## Shared options + +| Option | Meaning | +|---|---| +| `-d, --dist ` | Target distribution, `debian` or `ubuntu` | +| `-s, --series ` | Target series, for example `resolute` or `noble` | +| `-v, --version ` | Target package version | +| `-a, --arch ` | Target architecture, for example `amd64` or `riscv64` | +| `-p, --pocket ` | Distribution pocket: `updates`, `security`, `proposed` | +| `--ppa ` | Act on the named PPA | + +Defaults come from the host vendor, its development series, and its +architecture. When the target differs, pass the flags: packaging for +Ubuntu on a Debian host needs `-d ubuntu`, and a series or architecture +that differs from the host needs `-s` or `-a`. + +## Patch an Ubuntu package + +``` +pkh pull hello # source and orig tarball; add -d ubuntu off an Ubuntu host +# edit the package, committing each patch to git +pkh chlog # generates the entry, opens it for editing, commits it +git add debian/changelog && git commit -m "d/changelog" +pkh build # source package, written next to the tree +pkh deb # binary build in a chroot with build deps installed +pkh lint # lintian plus pkh-native checks +pkh put --ppa user/hello_xxx # uploads the .changes file from the build +git push xxx user-fork # push the branch to your fork +``` + +Run `pkh chlog` and `pkh build` from the root of the source tree; they +act on the package in the current directory. + +## Command reference + +- `pkh new [name]` scaffolds a buildable source package. `--lang` + picks the build system (`rust`, `python`, `meson`, `cmake`, + `autotools`, `go`, `shell`, `makefile`); `--source ` packages + existing sources instead. `--upstream-version` and `--revision` set + the version. `--description`, `--homepage`, `--license `, + `--command`, `--maintainer "Name "`, and `--depends` fill in + the package metadata, with the maintainer defaulting to + `DEBFULLNAME`/`DEBEMAIL` and then git config. `--quilt` and + `--native` choose the source format; `--orig-from + release|git|path|snapshot` and `--orig-path` control the orig + tarball. The changelog starts as `UNRELEASED`; `--release` targets + `--series` instead. `--defaults` answers every remaining question + with its default, which keeps the run non-interactive. + +- `pkh pull ` fetches a source package from the archive or + git. `--archive` skips git. `--ppa user/ppa` and `--repository + ` pull from a PPA or an external flat repository instead. + `-d`, `-s`, `-v`, and `-p` target an exact source. + +- `pkh chlog` generates the changelog entry from the commits since the + last version tag, opens it for editing, and commits it. `--backport`, + `--nmu`, and `--rebuild` apply the matching numbering scheme + (`3.1-1ubuntu2~24.04.1`, `1.0-1.1`, `1.0-1build1`); `-v` sets an + explicit version instead. + +- `pkh build` produces the .dsc. `--orig auto|always|never` controls + whether the upload includes the orig tarball; the default, `auto`, + includes it only when the upstream version changed. + +- `pkh deb` builds the binary packages in an isolated context with the + build dependencies installed. `--ppa` (repeatable) adds dependency + sources, `--inject ` preinstalls a package, and `-j` + caps parallel jobs. `--cross` cross-compiles instead of using + qemu-binfmt, but most packages cannot cross-compile, so prefer qemu. + Leave `--mode` unset unless you need a specific build context. + +- `pkh lint [path]` runs lintian plus the pkh-native checks. `--json` + emits a machine-readable report and `--list-tags` prints the native + tag catalog. `--fail-on` sets the severities that fail the run + (errors by default), `--suppress-tags` ignores tags, `--check` runs a + single native check, and `--info`, `--pedantic`, and + `--experimental` add detail. `--repack` packs the tree fresh instead + of reusing the existing build output. + +- `pkh put [changes]` uploads a .changes file to `--ppa user/ppa`. + With no argument it uploads the .changes from this package's last + build, found next to the source tree. `--force` re-uploads a file + that was already uploaded. + +- `pkh prune` removes build artifacts and caches. Run it with + `--dry-run` first to list them. `--all` also deletes the cached + chroot tarballs, which take long to download again, so use it when + you need the disk space. + +## Notes for agent runs + +- Pass `-d`, `-s`, and `-a` whenever the target differs from the host, + so runs are reproducible. +- Keep runs non-interactive. Pass explicit flags, use `pkh new + --defaults`, and set `EDITOR` before `pkh chlog` (`EDITOR=true` keeps + the generated text). Commands may ask short questions on the + terminal; flags avoid most prompts. +- Pass `RUST_LOG=debug` for pkh's own logs. `--verbose` on `pkh build` + and `pkh deb` prints raw tool output instead of the live view. +- pkh writes the build artifacts (.dsc, .changes, logs) next to the + source tree. `pkh put` finds them without arguments, and `pkh prune` + removes them again. +- Run `pkh lint` before `pkh put`. It exits nonzero when findings reach + the `--fail-on` level, which defaults to errors. +- pkh intercepts Ctrl+C, runs its cleanup hooks, and exits with status + 130. `pkh prune` removes anything left over. + +The upstream repository is https://git.vhaudiquet.fr/vhaudiquet/pkh. +Its README has longer workflow examples.