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
| Repository | Holds |
|---|---|
| phaenonlang/phaenon | The 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/design | The language design and every decision, in Markdown: what the language is, what it will be, and why |
| phaenonlang/debug | The phaenon/debug package: reads the line map, and points production errors at .phn positions through Monolog and Sentry |
| phaenonlang/jetbrains | The PhpStorm plugin, in Kotlin |
| phaenonlang/vscode | The 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:
- 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. - Golden tests that fail. The checker's corpus is one
.phnfile per feature underinternal/checker/testdata/, each finding the checker must report marked on its line,// want P2202. The emitter's goldens are pairs,X.phnbeside theX.phpit must compile to. - The implementation.
- PHPStan on the output. The emitted PHP must pass
php -l, load underphpand pass PHPStan at level max with nothing beside it. The checker may be stricter than PHPStan, never more lenient. - 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/emitCI 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 asfix(checker): …orfeat(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, thenfixandrevert, 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 ingo.modis 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
.phnor.phpthat shows it, the command you ran, whatphnprinted and what you expected. Addphn version,php -v, your operating system and how you installedphn. For anything that is PHP, whatphpitself 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.mdsays what to include.
Contributions are licensed under the MIT license, as the rest of each repository is.