Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
79 lines (59 loc) · 2.88 KB

CONTRIBUTING.md

File metadata and controls

79 lines (59 loc) · 2.88 KB
Raw

Contributing

Thanks for taking an interest. This is a small, deliberately low-dependency project, so contributing should be quick to get started with.

Getting set up

git clone https://github.com/css-scroll-driven/scroll-anim-fallback.git
cd scroll-anim-fallback
npm install
npm test

postcss is the only dependency in the entire tree. There is no bundler, no transpiler, and no test framework — tests run on Node's built-in node --test runner.

Ground rules

Keep the dependency count at one. If a change needs a new runtime or build dependency, open an issue first and explain why hand-writing it is worse. The UMD bundle is produced by packages/scroll-anim-fallback-runtime/build.mjs, about eighty lines of string handling, and that is on purpose.

Every change to a parser or to the range math needs a test. Both are pure functions, so tests are a couple of lines. Range-math changes should cite the spec behaviour they implement in the test name or a comment.

Keep DOM code out of range-math.js. The value of that module is that it is testable in Node. Measurement belongs in src/dom.js, wiring in src/index.js.

The runtime must stay free in supported browsers. Any change that makes init() allocate, query the DOM, or attach a listener before the CSS.supports() check will be rejected.

House style

  • Node ESM everywhere; no CommonJS.
  • JSDoc type annotations on every exported function, including @param, @returns and a one-line description.
  • Two-space indentation, semicolons, single quotes.
  • No dead code, no commented-out blocks, no TODO markers left behind.
  • Comments explain why, not what.

Tests

npm test                                          # everything
node --test packages/postcss-scroll-anim-fallback/test/
node --test packages/scroll-anim-fallback-runtime/test/

npm test runs the runtime build first, because the bundle test evaluates the generated file.

Pull requests

  1. Branch from master.
  2. Make the change, add tests, run npm test.
  3. If you touched the plugin's output or the manifest shape, run npm run examples and check the demos still behave.
  4. If you changed anything users see — options, manifest fields, API — update README.md and add a CHANGELOG.md entry under an Unreleased heading.
  5. Keep the PR focused. One behaviour change per PR is much easier to review.

Reporting bugs

A fallback that looks wrong is usually a range-math or mode-selection issue. The most useful report includes:

  • the source CSS rule,
  • the manifest entry the plugin produced for it,
  • the browser and whether it has native animation-timeline support,
  • what you expected to see and what you saw.

If it is a progress-fidelity issue, logging --saf-progress alongside the native animation's currentTime in a supporting browser makes the discrepancy obvious very quickly.