# CLAUDE.md — instructions Claude reads first

Claude Code reads this file at the repo root before doing work here. Follow it.

## Non-negotiable AI git boundary: commit locally, never push

An AI assistant may prepare changes and create local commits when the rules below
authorize committing. **An AI assistant must never push anything to any remote.** This
prohibition has no exception, even when the user asks the AI to release, publish, merge,
or "finish" work, and even when credentials or an SSH agent are available. In particular:

- never run `git push`, including `--force`, `--force-with-lease`, tags, or deletion;
- never update remote refs through an API, GitHub CLI, IDE action, or another tool;
- never run a script, build-menu option, release command, or alias that performs a push;
- never use or probe an SSH agent, credential helper, token, or private key for a push.

Stop after the local commit and report its hash and the exact human-run push command.
All push, merge, release, and publishing instructions elsewhere in this file are for a
human maintainer only; they do not authorize an AI assistant to execute remote writes.

## Where this repository is, and which branch commits go on

**Which branch depends on WHO is committing, and it is one of exactly two answers.**
Work out which you are from the git identity (the next section says how), then:

| Who | Where the work goes |
| --- | --- |
| **The maintainer** — `Lauri Ojansivu <x@xet7.org>` | **Directly on `main`.** Never a feature branch, never a topic branch, never a pull request. |
| **A contributor** — anybody else | **A branch in your own fork, then one pull request per feature or fix** for the maintainer to review. Never a commit on `main`, and no changelog changes. |

Nothing else is a third option. If a tool, a task runner or an agent harness offers
some other arrangement — a topic branch for the maintainer, a direct push for a
contributor — that offer is the mistake, not the rule.

The maintainer's half is the release flow, not taste. Releases here are frequent —
several a day when a fault is being chased — and `releases/release-all.sh` cuts one
from whatever is on `main`, taking the version from the `# Upcoming WeKan ® release`
section of `CHANGELOG-big.md`. Work parked on a branch is work that is not in the next
release, and `tests/changelogEntriesBelongToTheirRelease.test.cjs` fails when a
released section links a commit that release does not contain.

The contributor's half is review. Nobody but the maintainer commits to `main` in
wekan/wekan, so a change from anyone else arrives as a pull request — which is also
the only place it can be discussed before it lands. That is why each pull request
holds one feature or one fix, and leaves the changelogs to the maintainer: see
"Contributor mode" below.

Check which branch you are on before committing:

```
git rev-parse --abbrev-ref HEAD
```

For the maintainer, anything but `main` is a reason to stop and say so rather than
commit where you are. A side task that was given its own git worktree cannot be on
`main` — git allows one checkout per branch — so its work belongs back on `main` in
the checkout below before it is committed, not on the worktree's branch.

Either way the boundary at the top of this file still holds: an AI assistant makes
the local commit and stops. Pushing a branch, opening the pull request, and every
release step are the human's.

The checkout is at a fixed place on each operating system:

