Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
123 lines (84 loc) · 4.2 KB

CONTRIBUTING.md

File metadata and controls

123 lines (84 loc) · 4.2 KB
Raw

Contributing

Thank you for contributing to this PHP legacy compatibility project.

Project Focus

This repository exists to help developers migrate old PHP applications to PHP 8.x without shipping dishonest compatibility code.

Primary use cases include:

  • WordPress legacy themes and plugins
  • Laravel legacy applications
  • Symfony legacy bundles
  • CodeIgniter 2 and 3 projects
  • Magento 1 and legacy Magento integrations
  • Custom PHP frameworks and enterprise systems

How to Contribute

  1. Fork the repository.
  2. Create a feature branch.
  3. Make focused changes with clear intent.
  4. Add or update documentation when behavior changes.
  5. Run syntax validation before opening a pull request.
  6. Submit a pull request with a clear problem statement and implementation summary.

Code Style Rules

  • Use clear procedural PHP where early bootstrap safety matters.
  • Keep all code and comments in English.
  • Prefer clarity over clever abstractions.
  • Preserve compatibility behavior only when it can be reproduced honestly.
  • Document every public helper or polyfill with a full docblock.
  • Keep section ordering logical and version-aware.

No Fake Fallbacks Policy

This repository does not accept:

  • fake success returns
  • dishonest stubs
  • fake extension recreations such as ext/mysql, ext/mcrypt, or fake crypto substitutes
  • silent data corruption disguised as compatibility
  • placeholders that only hide fatal errors without restoring meaningful behavior

If a behavior cannot be restored exactly, the closest practical approximation must be documented clearly, including the limitation and why it exists.

Composer and Bootstrap Rules

This package intentionally does not auto-load both compatibility files through Composer.

Why:

  • php-legacy-compat-universal.php and php-legacy-compat-strict.php are mutually exclusive
  • auto-loading both would mix two compatibility policies in the same runtime
  • projects must intentionally choose one mode during bootstrap

Contributions must preserve that design unless there is a very strong and clearly documented reason to change it.

Testing Expectations

At minimum, contributors should:

  • run php -l against changed PHP files
  • run the repository lint workflow locally when practical
  • test the changed behavior on PHP 8.0, 8.1, 8.2, or 8.3 when relevant
  • verify that universal and strict modes still remain intentionally different
  • check that no redeclaration or bootstrap-order issues were introduced

If a change affects a removed or deprecated function, include a small usage example or reproducible case in the pull request description.

Pull Request Guidelines

Pull requests should:

  • address a real compatibility problem
  • explain the original historical behavior
  • state whether the implementation is a true polyfill, partial polyfill, safe fallback, or compatibility approximation
  • document limitations honestly
  • avoid unrelated formatting churn

Good pull request summaries usually include:

  • the old failing code pattern
  • the PHP 8 error or regression it caused
  • why the new implementation is accurate enough to ship
  • what remains intentionally unsupported
  • what release impact the change has: patch, minor, or major

Versioning Guidance

This project follows semantic versioning.

  • patch: non-breaking fixes, docs, metadata, safer bug fixes
  • minor: new non-breaking compatibility coverage or helpers
  • major: breaking compatibility-policy changes, renamed files, removed APIs, or changed loading expectations

If you believe a change deserves a new version category, mention that in the pull request.

Documentation Contributions

Documentation improvements are welcome, especially for:

  • PHP 8 migration examples
  • WordPress migration scenarios
  • Laravel and Symfony upgrade notes
  • CodeIgniter and Magento legacy usage
  • search-friendly documentation improvements that remain technically honest
  • release documentation and Packagist install guidance

Reporting Issues

When opening an issue, include:

  • PHP version
  • which file you loaded: universal or strict
  • the failing legacy code sample
  • the actual error message
  • the expected legacy behavior

License

By contributing to this repository, you agree that your contributions will be licensed under the MIT License.