# 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