Project
Feedback, issues and contributing
How to report a bug or make a suggestion on the project's Forgejo, what to include, what never to attach, and how code and documentation changes get in.
On this page
Latch is being handed to a small number of people to try. Your feedback is how it gets better. Everything goes through the repository's issue tracker so nothing is lost in a chat.
Where
The repository lives on the maintainer's own Forgejo. A public mirror is being set up; until it is live, the fastest way in is to say hello on Matrix and ask:
#latch:matrix.aurionblack.com— the room, for anyone playing Latch.@lockedtrainee:matrix.aurionblack.com— the maintainer, directly.
Project site, with screenshots and downloads: https://latch.aurionblack.com.
When the public mirror is live this page will name it.
- Bugs and suggestions: the Issues tab. There are two templates — Bug report and Suggestion — pick one and fill in the boxes.
- Roadmap: the Milestones tab. If your idea fits an existing milestone, say which.
- Discussion of a design (like Packs): comment on its issue.
Reporting a bug
Open Issues → New issue → Bug report. Include:
- Version — from the footer of any page, or
/healthz. - What you did — the exact steps. "Locked 4 h, spun, then tapped Undo" beats "undo is broken".
- What you expected and what happened — copy the sentence on screen word for word. Most refusals are deliberate and the sentence is the diagnosis; if it was wrong, the words are the evidence.
- Where — phone or desktop, browser, through the reverse proxy or the raw port.
- A screenshot if it helps — after you have looked at it. Screenshots carry whatever was on screen, including a reflection.
Never attach an export
latch.json, the CSVs and the bundle are your whole journal in plaintext. No bug needs
them. If a maintainer needs data, they will ask for one specific row.
Also skip: the API token, anything from .env, your reverse proxy's secrets.
Making a suggestion
Open Issues → New issue → Suggestion. The template asks three things:
- What were you trying to do? The situation, not the feature. "I finish tasks on the train and log them later" is what produced the when field; "add a date picker" would not have.
- What would you like to happen? Your best version of it.
- How does it fit the rules? Nothing leaves the box; the log stays honest; prose is private. If it bends one, say so — sometimes that is the interesting part.
Label it type/feature. A maintainer will add an area (area/ui, area/engine,
area/data, area/bot, area/ai, area/dist) and a priority, or a needs-maintainer label
if it is a decision only the maintainer can make. class-p marks anything that touches the
privacy boundary; expect those to take longer and get argued.
Labels
| Label | Meaning |
|---|---|
type/bug · type/feature · type/docs · type/chore |
what kind of issue |
area/* |
which part: ui, engine, data, bot, ai, dist |
prio/p1 · prio/p2 · prio/p3 |
next · soon · later |
class-p |
touches the privacy boundary — review egress |
needs-maintainer |
a decision only the maintainer can make |
blocked |
waiting on something else |
Contributing code
Pull requests are welcome once you have talked about the change on an issue. The ground rules:
- Run the tests —
.venv/bin/pytest -q. Three of them are standing guards and are not negotiable: no served page references an off-box origin; the/api/v1surface matches a written allowlist; no editor or rule form renders on a play page. - Modules, not core edits, for new game mechanics. See How modules work.
- The clock is derived. A change that writes to the clock rather than emitting an event will not be merged.
- Every refusal is a sentence. Errors are
LatchError("…")with words a person can act on. - Comments explain traps, not syntax. The code base marks load-bearing decisions with 🔴 and explains what breaks if you "simplify" them. Read those before touching nearby code.
- Small PRs. One idea each. Tests for behaviour, not for coverage.
Contributing to this guide
The guide is docs/*.md in the repository — plain markdown with a small front-matter block
(title, section, order, summary). Edit a page, open a PR with the type/docs label.
Callouts use the > [!NOTE] / [!TIP] / [!WARNING] / [!CAUTION] syntax, which renders
both on Forgejo and in the app. Links between pages are [text](page.md). Nothing in a page
may load anything from anywhere — an image has to be in the repository.
Conduct
Be kind, be specific, assume good faith. This is an adult game about a consensual kink;
discuss it like adults and leave other people's play alone. The maintainer's decision on
anything labelled needs-maintainer is final and is usually explained on the issue.
This page also ships inside the app, at /guide — so your own instance always serves the guide for the version you are running, with the internet unplugged. Get Latch · Something wrong here? Tell me.