From 19c09e8bc30a238ee5b12fe8d3336bc8af697e15 Mon Sep 17 00:00:00 2001
From: Eberhard Beilharz <eb1@sil.org>
Date: Wed, 15 Oct 2025 11:50:25 +0200
Subject: [PATCH] docs(linux): update packaging documentation

---
 docs/linux/packaging.md | 128 +++++++++++++++++++++++++---------------
 1 file changed, 80 insertions(+), 48 deletions(-)

diff --git a/docs/linux/packaging.md b/docs/linux/packaging.md
index 8e97f8e303..dc62cd5af7 100644
--- a/docs/linux/packaging.md
+++ b/docs/linux/packaging.md
@@ -8,8 +8,8 @@ We use different channels to build and distribute the Linux packages:
 - Launchpad repo for [stable](https://launchpad.net/~keymanapp/+archive/ubuntu/keyman),
   [beta](https://launchpad.net/~keymanapp/+archive/ubuntu/keyman-beta) and
   [alpha](https://launchpad.net/~keymanapp/+archive/ubuntu/keyman-alpha) versions
-- [pso](http://packages.sil.org/) and [llso](http://linux.lsdev.sil.org/ubuntu/)
-  for stable, beta, and alpha versions
+- [pso](http://packages.sil.org/) for stable versions
+- [llso](http://linux.lsdev.sil.org/ubuntu/) for stable, beta, and alpha versions
 - artifacts on [GitHub](https://github.com/keymanapp/keyman/actions/workflows/deb-packaging.yml)
   for pull requests
 
@@ -18,6 +18,84 @@ intended as a staging environment for testing. Packages on [pso](http://packages
 are uploaded manually after the packages received some testing. End users usually have only
 pso enabled.
 
+## Building packages locally
+
+It is possible to build packages locally. This can be done either directly on the machine,
+or in a Docker container which is more similar to the CI environment.
+
+### Building packages locally directly on the machine
+
+To build packages locally, you'll have to have the dependencies installed.
+
+The easiest way to achieve this is to use the `mk-build-deps` tool:
+
+```bash
+sudo apt install dh-python python3-all debhelper help2man devscripts \
+  equivs jq quilt
+sudo mk-build-deps --install linux/debian/control
+```
+
+Then you can build the Debian package with:
+
+```bash
+KEYMAN_TIER=$(cat TIER.md)
+export KEYMAN_TIER
+cd linux
+./scripts/deb-packaging.sh source
+mkdir -p make_deb
+cd make_deb
+dpkg-source --extract ../../keyman_*.dsc
+cd keyman-*
+dch -v$(cat VERSION.md)-1 ""
+debuild -us -uc
+```
+
+### Local package builds with Docker
+
+It is possible to use the usual Debian/Ubuntu tools to create the package locally.
+For someone who only occasionally deals with packaging it might be easier to use
+Docker and the scripts that run on GitHub actions:
+
+#### Prerequisites for local package builds with Docker
+
+You'll have to create the docker image.
+
+- clone [gha-ubuntu-packaging](https://github.com/sillsdev/gha-ubuntu-packaging)
+  repo
+- create the image:
+
+  ```bash
+  cd /path/to/gha-ubuntu-packaging
+  docker build --build-arg DIST=jammy --build-arg PLATFORM=amd64 -t sillsdev/jammy .
+  ```
+
+#### Building packages with Docker
+
+- create the source package
+
+  ```bash
+  cd $KEYMAN_ROOT
+  KEYMAN_TIER=$(cat TIER.md)
+  export KEYMAN_TIER
+  cd linux
+  ./scripts/deb-packaging.sh source
+  ```
+
+  This will create the source package in $KEYMAN_ROOT directory.
+
+- Create the binary packages with Docker:
+
+  ```bash
+  cd $KEYMAN_ROOT
+  DIST=jammy
+  docker run -v $(pwd):/source -i -t -w /source --platform=amd64 \
+    --env INPUT_DIST=$DIST --env INPUT_SOURCE_DIR=. \
+    --env INPUT_SOURCEPACKAGE=$(ls keyman_*.dsc | sort | tail -1) \
+    sillsdev/$DIST
+  ```
+
+  This will create the binary packages in `$KEYMAN_ROOT/artifacts`.
+
 ## Package builds
 
 Package builds happen on [Launchpad](#package-builds-on-launchpad) and
@@ -73,52 +151,6 @@ and of course the source code for the packages:
   to the main section `jammy`)
 - if the build is successful the job archives the artifacts
 
-### Local package builds with Docker
-
-It is possible to use the usual Debian/Ubuntu tools to create the package locally.
-For someone who only occasionally deals with packaging it might be easier to use
-Docker and the scripts that run on GitHub actions:
-
-#### Prerequisites for local package builds with Docker
-
-You'll have to create the docker image.
-
-- clone [gha-ubuntu-packaging](https://github.com/sillsdev/gha-ubuntu-packaging)
-  repo
-- create the image:
-
-  ```bash
-  cd /path/to/gha-ubuntu-packaging
-  docker build --build-arg DIST=jammy --build-arg PLATFORM=amd64 -t sillsdev/jammy .
-  ```
-
-#### Building packages with Docker
-
-- create the source package
-
-  ```bash
-  cd $KEYMAN_ROOT
-  KEYMAN_TIER=$(cat TIER.md)
-  export KEYMAN_TIER
-  cd linux
-  ./scripts/deb-packaging.sh source
-  ```
-
-  This will create the source package in $KEYMAN_ROOT directory.
-
-- Create the binary packages with Docker:
-
-  ```bash
-  cd $KEYMAN_ROOT
-  DIST=jammy
-  docker run -v $(pwd):/source -i -t -w /source --platform=amd64 \
-    --env INPUT_DIST=$DIST --env INPUT_SOURCE_DIR=. \
-    --env INPUT_SOURCEPACKAGE=$(ls keyman_*.dsc | sort | tail -1) \
-    sillsdev/$DIST
-  ```
-
-  This will create the binary packages in `$KEYMAN_ROOT/artifacts`.
-
 ## Package builds on Launchpad
 
 Package builds on Launchpad are triggered manually by running the Keyman script