Files
poli0981andClaude Opus 5.5 eabffbe652 feat(repo): maintenance mode, with triage that closes out-of-policy requests
MAINTENANCE.md is the policy: dependency updates on a schedule, high and
critical advisories fixed as soon as a fix exists, major platform upgrades,
bug/UI/UX/accessibility/translation fixes, and features only when they are
on docs/15's roadmap or genuinely needed.

- The feature form asks one required question — on the roadmap, needed for
  a fix, or something new — and links the policy and Discussions › Ideas.
- scripts/triage.mjs decides what happens, as a pure, unit-tested function;
  .github/workflows/triage.yml carries it out with `gh` alone. Something new
  is labelled maintenance-mode, commented and closed as not planned; the two
  in-policy answers get needs-triage; an outside `feat…` pull request is
  closed the same way. Owner, members, collaborators, bots and `roadmap` are
  exempt.
- pull_request_target checks out the base branch only, runs nothing from the
  pull request, and never interpolates a title or body into the shell.
- README gains a status badge and a "Project status" section; CONTRIBUTING,
  the PR template and the issue chooser say what is accepted.
- docs: 00 status, 11 inventory, 12 §2.6 and §5 (labels), 13 §6, 15 (a
  pointer to the policy, not a copy, and the decision-log rows); CLAUDE.md
  Phase 10.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 21:03:47 +07:00

10 KiB
Raw Permalink Blame History

Contributing to BookmarkMagic

Bug reports, parser samples and translation fixes are all genuinely useful, and none of them requires you to write code. If you only want to report something, open an issue and stop reading here — the forms ask for what is needed.

Security problems go through SECURITY.md, never a public issue.

The project is in maintenance mode (MAINTENANCE.md). What it takes: bug, UI/UX and accessibility fixes; translation fixes (wording wrong for a language or region, misleading spelling); dependency and security updates; major platform upgrades; and features that are already on the roadmap or genuinely needed. A feature request for something new, or a pull request titled feat… from outside the project, is closed automatically and labelled maintenance-mode — read, not deleted, and reopened if it fits. Ideas belong in Discussions › Ideas.

If something is hard or impossible to use — with a keyboard, a screen reader, a contrast theme, zoom — that is a defect, and it has its own form. ACCESSIBILITY.md says what is already known and how a report is handled.

Reporting a bookmark file that will not import

This is the most valuable report this project gets, because a sample becomes a permanent test and the bug can then never come back.

Sanitize the file first. From a clone of this repository:

node scripts/sanitize-bookmarks.mjs your-bookmarks.html

It needs nothing installed — plain Node. It writes your-bookmarks.sanitized.html next to the original, and prints what it found.

It reads the usual bookmarks.html export, a BookmarkMagic JSON file, Chrome's profile Bookmarks file (also Edge, Brave and Vivaldi), a Firefox bookmarks-YYYY-MM-DD.json backup, and our CSV. It refuses anything else rather than guess, and it refuses to write if its own output still looks personal.

What it destroys: every hostname, path, query value and fragment; every bookmark and folder title and description; Firefox keywords and tags; favicon data; local file: paths; in JSON, every string except structural fields (types, ids, timestamps), including Chrome's meta_info and sync blob.

What it keeps, because this is where the bug lives: the byte order mark, the doctype, the <META> line, comments, line endings, indentation, tag and attribute case, quoting style, attribute order, the tree's shape and depth, every timestamp exactly as written, whether a URL had a port, how deep its path was, whether it ended in a slash, how many query parameters it had, whether there was a fragment, any percent-escapes, and any HTML entities in a title. Distinct hosts stay distinct, so duplicate-detection bugs survive too.

That combination is the point: the sanitized file still reproduces the problem, without telling us where you browse. A test in tests/unit/scripts/ asserts exactly that against every fixture in the repo.

Please do not send a real bookmarks file — an export is a browsing history. Anything you attach to a GitHub issue is public and permanent; see legal/PRIVACY.md for what happens to anything you email.

Suggesting a translation fix

You do not need to clone anything. Use the translation issue form: the language, where the text appears, what it says now, and what it should say. Vietnamese is reviewed by the maintainer; Japanese, Simplified Chinese and Romanian are best-effort until a native pass, so corrections in those three are especially welcome.

One constraint if you send the change yourself: placeholders like {n} or {name} must appear in the translation exactly as in English — same names, same count. A build gate enforces it.

Setting up to write code

Node 26 or newer (see .nvmrc).

npm ci
npx wxt prepare
npm run verify

wxt prepare is not optional: tsconfig.json extends ./.wxt/tsconfig.json, which does not exist until it has run.

Using a git worktree? It needs its own npm ci and npx wxt prepare. With an empty node_modules/ the packages resolve upward from the parent checkout and almost everything appears to work — but knip then reports every devDependency as unused and verify fails in a way that looks like your change broke something.

Then npm run dev and load .output/chrome-mv3 at chrome://extensions with Developer mode on.

