Contributing

Thanks for your interest in swatch. Contributions of all sizes are welcome — bug reports, fixes, broader CSS coverage, docs, and examples.

Before you start

For anything beyond a small fix or typo, please open an issue first to discuss the change. This avoids duplicated effort and gives a chance to agree on the shape of the API before code is written.

Development

You’ll need Gleam (>= 1.16) and Erlang/OTP 28.

gleam deps download   # Fetch dependencies
gleam test            # Run the test suite
gleam format src test # Format the code
gleam build           # Compile

CI runs gleam test and gleam format --check src test. Both must pass before a PR can merge, so format locally before pushing.

Snapshot tests use birdie. When you change tokenising or rendering output, run gleam run -m birdie to review and accept new snapshots, then commit the updated files under birdie_snapshots/.

Pull requests

• Fork the repository, create a branch off main in your fork, and open the PR against scott-ray-wilson/swatch’s main.
• Keep the change focused — one logical change per PR.
• Add or update tests for any behavior change. For changes that affect tokenising or rendered output, add a birdie snapshot covering the new case.
• Add an entry to CHANGELOG.md under an ## [Unreleased] section at the top, creating the section if one doesn’t yet exist. Follow the Keep a Changelog format used by existing entries.

Commit messages

This project follows Conventional Commits. Common prefixes used here:

• feat: — new functionality
• fix: — bug fix
• docs: — documentation only
• refactor: — code change that neither fixes a bug nor adds a feature
• style: — formatting/whitespace only, no code change
• chore: — tooling, deps, release prep
• Append ! (e.g. refactor!:) for breaking changes.

Releases

Releases are cut by the maintainer. Tagging vX.Y.Z triggers the release workflow, which publishes to Hex and creates a GitHub release from the matching CHANGELOG.md entry.