Guide › 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.

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

https://forge.aurionblack.com/lockedtrainee/latch — browse the code, read the history, file an issue, open a pull request.

Clone it: git clone https://forge.aurionblack.com/lockedtrainee/latch.git
An account is a sign-up away, but each one is activated by hand — so there is a wait between registering and being able to post. Nudge the maintainer on Matrix if it drags.
No account yet, or would rather not have one? Say it in the room and it will get written down.

The mirror is downstream, and it is force-pushed

Development happens on the maintainer's own Forgejo and is mirrored out on every push. Issues, pull requests and comments live on the public mirror and are safe — only the git refs are overwritten. A commit pushed directly to the mirror would be lost on the next sync, so send changes as a pull request rather than pushing to main.

Also:

#latch:matrix.aurionblack.com — the room, for anyone playing Latch.
@lockedtrainee:matrix.aurionblack.com — the maintainer, directly.
https://latch.aurionblack.com — the project site: screenshots, the guide, downloads.
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/v1 surface 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 is docs/contributing.md in the repo. Spotted a mistake? Tell us how to report it →