Contributions of any kind are welcome.
Feel free to submit Github Issues or pull requests.
The documentation site has some details about internals.
-
Fork the repo.
-
Checkout the branch you want to make changes on.
- Typically, this will be
master. Note that most of the time,masterrepresents the next release of swagger-php, so Pull Requests that break backwards compatibility might be postponed.
- Typically, this will be
-
Install dependencies:
composer install. -
Create a new branch named
type/short-description, e.g.feat/encoding-shortcutorfix/empty-schema-serialization. -
Make changes.
-
If you are adding functionality or fixing a bug - add a test!
Prefer adding new test cases over modifying existing ones.
- Tests pass —
composer test - Static analysis is clean —
composer analyse - Code style is clean —
composer lintto check,composer csandcomposer rectorto fix - Reference docs regenerated —
composer docs:genleaves no diff - Hand-written docs updated for any behaviour or API change
composer docs:gen only rebuilds the generated pages; everything else under docs/ is
hand-written and will not update itself. See docs/dev/ for which is which, and
for the conventions those pages follow.
Pull request titles follow type(Scope): subject, e.g. feat(Spec): add encoding shortcut.
Pull request descriptions follow the template: a short Overview explaining why the change exists, in plain language — the problem, not the implementation — followed by a Changes list of the key changes, kept high level and free of code snippets unless one is genuinely unavoidable. Wrap class names, method calls, file paths and other identifiers in backticks.
A Changes entry names what moved, in one line; the diff is what says how. A condition, a count, a signature or a renamed method's new behaviour is something the reader gets by opening the diff, and restating it buries the one or two entries that carry the shape of the change. The Overview holds the reasoning, so an entry needs no because.
Keep the description to the changes at hand. History that lives elsewhere — earlier attempts, abandoned branches, related work in other pull requests — belongs in the issue or commit trail, not here, unless it has a direct bearing on the change being reviewed.
The prose rules in Writing documentation apply to descriptions and commit messages as well as to pages: state a fact once, do not claim what you have not verified, no marketing filler, no volatile values, no line-number citations.
Commit subjects follow the same type(Scope): subject shape as the title, with type one
of feat, fix, docs, test, chore or refactor. A commit message body documents
what the diff does; the reasoning belongs in the pull request description.
swagger-php follows semantic versioning. What a change earns:
Patch — a fix that changes generated output only where the old output was wrong, an internal refactor, a documentation or CI change. Anything a consumer can take without reading the release notes.
Minor — new public API, a new annotation or attribute, a new field on an existing one,
and any widening of a require constraint. A dependency change is a minor even when it
only widens: a patch is expected to be a drop-in with no effect on resolution, and widening
lets consumers install combinations that were impossible before.
Major — removing or re-signing public API, narrowing a require constraint, raising the
PHP floor, or changing generated output that a correct document could have depended on.
The commit type does not decide this. #2196 carried no feat — its subject is "Drop
symfony/console 7.4 requirement", which reads like a fix — but it is a minor, because
applications on Symfony 6.4 that could not install the library at all now can. Read the
effect on a consumer, not the prefix. The reverse holds too: a feat that only adds a test
helper changes nothing for anyone and is not a minor on its own.
Generated output is the case that needs care, because most fixes here change it. Correcting output that was invalid, or that no valid document could have relied on, is a patch — that is the bug being fixed. Changing output that was already valid is at least a minor, even when the new output is better, because a consumer's committed spec file or downstream generator will see a diff it did not ask for.
Public API is every class under src/ that a consumer can reach, which today means all of
them — nothing is marked @internal. In practice the classes people build on are Generator,
the analysers and processors, the annotations and attributes, and the Spec classes; the
Console classes exist for bin/openapi and are reached through the command line rather than
extended. That is a description of how things are used, not a promise, so when a change touches
a class outside that list, say so in the pull request rather than assuming nobody is on it.
If a release mixes levels, the highest one wins.
The documentation website is build from the docs folder with vitepress.
This process involves converting the existing markdown (.md) files into static HTML pages and publishing them.
Some reference content is based on the existing code, so changes to annotations, attributes and processors will require to re-generate those markdown files: composer docs:gen.
The actual published content is managed in the gh-pages branch and driven by a publish action.
composer test
composer test -- --filter CompilerTest # a single test classcomposer analysecomposer docs:gencomposer lintcomposer lint runs both php-cs-fixer and rector in dry-run mode, so a failure can come
from either. Apply the fixes with:
composer cs # php-cs-fixer
composer rector # rectorcomposer redoclycomposer docs:dev