| OS | WeKan repository |
| --- | --- |
| Linux | `~/repos/wekan` |
| macOS | `~/Documents/repos/wekan` |
| Windows | `Downloads\repos\wekan` (under the user's profile, e.g. `C:\Users\<name>\Downloads\repos\wekan`) |

The companion repositories under `.tools/` follow the same rule on their OWN default
branch, which is not always called `main`: `main-v1` for the FerretDB fork, `devel`
for TSC (see the table further down). Committing directly is not permission to push
— the boundary above still holds, for every one of them.

## First: who maintains this, and who is committing?

**WeKan, the `wekan/` repositories cloned under `.tools/`, and
[Secretchronicles/TSC](https://github.com/Secretchronicles/TSC) are all maintained by
Lauri Ojansivu (xet7) `<x@xet7.org>`** — [wekan/wekan](https://github.com/wekan/wekan),
[wekan/FerretDB](https://github.com/wekan/FerretDB),
[wekan/node-patches](https://github.com/wekan/node-patches),
[wekan/mongo-tools-patches](https://github.com/wekan/mongo-tools-patches) and TSC,
which is under the **Secretchronicles** organisation rather than **wekan** and is his
all the same — his GitHub profile, [xet7](https://github.com/xet7), says exactly that:
*"WeKan and TSC maintainer"*. Work done on the maintainer's behalf is committed as
**`Lauri Ojansivu <x@xet7.org>`** — that author, in every one of those repositories,
every time. Two rules follow from it and neither has an exception:

- **Name the actual participant — and an AI is only ever the participant when no
  human is behind the change.** One rule, two halves, and the test is simply whether
  a person made this change or a tool did it on its own:
  - **A human's AI is not a participant. It is invisible.** When the maintainer or a
    contributor uses Claude Code, Codex, Copilot as an assistant or any other model
    to do the work, that person is the author and the tool is not mentioned at all:
    no `Co-Authored-By:` trailer, no "Generated with", no assistant or model name —
    not in the commit message, not in a pull-request body, not in the CHANGELOG.
    [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) is where this comes from: *"For pull
    requests, mention only those participants that are **human**."* A
    `Thanks to ... and xet7 !` line credits people — the issue reporter and xet7 —
    never the tool that helped.

    It IS acknowledged, once, in exactly ONE place: the sponsors page,
    <https://wekan.fi/sponsors>, under *"AI donated by. All code and PRs verified by
    xet7"*, where **Claude**, **Codex** and **GitHub Copilot** are listed alongside
    the people and companies that donate hosting, servers, grants and testing to
    WeKan. That is the whole of the credit and it is deliberate. Attributing it per
    commit instead put the same fact on thousands of lines and drowned out the
    humans the entries exist to name, so it was moved to the one page that says who
    gives WeKan what. Acknowledging it anywhere else is not extra politeness; it is
    undoing that.
  - **An AI that raised the pull request ITSELF is the participant, and is named.**
    GitHub CodeQL filing a security fix, Copilot Autofix, Dependabot raising a
    dependency bump: nobody wrote those, so crediting a human would be false and
    crediting nobody would leave the change unattributed. Name the bot, the way the
    dependency sections below already close with `Thanks to dependabot.`
  So the same words — "Copilot", say — are forbidden in one commit and required in
  another, and what decides it is not the word but whether a person is behind the
  change.
- **If the git identity is missing or wrong in one of these checkouts, set it; do not
  commit under something else.** The `.tools/` clones are made by `build.sh` inside
  this checkout and can come up with no `user.name`/`user.email` of their own, which
  would silently author a commit as whatever the machine's default is:

  ```
  git -C .tools/<repo> config user.name  'Lauri Ojansivu'
  git -C .tools/<repo> config user.email 'x@xet7.org'
  ```

Check the current git identity before committing or releasing:

```
git config user.name && git config user.email
```

- **Maintainer mode** — the identity is `Lauri Ojansivu <x@xet7.org>` (name
  `Lauri Ojansivu`, email `x@xet7.org`), or it is unset in a checkout of one of the
  repositories above, which means it is to be SET to that as above rather than worked
  around. Then the AI ITSELF makes the commit, and makes it **directly on `main`**
  (see the section above), authored `Lauri Ojansivu <x@xet7.org>` — not as a
  co-author, not as a second author, but as that author and no other — with no pull
  request and with nothing anywhere in the commit message, the CHANGELOG entry or
  anything else it writes that says an AI was involved. Working for the maintainer
  is the invisible half of the attribution rule above — the acknowledgement for it
  already exists, on <https://wekan.fi/sponsors>, and belongs nowhere else. The **publishing / release
  steps** below are available to a human maintainer only: an AI stops after
  committing locally and never runs a step that pushes or publishes.

  **Maintainer mode is the only mode that commits directly and the only mode that
  updates changelogs**, in WeKan and in the maintainer's repositories under
  `.tools/` alike. It applies to the changes the WeKan maintainer makes, and to the
  changes of an agent working as the maintainer according to this file.
- **Contributor mode** — the identity is somebody ELSE, in a fork or a clone of your
  own — a person, or an AI that files pull requests on its own account. Then: do
  **not** commit directly to the repository or to `main`, and do **not** run any
  release/publishing step. Make the changes on a branch and open a **pull request**
  for the maintainer to review. The "commit as Lauri Ojansivu", "commit directly to
  `main`", changelog and release instructions below are **maintainer-only and do
  not apply to you**.

  Every pull request, to wekan/wekan or to a maintainer's repository under `.tools/`,
  follows two more rules:
  - **One feature or one fix per pull request.** Changes share a pull request only
    when they are related to that one feature or fix. Anything unrelated, however
    small, goes in a pull request of its own, so each can be reviewed, merged or
    declined without holding up the others.
  - **No changelog changes.** Do not edit `CHANGELOG-big.md`, `CHANGELOG.md`, or the
    `CHANGELOG.md` or `CHANGELOG` of a repository under `.tools/` — not an Upcoming
    entry, not TODO Later. Describe the change in the pull request instead. The
    maintainer writes the entry after merging, when there is a commit for it to link.

  Who that pull request credits follows the attribution rule above, and the two
  cases differ:
  - **A person contributing, with an AI helping them.** The person is the author and
    the tool is not mentioned — the pull request stays free of AI attribution, body
    and commits alike. Pushing the branch and opening the pull request are that
    person's own steps; the never-push boundary above means their AI stops at the
    local commit on the branch.
  - **An AI contributing on its own** — GitHub CodeQL raising a fix for something it
    found, Copilot Autofix, Dependabot. There is no human in that pull request at
    all, so it is named as the contributor it is. This is the one place an AI is
    credited by name in this project, and it is credited because it is the author,
    not because it assisted one.

Maintainer mode covers TSC as well: commit directly to its `devel` branch, no pull
request, same author and no AI attribution. What it does NOT bring along is WeKan's
house style — TSC keeps its own **GNU ChangeLog** `CHANGELOG` and its own release
process, because a project is read on its own terms (see the CHANGELOG section below).
The one repository under `.tools/` that is somebody else's is `sandstorm-io/sandstorm`,
cloned for reference only.

Everything below marked as maintainer-specific (committing directly, the exact commit
author, updating changelogs, and the entire "Making a release" / publishing flow) applies
only in maintainer mode. The rest (translation policy, tests, validating from code) is
good practice for everyone.

## Process: "Fix open issues"

When asked to fix an open issue (one issue at a time):

1. **Read the whole issue** — the description AND all comments (e.g.
   `gh issue view <n> --comments`, or the GitHub API `.../issues/<n>/comments`).
2. **If it is a bug, first check whether it is already fixed** in the current WeKan
   AND FerretDB source code (read the actual code, not just changelogs). It may have
   been fixed already.
3. **If it is NOT fixed yet, fix it**, using the newest documentation and issues of
   the dependencies involved, checking where the newest MAINTAINED dependency lives and
   reading its source and issues:
   - Meteor 3 docs — https://docs.meteor.com/
   - Meteor 3 source + issues — https://github.com/meteor/meteor/issues
   - other Meteor software docs/code (e.g. Rocket.Chat) for how they solved it
   - Meteor forums — https://forums.meteor.com
   - AtmosphereJS — https://atmospherejs.com/ ; Packosphere — https://packosphere.com/
   - Meteor Community Packages — https://github.com/meteor-community-packages
   - Meteor-Files — https://github.com/veliovgroup/Meteor-Files
   - npm — https://www.npmjs.com
4. **After fixing, add tests** — unit tests, negative tests, and UI tests where
   appropriate — and **run the new tests to verify they pass** (see Tests / the sandbox
   build+test instructions in `docs/Security/Sandboxes/vscodium/README.md`).
5. **Commit** (maintainer only — when the current git user is `Lauri Ojansivu
   <x@xet7.org>`), with no "Co-Authored" / AI trailer, a message body ending:

   ```
   Thanks to (GitHub nickname of the issue creator) and xet7 !

   Fixes #1234,
   ```

   A contributor instead commits on a branch for one pull request that fixes this
   one issue, with no changelog changes (see "Contributor mode" above).
6. **If the bug is already fixed**, still add a commit that CLOSES the issue (a commit
   whose message ends `Fixes #1234,`), noting where/when it was fixed.

Fix from source and test — do not guess. If the environment cannot run the relevant
test (e.g. Docker is unavailable in this sandbox), reproduce as closely as possible
from source and say clearly what was and was not verified.

## Translations (Transifex ↔ direct LLM fill, no external service)

WeKan translations live in `imports/i18n/data/<lang>.i18n.json` (flat
`key -> string`, 2-space indent, key order matches `en.i18n.json`). Transifex holds
the human translations. **The policy is: never overwrite a human translation in the
correct language with a filled (or English) one, but always take the newest correct-
language translations from Transifex. Text in another language is not protected: the
locale tag is authoritative, and wrong-language or mixed-language values must be
replaced with the language named by that tag.**

- Pull with `releases/translations/pull-translations.sh`. It runs `tx pull -a -f`
  (which fills every string that is UNtranslated on Transifex with the English source)
  and then a **per-key merge** (`releases/translations/merge-translations.mjs`) that,
  for every language file and every key:
  - Transifex has a real translation in the locale's declared language (pulled value
    differs from English) → **keep it** (the newest correct-language human translation
    always wins);
  - the pull returned English but the pre-pull local file has a translation →
    **restore the local translation as the fallback**. It may be human or a direct
    machine/LLM fill; either way it remains local, while a real correct-language
    Transifex translation takes precedence;
  - **no translation anywhere** (untranslated on Transifex AND never committed) → leave
    the English source as a placeholder. **This is the only case a non-human value is
    used.** A separate fill step may fill *only* these English placeholders, so a filled
    string can never overwrite a human translation.
- After the merge, audit for mixed or wrong-language values. A value that differs from
  English can still be wrong for its locale; replace it directly as described below.
- **The pull workflow never pushes translations to Transifex.** It cannot distinguish a
  restored human translation from a committed direct fill, so automatic push-back would
  misrepresent machine/LLM translations as human. Push only separately reviewed,
  provenance-known human translations with an explicit push command.

### Filling the remaining untranslated strings — directly, no translation service

The strings still equal to the English source after the merge are the ones untranslated
**everywhere** (Transifex + git). Translate these **directly** — the maintainer or the
assistant (an LLM) writes the translation itself, using that language's **existing
translations** and general **kanban terminology** for the language as the reference.
**Do NOT wire up any external translation service, API, endpoint, key or password** — an
earlier `machine-translate.mjs` that called LibreTranslate/DeepL is removed on purpose
(it did not work and needed a password). There is **no `WEKAN_MT*` env var** anymore.

- **EVERY language gets translated — including the ones nobody has volunteered for.**
  Klingon, Volapük, Wolof, Venda, Tamazight, Acehnese and the rest are not exceptions:
  WeKan cannot find a speaker for every language, and a file left in English stays in
  English for years. **Look the words up.** Any dictionary, word list, grammar or
  Wiktionary page on the Internet is a legitimate source — read it, take the terms it
  gives, and write the translation from them.
- **A locale file must contain its declared language, not whichever language happened
  to seed it.** If a Mongolian file contains Russian, replace the Russian with
  Mongolian; likewise replace French, German, Malay, Zulu or any other wrong-language
  text with the language named by the file's locale tag. This rule applies to isolated
  mixed-language values and to an entire wrongly seeded file. Wrong-language text is
  not a human translation for that locale and does not receive human-preference
  protection. Because `fill-translations.mjs --apply` deliberately writes only English
  placeholders, make these corrections directly in the locale JSON (preserving key
  order and formatting), add regression coverage for the correct language/script, and
  note low-confidence replacements in the commit. Script checks alone are insufficient
  when both languages share a script, such as Russian and Mongolian; inspect vocabulary
  as well.
- **Placeholders are code, not language. Never translate them.** Any source token that
  begins and ends with underscores (for example `__board__`, `__card__` or
  `__username__`) and any format token whose token begins with `%` (for example `%s`,
  `%d` or `%1$s`) must be copied from the corresponding value in `en.i18n.json`
  exactly, character for character. Preserve every placeholder, its spelling, case,
  count and format; translate only the prose around it. If a locale has translated,
  renamed, removed or malformed one of these tokens, restore the original token from
  the same key in `en.i18n.json`, even when the surrounding translation is human.
  Regression coverage for a translation batch must compare its underscore-delimited
  and percent-prefixed token inventory with English so a translated placeholder cannot
  pass as ordinary prose.
- **Add the languages WeKan does not have yet.** The 154 files under
  `imports/i18n/data/` are not the list of languages worth supporting - they are the
  list somebody happened to start. When a language has a dictionary, a word list or a
  Wiktionary anywhere on the Internet, it can have a WeKan. Adding one is three edits,
  and all three are needed or the language is invisible:
  1. `imports/i18n/data/<tag>.i18n.json` — the strings, in `en.i18n.json`'s key ORDER
     (`tests/boardItemLinks.test.cjs` checks that), 2-space indent.
  2. `imports/i18n/languages.js` — `{ code, tag, name, load, rtl }`. The **name is
     written in that language itself** ("Suomi", "tlhIngan Hol"), the way every entry
     there already is, because it is read by somebody who does not read English. `rtl:
     true` for Arabic, Hebrew, Persian, Uyghur and the rest that are written
     right-to-left.
  3. `client/components/users/userHeader.js` — the `flagMap` in `languageFlag()`, so the
     picker shows a **flag** beside the name. A language without a country of its own
     takes the flag of where it is spoken, and a constructed one (Esperanto, Klingon,
     Volapük) keeps the `🌐` fallback rather than being given somebody's country.
- **A bad translation beats no translation.** An imperfect string is readable, it is
  obviously improvable, and it is an *invitation*: somebody who speaks the language sees
  it is wrong and fixes it, which an English placeholder never provokes. So: do not skip
  a language because the result would be imperfect. Translate it, say in the commit which
  ones were done with low confidence, and let a human correct it — the merge rules below
  guarantee that when that human translation arrives on Transifex, it REPLACES the filled
  one and is never overwritten by it.

- `node releases/translations/fill-translations.mjs --missing` — per-language count of
  strings still needing translation (English + `en-*` variants are skipped: English by
  design). Also printed at the end of `pull-translations.sh`.
- `node releases/translations/fill-translations.mjs --list <lang> [--limit N]` — dump the
  untranslated keys of a language as `{ key: englishSource }` for the translator to fill.
- `node releases/translations/fill-translations.mjs --apply <lang> <translated.json>` —
  merge the translations back. It writes **only** into placeholder keys, so it can
  **never** overwrite a human translation, and a value still equal to English/empty is
  ignored. Key order and 2-space indent are preserved.

**Both directions are safe, and it is verified:**
`node releases/translations/verify-human-preference.mjs` proves (pure-logic, no network)
that a real Transifex translation wins, the pre-pull local translation fills only an
English result, a fill only touches placeholders, and the pull script contains no push.
Thus **correct-language Transifex human strings are preferred and merged**, remaining
keys retain their local human or machine/LLM translations, and nothing restored or
filled is pushed to Transifex as if it were human. Wrong-language values are corrected
directly after the merge.

## General practices (from .tools/log/v10/Claude.txt)

- **[maintainer only]** Commit as `Lauri Ojansivu <x@xet7.org>`, with **no**
  "Co-Authored-By" or any other AI trailer, directly to the `main` branch of WeKan and
  the `main-v1` branch of the FerretDB fork. **Do not make pull requests.**
  (Contributors do the opposite: work on a branch and open a pull request — see the
  top section.)
  This is the same rule as the top section, restated where the release work is: one
  author, `Lauri Ojansivu <x@xet7.org>`, and no AI attribution anywhere.
- Lauri Ojansivu (xet7) maintains WeKan (https://wekan.fi), the FerretDB v1 fork, and
  the two patch repositories under `.tools/` — node-patches and mongo-tools-patches.
- Directory structure:
  - `wekan` — this repo (https://github.com/wekan/wekan); see
    `docs/DeveloperDocs/Directory-Structure.md`; `CHANGELOG-big.md` and `CHANGELOG.md` at root. It is at
    `~/repos/wekan` on Linux, `~/Documents/repos/wekan` on macOS and
    `Downloads\repos\wekan` on Windows. The maintainer commits on `main`; a
    contributor works on a branch and opens a pull request — see "Where this
    repository is, and which branch commits go on" above.
  - `.build/` and `_build/` — the two BUILD directories, generated and
    gitignored, easy to confuse and different things. `.build/` is the RELEASE
    bundle (`meteor build .build --directory`; `.build/bundle` is what is
    deployed, tested and packaged). `_build/` is rspack's compiled output,
    written by ANY Meteor compile, and Meteor reads the app's main modules from
    `_build/main-prod/` — so it is a HANDOFF, not a leftover, and must **not**
    be added to `.meteorignore` (ignoring it breaks the build; that file says
    why). Never edit or commit either, and SKIP `_build/` in anything that walks
    the repository: it holds a bundled second copy of every source file, so a
    tool that reads it sees every file twice and reports the bundler's rewritten
    code as if it were source. That is not hypothetical — a source-scanning test
    did exactly that and failed on generated code nobody can edit.
  - `.tools/w/wekan.fi` — the WeKan website companion repository.
  - `.tools/` — everything that is NOT part of this repository but is needed to
    build, test and release it, in ONE directory that `.gitignore` and
    `.meteorignore` already exclude (each used to need its own ignore entry at
    the repo root), so nothing in it can reach a commit or a Meteor rebuild. Two
    different kinds of thing live there, and the difference matters:

    **Companion git repositories.** Separate repositories with their own history,
    branches, changelog and release flow — a commit here is never a commit there.
    `build.sh`'s `ensure_tool_repo` clones one on demand (SSH first, HTTPS
    second), so a fresh checkout needs no manual setup:

    | Path | Repository | Branch | What it is |
    | --- | --- | --- | --- |
    | `.tools/w/FerretDB` | wekan/FerretDB | `main-v1` | the FerretDB v1 fork WeKan ships as its default database |
    | `.tools/w/node-patches` | wekan/node-patches | `main` | patches to upstream Node.js; builds the `node-<platform>` binaries the bundles, the Docker image and the snap embed |
    | `.tools/w/mongo-tools-patches` | wekan/mongo-tools-patches | `main` | patches to the MongoDB Database Tools; builds `mongo-tools-<arch>`, all eight tools as one program |
    | `.tools/Secretchronicles/TSC` | Secretchronicles/TSC | `devel` | the game xet7 also maintains — same author and maintainer mode, its own GNU ChangeLog and release process |
    | `.tools/sandstorm` | sandstorm-io/sandstorm | — | upstream Sandstorm, when present — somebody else's project, cloned for reference |

    **Unpacked toolchains and caches.** Downloads, not repositories — put there by
    the sandbox instructions in `docs/Security/Sandboxes/vscodium/README.md`, deleted
    and re-fetched freely, never committed anywhere:
    `node-v<version>-linux-<arch>/` (the Node.js the test suites are run with),
    `go/` with `gopath/`, `gomodcache/` and `gocache/` (FerretDB's Go builds),
    `.meteor/` when `HOME` is pointed at `.tools`, and the `TSC*` AppImage.
  - **Temporary files belong in `.tools/tmp`, never in `/tmp`.** At the start of
    work that creates temporary files or runs tools which may create them, make
    `.tools/tmp` if necessary and export its absolute path as `TMPDIR` before
    invoking `mktemp`, npm, node-gyp, compilers, test runners or build scripts.
    Keep task-specific subdirectories beneath it and remove only the exact
    subdirectories the task created. The host `/tmp` may be a small tmpfs even
    when the repository filesystem has ample space. On Windows, use
    `.tools\\tmp` and set both `TEMP` and `TMP` to its absolute path for the
    command or script. `.tools/` is already excluded by `.gitignore` and
    `.meteorignore`, so these files cannot enter a commit or trigger Meteor.
  - **Do NOT add a `CLAUDE.md` or an `AGENTS.md` to any repository under
    `.tools/`.** node-patches and mongo-tools-patches each had a pair and they were
    REMOVED on purpose: the rules are the same for every one of these repositories,
    and a second copy of a rule drifts from the first. THIS file, and its `AGENTS.md`
    twin beside it, are where they live for all of them. Something true of only one
    of those repositories goes in that repository's own `README.md` or `docs/`,
    never in a new instruction file — and if you find one there, remove it rather
    than updating it.
  - `.tools/w/FerretDB` specifics — FerretDB `.go` files must contain **no**
    application-specific names (say "the client" / "a Meteor 3 driver" / a bare
    `#NNNN`); its `CHANGELOG.md` may use `wekan/wekan#NNNN`.

### CHANGELOG

- **[maintainer only] Changelogs are updated only in maintainer mode.** This whole
  section is for the maintainer and for an agent working as the maintainer, in WeKan
  and in the repositories under `.tools/`. A pull request contributor changes no
  changelog in any of them (see "Contributor mode" above).
- **Every repository writes its changelog in the format that repository's own file
  already uses.** Open its changelog, read the entries above the place you are
  adding one, and match them — never import another project's shape into it. The
  five that come up here:

  | Repository | File | Format |
  | --- | --- | --- |
  | `wekan/wekan` | `CHANGELOG-big.md` (and the generated `CHANGELOG.md`, below) | the WeKan format this section describes: `# Status` (Platforms/Version/TODO Later nested as `<details>`), then `# v<MAJOR>.<MINOR> YYYY-MM-DD WeKan ® release` sections of `<details>` entries whose `<summary>` links the commit |
  | `wekan/node-patches` | `CHANGELOG.md` | the same WeKan format, with `# Upcoming node-patches release` |
  | `wekan/mongo-tools-patches` | `CHANGELOG.md` | the same WeKan format, with `# Upcoming mongo-tools-patches release` |
  | `wekan/FerretDB` | `CHANGELOG.md` | **upstream FerretDB's** format, not WeKan's: `## [v1.48.0](tag URL) (YYYY-MM-DD)` and `### New Features 🎉` / `### Fixed 🐛` / `### Other Changes 🤖` bullets ending `by @xet7. Thanks to xet7.` |
  | `Secretchronicles/TSC` | `CHANGELOG` (no extension) | **GNU ChangeLog** format: a `YYYY-MM-DD  Name  <email>` header line, then TAB-indented `* Version …` / `* Fix: …` / `* Misc: …` entries, wrapped and continued with further tabs, each ending `(by Name)` |

  The reason is the reader, not consistency for its own sake: a FerretDB release is
  read beside upstream FerretDB's releases, and a TSC entry beside a decade of GNU
  ChangeLog entries. A WeKan-shaped `<details>` block in either would be the odd one
  out and would break the tooling that parses them. When this file and the file being
  edited disagree, **the file being edited wins** — and everything below in this
  section is about the WeKan format specifically.
- **WeKan has TWO changelogs, and only one is written.** `CHANGELOG-big.md` is
  the changelog: `# Status`, `# Upcoming WeKan ® release` and every release in
  full, in the `<details>` format below - every rule in the rest of this section
  is about it, and every entry, fix and release goes into it. `CHANGELOG.md` is
  the SHORT changelog, generated from it by `node releases/changelog-short.mjs`
  and never edited by hand:

  | | `CHANGELOG.md` |
  | --- | --- |
  | Status, TODO Later | none |
  | First | the unreleased `# Upcoming WeKan ® release`, when there is one: its **In short** paragraph only, then `[All changes so far](CHANGELOG-big.md#upcoming-wekan--release)` |
  | Below it | the five newest `# v<MAJOR>.<MINOR> YYYY-MM-DD WeKan ® release` |
  | Per release | its **In short** paragraph only, then `[All changes in v…](CHANGELOG-big.md#anchor)` |
  | Markup | plain Markdown: no `<details>`, `<summary>`, `</summary>` or `</details>`, and every HTML link a Markdown link |

  It exists because the big file is for whoever writes and audits a release,
  and most readers - GitHub's front page, the Sandstorm App Market
  (`sandstorm-pkgdef.capnp` embeds it), the Helm chart's changelog link - want
  what changed lately, at a glance. `releases/release-all.sh` regenerates it
  right after naming the new release, so it is in the same release commit, and
  `releases/changelog.sh` does the same; `tests/changelogShort.test.cjs` fails
  when it is not exactly what the generator writes. So: write
  `CHANGELOG-big.md`, run the generator, commit both - and never edit
  `CHANGELOG.md` to fix something, because the next run overwrites it.
- **"Update wekan changelog" means both files, in this order:**
  1. Find what is not in the changelog yet: `git log` since the newest commit
     `CHANGELOG-big.md`'s Upcoming section (or, when it has none, the newest
     release's `Prepare v… release` commit) already covers, by anybody - a
     merged pull request and the maintainer's own commits alike.
  2. Check whether a release was cut since the last update (`release-all.sh`
     renames Upcoming to `# v<NEW> …` and opens no new one). If there is no
     `# Upcoming WeKan ® release` heading, add it from
     [docs/DeveloperDocs/Changelog-Upcoming-Template.md](docs/DeveloperDocs/Changelog-Upcoming-Template.md)
     above the newest release - never add an entry to a released section.
  3. Write the entries into that Upcoming section of `CHANGELOG-big.md`, in the
     format described below (subsections, topic groups, `<details>` entries
     linking each commit), and update its **In short** paragraph so it still
     names the release's main outcomes.
  4. Run `node releases/changelog-short.mjs`: `CHANGELOG.md` then shows that
     Upcoming **In short** first and the five newest releases below it, with the
     longer details only in `CHANGELOG-big.md`.
  5. Run the changelog tests - `tests/changelogShort.test.cjs`,
     `tests/changelogFormat.test.cjs`,
     `tests/changelogEntriesBelongToTheirRelease.test.cjs` (or
     `node tests/run-node-suites.cjs changelog`) - and commit
     `CHANGELOG-big.md` and `CHANGELOG.md` together.
- During development, add entries under a new `# Upcoming WeKan ® release` section above
  the newest release (FerretDB uses `## Upcoming FerretDB release`; the patch repos use
  `# Upcoming <repo> release`). Do **not** hand-edit
  `package.json` or any other version reference — the release workflow bumps those.
- **Whenever `# Upcoming WeKan ® release` is updated, audit every feature, bug fix
  and security fix in that section for regression coverage.** If coverage does not
  exist yet, add a positive test, a negative test and a UI test wherever that kind
  of test is possible and relevant. Run the tests that can run in the current
  environment; when a UI stack or another required service is unavailable, still
  add and syntax-check/register the test and state clearly what could not be run.
  Do not duplicate an existing test merely to satisfy the audit — extend it when
  that keeps one behavior in one suite.
- **CHANGELOG-big.md stays small enough for GitHub to show it.** GitHub renders
  Markdown up to 500 KiB; above that it shows only plain source text, and above
  about 2 MB nothing at all ("we can't show files that are this big right
  now"). The changelog reached 2.6 MB over 1,100 releases back to 2015 (#6580),
  and keeping only the current month still came to 2.1 MB, because releases
  here are frequent and large. So the cut is by SIZE: 450,000 bytes
  (`BUDGET` in `releases/changelog-archive.mjs`), under GitHub's limit with
  room for the Status links to grow:

  | | |
  | --- | --- |
  | `CHANGELOG-big.md` | `# Status` (Platforms/TODO Later inside it), `# Upcoming`, and the newest releases that fit the budget |
  | `old-CHANGELOG/<year>/<MM>.md` | a month's releases, newest first; a month over the budget continues in `<MM>-part2.md`, `<MM>-part3.md`, ... |
  | `old-CHANGELOG/<year>.md` | 2015–2025, whole |

  Past years 2015–2025 stay one file each because they are already small
  (30–107 KB). Every archive part fits the budget too, so it renders on GitHub;
  only a single release larger than the budget gets a part of its own and is
  shown as text. Each archive opens with a **release count** — per month in a
  year file, per day in a month part — a split month's parts link each other,
  and a bullet in `# Status`'s "Newest WeKan at these platforms" details links
  every one.
  That `git blame` is less useful on the split file is accepted: the history is
  still in git (`gitk`, `git-gui`, `git log --follow`), and being small enough
  to open is worth more.

  Run `node releases/changelog-archive.mjs` whenever CHANGELOG-big.md has grown -
  after a release is the natural moment. It is idempotent — a run with nothing
  to move only refreshes the tables and parts — and it decides from the FILE
  rather than the clock, so two people running it agree.
  `tests/changelogArchive.test.cjs` fails when CHANGELOG-big.md is over the budget.
  An archived section is never edited, for the same reason a released one is
  not.
- **The file's shape, top to bottom** — keep it exactly as it is now. There is
  exactly ONE `#` heading before the releases: `# Status`. Platforms, Version
  and TODO Later are `<details>` blocks nested inside it, not headings of
  their own (they used to be `# Platforms` and `# TODO Later`; both were
  folded under `# Status` so the file opens with a single top-level section
  rather than three):
  1. `# Status` — opens with a `<details>` whose `<summary>` is `More status
     info`, holding a link to <https://wekan.fi/status/>. Then a `<details>`
     whose `<summary>` is `Newest WeKan at these platforms`, holding the line
     `Newest WeKan at these platforms:` and the Install / Upgrade / Docs / Mac
     ChangeLog bullets, plus the `Older releases:` bullet linking the per-year
     archives. Then a `<details>` whose `<summary>` is `Databases` listing
     which databases WeKan supports and how each is tested, kept in step with
     `docs/Databases/Supported.md`. Then a `<details>` whose `<summary>` is `Version` holding
     "which WeKan version uses what". Then a `<details>` whose `<summary>` is
     `TODO Later`, itself holding a `<details>` whose `<summary>` is `Carried
     to a future release.` explaining the list, then one `<details>` per
     category (below). There is no `# Version` or `# TODO Later` heading of
     its own.
  2. The releases, newest first, each `# v<MAJOR>.<MINOR> YYYY-MM-DD WeKan ® release`.

  Nothing else is an `#` heading. A `##`/`###` inside a release would break the
  version list, and a wrapped line that BEGINS with `#` (e.g. an issue number such
  as `#6514`) becomes a heading too — escape it `\#6514` or keep it off the line
  start.
- **A release's order of subsections** — CRITICAL SECURITY ISSUES first, then new
  features, then the Admin Panel / UI reorganisation if there is one, then dependency
  updates (`Thanks to dependabot.`), then bug fixes, then developer-facing changes,
  documentation and translations. The section ends with the line `Thanks to above
  GitHub users for their contributions and translators for their translations.`
- **Every entry is a `<details>` block, and they are what a release is made of.**
  The `<summary>` is the SHORT description of what was done and IS the link to the
  commit — the hash lives in the `href` and is never on the page — followed by the
  `Thanks to …` sentence. Clicking it reveals the long description:

  ```
  <details>
  <summary><a href="https://github.com/wekan/wekan/commit/<hash>">Short description of
  what was done</a>. Thanks to (issue creator's GitHub nickname) and xet7.</summary>

  The long description: what was wrong, why, what it does now, what the test pins.
  Word-wrapped at 80 characters, ordinary markdown - links, `code`, emphasis.

  </details>
  ```

  Exactly as above: `<details>` and `</details>` each on their own line, the whole
  `<summary>…</summary>` on ONE line, a blank line under it, the body, a blank line,
  the close — and a blank line between two blocks.
- **The summary is one line at a glance** — aim for ≤ 110 characters — and PLAIN text:
  no `[text](url)`, no `**bold**`, no backticks inside `<summary>`, because a link
  cannot nest inside the `<a>` and the rest renders literally. It ends with a full
  stop, then `Thanks to …`. Every summary in a release links its own commit.
- **A change with nothing more to say stays a plain bullet** —
  `- [Short description](https://github.com/wekan/wekan/commit/<hash>). Thanks to xet7.`
  — and a dependency batch keeps its `- **package 1.2.3 → 1.2.4** — one line on what
  it is` bullets, closing with `Thanks to dependabot.` That bot is named for the same
  reason CodeQL and Copilot Autofix are: it raised those pull requests itself, with no
  human behind them, so it IS the contributor (see the attribution rule at the top).
  A `<details>` whose body only
  repeats its summary is noise; use one when there IS a longer story to reveal, which
  is most fixes.
- **TODO Later's own blocks are the same shape with two differences:** the `<summary>` is
  the short category text (no `<a>`, because nothing was committed), and there is **no
  `Thanks to`** — nothing is done yet, so there is nobody to thank. The body lists the
  issues as `[#NNNN](https://github.com/wekan/wekan/issues/NNNN) (one-line reason)`.
- **The hash is never the link text.** `[f1c89548e](…)` shows a hash to a reader who
  cannot do anything with it; the link text says what changed. Same for `[merge
  commit](…)` and for a bare URL — see the next rule.
- **Never show a long URL as visible text.** A link is always
  `[short text](url)` — an issue is `[#6524](…/issues/6524)`, an advisory is
  `[GHSA-xxxx](…)`, a security page is `[ZipBleed](https://wekan.fi/hall-of-fame/zipbleed/)`.
- **Subsection headers read as ONE flowing sentence.** The FIRST subsection of a release
  starts with `This release ` (e.g. `This release fixes the following bugs:`); every LATER
  subsection in the SAME release starts with a lowercase `and ` instead of repeating
  `This release ` — e.g.
  `This release fixes the following bugs:` … `and updates the following dependencies:` …
  `and has the following developer-tooling fix:` … `and improves the translation workflow:`
  … then the closing `Thanks to above GitHub users …` line. A release with only one
  subsection just keeps its single `This release …:` header. Use `and adds the following
  new features:`, `and fixes the following bugs:`, `and updates the following
  dependencies:`, etc., matching the verb to the subsection.
- **The Upcoming section opens with an `**In short:**` paragraph.** It must be
  short: put one compact, high-level paragraph directly under the
  `# Upcoming WeKan ® release` line. Aim for 2–4 sentences and no more than about
  120 words, however many commits the release contains. Name only the release's
  major outcomes or themes, with notable names in `**bold**` so it can be skimmed.
  It is not a commit inventory, progress log or miniature changelog: do not list
  batches, per-language counts, individual test fixes or every touched component,
  do not link commits, and do not repeat entry wording. The topic groups and their
  `<details>` blocks below carry that information. Keep the paragraph current as
  topics change, and shorten it when added commits make it grow. A finished release
  keeps the paragraph it was written with.
- **Neither changelog nor the release notes may contain a binaries provenance
  section or a Platform/Bundle/Binary/From/Version/Checked/SHA256 table.**
  Do not add "Binaries in these bundles" at the top or bottom of either.
  Release notes summarize each Translations group as only a list of updated
  languages. Add `**Languages updated:**` with comma-separated full language
  names below the group label; keep detailed entries in the changelog and audit.
  When more than 20 languages were updated, too many to list, give only their
  count instead: `**Languages updated:** 172 languages.`, which the release
  notes show as "Updated translations at 172 languages." Every part of the
  Upcoming section is optional: a part with nothing to say - no translations,
  no security fixes - is left out rather than added empty.
  Release notes have only In short, Security, Translations (language list),
  the standard thanks line and More details at ChangeLog with the release
  anchor link into CHANGELOG-big.md. Other details stay in CHANGELOG-big.md. Keep download
  verification and `provenance.tsv` build artifacts for diagnostics; do not
  append their contents or `releases/provenance-table.sh` output to notes.
- **Inside a subsection, entries are GROUPED BY TOPIC/AREA.** A release touches a handful
  of areas and repeating the area's name in every summary is the noise this
  removes — twelve entries that each begin "All Boards:" say "All Boards" twelve
  times and the part that differs starts halfway through the line. Instead the area
  is named ONCE, as a bold line with a short description of what the group covers,
  and every entry under it drops the prefix:

  ```
  and fixes the following bugs:

  **The first header bar** - how it lays itself out, and what sits under it.

  <details>
  <summary><a href="…">It fills each row before starting the next one</a>. Thanks to xet7.</summary>
  …
  </details>

  <details>
  <summary><a href="…">It wraps to a second row instead of hiding the buttons that do not fit</a>. Thanks to xet7.</summary>
  …
  </details>

  **All Boards** - the overview and its search.

  <details>
  …
  ```

  The group line is `**Topic** - short summary.` on ONE line where practical,
  wrapped at 80 like everything else, with a blank line under it. This line is the
  high-level summary of ALL commits in that topic: say what changed and why it
  matters without copying a commit summary or enumerating implementation details.
  The `<summary>` under it gives each commit's short outcome, and the expanded
  `<details>` body carries the implementation, rationale and test evidence. In
  other words, the release reads from release summary → topic summary → commit
  detail, with each level adding information instead of repeating the level above.
  The group line is NOT a heading: a `##` inside a release breaks the version list
  (see above). Group labels are the areas of the
  app — `All Boards`, `The first header bar`, `The left menus`, `The Admin Panel`,
  `Board views`, `Public Boards`, `Member Settings`, `Board roles` — and the same
  label is reused across subsections when an area has both a feature and a fix.
  EVERY entry of a grouped subsection belongs to a group, including a group with
  one entry: a section that is half grouped and half loose reads as a mistake. Put
  each commit under the topic it actually changes; do not create a chronological
  catch-all group. A subsection with only one entry, and the dependency bullets,
  stay flat.
- **CRITICAL security header — match the previous releases' wording.** A security release
  leads with `This release fixes the following CRITICAL SECURITY ISSUE of
  [Name](https://wekan.fi/hall-of-fame/namebleed/):` for a single named *Bleed, or
  `This release fixes the following CRITICAL SECURITY ISSUES:` for several — NOT
  `CRITICAL VULNERABILITIES`. Each security bullet still links its own
  `https://wekan.fi/hall-of-fame/...bleed/`. CodeQL-only releases use the established
  `This release fixes the following SECURITY ISSUES found by GitHub CodeQL code scanning:`.
  Because CRITICAL comes first, it keeps the `This release ` prefix; a following non-security
  subsection becomes `and …` per the rule above.
- **TODO Later** — a `<details>` nested inside `# Status` near the TOP of
  `CHANGELOG-big.md` (above the version sections), a triage backlog for open
  issues that were **investigated but not fixed here**, each
  recorded with a concrete REASON so whoever picks it up next knows why. Use it when working
  through open issues (the "Fix open issues" process): for each issue, either **fix it** (commit
  ending `Fixes #NNNN,`), **close it** if already fixed in current code (commit `Close #NNNN` /
  `Fixes #NNNN,`), or — when it can't be fixed/verified in this environment — **add it to `TODO
  Later` under the matching category with the reason**. Group issues by category bullet, e.g.:
  *Need specific infrastructure / a running server stack* (LDAP/WebHooks/Sandstorm/proxy —
  environment owners), *Need the running app to reproduce/verify* (runtime UI / publication /
  mergebox / router state, not unit-testable), *Already correct in the current code* (verified by
  reading; could not reproduce), *Feature requests / behaviour-by-design rather than bugs*, and
  *Needs a maintainer decision on the intended contract*. Each category is a `<details>`
  whose `<summary>` is the SHORT category text and whose body lists the issues with their
  reasons — and with **no `Thanks to` line**, because nothing is done yet, so there is
  nobody to thank. Each entry is a normal issue link
  `[#NNNN](https://github.com/wekan/wekan/issues/NNNN) (one-line reason)` — issue links here, NOT
  commit links (nothing was committed). **Keep it current:** when an issue in `TODO Later` gets
  fixed, REMOVE it from the list (its fix commit's `Fixes #NNNN` closes it); do not leave fixed
  issues in the backlog. This is the only CHANGELOG place that uses issue links and lives above
  the releases; everything else uses the per-release commit-link bullets above.
- FerretDB Upcoming structure — `### New Features 🎉`, `### Fixed 🐛`, `### Other Changes
  🤖`; entries end `... by @xet7. Thanks to xet7.`
- Word-wrap both CHANGELOGs at 80 chars, but never break a long link across lines (a
  `<summary>` line, or any other line carrying a link, may be longer). Continuation
  lines of a plain bullet are indented by two spaces.

### Commit message structure

```
Do something.

Thanks to (original creator of issue) and xet7 !

Fixes #1234,
Fixes #1235.
```

- **A commit that fixes a GitHub issue ENDS with `Fixes #NNNN`** — last lines of
  the message, one per issue, comma after each and a full stop on the last. That
  trailer is what closes the issue when the commit is pushed; a fix that only
  *mentions* the number in prose leaves the issue open, and somebody has to close
  it by hand later or it stays open forever. Several issues in one commit get
  several lines. The same applies to an issue that turns out to be **already
  fixed**: commit the test or the note that proves it and end with `Fixes #NNNN,`
  so the issue closes with a reference to where it was fixed.
- **Only when the commit really fixes it.** A commit that improves the
  diagnostics, narrows the cause, or fixes one of several reported problems
  references the issue in the body (`#6585 comment 5276581923`) and does NOT
  carry the trailer — closing an issue whose reporter is still stuck is worse
  than leaving it open. If an issue was closed and then REOPENED for follow-up
  items (as #6586 was), it is fixed again only when those items are done.
- **A commit with no issue behind it has no trailer** — the email reports, the
  release-tooling fixes found in build logs, refactors. `Thanks to ... and xet7 !`
  still names whoever reported it.

### Making a release — no version number needed  **[human maintainer only — never AI]**

All publishing / release steps below are human-maintainer-only. Contributors and AI
assistants never run them. An AI may prepare a local release commit only when requested,
then must stop and hand the commit and command sequence to the human maintainer.

**Releases are FREQUENT, and that is the normal state of this repository — not an
interruption to it.** The maintenance loop is:

1. `./build.sh` (or `build.bat` on Windows) → **option 1, "git pull and git
   push"**. Both directions do the whole job: a pull rebases and then repairs the
   CHANGELOG commit links the rebase made stale, and a push repairs them again
   BEFORE publishing, because a stale link that reaches GitHub 404s for everyone
   who reads the release notes.
2. `./releases/release-all.sh`, **with no arguments**, whenever there is something
   worth shipping — which is often, several times a day when a fault is being
   chased. It takes the version from the CHANGELOG and needs nothing typed.

So a release happening "in the middle" of a piece of work is not a special case
to reason about; it is what always happens, and anything that only works when
releases are rare is broken here. Two consequences worth stating, because both
have cost a released section its accuracy:

- **Work continues immediately after a release**, so an entry written right
  after one has to go somewhere. `release-all.sh` renames `# Upcoming WeKan ®
  release` to `# v<NEW> …` and stops there — it does **not** create a new,
  empty `# Upcoming` section. CHANGELOG-big.md never carries an
  `**In short:** nothing here yet.` placeholder sitting between releases; it
  used to (via a now-deleted `releases/changelog-open-next.mjs`), and that
  meant the file always had a section saying nothing, from the moment a
  release was cut until the first real entry replaced it. Instead: **add `#
  Upcoming WeKan ® release` yourself, by hand, the moment you have a real
  entry for it** — not before — using the skeleton at
  [docs/DeveloperDocs/Changelog-Upcoming-Template.md](docs/DeveloperDocs/Changelog-Upcoming-Template.md).
  An entry appended above the closing `Thanks to above GitHub users …` line
  with no Upcoming section yet lands INSIDE the release just published — the
  same mistake the auto-created section used to prevent — but it is caught
  regardless: `tests/changelogEntriesBelongToTheirRelease.test.cjs` asks git
  which commits a release actually contains and fails when a section links
  one that is not an ancestor of that release, whether or not an Upcoming
  heading existed first. Run that test (or `build.sh`'s node-suite option)
  before committing a CHANGELOG entry written right after a release.
- **A released section is a RECORD, not a draft.** When a release turns out to be
  broken, its section keeps saying what it shipped — including the part that was
  wrong — and the fix goes in a new `# Upcoming` above it. Do NOT edit a
  published entry to describe the smaller, tidier change you wish had shipped;
  add to it that it was wrong and where the fix is. Somebody reading v10.97's
  notes is most likely somebody whose v10.97 just died.

- WeKan: run `./releases/release-all.sh` (no arguments). It renames
  `# Upcoming WeKan ® release` to the next version (same increment as the last release;
  9.99 → 10.00) dated today, commits + pushes, and triggers
  `.github/workflows/release-all.yml` — whose `bump` job bumps `package.json` and every
  version reference and rebuilds the API docs, whose `prepare` job then pushes the tag
  `v<new>` and checks the notes exist, and whose `release` job publishes the GitHub
  Release the bundle jobs attach to. An explicit `oldversion newversion` pair still
  overrides. Adding entries under Upcoming is the only hand step.
- **A release that FAILED and one that shipped BROKEN are handled differently, and
  the difference is whether anything was PUBLISHED.** Both happened with v10.92, so
  neither is hypothetical:
  - **Nothing published** (the workflow died before the GitHub Release existed): there
    is no release for that number, so `# v<new> …` must not claim there is one. Rename
    the heading back to `# Upcoming WeKan ® release`, add the fix under it, and run
    `release-all.sh` again — it will take the same number, since the newest release is
    still the previous one.
  - **It published, and something in it is broken**: the release exists and people can
    download it, so its section STAYS as it is — a released section is a record, not a
    draft. Add a NEW `# Upcoming WeKan ® release` above it with the fix, exactly as
    during ordinary development, and the next run takes the next number.
  What decides it is the GitHub Release, not the tag: `prepare` pushes the tag early,
  so a tag can exist for a release that never published.
- FerretDB: run `./build.sh release-ferretdb` from `.tools/w/FerretDB` (no
  version). It renames `## Upcoming FerretDB release` to the next version with the
  correct git-tag link, commits + tags + pushes, then triggers `release-all.yml` (which
  in turn triggers `docker.yml` for the multi-arch image). It refuses to re-release an
  already-tagged version.

### Security issues

- Fix the vulnerability, add a CRITICAL section to the WeKan CHANGELOG like previous
  entries (maintainer mode only, as with every changelog change), and update `.tools/w/wekan.fi/hall-of-fame/index.html` and the vuln-name
  subdirectory `index.html` like previous security issues.
- **Every security fix gets a TEST and a NEGATIVE TEST, and they are written so the
  fault cannot exist ANYWHERE in the codebase — not just at the place it was
  reported.** A test that pins one call site leaves the same mistake free to live in
  the other five, and that is how most of these arrive: SignupBleed's guard read an
  option nothing sets, and the same shape sat in a second endpoint; the source-map
  trim was safe on the client and fatal on the server. So:
  - the **test** proves the fix does what it claims, driving the decision itself
    where that is possible. A pure module — `loginFailureDecision.js`,
    `lockoutDecision.js` — can be tested as arithmetic, without a server or a
    database, and reproduces the reporter's attack exactly rather than approximately;
  - the **negative test** proves the fault is gone rather than moved. Search the
    whole tree for the SHAPE of it and assert nothing matches: no other endpoint
    reads the dead option, no other counter is global, no other caller skips the
    check. When the shape is a pattern, pin the pattern.
  - and a test that reads the source is a real test here. `tests/*.test.cjs` may
    parse a file and fail on a construct — that is what makes "and nowhere else"
    checkable at all.
- **If somebody ATTEMPTS the attack, and the secure default DENIES it, that denial
  has to be visible in Admin Panel → Problems** — in every case where the denial can
  be attributed. This applies to every security fix added to Upcoming. That is the
  difference between a hole that is closed and a hole that is closed and watched:
  an administrator should be able to see that somebody tried.
  - Add a key to the catalog in `models/lib/securityCategories.js` (category, the
    hall-of-fame `bleed` name, severity, CWE), and call
    `require('/server/lib/securityLog').record({ key, action: 'blocked', source, detail })`
    on the refusal path. `action` is `'blocked'` when the fix stopped it and
    `'detected'` when it was only noticed.
  - **Wrap the call so logging can never break the guard**:
    `try { ... } catch (e) { /* logging must never break the guard */ }`. The refusal
    matters more than the record of it.
  - **Only log an ATTEMPT, never ordinary use.** The test to apply is whether a
    legitimate user can reach that line. Registration refused while registration is
    off has no legitimate caller, so it is logged; an admin endpoint whose fault was
    in what its answer CARRIED fires on every normal call, so it is NOT — that is why
    HashBleed (GHSA-6qpx-x7vr-p9w6) deliberately has no key. A log that fills with
    normal traffic hides the one line that mattered.
  - Where the denial cannot be attributed to an attempt — a fix that changes what a
    response contains, or one that only takes effect at build time — there is nothing
    to record, and that is a decision to state in the entry rather than an omission.
- **Admin Panel → Problems is a SUMMARY, never a row per event.** A guard on a path
  an attacker controls fires as fast as they can send, so a document per occurrence
  grows the database with the attack, turns the page into a scroll of near-identical
  lines, and buries the one event that mattered under ten thousand that did not. The
  admin's question is never *list every attempt* — it is *what is happening, how
  much, since when, and who*. So each problem is ONE row that accumulates
  (`models/lib/eventLogSummary.js`, written through `server/lib/eventLogFold.js`,
  shared by the security, speed and test loggers):

  | field | what it holds |
  | --- | --- |
  | `count` | how many times this problem has happened |
  | `firstAt` … `at` | the window it happened in |
  | `actors` | who, each with their own count — `username1 25, 100.100.100.100 30` |
  | `username` / `ip` / `detail` | the MOST RECENT occurrence |

  - **Identity is the KIND of thing that happened** — stream, `bleed`, category,
    action, source, severity, CWE (and `type`/`db`/`kind` for the database stream).
    The actor is NOT part of it: putting a username or an address in the key gives a
    row per attacker per attempt, which is the cost being removed.
  - **A username and an address are tallied SEPARATELY**, not as a pair. They answer
    different questions — which account, and where from — and an unauthenticated
    attempt has an address and no name.
  - **The tally is CAPPED** (`MAX_ACTORS`), with the remainder counted in
    `actorsOverflow`. Otherwise an attacker rotating addresses grows the row with the
    attack and reintroduces the same bug one level down — and *"and 9,412 others"* is
    itself the signal that the source is spread rather than single.
  - **A logger that writes per event is a bug to fix, not a style.** If one is added
    or found, route it through the shared fold and migrate what it already wrote
    (`server/lib/eventLogSummaryMigration.js` folds legacy rows in place, in batches,
    idempotently).
- **Every hall-of-fame vulnerability that CAN be detected at runtime should have a
  catalog key**, so Admin Panel → Problems groups attempts under the same name the
  Hall of Fame uses and an admin can go from one to the other.
  `tests/hallOfFameProblemsCoverage.test.cjs` lists the names that have no key and
  requires each to be accounted for — a *Bleed with nothing to detect (a fix that
  changed what a response carried, or one that only applies at build time) is
  recorded there as a deliberate omission with its reason, not left silent.
- **A Hall of Fame row has EIGHT cells**, in this order: CVE, Icon, Vulnerability
  name, Date, Responsible Security Disclosure by, Stars, Process, Vulnerabilities.
  One thing per cell — the name without its icons, the Font Awesome icons alone in
  Icon (still wrapped in `<h2>`), the reporter alone in "by", the `GoldStar.png`
  images alone in Stars, and the sentence about how the report arrived (coordinated
  disclosure, GitHub advisory, code scanning, found while reviewing …) in Process.
  In "by", the reporter's NICKNAME is the link —
  `<b><a href="https://github.com/nick">nick</a></b>`, never the name followed by a
  separate "(GitHub)" link. **Check the account exists before linking it** (a 404 or,
  worse, somebody else's profile is the failure here); a real name, a company or a
  tool such as GitHub CodeQL is not a GitHub user and stays plain text. Do not write
  a role note after a name — no `(fix)`, `(found)` or `(found and fix)`: this column
  is the credit, and the Process cell beside it already says how the report arrived.
  Stars is a column so it can be compared down the page; do not put a star, an icon
  or the process sentence back into another cell. A page-local `<style>` in
  `index.html` keeps a row's stars on ONE line from 900px up (they are a count) and
  sizes them at 24px, and keeps the icon and its red drop on one line at every width
  (they are one icon) — the table itself stays percentage-sized with no fixed or
  minimum width, so it fills the page at every browser width.
- **A report that arrives WITHOUT a GHSA is upgraded when its GHSA arrives.** The
  stars follow `.tools/w/wekan.fi/hall-of-fame/Audit-Stars.md`: a GHSA with a
  suggested fix is 5, a report sent to security@wekan.fi or any other way, with a
  suggested fix, is 3. When that researcher is later able to add a GitHub security
  advisory for the same report, the maintainer requests the CVE through the GHSA
  process, and the row's 3 stars become 5. So whenever an AI updates or audits the
  Hall of Fame, it checks each 3-star row whose Process says the report came
  without a GHSA against [WeKan Security
  Advisories](https://github.com/wekan/wekan/security/advisories): when a GHSA for
  that report now exists, it sets the row to 5 stars on the index AND on the row's
  own page, links the GHSA (and the CVE in the CVE cell once one is assigned),
  rewrites the Process cell to say the report later arrived as a GHSA, and records
  the change in Audit-Stars.md. Match by the report's subject and reporter, not by
  a nearby advisory - a GHSA about something else is no upgrade. Until the GHSA
  exists, the row stays at 3 and its Process cell says the GHSA is awaited.
- **On the Hall of Fame index page, the Process and Vulnerabilities cells are
  collapsed.** Those two columns carry the prose — how the report arrived, and the
  whole story of the vulnerability — so the page would be one wall of text and the
  columns that identify a row (CVE, name, date, reporter, stars) would be far apart.
  In `hall-of-fame/index.html`, and ONLY in those two `<td>`s, the cell's content
  sits inside a `<details>` whose summary is the column's own name — `Process` for
  the Process cell, `Details` for the Vulnerabilities cell:

  ```
  <td valign="top">
    <details>
    <summary>Details</summary>

    <ul>
      <li>… the same list as before …</li>
    </ul>
    </details>
  </td>
  ```

  The summary is that plain word, there is a blank line under it, and the cell's
  contents are otherwise unchanged. The other six cells of the row stay as they are
  — they are what a reader scans — and so does the header row.
- **The vuln-name subdirectory page is NOT collapsed.** `hall-of-fame/<name>bleed/index.html`
  is the page a reader opened on purpose, for one vulnerability: its table cell stays
  open and its `<h2 class="hof">Details</h2>` prose section below the table stays as
  it is. Only the index, which lists them all, hides them behind the summary.

### Tests

- `build.sh` / `build.bat` have a menu to install dependencies, build
  WeKan and run tests.
- Add tests, negative tests and UI tests for all new features and fixes that do not yet
  have tests. When adding a test, run or validate it and fix it until it works.
- **"Check newest test logs":** test logs go into a `log/<datetime>/` directory,
  one per run (e.g. `2026-07-21_20-58-09/`). That is **`.tools/log/`** inside the
  repository's ignored tool area, so a run does not show up in `git status` and
  does not depend on the parent directory being writable. The
  newest datetime directory is the latest run. Each holds the Playwright per-browser
  logs (`wekan-alltests-chromium.log`, `-firefox.log`, `-webkit.log`), the mocha/unit
  log (`wekan-alltests-mocha.log`), the e2e/import logs, and `wekan-test-server.log`
  (the WeKan test server + database output). A whole-run directory also holds the
  database-conformance logs (`db-conformance-*.log`, `-report.md`, `-summary.txt`)
  and FerretDB's own (`ferretdb-unit.log`, `-vet.log`, `-integration.log`). "Check
  the newest test logs" means: open the most recent
  `.tools/log/<datetime>/` and read those.
- **Check and fix WHILE the tests are still running.** A full run takes a long time
  (three browsers, then every database with an image for this CPU, then FerretDB's
  own suites), and its stages finish one at a time. Do not wait for the end: read
  the logs that are already written, fix what they show, and then look again for the
  stages that have finished since — repeat until every stage has run and everything
  found is fixed. Two things make this work:
  - A stage's log file is complete when its `===== ... finished` line is there; a
    file whose mtime is still moving is a stage in progress, and its failures so far
    are already real and worth fixing.
  - The node suites are run by `tests/run-node-suites.cjs`, which runs ALL of them
    and lists every failure at the end (`===== node suites: N run, M failed`). They
    are the fastest signal - about 15 seconds for 260 suites - so they are usually
    what to fix first while the browsers are still going.
- **A failing guard is not automatically a broken app.** Most of these suites read
  the source and pin a behaviour. When one fails, decide which side is wrong: fix
  the CODE when the guard still describes what WeKan should do, and fix the GUARD
  when the behaviour deliberately changed - and then say in the test WHY, so the
  next reader knows it was a decision and not a slip. Every fixed test keeps the
  assertion that made it valuable; do not delete a test to make a run green.

## Environment

- The editor (VSCodium) runs inside a **Flatpak sandbox**, launched by
  `docs/Security/Sandboxes/vscodium/vscodium-sandbox.sh`. What the sandbox allows/blocks and
  how it is set up is documented in `docs/Security/Sandboxes/vscodium/README.md` in that
  same directory — read it when something behaves differently than a normal host (file
  access, network, running services).

### Flatpak sandbox: install task tools under `.tools/`

- In the Flatpak sandbox launched by
  `docs/Security/Sandboxes/vscodium/vscodium-sandbox.sh`,
  the repository may be the only writable/shared host directory. When a command
  needs a tool that is missing, install its binary, virtual environment, models
  and caches under the repository-local `.tools/` directory. Do not install it
  into the read-only Flatpak image or scatter generated tool files through the
  source tree. `.tools/` is excluded by both `.gitignore` and `.meteorignore`, so
  local toolchains neither enter commits nor consume Meteor file-watcher slots.
- Use the version selected by the repository, resolved from the current files at
  install time; never copy a version number from an old log or hard-code the
  example currently shown in the sandbox README. In particular: Node.js and npm
  come from `NODE_VERSION` and `NPM_VERSION` in `Dockerfile`; Meteor comes from
  `.meteor/release`; companion repositories use the versions in their own build
  scripts or module files. Use the architecture reported by `uname -m`. Reuse an
  existing matching `.tools` installation before downloading another copy.
- Follow the complete, tested bootstrap commands and environment variables in
  `docs/Security/Sandboxes/vscodium/README.md`, especially its "Reuse same
  in-sandbox toolchain" and test-runtime sections. Prefer repository setup
  helpers such as
  `build.sh` and `releases/ensure-tools.sh` when they already install the needed
  pinned tool. Keep `HOME`, `PATH`, `GOROOT`, `GOPATH`, `GOCACHE`, `GOMODCACHE`
  and similar overrides scoped to the command or sandbox terminal; do not change
  the real host home or a system installation.
- For screenshot or image text that cannot be read by the normal image viewer
  because Flatpak/bubblewrap cannot create a user namespace, install RapidOCR
  locally instead of guessing from filenames or logs:

  ```bash
  python3 -m venv .tools/ocr-venv
  .tools/ocr-venv/bin/pip install rapidocr_onnxruntime pillow
  .tools/ocr-venv/bin/python -c 'from rapidocr_onnxruntime import RapidOCR; import sys; result, _ = RapidOCR()(sys.argv[1]); print("\n".join(row[1] for row in (result or [])))' path/to/screenshot.png
  ```

  Process a timestamped screenshot series in chronological order and correlate
  OCR output with the matching `.tools/log/<datetime>/` files. OCR is evidence
  with recognition errors: retain timestamps and coordinates when needed, verify
  suspicious numbers against adjacent frames, and do not claim visual details
  that neither OCR nor another available viewer confirmed.

### Always validate from the actual code

- When doing anything, check how it actually works in the code first.