profilarr/docs/DEVELOPMENT.md

Development

This guide covers the branching model, release process, and versioning. For how to submit changes, see CONTRIBUTING.md.

• Development Model
  • Feature Branches
  • Develop
  • Stable
    • Hotfixes
• Versioning
• Examples
  • Adding a settings page
  • Bug found during testing
  • Fast patch release
  • Hotfix while mid-feature
  • Multiple features in progress
• Reference

Development Model

Changes flow through three stages:

• Feature branches: where work gets built
• develop (:develop): where work gets tested
• Stable (:latest): where work gets released

feature branches → develop (:develop) → tagged release (:latest)

Feature Branches

All new work happens on feature branches created off develop. There can be multiple in progress at once, both internal and community contributions. Each branch is independent and gets deleted after merging.

When a feature branch is ready, it gets squash merged into develop for testing. Squash merging collapses all the commits on the branch into a single commit on develop. This keeps develop's history clean: one feature, one commit, regardless of how many "wip" or "fix typo" commits happened on the branch. The squashed commit message is the PR title, so develop reads as a list of conventional commit entries.

The maintainer decides which branches go in and when; if there's contention, it's discussed with testers. Smaller batches are preferred to avoid overloading beta testers and to keep the gap between :develop and :latest short.

Develop

develop is the default branch, but it's not where day-to-day work happens. It's the testing branch: it always contains the next release being evaluated by beta testers. Every push to develop builds the :develop Docker image.

:develop is not guaranteed to be stable. Expect untested features and minor issues. It won't have major breaking changes, but things may not work perfectly. Don't run it on a setup you depend on.

Nothing is committed directly to develop. Bug fixes found during testing go through the same feature branch → PR → squash merge flow as everything else. This ensures all changes run through CI before landing. Active feature branches rebase onto develop to pick up these fixes.

Before merging anything into a free develop, define the next release batch: target version, included PRs, whether it needs a soak, and what kind of fixes are allowed while it soaks. Use a local .release-plan.md scratch file if useful; it's ignored by git so the plan can change without repo churn.

Once the batch is assembled, treat develop as that release candidate. Don't add unrelated work during the soak; it either fixes the current batch or waits for the next one. Small, low-risk bug fixes may be added if they are easy to verify and don't change the release risk profile.

Stable

What a release needs depends on what's in it. Automated tests must pass either way.

