PR & Issue Hygiene¶

Clear, consistent issues and pull requests make collaboration easier for everyone. Follow these conventions when opening or reviewing work in this repository.

Issues¶

When to open an issue¶

Open an issue before starting significant work so the approach can be discussed and duplicate effort avoided. You do not need an issue for small typo fixes or trivial one-line patches.

Issue title¶

Use an imperative sentence that describes the desired outcome:

✅ Good	❌ Avoid
`Add dark-mode toggle to Settings tab`	`dark mode??`
`Fix streak reset when app is opened at midnight`	`bug with streaks`
`Document architecture and contribution flow`	`improve docs`

Issue body¶

Use the following template (the repository's default issue template uses this structure):

## Summary
One or two sentences describing what and why.

## Scope
- Bullet list of what is in-scope.
- Explicitly call out anything that is out-of-scope.

## Acceptance Criteria
- [ ] Testable, observable outcome 1
- [ ] Testable, observable outcome 2

## Dependency Hints (optional)
- Depends on: #NNN — short description

Labels¶

Label	Meaning
`bug`	Something is broken
`enhancement`	New feature or improvement
`docs`	Documentation only
`good first issue`	Suitable for first-time contributors
`blocked`	Waiting on another issue or external factor

Pull requests¶

Branch naming¶

feat/<short-description>     # new feature
fix/<short-description>      # bug fix
docs/<short-description>     # documentation only
chore/<short-description>    # tooling, deps, CI
refactor/<short-description> # refactor without behaviour change

PR title¶

Match the same imperative-sentence convention as issues. The title becomes the squash-merge commit message, so keep it concise (≤ 72 characters).

PR description¶

## What
One sentence describing the change.

## Why
Why this change is needed (link to the issue with `Closes #NNN`).

## How (optional)
Key implementation decisions, trade-offs, or anything the reviewer should pay attention to.

## Checklist
- [ ] `bun run lint` passes
- [ ] `bun run test` passes
- [ ] `bun run build` passes
- [ ] Relevant docs updated
- [ ] New behaviour covered by tests (if applicable)

Review expectations¶

PRs must pass the CI pipeline (lint → test → build) before requesting review.
Address every review comment or explicitly resolve it with a brief explanation.
Keep PRs focused — one logical change per PR. Large changes should be split or discussed in an issue first.
Reviewers aim to respond within two business days.

Merge strategy¶

All PRs are squash-merged into main. The squash commit message is taken from the PR title, so keep it meaningful.

Commit messages¶

Individual commits within a PR branch do not need to follow a strict convention — they are squashed on merge. That said, clear commit messages help during review:

feat: add counter archive action
fix: prevent streak reset when date is unchanged
docs: expand architecture section in README
chore: upgrade Vite to v8

Use the type: description prefix (feat / fix / docs / chore / refactor / test) and keep the description under 72 characters.