ProjectContributing

Project

Contributing

The repositories of Phaenon, how a change is made and tested, the commit and pull request conventions, and where to report a bug.

Phaenon is open source under the MIT license and pre-alpha: the language and the command line still change between releases. A bug report with a small reproduction is the most useful contribution there is. A change to the language starts as a change to its design.

The repositories

RepositoryHolds
phaenonlang/phaenonThe compiler phn, in Go: lexer, parser, type checker, emitter, migrate, fmt, the language server; the signatures of PHP's own library it checks against; the phaenon/phn Composer plugin
phaenonlang/designThe language design and every decision, in Markdown: what the language is, what it will be, and why
phaenonlang/debugThe phaenon/debug package: reads the line map, and points production errors at .phn positions through Monolog and Sentry
phaenonlang/jetbrainsThe PhpStorm plugin, in Kotlin
phaenonlang/vscodeThe VS Code extension, in TypeScript

Each code repository has a CONTRIBUTING.md that says what a pull request to it must satisfy, and an AGENTS.md that maps its code and its tests. The README of design says how to propose a change to it.

How a change is made

Every feature of the language goes through the same five steps, in order:

  1. A design document. The feature is a section in its document in design, and the decision is a row in that document's decision section: what was decided and why. Where the draft text and a decision differ, the decision wins.
  2. Golden tests that fail. The checker's corpus is one .phn file per feature under internal/checker/testdata/, each finding the checker must report marked on its line, // want P2202. The emitter's goldens are pairs, X.phn beside the X.php it must compile to.
  3. The implementation.
  4. PHPStan on the output. The emitted PHP must pass php -l, load under php and pass PHPStan at level max with nothing beside it. The checker may be stricter than PHPStan, never more lenient.
  5. A real code base. A feature is done when a real project's own test suite, PHPStan and coding-style checks pass on its compiled output. The language is developed against the code of the platform behind tequila.dev, from its libraries to its services.

For everything that is PHP, php itself is the reference: the lexer, the parser and the printer are tested against the .phpt files of PHP's own source, with php as the oracle.

A change to the language (new syntax, a new diagnostic, a change in what the checker accepts or the emitter writes) starts as a pull request to design that edits the draft and adds the decision. The maintainers decide design changes, so open an issue to discuss the idea before you write the code.

Building and testing the compiler

The compiler needs the Go toolchain its go.mod names, Go 1.27, and nothing else: the module has no dependencies. With PHP 8.5 on your PATH, the tests that take php as the oracle run too.

go build -o bin/phn ./cmd/phn
go test ./...
ok  	github.com/phaenonlang/phaenon/cmd/phn	85.892s
?   	github.com/phaenonlang/phaenon/internal/ast	[no test files]
ok  	github.com/phaenonlang/phaenon/internal/checker	8.907s
…
ok  	github.com/phaenonlang/phaenon/internal/types	0.652s
?   	github.com/phaenonlang/phaenon/stdlib	[no test files]
ok  	github.com/phaenonlang/phaenon/stdlib/gen	0.756s
?   	github.com/phaenonlang/phaenon/tools/release	[no test files]

A green go test ./... does not run everything. The suites that need a clone of PHP's source, a PHPStan, a PHP 8.6 or Composer skip unless an environment variable names it; the compiler's AGENTS.md lists every variable. Run the ones your change touches.

Golden files are rewritten by the tests, never edited by hand, and their diff is read before it is committed:

PHAENON_UPDATE=1 go test ./internal/emit

CI runs gofmt -l, go vet (native and WebAssembly) and go test ./... on every pull request.

The other repositories build with their own tools: composer test and composer stan in debug, ./gradlew test in jetbrains, npm test in vscode. Their CONTRIBUTING.md files give the details, among them how to run an editor's tests against a phn you built.

Commits and pull requests

A pull request targets main. It is squash-merged, so its title becomes the commit on main, from which release-please sets the next version and writes the changelog. The pull request check holds it to Conventional Commits:

  • The title is type(scope): subject, such as fix(checker): … or feat(emit): …, with ! after the scope for a breaking change to the language or the command line.
  • Every commit in the pull request is a Conventional Commit too, with a body that says what changed and why.
  • The title's release impact is the highest of its commits': a breaking change, then feat, then fix and revert, then the rest (docs, refactor, test, build, ci, chore).

Beyond what CI checks, the compiler's conventions hold:

  • gofmt, and the standard library only: a new requirement in go.mod is the maintainers' decision.
  • Golden files and the embedded PHP stubs are byte-sensitive: no formatter or whitespace clean-up touches them.
  • A PHPStan rule the checker deliberately lacks goes into the allow-list in internal/checker/phpstan_test.go, with the reason.
  • Diagnostic codes are stable once published, one mistake to one diagnostic.
  • A language change links its change in design.

How Phaenon is developed

Phaenon is developed AI-first: agents built on Anthropic's Claude Fable models write most of the code and the documents, and every change is a pull request a maintainer reads before it merges. A contribution is reviewed the same way, whoever or whatever wrote it.

Reporting a bug

  • The compiler rejects, mistypes or miscompiles something, or a command misbehaves: open an issue on phaenonlang/phaenon with the smallest .phn or .php that shows it, the command you ran, what phn printed and what you expected. Add phn version, php -v, your operating system and how you installed phn. For anything that is PHP, what php itself does is the reference.
  • An editor misbehaves: open the issue on phaenonlang/jetbrains or phaenonlang/vscode.
  • An idea for the language: open a feature request on the compiler's repository, where it is discussed before anything is designed.
  • A security issue: never a public issue. Report it privately through GitHub's private vulnerability reporting; the compiler's SECURITY.md says what to include.

Contributions are licensed under the MIT license, as the rest of each repository is.