If the batch contains anything that needs other people to verify it (a new feature, anything risky, or anything the author can't confidently confirm alone), it soaks on develop until the maintainer is satisfied it's ready.

If the batch is entirely small, low-risk changes the author can verify themselves (most bug fixes, docs, dependency bumps, minor tweaks), it can be tagged as soon as CI passes; no soak needed.

This is the same bar as a hotfix, pointed forward: if you can confidently verify it yourself, it doesn't need the beta cycle. Once the criteria are met, develop gets tagged (e.g. v2.3.0) which builds the :latest and :v2.3.0 Docker images.

The soak applies to the batch as a whole. Once a batch is being soaked, don't tack new untested work onto it; that resets the testing clock. New features wait for the next batch.

Then the cycle repeats: the next batch of complete feature branches is merged into develop for testing.

Release Communication

When a minor or major release starts soaking on develop, two things happen:

1. Bulletin announcement: publish an announcement via the bulletin repo targeting the current stable version range. This reaches every running instance and lets users know a new release is available for testing on :develop.

2. GitHub Discussion: open a discussion in the profilarr repo summarizing what's in the batch, what to watch for, and where to report issues. Link this discussion from the announcement's link field so users go straight from the inbox to the feedback thread.

Both go out once :develop has rebuilt with the full batch merged. Don't announce a planned release before there's something to test.

Patch releases that skip the soak (bug fixes, deps, docs) don't need either. They're tagged as soon as CI passes and show up in the normal release notes.

Hotfixes

If a core feature is broken in a stable release and it can't wait for the next minor version, a hotfix is applied against the stable tag. The bar for this is high; a core feature must be broken, not a cosmetic issue or minor annoyance. Small issues wait for the next minor release.

develop:  A — B — C — D — E — F — G  (HEAD, testing v2.3.0)
                      ↑
                  v2.2.0 (broken)

# Branch from the stable tag
git checkout -b hotfix/v2.2.0-sync-crash v2.2.0

# Fix the bug, verify locally
git commit -m "fix: crash when syncing empty profiles"

# Tag the patch release
git tag v2.2.1
git push origin hotfix/v2.2.0-sync-crash --tags

This builds :latest from the fix without including any untested work. The maintainer tests the fix locally before tagging; hotfixes don't go through the full beta testing cycle. If the fix isn't something you can confidently verify yourself, it's not a hotfix.

Then the fix is brought into develop:

git checkout develop
git cherry-pick <commit-hash>
# If the cherry-pick conflicts, resolve and continue:
#   git add <resolved-file>
#   git cherry-pick --continue
git push

# Clean up
git branch -d hotfix/v2.2.0-sync-crash

Versioning

Version bumps are scoped to what the user achieves, not what the developer changed. Define each feature by its atomic goal: the smallest user-facing unit with a describable purpose. Version against that goal, not against the size of the diff or whether the code is "new."

Patch: the goal stays the same; the how changes.

A number input's goal is "increase and decrease an integer." Adding hold-to-change with an acceleration curve is a patch. The user still increases and decreases an integer; the interaction just got smoother. New code, new behavior, but same atomic plane.

Minor: the goal expands.

That same number input gains float support. The user can now do something they couldn't before: work with decimal values. The atomic plane grew, even if the code diff is small.

Major: the product-level contract breaks.

The PCD format changes and existing databases can't be read without migration. The Docker volume layout changes and existing mounts break on upgrade. An entire workflow gets removed that users built around. Major means the user's existing setup stops working or requires manual intervention to continue. This is about the application's contract with its users, not individual components.

A release batch takes the version of its highest-impact change. If any change in the batch is a minor, the release is a minor. If every change is a patch, the release is a patch.

Examples

Adding a settings page

You want to add a settings page. There's nothing currently being tested on develop; the last release was tagged.

# Start your feature branch
git checkout develop
git pull
git checkout -b feat/settings-page

You work on it over a few days. Commits don't matter much since they'll be squashed:

git commit -m "wip: settings page layout"
git commit -m "feat: wire up settings form"
git commit -m "fix: form validation"
git push origin feat/settings-page

It's ready. You open a PR on GitHub targeting develop. The PR title is your commit message:

feat: add settings page

You squash merge the PR. develop now has one clean commit: feat: add settings page. The :develop image rebuilds. Beta testers start testing.

A week goes by with no issues. Automated tests pass. You tag it:

git checkout develop
git pull
git tag v2.4.0
git push --tags

:latest and :v2.4.0 build. Stable users get the update. You delete the feature branch.

Bug found during testing

The settings page feature is on develop. A beta tester reports that saving settings clears the form instead of showing a success message.

Create a fix branch, just like any other change:

git checkout develop
git pull
git checkout -b fix/settings-save-message

Fix the bug, commit, and push:

git commit -m "fix: show success message after saving settings"
git push origin fix/settings-save-message

Open a PR targeting develop with the title fix: show success message after saving settings. CI runs. Once it passes, squash merge the PR. :develop rebuilds. The tester confirms the fix.

No other issues come up. Two testers and the maintainer sign off. You tag it:

git checkout develop
git pull
git tag v2.4.0
git push --tags

The bug fix shipped as part of the minor release. No separate patch needed.

If you have feature branches in progress, they rebase onto develop to pick up the fix:

git checkout feat/notifications
git fetch origin
git rebase origin/develop
git push --force-with-lease

Fast patch release

The last minor (v2.5.0) is tagged. Since then, three small changes have landed on develop: a dropdown clipping fix, a typo in an error message, and a dependency bump. All three are low-risk and easy to verify yourself.

There's no feature in the batch and nothing risky, so it doesn't need a soak. Once CI passes, you tag it:

git checkout develop
git pull
git tag v2.5.1
git push --tags

:latest and :v2.5.1 build. It's a patch because the batch is only fixes. If a feature had landed in the batch it would be a minor, and anything needing verification would soak first.

Hotfix while mid-feature

You're halfway through building a notifications system on feat/notifications. A user reports that syncing crashes on the stable release (v2.4.0). It's a core feature, so it needs a hotfix.

# Stash or commit your in-progress work
git checkout feat/notifications
git commit -m "wip: notification preferences"

# Branch from the stable tag
git checkout -b hotfix/v2.4.0-sync-crash v2.4.0

# Fix the bug, verify locally
git commit -m "fix: crash when syncing empty profiles"

# Tag the patch release
git tag v2.4.1
git push origin hotfix/v2.4.0-sync-crash --tags

:latest rebuilds from the fix. Stable users get v2.4.1.

Now bring the fix into develop and clean up:

git checkout develop
git cherry-pick <commit-hash>
git push
git branch -d hotfix/v2.4.0-sync-crash

Then go back to your feature and rebase to pick up the fix:

git checkout feat/notifications
git fetch origin
git rebase origin/develop
git push --force-with-lease

Your feature branch now includes the sync fix. You continue working where you left off.

Multiple features in progress

The settings page (feat/settings-page) is on develop being tested. While that happens, you finish a notifications system and start working on a dark mode feature.

feat/settings-page    → merged into develop, being tested
feat/notifications    → complete, waiting in queue
feat/dark-mode        → in progress

Testers sign off on the settings page. You tag it:

git checkout develop
git pull
git tag v2.4.0
git push --tags

Now develop is free. The notifications feature is next. You open a PR for feat/notifications targeting develop, rebase first:

git checkout feat/notifications
git fetch origin
git rebase origin/develop
git push --force-with-lease

Squash merge the PR. :develop rebuilds with the notifications feature. Beta testers start testing.

Meanwhile, you keep working on dark mode. When a bug fix lands on develop during notifications testing, you rebase to pick it up:

git checkout feat/dark-mode
git fetch origin
git rebase origin/develop
git push --force-with-lease

When notifications is tagged, dark mode is next in the queue.

Reference

• docs/ARCHITECTURE.md - full codebase encyclopedia (modules, data flow, PCD)
• docs/CONTRIBUTING.md - how to submit changes, guidelines, conventions
• deno task stats - per-module code stats (TS/JS/Svelte/CSS/SQL/C#)