till
a371646238
The quick start downloads two files and pulls the image; no clone, no build. README figures brought up to date (it still said Astro 5, 124 tests, 16 migrations). Upgrade notes for 1.0 installs: the volume ownership change and the basic-ftp NAT behaviour. Help page and in-app changelog in English and German.
80 lines
3.0 KiB
Markdown
80 lines
3.0 KiB
Markdown
# Contributing
|
|
|
|
Thanks for looking. Klarbild is a small project with one maintainer, so the most
|
|
useful contributions are the ones that arrive ready to merge: a clear problem, a
|
|
minimal change, and a test where a test is possible.
|
|
|
|
## Getting it running
|
|
|
|
```bash
|
|
npm install
|
|
cp .env.example .env # DATABASE_URL, SESSION_SECRET, ENCRYPTION_KEY
|
|
npm run dev
|
|
```
|
|
|
|
You need a PostgreSQL to point `DATABASE_URL` at; `docker compose up db` gives you
|
|
one. Migrations run themselves on the first request.
|
|
|
|
```bash
|
|
npm test # 130 tests, no database needed
|
|
npx tsc --noEmit # must be clean
|
|
npm run build
|
|
```
|
|
|
|
Both `npm test` and `tsc` run in CI and both must be green.
|
|
|
|
## How the code is laid out
|
|
|
|
```
|
|
src/lib/print*.ts the print engine — pure arithmetic, heavily tested
|
|
src/lib/paper.ts 86 image sizes, 19 paper formats, the size parser
|
|
src/lib/modules.ts which optional modules are switched on
|
|
src/lib/i18n.ts translation; the English sentence is the key
|
|
src/components/ React islands, one per screen
|
|
src/pages/ Astro pages and the API under src/pages/api/
|
|
migrations/ numbered SQL, forward-only, idempotent, run on boot
|
|
tests/ node:test, no framework
|
|
```
|
|
|
|
The rule that matters most: **the browser preview and the server-side PDF use the
|
|
same layout code.** If you change how a sheet is laid out, change it in
|
|
`src/lib/printlayout.ts` and both follow. Anything that recomputes geometry in a
|
|
component is a bug waiting to happen.
|
|
|
|
## House style
|
|
|
|
- Comments explain **why**, and carry the number that justifies the decision.
|
|
"Measured: 440 MB of images peaked at 196 MB of memory" is worth more than
|
|
"stream the files". Please keep that habit; it is most of what makes this
|
|
codebase navigable.
|
|
- No new dependency without a reason in the pull request. There are 20 runtime
|
|
dependencies and that is already plenty.
|
|
- Two-space indent, no semicolon crusade, no reformatting of files you did not
|
|
otherwise touch.
|
|
- Metric units. English decimal point in English strings.
|
|
|
|
## Translation
|
|
|
|
The English string in the source **is** the key. To add a language:
|
|
|
|
1. Copy `src/locales/de.json` to `src/locales/<code>.json` and translate the values.
|
|
2. Add the code to `LOCALES` and `LOCALE_NAMES` in `src/lib/i18n.ts`, and to
|
|
`DICTS` in `src/lib/i18n.server.ts`.
|
|
|
|
A missing key falls back to English, so a partial translation is still useful. Never
|
|
build a sentence by concatenation — use a named placeholder: `t('{done} of {total}
|
|
done', { done, total })`.
|
|
|
|
## Adding a module
|
|
|
|
Optional features live behind `src/lib/modules.ts`. A new one needs: an entry in
|
|
`MODULE_IDS` and `MODULE_INFO`, a `has('yours')` guard on its navigation entry and
|
|
its settings card, and `if (!has('yours')) return moduleOff('yours')` at the top of
|
|
every API route it owns. The test is simple — with the module off, the instance
|
|
should not hint that the feature exists.
|
|
|
|
## Pull requests
|
|
|
|
One change per pull request. Say what breaks if it is wrong. If you found a bug you
|
|
are not fixing, an issue with a reproduction is genuinely useful on its own.
|