1 files changed, 149 insertions, 0 deletions
diff --git a/WORKFLOW.org b/WORKFLOW.org
new file mode 100644
index 0000000..95fdb25
--- /dev/null
+++ b/WORKFLOW.org
@@ -0,0 +1,149 @@
+#+title: Workflow
+#+author: cashmere
+
+* Overview
+
+This repository contains custom FreeBSD ports. The goal is to build and test them in an isolated jail using the standard FreeBSD tooling rather than ad-hoc =make DISTFILES=...= invocations.
+
+* Tool choice: poudriere
+
+After comparing the common FreeBSD port building tools:
+
+- *poudriere* :: The standard tool for building and testing ports in isolated jails. Supports ZFS, overlays, reproducible bulk builds, and =testport= for individual ports. Best fit for this workflow.
+- *synth* :: A lighter alternative, but less commonly used for custom port trees and lacks the overlay/jail flexibility of poudriere.
+- *portmaster* / plain =make= :: Good for installing packages on a live system, but do not provide isolated build environments, so they do not solve the "rebuild everything from source" problem.
+
+* Layout
+
+#+begin_example
+~/ports
+├── devel/
+│   ├── bash-language-server/
+│   ├── just-lsp/
+│   ├── nixd/
+│   ├── py-rassumfrassum/
+│   ├── pyrefly/
+│   └── yaml-language-server/
+├── distfiles/          # shared distfiles cache
+├── misc/
+│   └── kimi-code/
+├── security/
+│   └── pinentry-emacs/
+├── WORKFLOW.org        # this file
+└── .agent-shell/
+    └── poudriere.conf  # reference config
+#+end_example
+
+Each category directory (=devel/=, =security/=, etc.) mirrors the top-level layout of the official Ports Collection.
+
+* Setup instructions
+
+** 1. Install poudriere
+
+#+begin_src sh
+doas pkg install -y poudriere
+#+end_src
+
+** 2. Configure poudriere
+
+#+begin_src sh
+doas cp ~/ports/.agent-shell/poudriere.conf /usr/local/etc/poudriere.conf
+#+end_src
+
+Key settings:
+- =ZPOOL=zroot= :: reuse the existing ZFS pool.
+- =DISTFILES_CACHE=/home/cashmere/ports/distfiles= :: share the distfiles
+  already collected in this repo.
+- =PACKAGE_FETCH_BRANCH=quarterly= and =PACKAGE_FETCH_URL=pkg+https://pkg.FreeBSD.org/FreeBSD:15:amd64= ::
+  tell poudriere to fetch official binary packages for dependencies instead of
+  compiling everything from source.
+
+Important: the official ports tree (=/usr/ports=) must be kept on the same
+quarterly branch as the binary repository. See step 4 below.
+
+** 3. Create a build jail
+
+Use a jail matching the host version (15.1-RELEASE at the time of writing):
+
+#+begin_src sh
+doas poudriere jail -c -j 151amd64 -v 15.1-RELEASE -a amd64
+#+end_src
+
+** 4. Create a ports tree overlay
+
+The base tree must track the same quarterly branch as the binary package
+repository configured in step 2. For FreeBSD 15.1 amd64 the current quarterly
+branch is =2026Q3=.
+
+#+begin_src sh
+  # Base tree from the official ports collection
+doas poudriere ports -c -p base -m null -M /usr/ports
+  # Overlay pointing at this repository
+doas poudriere ports -c -p custom -m null -M /home/cashmere/ports
+#+end_src
+
+Then tell poudriere to use the overlay:
+
+#+begin_src sh
+doas poudriere ports -u -p base
+doas poudriere ports -u -p custom
+#+end_src
+
+To switch an existing =/usr/ports= checkout to quarterly:
+
+#+begin_src sh
+cd /usr/ports
+git config --global --add safe.directory /usr/ports
+git fetch origin 2026Q3
+git checkout -B 2026Q3 FETCH_HEAD
+#+end_src
+
+After that, update with:
+
+#+begin_src sh
+cd /usr/ports && git pull origin 2026Q3
+#+end_src
+
+* Building a port
+
+The easiest port to validate the workflow is =devel/py-rassumfrassum= (pure Python, small dependency tree). To build and test it in the isolated jail:
+
+#+begin_src sh
+doas poudriere testport -j 151amd64 -p base -O custom -o devel/py-rassumfrassum
+#+end_src
+
+For a bulk build of a list:
+
+#+begin_src sh
+cat > /tmp/pkglist <<'EOF'
+devel/py-rassumfrassum
+EOF
+doas poudriere bulk -j 151amd64 -p base -O custom -f /tmp/pkglist
+#+end_src
+
+Once =py-rassumfrassum= builds cleanly, heavier ports like =devel/pyrefly= can be added to the list. Avoid using =security/pinentry-emacs= as a smoke test — it depends on =editors/emacs=, which pulls in a very large dependency tree (X11, GCC, etc.).
+
+* Validated workflow
+
+The following commands have been executed successfully:
+
+1. First run (populated the empty jail with Python dependencies):
+#+begin_src sh
+doas poudriere testport -j 151amd64 -p base -O custom -o devel/py-rassumfrassum
+#+end_src
+Result: success, build time ~6 seconds.
+
+2. Second run (reproducibility check):
+#+begin_src sh 
+doas poudriere testport -j 151amd64 -p base -O custom -o devel/py-rassumfrassum
+#+end_src
+#+RESULT: success, build time ~3 seconds.
+
+3. Node-based port with binary package prefetching:
+#+begin_src sh
+doas poudriere testport -j 151amd64 -p base -O custom -o devel/bash-language-server
+#+end_src
+#+RESULT: success. All official-tree dependencies (=www/node24=, =devel/cmake-core=,
+=devel/icu=, =dns/c-ares=, etc.) were fetched as binary packages; only
+=devel/bash-language-server= from the custom overlay was built from source.
+