The Joomla! Framework is developed by volunteers, and every contribution helps, whether it is a bug report, a fix, a test, a piece of documentation or an answer to somebody else's question.
Every package has its own repository in the Joomla! Framework GitHub organization, for example joomla-framework/application. Issues, pull requests and discussions are handled in the repository of the package they concern. The package status page lists all packages with their latest releases. Packages marked as abandoned are no longer maintained and their repositories are read-only.
The repositories share the same branch layout. Each major version is developed in its own branch:
| Branch | Version | Status |
|---|---|---|
4.x-dev |
Framework 4 (PHP 8.3+) | Current version and default branch: new features, bug fixes and security fixes |
3.x-dev |
Framework 3 | Security fixes only |
2.0-dev |
Framework 2 | No longer supported |
1.x-dev |
Framework 1 | No longer supported |
Pull requests, whether bug fixes or new features, should target 4.x-dev. The 3.x-dev branch only receives security fixes, which are handled through the Security Strike Team.
Open an issue in the repository of the affected package. Before you do, please check whether the issue has already been reported. The issue templates ask for the information we need:
For questions about using a package, please use the repository's Discussions or the mailing list instead of the issue tracker.
Please do not report security issues in public issues or pull requests. Report them to the Joomla! Security Strike Team through the contact form, with as much detail about the issue as possible.
You need PHP 8.3 or newer, Composer and Git. Fork the repository on GitHub, then clone your fork, check out the branch you want to target and install the dependencies:
git clone https://github.com/<your-username>/application.git
cd application
git checkout 4.x-dev
git checkout -b my-fix
composer installcomposer install also installs the tools used below: PHPUnit, PHP_CodeSniffer and PHPStan. Each repository has an .editorconfig file (4 spaces, LF line endings, UTF-8), which most editors pick up automatically.
The packages follow PSR-12, with no limit on the line length. The rules are defined in the ruleset.xml file of each repository and checked with PHP_CodeSniffer:
# Fix what can be fixed automatically, then list the remaining issues
composer style
# Run the same check as the CI
vendor/bin/phpcs --standard=ruleset.xml src/Most IDEs, for example PhpStorm and Visual Studio Code, can run PHP_CodeSniffer with the repository's ruleset.xml and show violations directly in the editor.
The code is analysed with PHPStan, using the configuration in phpstan.neon. Run it with vendor/bin/phpstan. Existing findings are recorded in phpstan-baseline.neon; new code should not add entries to the baseline.
Whether your pull request fixes a bug or adds a feature, please include unit tests for your change. The tests live in the Tests directory and use PHPUnit:
composer test # run the test suite
composer testdox # run it with readable test names
composer coverage # write an HTML coverage report to build/coverageThe CI runs the tests on all supported PHP versions (currently 8.3, 8.4 and 8.5), and once more with the lowest dependency versions the package allows. If your change depends on a newer version of a dependency, raise the version constraint in composer.json; you can reproduce that run with composer update --prefer-lowest.
Not everyone is familiar with PHPUnit, and that's fine. Submit your pull request anyway and ask for help; the maintainers and the community will help you write the tests.
Each package documents itself in its docs directory, written in GitHub Flavored Markdown. The documentation of the 3.x-dev and 4.x-dev branches is published in the documentation section of this site, and updated automatically after changes are merged.
index.md is the navigation of the package's documentation, it is shown as the sidebar on this site.overview.md introduces the package; it is the first page shown for a package.v3-to-v4-update.md (and the files for older versions) describe the changes that break backward compatibility between major versions.Links between documentation pages should be relative links to the Markdown files (for example [Configuration](configuration.md)); this site turns them into links to the corresponding pages.
When your pull request changes the behaviour of a package or adds a feature, please update the documentation in the same pull request. Changes that break backward compatibility must also be added to the update guide of the next major version.
Before you submit a pull request, make sure that the coding standards check, PHPStan and the tests pass locally. They also run automatically on every pull request, and should pass before it is merged. The pull request template asks for:
New classes, methods and properties need a @since tag in their docblock with the version they will be released in, for example @since 4.1.0. If you're not sure which version that will be, mention it in the pull request and the maintainers will set it.
Please be patient, as not every pull request can be reviewed right away by the Framework team, and be open to feedback. Maintainers and other community members may suggest changes or ask questions about your change. This is part of the review process and helps everyone understand the change and improve the code.
All contributors are expected to follow the Joomla! Code of Conduct. By contributing, you agree that your contribution is licensed under the GNU General Public License version 2 or later, the license of the Framework.