npm run verify runs lint, type-check, knip, the grep gate, the licence gate (npm run check:licenses) and the tests. It must be green before every commit. For anything release-bearing use npm run verify:full, which additionally runs coverage, the build, and the gate that inspects the built manifest — verify alone is weaker than what CI and a release tag enforce.

The rules that are not negotiable

These are what the extension promises in its store listing and privacy policy, so they are not style preferences:

  • Zero runtime dependencies. Not "few". A new one needs discussion first.
  • Exactly two permissions, bookmarks and storage. Changing that list is a minor-version event that also requires re-certifying the store's privacy answers.
  • No network access of any kind — no fetch, XMLHttpRequest, WebSocket, EventSource or sendBeacon. npm run guard fails the build on any of them.
  • No eval, {@html} or innerHTML. File content reaches the DOM as text.
  • src/lib/core/ is pure: it imports nothing from browser/, stores/, Svelte or chrome.*.
  • Files stay under 300 lines (hard limit 500), functions under 50 (hard 80).
  • Every user-visible string is an i18n key present in every locale (en, vi, ja, zh-CN, ro — LOCALES in src/lib/i18n/resolve-locale.ts).

CLAUDE.md is the entry point and docs/ is the binding specification — where code and docs disagree, the docs win. A behaviour change that skips its doc leaves the spec lying, which is why the PR checklist asks about it.

Changing the interface

ACCESSIBILITY.md tells users what works; docs/06 §5 is the specification behind it. A change to a component has to keep both true:

  • Keyboard. Whatever a pointer can do, a key can do. A control that is not a tab stop on purpose (the tree's row buttons) has its key documented.
  • Focus. Always visible — check it on a control with a filled background, where the default ring can vanish into the fill — and never dropped: when the focused thing goes away, focus is put somewhere deliberate (src/lib/components/focus-heading.ts has the helpers).
  • Names. Icons are decorative; the control carries the name. Anything a screen reader speaks is an i18n key in every locale.
  • Not colour alone, not motion. A state shown by a fill or a shadow needs a forced-colors equivalent; anything that moves sits behind prefers-reduced-motion: no-preference. Tests enforce the second (tests/unit/styles/motion.test.ts) and hold the list for the first (forced-colors.test.ts).
  • Native first. A <button>, a <dialog>, a <fieldset> before an ARIA role. A role is a promise of that role's keyboard behaviour: the previews lost role="tree" because they did not have the arrow keys.
  • Try it. Unplug the mouse, then run one screen reader over the screen you changed. Say in the PR which one, or that you could not.

There is no component test framework here, so logic that can leave a component does, and is tested where it lands (src/lib/edit/, src/lib/stores/).

Turning a reported file into a regression test

The full ritual, in order, because it is easy to do four fifths of it:

  1. Commit the sanitized sample to tests/fixtures/ (or weird/, or malformed/). Note that .gitattributes sets tests/fixtures/** -text, so line-ending normalization cannot rewrite the CRLF or BOM bytes the bug may depend on — do not "fix" that.
  2. Add the regression test to tests/unit/core/fixtures.test.ts, the only parser regression suite. A browser export goes in its BROWSER_EXPORTS array, which drives a shared set of assertions; anything else gets its own case. There is no shared fixture-loading helper — that file has its own loader.
  3. Fix the parser in src/lib/core/parse/. The test and the fix land in the same pull request; a fixture with no test is just a file.
  4. Write the quirk down in the parser source and in docs/04 §1.2. The format chapter is where the next person looks to understand why the code is shaped oddly.
  5. Update docs/11 §2's inventory and CHANGELOG.md's [Unreleased].

If the fix changes what a format is able to preserve, that is a specification change: update docs/04 first, then tests/helpers/tree.ts's project() — it models each format's documented lossiness, and widening it without the doc turns a real regression into a passing test.

Translations, in code

src/lib/i18n/locales/en.ts is the schema; every other locale (vi.ts, ja.ts, zh-CN.ts, ro.ts, each with its -notices and -import parts) is typed satisfies Dict against it, so a missing key is a compile error.

Never add as const to en.ts. It would make Dict a tree of string literal types, and every correct translation would become a type error — the only way to make the build pass would be leaving every other locale in English.

The gates that run on every change:

  • identical key paths across the locales;
  • identical interpolation tokens per string;
  • no empty leaves;
  • plural keys carrying exactly the forms the language needs: {one, other} everywhere, plus few in Romanian ("1 marcaj", "5 marcaje", "20 de marcaje");
  • language names written as endonyms, identical in every dictionary;
  • for Romanian, comma-below ș ț only, never the cedilla look-alikes.

See docs/07 for register and tone in each language. Adding a whole new language has its own checklist: docs/07 §6.

Commits and pull requests

Conventional Commits (fix(import): …, feat(edit): …, docs: …, chore(deps): …). Small commits, one concern each; tests land with or before the implementation. The PR template lists the rest.