Wild HQ repositories live on GitHub under wildbasehq and are mirrored into Wildbase Work. Code review happens on GitHub. Issues, project status, and the durable reason for the work live in Wildbase Work.

Repository-local instructions win when they are more specific than this page. If they contradict this page in a meaningful way, fix the contradiction rather than quietly choosing whichever rule is easier.

These rules apply prospectively to new contributions from this page’s review date. Earlier repository history remains part of the record; it is not rewritten to pretend the rules already existed.

Repository-specific procedures live in Doing the work and Running Packbase. Use those pages for local commands, frontend and API recipes, database changes, releases, and incident response.

Access and identity

Ask for GitHub organisation access when a task needs it. Multi-factor authentication is required.

All commits must be GPG signed. No exceptions.

git config --local commit.gpgsign true
git config --local user.signingkey YOUR_KEY_ID

Some password managers and developer tools can manage signing keys. Whatever tool you use, verify that GitHub shows the commit as verified before relying on it.

Ownership and licensing

Copyright does not move by assumption. A repository’s licence, contribution guide, and any separately accepted contributor terms govern how a contribution may be used.

If a repository does not yet publish those terms, ask before making a substantial contribution and fix that gap before inviting broader work. This handbook does not assign anyone’s copyright or replace a contribution agreement.

Commits and branches

Use Conventional Commits. Keep the subject under 50 characters and use the body for context that will matter later.

feat: add account export
fix: preserve feed ordering
docs: explain recovery steps
refactor: simplify route parsing

Name branches for the kind of change and its subject:

feature/account-export
fix/feed-ordering
refactor/route-parsing

Prefer a small series of understandable commits over one mystery dump. Do not rewrite published history other people may be using without coordinating first.

Pull requests come first

Open a draft pull request before writing substantial code. The first version can contain only the linked Wildbase Work task, the problem, the intended approach, and the checks you expect to run. Early visibility is cheaper than reviewing a finished wrong turn.

Every pull request must:

  • link to its Wildbase Work task;
  • explain the user-visible or operational effect;
  • identify important risks and deliberate omissions;
  • include an honest test plan;
  • receive at least one approval; and
  • pass the repository’s required checks.

Do not commit directly to the default branch. Everything goes through a pull request. This includes maintainers and people with administrative access.

Request review while the change is still easy to reshape. A reviewer checks behaviour, safety, clarity, and fit—not whether the author types code the same way they do.

Start with the domain

Model the thing before its infrastructure:

  1. define the core types, states, and behaviours;
  2. make relationships and invalid states explicit;
  3. build pure business rules where practical;
  4. add persistence, frameworks, queues, and transport at the edges.

For TypeScript:

  • keep strict mode enabled;
  • do not use any without a written, local justification;
  • prefer inference when the type is already obvious;
  • use literal and discriminated unions for meaningful states; and
  • make impossible states difficult to represent.

Use each repository’s existing runtime. The Packbase server is TypeScript on Node.js, Packbase web currently invokes Bun for scripts, and this site uses Node.js and Astro. TypeScript with Bun is the starting preference for a new service only when no existing system already owns the work. Existing boring technology gets first refusal; a new runtime or dependency has to earn its ongoing cost.

Test the claim

There is no universal coverage number. Every change does need proportionate evidence that its claim is true.

  • A bug fix gets a regression test when the failure can be reproduced reliably.
  • Business rules and data transformations prefer fast automated tests.
  • Risky migrations need a recovery or rollback plan.
  • Interface work checks keyboard use, narrow layouts, long content, loading, empty, error, and reduced-motion states as relevant.
  • A change that cannot be tested explains why, what was checked instead, and what uncertainty remains.

CI passing is necessary, not proof that the product works. Read the diff and exercise the behaviour that changed.

When things break

Do not panic. Then panic briefly if it helps. Then make the situation smaller.

For a hotfix:

  1. create an urgent Wildbase Work task;
  2. branch from the default branch;
  3. make the smallest change that stops the harm;
  4. fast-track review and the relevant checks;
  5. deploy or release;
  6. verify the affected behaviour; and
  7. record the cause, remaining risk, and follow-up work.

Fix forward when that is safer than rollback. Protect people and data before protecting elegance.

There is no break-glass exception to signed commits, pull requests, approval, required CI, or default-branch protection. If no reviewer is available, use an authorised non-code mitigation such as maintenance mode or a documented rollback to a known revision, or wait for review. Do not turn urgency into an unreviewed code path.

Incident notes explain the system, context, detection, and safeguards that failed. They do not turn a good-faith mistake into a culprit story.

The quality bar

Code should be readable by a volunteer returning months later, straightforward to verify, safe to change, and fast enough for the people using it. Cleverness has to pay rent.

LLM and AI tools

LLMs may assist with tab completion and autofill. They are not authors, reviewers, or autonomous workers. Agents and autonomous coding tasks are not allowed for Wild HQ code.

At least 90% of every contribution must be written by a person; aim higher. That allowance covers small inline completions, not generated features, pull requests, migrations, tests, reviews, or operational changes. A volunteer remains responsible for every line they submit and must be able to explain and defend it during review or whenever a collaborator asks.

Even for inline completion:

  • no password, token, private key, recovery code, personal or customer data, security report, or confidential agreement is sent to any AI service;
  • the volunteer reads and understands the resulting change;
  • ordinary review, signing, and testing rules still apply; and
  • the tool does not approve, merge, deploy, release, moderate, or vote in a person’s place.

Wild HQ does not grant or reimburse AI subscriptions, tokens, or credits. Prefer on-device completion when it is capable, so repository material stays on the device.

→Testing and documentationHow to choose proportionate checks, report evidence honestly, and keep repository and handbook guidance aligned with reality.