Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
143 lines (117 loc) · 5.75 KB

CONTRIBUTING.md

File metadata and controls

143 lines (117 loc) · 5.75 KB
Raw

Contributing to fastchart

Requirements

  • PHP 8.1 or later (debug build recommended for development: --enable-debug)

  • C compiler: GCC 11+, Clang 14+

  • phpize and php-config (from php-dev / php8.x-dev)

  • GNU Make

  • libpng, libjpeg-turbo, libwebp, FreeType development headers:

    • Debian / Ubuntu: apt install libpng-dev libjpeg-turbo8-dev libwebp-dev libfreetype-dev
    • RHEL / Fedora: dnf install libpng-devel libjpeg-turbo-devel libwebp-devel freetype-devel

    Probed via pkg-config in config.m4. plutovg + plutosvg are vendored under vendor/ — no install needed.

  • ext/gd is not a runtime requirement. The test suite uses ext/gd in roughly 90 PHPT files to round-trip raster output for pixel inspection; those tests SKIP cleanly when ext/gd isn't available. If you want to run the full suite, build ext/gd once against your PHP install (recipe in AGENTS.md).

Bug reports

Use the GitHub issue tracker. Include:

  • PHP version (php -v)
  • fastchart version (php -r 'echo phpversion("fastchart");')
  • plutovg version (vendored; report the vendor/plutovg/ git hash if known)
  • Operating system and compiler version
  • Minimal reproducing code: the chart class, the setters you called, the data array, and the rendered output (or crash trace) you got vs. expected
  • Any error messages, exceptions, or sanitiser output

Before filing, try to reproduce against the latest master branch.

For security issues, do not file a public issue. See SECURITY.md for the private reporting process.

Pull requests

  1. Fork and clone the repo.

  2. Create a topic branch off master.

  3. Make your changes.

  4. Add or update tests in tests/ (PHPT format).

  5. Build clean and run the full suite:

    ~/php-install-PHP-8.4/bin/phpize
./configure --with-php-config=$HOME/php-install-PHP-8.4/bin/php-config \
    --enable-fastchart --enable-fastchart-dev
make -j$(nproc)

ASAN_OPTIONS=detect_leaks=0 \
TEST_PHP_EXECUTABLE=$HOME/php-install-PHP-8.4/bin/php \
TEST_PHP_ARGS="-d extension=$HOME/php-src-8.4/ext/gd/modules/gd.so \
               -d extension=$(pwd)/modules/fastchart.so" \
NO_INTERACTION=1 \
$HOME/php-install-PHP-8.4/bin/php run-tests.php tests/

    detect_leaks=0 is for the routine local ext/gd sweep when using the ASAN debug PHP build described in AGENTS.md. The CI-style leak check uses detect_leaks=1 and the narrow suppressions file in .github/lsan-suppressions.txt; run that path when validating memory-management changes. For a quick render smoke without ext/gd:

    ~/php-install-PHP-8.4/bin/php \
    -d extension=$(pwd)/modules/fastchart.so \
    scripts/asan-render-smoke.php

    Any LeakSanitizer: detected memory leaks output is a fastchart regression and must be fixed before the PR lands.

  6. Verify zero compiler warnings (--enable-fastchart-dev adds -Werror -Wextra -Wstrict-prototypes; the release matrix treats any warning as a build failure) and that the full PHPT suite passes.

  7. Push and open a PR against master.

Commit message conventions

  • Short imperative subject line (≤ 72 chars).
  • Body wraps at 72 columns, explains why not what.
  • No Co-Authored-By lines. No AI attribution.
  • Audit the message against git show --stat HEAD before pushing. If the subject claims a fix in fastchart_axis.c, the diff had better show it.

Test guidelines

  • Tests use PHPT format. See existing tests under tests/ for shape.
  • Prefer exact-byte expectations via --EXPECT--. Use --EXPECTF-- only when the output legitimately varies (e.g. line numbers in exception traces).
  • Pixel-count tests (image-region color counts) need realistic thresholds: account for thick lines transiting the region, not just the swatch / fill the test is targeting. See tests/008_legend.phpt and tests/016_legend_position.phpt for the threshold-comment idiom.
  • Visual regressions: re-render the relevant docs/examples/*.png via the example scripts and eyeball the diff before opening the PR. The gallery is the de-facto visual baseline.

Code style

  • Tabs for indentation, K&R braces, follows the wider PHP-src convention.
  • Comments only when the why is non-obvious. Implementation detail doesn't need a comment; an external-API constraint (e.g. plutosvg's data-URI loader handling only PNG/JPEG) does.
  • File headers carry the BSD 3-Clause boxed comment plus an | Author: line. New files credit yourself there too.
  • Class registration goes through fastchart_arginfo.h, generated from fastchart.stub.php by ~/php-src/build/gen_stub.php. Do not hand-edit fastchart_arginfo.h. Run /php-stub-regen after any stub change.
  • Memory: use PHP's emalloc / efree at the Zend boundary. efree(NULL) is undefined behavior in Zend; keep the fc_efree_opt null-guard wrapper rather than removing it as "dead code".
  • Truecolor canvas only. fastchart_require_truecolor() rejects palette images at every draw() entry. New entry points must call it.
  • Per-class state lives on the chart's typed C struct (fastchart_<name>_obj), not the generic fastchart_obj. Setters parse user input into typed C arrays at setter time; draw() is pure rasterisation.

Release workflow

For maintainers cutting a new version: run /release-ext (or the /release shim). It reads .release-config, runs the build matrix (PHP 8.1 through 8.5), tags bare semver, drives the changelog date-stamping. CHANGELOG follows Keep-a-Changelog; the PHP_FASTCHART_VERSION literal in php_fastchart.h always holds the next-to-tag version (no -dev suffix).

License

By submitting a patch you agree to license your contribution under the same license as the project (BSD 3-Clause).