Contributing

View Source

Start with the architecture, testing guide and script guide. They explain where code belongs, how to write focused tests and how to run the required checks. For using the library in an application, see the user guide.

Set up a checkout

Install a supported Elixir release and compatible Erlang/OTP. The testing guide lists the supported runtime images and platform prerequisites. Use your preferred runtime installer; commands prefixed with mise exec -- use mise when available.

Fork the repository, clone your fork and create a branch:

git clone https://github.com/YOUR_USERNAME/native_elixir_pdf_utilities.git
cd native_elixir_pdf_utilities
git switch -c my-change
mix deps.get

Make and check a change

Keep the change focused. Public functions need @doc and @spec. Validators own input and semantic rules; consumers use their validated results. Recoverable public failures use shared diagnostics, and tunable resource ceilings belong in NativeElixirPdfUtilities.Limits.

Name source files for their module and tests for their observable behavior. Use synthetic fixture data. Rendering changes need focused unit coverage and browser parity fixtures when the output changes visibly. Run focused checks while working, then run the complete quality matrix before submitting a pull request:

./scripts/quality-matrix

The testing guide covers coverage, performance, Chromium comparisons, warnings and result interpretation. Local validation and required CI checks must pass. Report any check you could not run and have a maintainer complete it before the change is ready.

Document a change

Update the relevant user guide when supported behavior changes. Keep reusable architecture, testing and contribution procedures in docs/contributing/.

Put implementation plans, wave records, investigations, audits and temporary coverage inventories in ignored tmp/. Keep validation logs and measurement artifacts in ignored .quality/. Never stage, commit, push, publish or package those local records.

Try the manual app

The separate manual application exercises rendering and PDF editing workflows:

cd dev/manual_web
mix deps.get
mix run --no-halt

Open the app or its OpenAPI document. Use synthetic fixture files. The app is development tooling and is not included in the Hex package.

Submit a change or report a problem

Review everything you submit, including code produced with AI tools. Push your branch to your fork and open a pull request against main. Describe the problem, resulting behavior, validation and any unresolved warnings. Address review feedback and rerun affected checks after changes. The maintainer decides when to release.

For a bug report, include the library version, a small synthetic reproduction, expected behavior and diagnostics. Follow the security policy for private vulnerability reports.