debian maintaining notes

1 files changed, 111 insertions, 0 deletions

diff --git a/software/debian_maint.page b/software/debian_maint.page
new file mode 100644
index 0000000..1e74f34
--- /dev/null
+++ b/software/debian_maint.page
@@ -0,0 +1,111 @@
+---
+format: markdown
+title: Debian Maintainership
+...
+
+## Reference
+
+- [Official Policy Manual]([https://www.debian.org/doc/debian-policy/):
+  basically a style guide for how software should be packaged and how a Debian
+  operating system should work.
+- [Packaging Tutorial](https://www.debian.org/doc/manuals/packaging-tutorial/packaging-tutorial.en.pdf):
+  this was a great getting-started resource for me: what files under `debian/`
+  do what, what automated tooling exists, how packaging has changed over time,
+  etc. "Hands on".
+
+## Developer Machine Setup
+
+Install pacakges:
+
+    sudo apt install build-essential ccache cdbs cowbuilder debhelper \
+        devscripts dgit dh-make distcc fakeroot git-buildpackage lintian \
+        pbuilder quilt sbuild schroot svn-buildpackage wdiff piuparts
+
+I set the following user-wide environment variables:
+
+    QUILT_PATCHES="debian/patches"
+    DH_VERBOSE=1
+    DEB_BUILD_MAINT_OPTIONS="hardening=+all"
+    DEBFULLNAME=""
+    DEBEMAIL=""
+
+Create a `cowbuilder` environment:
+
+    sudo cowbuilder --create            # on new machines
+    sudo cowbuilder --update            # ~regularly
+    sudo cowbuilder --build thing.dsc   # do the build
+
+## Basic Commands
+
+Run from inside source directory, except apt-get commands:
+
+    apt-get source $PKG
+    dch -i      # new debian/changelog entry w/ incremented version
+    dch "some task" # adds line to current changelog entry
+    uscan -v .  # manually check for new package version
+    gbp import-orig --uscan     # import new release via uscan (for gbp-developed packages)
+    lintian -EviIL +pedantic    # after build
+    apt-get build-dep $PKG
+    dpkg-buildpackage -us -uc   # just build a package on local machine (no sign)
+    # OR
+    debuild -us -uc   # same as above + lintian? no color
+    sudo debi         # install locally
+    debdiff pkg_1.0.deb pkg_1.0-1
+    dh_make -f ../something-1.0.tar.gz  # does the renaming to .orig.tar.gz automatically
+    pdebuild --pbuilder cowbuilder
+
+Patching:
+
+    edit-patch
+
+## dgit
+
+`dgit` is complicated! Mostly because it is flexible/powerful, works with a lot
+of packaging workflows, and there is not a clear default workflow of packaging
+in general or with `dgit`.
+
+In particular dgit is mostly just about interfacing with debian project
+infrastructure, not storing packaging info in git format. There are multiple
+tools/workflows for the later (git-buildpackage ("gpb"), git-dpm, etc).
+
+## Debian Helper (`dh`)
+
+To override individual built targets, just define them in `debian/rules`.
+
+Starting from scratch, when you have tarballs:
+
+1. `mkdir` and `git init` an empty repo
+2. `gbp import-orig --pristine-tar <tarball>`. You can filter files out here if
+   you need to, eg for policy/copyright reasons.
+3. `dh_make -p $PKG_$VERSION` to start with defaults.
+
+## Other Tasks
+
+Mentors uploads (see [intro](https://mentors.debian.net/intro-maintainers)):
+
+- setup a `~/.dput.cf`
+- create a webface account
+- upload with: `dput mentors SOMETHING.changes`
+
+`pbuilder` for cross-platform/cross-arch builds (eg, armel, mips):
+
+    # setup ~/.pbuilderrc:
+    #  https://jodal.no/2015/03/08/building-arm-debs-with-pbuilder/
+    sudo apt install qemu-user-static
+    sudo OS=debian DIST=stretch ARCH=armel pbuilder --create
+
+then, each test build (slow!):
+
+    sudo OS=debian DIST=stretch ARCH=armel pdebuild
+
+Running piuparts is simple (but slow):
+
+    sudo piuparts <pkg>.deb
+
+Create a quick blank debug docker (faster than most other tools for creating
+throw-away environments):
+
+    docker pull debian:sid
+    docker run -t -i debian:sid bash
+    # In container:
+    apt update