PureJsImage
GitHub

Contributing

Contribution requirements.

Changes must follow the repository’s TypeScript, dependency, testing, benchmark, documentation, and changelog requirements.

Pull requests to mainTests requiredMIT licensed

Scope and requirements

Focused bug fixes and performance improvements are welcome when they include tests, leave the complete suite passing, and follow the performance and code-style rules in AGENTS.md.

  • Add a focused regression test for every behavior change.
  • Include reproducible before-and-after measurements for performance claims.
  • Validate output correctness before counting benchmark timing.
  • Prefer direct fixes that reduce work, memory traffic, or allocation pressure.

Adding functionality

Explain why the feature belongs in PureJsImage and compare its technical value with its bundle-size, memory, maintenance, and API cost.

For a substantial addition to the core or a default entry point, you may open an issue or discussion first. This is encouraged when the design or bundle impact is uncertain, but it is not required.

Module boundaries. A transform, codec, provider, or other feature that can use a separate explicit import should remain outside the default bundle. A focused pull request does not require a prior issue.

The optimized TypeScript engine remains the default reference and fallback. Optional WASM and future WebGPU providers require explicit imports and registration and must never load or bundle themselves by default. An accelerator must preserve exact pipeline semantics and decline work it cannot express equivalently.

Tests and benchmarks

Install the locked dependencies and run the full repository gate:

Terminal
npm ci
npm run check

Also run the narrowest relevant fixture verifier or benchmark. Performance pull requests should report representative wall time and peak RSS, plus throughput, allocations, output size, or lossy quality when those measurements matter.

Benchmark validity. Unsupported, corrupt, or invalid output is a failed benchmark regardless of speed.

APIs, docs, and changelog

Any change that adds or extends a public API must update the root README and the applicable public documentation pages. Keep capability claims exact and document unsupported boundaries.

Every pull request must add a concise entry to the appropriate heading under [Unreleased] in CHANGELOG.md. Do not change the package version or prepare a release. Release manager Aaron Decker (a-r-d) moves those entries into releases.

Code, AI, and tooling

  • Follow all strict TypeScript, dependency, memory, hot-path, test, and benchmark requirements in AGENTS.md.
  • If you use an AI coding tool, tell it to read and follow AGENTS.md before it changes the repository. You remain responsible for reviewing its output.
  • Do not change formatter or linter settings without discussing the proposal with the maintainer first.
  • Keep the published package free of runtime dependencies and do not disguise third-party production codec implementations as local code.

Open the pull request

  1. Target the main branch directly.
  2. Update your branch from the latest main and resolve every conflict locally.
  3. Run npm run check and the relevant fixtures or benchmarks.
  4. Include the documentation and [Unreleased] changelog updates.
  5. Describe the problem, approach, evidence, and any bundle-size, compatibility, or memory tradeoffs.

Keep the pull request conflict-free and limited to one coherent change. An issue is optional; a clear pull request with evidence is enough for a modular, self-contained addition.

License and contact

All contributions are submitted under the repository’s MIT License. By opening a pull request, you agree that your contribution may be distributed under that license.

Questions can be directed to Aaron Decker through www.ard.ninja.