Pull request

A PR is squash merged or rebase merged, never with a merge commit. Squashed, the title becomes the commit subject on main and the release-notes line. Rebased, every commit lands as it is and each subject is a release-notes line. docs/agent/dev.md ("Commits: the subject is the changelog", "Pull requests") holds the rules; this file is the procedure. dev.md wins.

1. Read the branch

git fetch origin
git log --reverse --format='%h %s%n%b' origin/main..HEAD
git diff --stat origin/main...HEAD

Read the diff wherever a subject does not state the user-visible change. Report a non-empty HEAD..origin/main as "branch is behind". Do not rebase unasked.

2. Squash or rebase

Count the entries a release-notes reader sees: commits of a shown type (feat, fix, security, perf, docs) plus any commit carrying !, Upgrade: or BREAKING CHANGE:. Tests, refactors and chores serving one of those add no entry.

• One visible entry: squash. The title is that entry.
• Several, and every commit stands alone and passes commit-lint: rebase. Say so in the handover, and write the title as the lead change; it is not a changelog line.
• Several, but mixed with fixups or work in progress: report it. The branch needs cleaning into coherent commits, or splitting. Do not rebase unasked.

Never write a title containing "and".

3. Title

• Format: type(scope)!: subject. Types and scopes come from the dev.md tables.
• The scope names what a reader recognises, a stacklet or a bot, never a file.
• Imperative, lowercase after the colon, no full stop, no identifiers.
• Name the concrete change, not its effect: add an install hint to restart core on the first start, not say how to finish the agent's first start.
• Limit 72 characters as commit-lint counts them; dev.md asks for under 70. The (#N) appended at merge does not count.
• Use ! only when the user must act. The description then carries Upgrade: or BREAKING CHANGE:.
• Single-commit branch whose subject passes: reuse that subject.

4. Description

## Summary
- <user-visible change, and why>

Upgrade: <required action, as markdown>
Refs: #127

• One to three bullets. Footers only when they apply.
• Start with the situation the PR answers, then what it changes: "The agent is beta. After its first ./stack up agent, it can sign in only after a core restart." then "The hints shown after ./stack up agent tell the admin to run ./stack restart core, then ./stack restart agent."
• Plain technical English: state what the change does. No paraphrase such as "now say so" or "provide the required information".
• No "Test plan" section. Test output and measurements go in a PR comment.
• No em dashes. Use a comma, colon, period or parentheses.
• No Co-Authored-By, no "Generated with" line, no tool link: this repository is public and commit-lint rejects all three.

4b. Read the diff as a reviewer

Check the new and touched code against docs/agent/dev.md, "Clean code: what a reviewer checks". Fix what breaks a rule before opening the PR, or say in the handover which rule it breaks and why.

5. Check

python3 tools/commit-lint --title "<title>"
python3 tools/commit-lint --body "<description>"
python3 tools/commit-lint --range origin/main..HEAD

CI runs the third over every commit in the PR. Fix and re-run until all three pass. Rewording a pushed commit needs a force push: request approval first.

Output: the title, the description in a code block, the three results.

6. Open

Pushing and opening a PR need explicit approval, for every push. With approval:

git push -u origin HEAD
gh pr create --base main --title "<title>" --body-file <file>

Add --draft when asked. Never merge.

Merge

State the merge mode when handing the PR over.

Squash: the repository builds the squash body from the branch's commit messages, not from the PR description. A footer written in the description reaches main only when the merge uses the description as the body: the merge dialog, or gh pr merge --squash --body-file.

Rebase: gh pr merge --rebase. The commits land unchanged, so their footers are the ones that count; one written only in the description is lost.

Issues

Work that is not done in this branch goes into a GitHub issue: something found mid-task, a follow-up, a bug to fix later. One issue per piece of work. Every issue ends with a definition of done, the checks that prove it is finished. Pick the template by kind.

Title. A feature says what becomes possible, in the imperative: "Give CLI plugins a secret lookup instead of a snapshot of every secret". A bug says the symptom as a reader meets it: "Paperless login returns 500 on a first-time signup". No class or function names unless a reader types them.

Feature: a story with a definition of done

## Story
As <an admin | a family member | a stacklet author>, I want <capability>,
so that <outcome>.

## Context
What exists today and why it is not enough. Point at the code
(`lib/stack/stack.py`, `stacklets/<id>/...`), ADRs and PRs.

## Proposal
The change, at the level a reviewer can argue with.
Out of scope: <what this issue does not cover>.

## Definition of done
- [ ] <an observable check: a command and its result, or a behaviour>
- [ ] <a caller-side test that states the behaviour>
- [ ] <docs updated: `docs/stack-reference.md` for framework behaviour>

Example: an admin wants the provider's "My apps" page to show an icon per service. Done when stack up id sets a logo on every registered client that has none, stack up id a second time uploads nothing, and a test drives both runs against a stand-in for the provider's API.

Bug: steps to reproduce, expected and actual behaviour

## Summary
What breaks, for whom, in one sentence.

## Steps to reproduce
1. <from a known state: which stacklets are up, which mode>
2. <the action>
3. <what to look at>

## Expected behaviour
What should happen, and where that is promised (a doc, a test, a spec).

## Actual behaviour
What happens. Error text verbatim and trimmed.

## Environment
`./stack version`, macOS version, OrbStack or Docker Desktop, port or
domain mode, the stacklets involved.

## Cause
If known: the file and why. Otherwise leave the heading out.

## Definition of done
- [ ] <a test that fails before the fix and passes after it>
- [ ] <the steps above now give the expected behaviour>

Example: steps "bring up id and docs in domain mode, open the docs login, choose the provider button as a user whose account is not linked yet". Expected: Paperless creates the account and logs in. Actual: 500, with MultipleObjectsReturned in the Paperless log. Done when a test pins one provider entry per client id.

Rules

• Examples and reproduction steps use the demo family and example domains (home.example.family), never a real instance, name, address or log excerpt with personal data. This repository is public.
• No em dashes. No secrets, tokens or passwords, also not in logs.
• Opening an issue publishes it: ask first. With approval: gh issue create --title "<title>" --body-file <file>.
• A commit or PR that resolves the issue carries Closes: #N; one that only relates to it carries Refs: #N.