How work gets planned and shipped

The engineering view of both work streams: how a feature request becomes a GitHub issue, how a bug is triaged, and what has to be true before either is done.

PatchMon takes work from two places and handles them differently. Bugs live in GitHub Issues. Feature requests live on this portal. This page is the contributor's view of what happens to each, and where the two meet.

The short version: this portal holds the customer-facing state of a feature request, GitHub holds the engineering state, and a person moves information between them. There is no integration doing it automatically, so the links between the two are what stop things getting lost.

A feature request, end to end

Portal request (Open)
      |
      v   reviewed in a batch, after it has had time to gather votes
  Under Review
      |
      +--> Declined, always with a reason
      +--> Deferred, revisited later
      |
      v
  Accepted            reaches the public roadmap, carries no date
      |
      v   a maintainer opens a GitHub issue and links it both ways
  Planned
      |
      v   work starts, branch opens
  In Progress
      |
      v   pull request merges, "Closes #N" closes the GitHub issue
  In Progress         still, because merged is not released
      |
      v   release published
  Completed           with a link to the changelog entry

Three points on that path are a person doing something by hand:

At review. A maintainer opens the GitHub issue, puts the request's URL in the issue body, and comments the issue link back on the request.
When work starts. The request moves to In Progress.
At release. Everything that shipped moves to Completed and gets the changelog link.

The third one is batched into the release procedure rather than done per pull request, which is why it holds together without automation.

Comments do not sync in either direction. If you want engineering detail, follow the linked GitHub issue. Comments left here are read, but they do not appear on GitHub, and vice versa.

A bug, end to end

GitHub issue, Bug Report template
      |
      v   triage
  Issue type: Bug
  Priority:   Urgent / High / Medium / Low
  Effort:     High / Medium / Low
  Start date and Target date, if it is being scheduled
  Labelled good first issue or help wanted where it suits
      |
      v
  Branch, then a pull request referencing "Fixes #N"
      |
      v   checks green, review, merge
  GitHub closes the issue itself
      |
      v   release published
  Listed in the release notes, and in the changelog on this portal

Bugs never touch this portal, so there is no status here to keep in step. That is why the bug path has one manual step and the feature path has three.

The triage fields

Priority and Effort are repository issue fields on PatchMon/PatchMon rather than project board fields, so you can read them directly on the issue.

Field	Values	What it means
Priority	Urgent, High, Medium, Low	How soon it gets attention. Urgent bypasses the queue and can go out in a patch release on its own.
Effort	High, Medium, Low	Rough size. Three buckets only, deliberately, so nobody spends time arguing between a 3 and a 5.
Start date	date	Set when work is expected to begin.
Target date	date	Set when a fix is aimed at a particular release.

They are set at triage and kept current on issues that are actually scheduled. An untriaged issue carries needs-triage and may have neither.

If you are looking for something to pick up, low Effort with a help wanted or good first issue label is the place to start.

Why Completed waits for the release

A request marked Completed sends people looking for the feature in the version they are running. If that flipped when the pull request merged, it would be true for the repository and false for everyone who installs releases.

So merged work stays In Progress until the release that carries it is published. It costs nothing and it means Completed always means "you can have it".

The links that hold it together

Nothing syncs, so the chain of references is what makes the release-day sweep a two minute job rather than an excavation:

the request URL goes in the GitHub issue body
the issue number goes in the pull request, via Fixes #N
the pull request appears in the release notes
the release notes become the changelog entry

If you are opening a pull request against a tracked issue, the Fixes #N line is the part you own.

What "done" means

Before a change is merged:

make check passes in server-source-code and in agent-source-code, covering formatting, go vet, golangci-lint and tests
npx biome check src/ is clean for any frontend change
database migrations have both an .up.sql and a .down.sql
user-facing behaviour changes carry their documentation update in the same pull request
every check on the pull request is green, see What happens when you open a pull request
a maintainer has reviewed it

Labels you will see

Label	Meaning
`needs-triage`	Not yet reviewed by a maintainer.
`needs-accepted-request`	Feature pull request with no accepted request on this portal. Not merged, and not closed either.
`deferred-stability-phase`	Parked while we focus on stability. Will be revisited, not rejected.
`moved-to-feedback`	Imported to this portal, tracked here from now on.
`approved-for-build`	A maintainer has approved the Docker image build for a fork pull request.
`documentation`	Documentation only.

Edge paths

Situation	What happens
You post a bug on this portal	A maintainer opens the GitHub issue, comments the link on your post, and resolves the post. It is not tracked in both places.
You raise a feature as a GitHub issue	A maintainer labels it `enhancement`, moves it to this portal, comments the link, and closes the issue. Nothing you wrote is lost.
Feature pull request with no accepted request	Labelled `needs-accepted-request` and left open while the request goes through review.
A feature during the stability phase	Labelled `deferred-stability-phase`. That is scheduling, not rejection.
Two requests describing the same thing	Merged on the portal. Votes and comments combine, so nobody has to re-vote.
An urgent regression	Priority Urgent skips the queue. The review batch is not a hard gate.

Our current focus: stability

The next few release cycles prioritise stability over new features. Feature pull requests raised during this period may be labelled deferred-stability-phase and picked up later.

That is a scheduling decision, not a judgement on the change.