hauler/DEVELOPMENT.md

Development Guide

This document covers how to build hauler locally and how the project's branching strategy works.

It's intended for contributors making code changes or maintainers managing releases.

---

Local Build

Prerequisites

• Git - version control of the repository
• Go — check go.mod for the minimum required version
• Make - optional... for common commands used for builds
• Docker - optional... for container image builds

Clone the Repository

git clone https://github.com/hauler-dev/hauler.git
cd hauler

Build the Binary

Using make...

# run this command from the project root
make build

# the compiled binary will be output to a directory structure and you can run it directly...
./dist/hauler_linux_amd64_v1/hauler
./dist/hauler_linux_arm64_v8.0/hauler
./dist/hauler_darwin_amd64_v1/hauler
./dist/hauler_darwin_arm64_v8.0/hauler
./dist/hauler_windows_amd64_v1/hauler.exe
./dist/hauler_windows_arm64_v8.0/hauler.exe

Using go...

# run this command from the project root
go build -o hauler ./cmd/hauler

# the compiled binary will be output to the project root and you can run it directly...
./hauler version

Run Tests

Using make...

make test

Using go...

go test ./...

Useful Tips

• The --store flag defaults to ./store in the current working directory during local testing, so running ./hauler store add ... from the project root is safe and self-contained. Use rm -rf store in the working directory to clear.
• Set --log-level debug when developing to get verbose output.

---

Branching Strategy

Hauler uses a main-first, release branch model. All development flows through main and release/x.x branches are maintained for each minor version to support patching older release lines in parallel.

Branch Structure

main          ← source of truth, all development targets here
release/1.3   ← 1.3.x patch line
release/1.4   ← 1.4.x patch line

Release tags (v1.4.1, v1.3.2, etc.) are always cut from the corresponding release/X.Y branch, never directly from main.

Where to Target Your Changes

All pull requests should target main by default and maintainers are responsible for cherry picking fixes onto release branches as part of the patch release process.

Change Type	Target branch
New features	main
Bug fixes	main
Security patches	main (expedited backport to affected branches)
Release-specific fix (see below)	release/X.Y directly

Creating a New Release Branch

When main is ready to ship a new minor version, a release branch is cut:

git checkout main
git pull origin main
git checkout -b release/1.4
git push origin release/1.4

The first release is then tagged from that branch:

git tag v1.4.0
git push origin v1.4.0

Development on main immediately continues toward the next minor.

Backporting a Fix to a Release Branch

When a bug fix merged to main also needs to apply to an active release line, cherry-pick the commit onto the release branch and open a PR targeting it:

git checkout release/1.3
git pull origin release/1.3
git checkout -b backport/fix-description-to-1.3
git cherry-pick <commit-sha>
git push origin backport/fix-description-to-1.3

Open a PR targeting release/1.3 and reference the original PR in the description. If the cherry-pick doesn't apply cleanly, resolve conflicts and note them in the PR.

Fixes That Only Apply to an Older Release Line

Sometimes a bug exists in an older release but the relevant code has been removed or significantly changed in main — making a forward-port unnecessary or nonsensical. In these cases, it's acceptable to open a PR directly against the affected release/X.Y branch.

When doing this, the PR description must explain:

• Which versions are affected
• Why the fix does not apply to main or newer release lines (e.g., "this code path was removed in 1.4 when X was refactored")

This keeps the history auditable and prevents future contributors from wondering why the fix never made it forward.

Summary

            ┌─────────────────────────────────────────► main (next minor)
            │
            │  cherry-pick / backport PRs
            │  ─────────────────────────►  release/1.4  (v1.4.0, v1.4.1 ...)
            │
            │  ─────────────────────────►  release/1.3  (v1.3.0, v1.3.1 ...)
            │
            │  direct fix (older-only bug)
            │  ─────────────────────────►  release/1.2  (critical fixes only)