Documentation
Deploy
Docs

Contributing Guide

Thank you for considering a contribution to MonkeysLegion!

Whether you’re fixing a typo, adding tests, or building an entire package, your help makes the framework better for everyone.

1 · Before you start

  1. Search existing issues / PRs – the idea might already be in flight.

  2. Read the Code of Conduct – we enforce a friendly, inclusive space.

  3. Pick the right repo – every package lives in its own GitHub repository under MonkeysCloud. Open issues & PRs there, not in the monorepo.

2 · Local setup

git clone https://github.com/MonkeysCloud/MonkeysLegion-Skeleton.git monkeyslegion
cd monkeyslegion
composer install
cp .env.example .env     # set DB creds if the package needs one
vendor/bin/ml serve      # optional: dev server
vendor/bin/phpunit       # run the test suite

Tip: Most packages don’t require MySQL—SQLite :memory: works for tests.

3 · Branching & naming

Type

Branch prefix

Examples

Bug fix

fix/

fix/router-trailing-slash

Feature

feat/

feat/validation-sameas

Docs

docs/

docs/add-testing-guide

Refactor

ref/

ref/entity-scanner-speed

Fork → create a branch → commit → push.

4 · Commit message style

feat(router): add trailing slash redirect
Closes #123

  • Start with type(scope): summary, max 72-char.

  • Body (optional) explains why.

  • Reference the issue number so GitHub auto-links.

5 · Coding standards

  • PSR-12 formatting (phpcs --standard=PSR12).

  • Strict types at file top: declare(strict_types=1);.

  • Null-safe, typed properties, promoted constructors.

  • Psalm level 6 (or higher) passes with no errors.

  • No global helpers inside packages—use proper DI.

Run locally:

composer analyse   # psalm + phpcs
composer test      # phpunit + coverage

6 · Tests & coverage

  • Unit tests for pure functions / services.

  • Feature tests for middleware, controllers, CLI commands.

  • Target ≥ 80 % line coverage for new code.

  • Use SQLite :memory: for DB tests unless MySQL-specific SQL is required.

  • Snapshot UI tests (Playwright) must have a base image in tests/Playwright/_snapshots.

7 · Documentation

  • Update package README and /docs/package-name.md.

  • Code examples must run on PHP 8.4.

  • Screenshots or diagrams go in docs/_static/.

8 · Opening a pull request

  1. Push your branch to your fork.

  2. Open a PR against main of the package repo.

  3. Fill out the PR template:

    • About / Why

    • Changes introduced

    • QA steps

    • Checklist (tests, docs, changelog)

  4. CI must be green (GitHub Actions run tests, Psalm, PHPCS, Playwright).

A maintainer will review within a few days; small patches usually merge quickly, larger features may need design discussion.

9 · Changelog

Add an entry in CHANGELOG.md under ## [Unreleased]:

### Added
- Router: new `trailingSlashRedirect()` helper. (#123 by @yourhandle)

Follow Keep a Changelog format.

10 · Release process (for maintainers)

  1. git tag vX.Y.Z && git push --tags

  2. GitHub Action builds & publishes the tagged Composer package.

  3. Draft release notes from CHANGELOG.md, publish on GitHub.

11 · Contributor license

By submitting a PR, you agree your code is released under the package’s MIT license.

12 · Need help?

  • Slack: #monkeyslegion-dev

  • GitHub Discussions: ask architecture questions or request feedback before coding.

  • Office Hours: core maintainers host a 30-min Zoom every first Friday.

We’re excited to see what you’ll build—welcome to the Legion! 🐒🎉