breadpad/CONTRIBUTING.md

Contributing

breadpad — Quick-capture scratchpad and note viewer (breadman) with AI classification.

Part of the bread ecosystem; this repo follows the same branch/release workflow as every other ecosystem product.

Branches

There is one long-lived branch: main. All day-to-day work lands here. Every push to main automatically builds and publishes a dev-track build (see Tracks below) — a real install you can test before cutting anything more formal.

New work — features and bug fixes alike — goes on a short-lived branch:

feature/<short-name>
fix/<issue-number-or-short-name>

Branch off main, open a PR/push back into main when ready. Short-lived branches get deleted on merge — they never accumulate the kind of drift a second long-lived branch does.

The release cycle

There's no separate beta or release branch — "stable" and "beta" are both just tags on main, not branches that need to be kept in sync:

1. Work accumulates on main via feature/x / fix/x branches. Each push auto-publishes a dev build — install it with bakery track set dev and bakery update --all, then fix anything broken with another push.
2. When you want to stabilize before a real release, tag a release candidate: git tag vX.Y.Z-rc.1 && git push origin vX.Y.Z-rc.1 (push to both remotes). That tag alone triggers a beta-track build — "freezing" is just pausing pushes to main while you test it, not a branch operation. Cut -rc.2, -rc.3, etc. for further fixes.
3. Once an RC has gone without issues, tag the real release: git tag vX.Y.Z && git push origin vX.Y.Z — that's what triggers the signed stable release build.

Tracks, from a user's perspective

bakery track show              # what you're currently on (defaults to stable)
bakery track set dev           # or beta, or stable
bakery update --all            # pull the latest build on your current track

Track	What it is	Published from
stable	The last tagged release	a vX.Y.Z tag
beta	Latest release candidate	a vX.Y.Z-rc.N tag
dev	Bleeding edge	main, on every push

Dev versions are auto-computed (X.Y.Z-dev.<timestamp>+<sha>) from the latest published stable tag, so they always sort as newer than what you have installed — no manual version bumping needed. Beta versions are just the RC tag itself (already valid semver, already sorts below the real release it's a candidate for).

Local development

cargo build --release --workspace
cargo test --release --workspace

CI

• check.yml — clippy + test, triggered on push to feature/**/fix/**. Fast-fail before anything reaches main.
• dev-release.yml — triggered on push to main.
• rc-release.yml — triggered on any vX.Y.Z-rc.N tag push.
• release.yml — triggered on any other v* tag push, cuts the actual stable release.

All of these build inside a pinned Arch Linux container on a self-hosted runner — not the runner host's native environment. Arch's repos carry current gtk4/libadwaita/gtk4-layer-shell as prebuilt packages, so there's no from-source library build to go stale. The Containerfile and build script are shared across bread-ecosystem GTK4 products, living in bread-ecosystem/ci/; ci/build.sh here is a thin wrapper that clones that repo at the commit pinned in ci/bread-ecosystem.rev (not main — an unrelated change there shouldn't silently affect this repo's release builds) and delegates to it. Bump the pin deliberately when you want the shared image or build logic updated. A ci/deps.txt here (currently absent — breadpad needs nothing beyond the shared base) would layer on extra pacman packages if that ever changes. Nothing runs automatically on plain commits or PRs beyond the jobs listed above. See bread-ecosystem's docs/release-channels.md for the full policy, including how a new product gets wired onto these tracks.

Questions

Open an issue on this repo's Forgejo tracker.