Contributing

Three paths, and they suit different moments.

A trap, from where you hit it

You just lost an hour to something. That is the moment the detail is still in your head, and it is the moment you are least willing to open a browser. Call the tool instead:

{
  "library": "better-auth",
  "version": "1.7.3",
  "symptom": "Role changes do not reach the session until the cookie cache expires.",
  "fix": "Disable session.cookieCache for role-gated apps, or call auth.api.getSession with disableCookieCache on routes that check roles, and invalidate the session on role change.",
  "evidence_url": "https://github.com/better-auth/better-auth/issues/1234"
}

submit_trap needs a key, because a submission is attached to an identity a reviewer can write back to. A free key is enough. It returns a submission id and nothing else is served until a person reproduces it. Expect days, not minutes.

What makes a submission easy to verify: an exact version, a symptom written as the thing you observed rather than the thing you concluded, a fix someone can paste, and a link to an issue, a commit, or a changelog entry. What makes one hard: "sometimes breaks", a version range you guessed, or a fix that is really a workaround for a different bug.

Accepted submissions become a trap row in review status against the library, creating the library entry if the corpus does not have one yet. A reviewer then publishes it or leaves a note on why not.

A verdict, as a pull request

A verdict is a bigger claim and it goes through review in the open. Fork WellWorn-dev/wellworn, add one YAML file at verdicts/<kind>/<slug>.yaml, and open a pull request. The format page has the fields.

Run the validator before you push. It is what CI runs on every pull request, and it needs no dependencies:

pnpm validate:verdicts

It checks the six required fields, that the kind matches the folder, that the slug matches the file name, that exactly one node has role pick, and that every source carries both a URL and a fetched_at date. It prints one line per file with problems and a count at the end.

Nothing merges automatically. A reviewer takes the pull request into the review queue, and the publish stamps verified_by, verified_at and expires_at from the reviewer rather than from your file. How verdicts are made has the rest.

What a reviewer checks

Beyond the mechanical checks, three questions decide it. Is every source dated and reachable, and does it actually say what the verdict says it says. Is alt_wins_when a real condition somebody could test their own project against, rather than a hedge. Would the pick still be right for someone whose constraints differ from yours in one way, and if not, is that difference written down.

Verdicts are CC BY-SA 4.0. You keep authorship credit on the page, and the corpus stays reusable.

A verdict that is wrong

Every verdict page carries a Dispute this verdict button. It opens a mail to support@wellworn.dev with the verdict slug in the subject, and it goes to the same review queue as submissions. Say which claim is wrong and what you observed instead; a verdict that loses its evidence is retired rather than edited quietly, so a dispute that lands is visible in the corpus history.

Trap rows carry their evidence link on the trap page for the library, which is usually the fastest way to check whether a warning still holds before you dispute it.

Something missing rather than something wrong

If there is no verdict for a question you keep asking, the request page is the shortest path: one sentence for the question, then your constraints. Requests with a real constraint list get written first, because they are the ones that can be answered rather than argued about.