Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
86 lines (68 loc) · 3.66 KB

CONTRIBUTING.md

File metadata and controls

86 lines (68 loc) · 3.66 KB
Raw

Contributing

Thanks for taking the time. This is a small, dependency-free project and the bar for a good contribution is mostly "it is easy to review".

Getting set up

git clone https://github.com/css-scroll-driven/view-transition-debugger.git
cd view-transition-debugger
node --test "tests/*.test.js"

That is the whole setup. There is no install step, no bundler, and no dependencies — Node is needed only to run the tests.

To try your change in the browser: load the folder unpacked from chrome://extensions with Developer mode on, run the demo with python3 -m http.server 8000 --directory test-page, and exercise the panel against the pages there. After editing, press the reload icon on the extension's card, then reload the inspected page and reopen DevTools.

Reporting a bug

Please include:

  • Your Chrome version (from chrome://version).
  • Whether the transition is same-document or cross-document.
  • A minimal page that reproduces it, or the relevant part of the recorded transition from the panel.
  • What the panel showed versus what you expected.

Missing or wrong findings are especially useful reports — the rules are heuristics and they will have blind spots.

Making a change

  1. Open an issue first for anything larger than a bug fix, so we can agree on the approach before you write it.
  2. Branch from master.
  3. Keep the change focused. A pull request that fixes one thing gets merged; one that fixes one thing and reformats four files does not.
  4. Add tests. Any logic that can be a pure function in lib/ should be, and should come with cases in tests/.
  5. Run node --test "tests/*.test.js" before pushing. All tests must pass.
  6. Update CHANGELOG.md under an Unreleased heading, and update the README if you changed behaviour, a threshold, a rule, or the message protocol.

Project conventions

These are the rules that are easy to break by accident:

  • Content scripts must stay classic scripts. injected/instrument.js and content/bridge.js cannot use import or export — MV3 injects them as classic scripts. A test enforces this. Extension pages (panel/, devtools/) may use ES modules freely.
  • lib/ must stay pure. No DOM, no chrome.*, no globals beyond standard JavaScript, so everything there runs under node --test.
  • The protocol constants are duplicated on purpose. If you change a message type in lib/protocol.js, change the matching literal inside the >>> PROTOCOL block in injected/instrument.js. A test fails if they drift.
  • The instrumentation must never break the page it observes. Wrap anything that can throw. Never change what a page-visible promise resolves or rejects with. The invariants are listed in the comment above the patch — read them before touching it.
  • Never build DOM from strings in the panel. Record content comes from an untrusted page. Use textContent and element creation, as the existing helpers do.
  • Two-space indentation, semicolons, single quotes in JavaScript.

Adding a finding rule

  1. Write the rule as a pure function in lib/findings.js taking a record and returning an array of findings.
  2. Add its id to RULE_IDS. The RULE_IDS matches the rules that can actually fire test will fail until the rule can be triggered by a record.
  3. Give it a learnMore URL from the DOCS map.
  4. Add tests: one case where it fires, one just under the threshold where it does not, and one for malformed input.
  5. Add a row to the finding-rule table in README.md.
  6. If possible, plant a reproduction in test-page/broken.html.

Licence

By contributing you agree that your contribution is licensed under the MIT License.