Contributing to DBIx::Fast

Thanks for helping! This file explains how the project is organised and what a change needs before it can be merged.

Where the code lives

• Public repository (GitHub): https://github.com/SeHarrys/dbix-fast - issues and pull requests are welcome there.
• Day-to-day development happens on the maintainer's private GitLab and is mirrored to GitHub, so a merged pull request is brought over by hand and shows up on GitHub with the next push.

Security issues: never open a public issue - see SECURITY.md.

Development setup

Perl 5.38+ and the dependencies from Makefile.PL (cpanm --installdeps .), plus the optional ones for full coverage:

cpanm LRU::Cache Cpanel::JSON::XS Term::ANSIColor CHI \
      DBD::SQLite DBD::MariaDB DBD::Pg \
      Test::Pod Test::Pod::Coverage Pod::Coverage Test::CPAN::Changes

The SQLite suite needs nothing else. ./dev/test.sh (repository only, not in the CPAN tarball) starts throwaway MariaDB, PostgreSQL and MySQL containers and runs everything:

./dev/test.sh          # containers + full suite (4 drivers + author tests)
./dev/test.sh release  # the pre-release gate

See dev/README.md for the details (driver client libraries, DBD::mysql on Debian, the release and full_release gates).

What a change needs

• Tests. A bug fix comes with a regression test that fails without the fix. Driver-specific behaviour gets a test under t/driver/ (they skip unless the DBIX_FAST_TEST_* variables are set).
• The whole suite green on all four drivers: ./dev/test.sh.
• Documentation. POD for every public method (enforced by t/pod.t), and every module keeps the standard sections - =encoding utf8, NAME, SYNOPSIS, SEE ALSO, AUTHOR, LICENSE (enforced by t/pod_sections.t).
• A line in Changes under the upcoming version - one short line per change (t/changes.t checks the format).

Code conventions

• use v5.38; and signatures; classes with Object::Pad 0.807.
• Values always go through placeholders; identifiers are validated and quoted (_safe_id, _quote_ident_path) - never interpolate data into SQL.
• JSON: Cpanel::JSON::XS, falling back to JSON::PP only because the former is an optional dependency.
• Errors: throw through Exception() (validation) or let the typed DBIx::Fast::X::DB classes carry driver errors; keep their text stable - applications match on it.
• Prefer simple, readable code over clever abstractions.

Commit messages

Say what changed and why; reference the test that covers it.