Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
82 lines (56 loc) · 3.78 KB

CONTRIBUTING.md

File metadata and controls

82 lines (56 loc) · 3.78 KB
Raw

Contributing to PHPantom

Thanks for your interest in contributing!

Getting Started

  1. Fork and clone the repository
  2. Follow the build instructions to get a working development environment
  3. Read ARCHITECTURE.md for an overview of how the codebase is structured

Before Submitting a PR

All six CI checks must pass with zero warnings and zero failures:

cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --check
find examples/php -name '*.php' -print0 | xargs -0 -n1 php -l
php -d zend.assertions=1 examples/php/scaffolding/assertions.php
php -l examples/laravel/app/Demo.php
phpantom_lsp analyze --project-root examples/laravel --no-colour

Note that clippy runs twice, once for library code and once including test code. The php -l checks ensure the examples/php/ playground remains valid PHP. The php -d zend.assertions=1 run executes assertions.php's runDemoAssertions() to verify that scaffolding/scaffolding.php's stubs actually return what their docblocks claim. The final php -l and phpantom_lsp analyze runs check examples/laravel/ for syntax errors and diagnostic regressions. app/Demo.php carries three deliberate mistakes: Artisan::call('does:not-exist') demonstrates invalid_laravel_command, and one view('welcome', …) call both leaves out a variable the template declares and passes a misspelled key, demonstrating missing_view_variable and unused_view_variable. So the analyze run must report exactly [ERROR] Found 3 errors on those two lines, not [OK] No errors; any other count, or an error on a different line, is a regression.

Code Style

  • Run cargo fmt before committing
  • Fix clippy warnings rather than suppressing them. Avoid #[allow(clippy::...)] unless truly necessary.
  • Add /// doc comments to all public functions and struct fields

Testing

  • Integration tests go in tests/completion_*.rs or tests/definition_*.rs, one file per feature area
  • Use create_test_backend() from tests/common/mod.rs for same-file tests
  • Use create_psr4_workspace() for cross-file / PSR-4 tests
  • Test the happy path, edge cases, and interactions with existing features
  • When adding a feature, update examples/php/demo.php with working examples (and verify with php -l examples/php/demo.php). For Laravel-specific features, also update examples/laravel/app/Demo.php (and verify with php -l examples/laravel/app/Demo.php).

See BUILDING.md for more on running tests and manual LSP testing.

Changelog

Update CHANGELOG.md when your PR adds, changes, or fixes something a user would notice. Add entries under ## [Unreleased] in the appropriate subsection (### Added, ### Fixed, ### Changed, or ### Removed). Write for end users, not developers: describe what changed in the editor, not which internal modules were touched. See the existing entries for the style and level of detail expected.

Documentation

The documentation site is built with Zensical. The only dependency you need is uv.

Preview the docs locally with live reload:

uv run zensical serve

Then open http://127.0.0.1:8000 in your browser. Changes to files in docs/ and zensical.toml are reflected immediately. If port 8000 is already in use, pick a different one:

uv run zensical serve -a 127.0.0.1:8200

Build the docs for offline use:

uv run zensical build

The output is written to site/ (gitignored). uv handles creating a virtual environment and installing all Python dependencies automatically on first run.

Reporting Issues

Open an issue on GitHub with:

  • What you expected to happen
  • What actually happened
  • Steps to reproduce (a minimal PHP snippet is ideal)