Contributing to the Joomla! Framework
As of June 2017, the individual repositories in the Joomla! Framework GitHub organization are generally structured the same.
Most repositories have two branches representing the two major Framework versions; 1.x and 2.0.
- Except for the noted exceptions below, the
masterbranch represents the stable 1.x branch and the
2.0-devbranch represents the upcoming 2.0 release
- The Crypt and Form packages use the
masterfor 2.0 and a
1.x-devbranch for 1.x
- The Log package has no 2.0 branch since this package has been deprecated
- The Renderer package is not part of Framework 1.x, therefore its
masterbranch represents the 2.0 release
Joomla! Framework packages are PSR-4 compliant and follow a common filesystem structure.
.github- GitHub repository metadata (contributing guidelines, issue and pull request templates)
.travis- Configuration files for the Travis-CI platform, including the directory where the PHP_CodeSniffer git submodule is checked out to
docs- As part of the Framework 2.0 release, documentation is being added to each package; this directory is not present in the 1.x branches
src- The production code for the package
tests- The test suite for the package
NOTE The Crypt and Form 1.x branches are still structured for PSR-0 support due to backward compatibility implications with migrating to PSR-4 and as such those branches have a slightly different repository structure. Additionally, the Session package's 1.x branch was not migrated to PSR-4 and still follows the PSR-0 structure.
Issue tracking and pull requests are managed via GitHub in each package's repository. All of the Framework's packages are listed under the Joomla! Framework organization. You can find the documentation about how to fork a repository and start contributing to the Joomla! Framework at https://help.github.com/articles/fork-a-repo.
All contributions are welcome to be submitted for review for inclusion in the Framework, but before they will be accepted, we ask that you follow these simple guidelines:
Please be patient as not all items will be tested or reviewed immediately by a Framework maintainer. Also be receptive to feedback about your changes to the Framework. The maintainer team and other community members may make suggestions or ask questions about your change. This is part of the review process, and helps everyone to understand what is happening, why it is happening, and potentially optimize your code.
Joomla! Contributor Agreement
Ideally, everybody who contributes to the Framework, or any other Open Source Matters (OSM) supported project for that matter, should sign the Joomla! Contributor Agreement (JCA). But, we are aware that some contributors will not want to take the extra effort, especially for one-time contributors of modest amounts of code. As a compromise, the Joomla! Project requires a JCA from anybody who makes a significant contribution to Joomla! or any other OSM project. "Significant" is, of course, a judgment call. As a general guideline, if you as an individual have contributed or intend to contribute over 100 lines of code to the Joomla! Framework, we will ask for you to sign the JCA. If you are contributing as an employee of a company (that is, the work you are contributing was done on company time) then we need a JCA with your company's signature no matter how small the contribution is.
When you add new classes, properties or methods, please use
__DEPLOY_VERSION__ in the
@since tags in Docblocks. We'll replace that marker with the actual version the changes are deployed in.
All submitted code must be compliant with the Joomla! Coding Standards. This standard is documented at https://developer.joomla.org/coding-standards.html. There is a tool called PHP_CodeSniffer that allows you to validate your code against the Joomla! Coding Standards.
Install & Use
PHP_CodeSniffer is installed as part of a
composer install, helpful when you are cloning a package's git repository. Please see https://github.com/squizlabs/PHP_CodeSniffer for more documentation on PHP_CodeSniffer.
The Framework repositories are in a state of transition presently with some repositories using the 1.x Coding Standards definition and some using our updated 2.x Coding Standards. The repositories running the 2.x definition require no additional setup instructions, however the 1.x definition requires ensuring the git submodule is correctly installed.
To run PHP_CodeSniffer with the Joomla! Coding Standards for repositories using the 1.x standard, you must download the standard. These packages can be identified by having a
"squizlabs/php_codesniffer": "1.*" dependency in the package's
composer.json file. When cloning a package's git repository, the coding standard is set up as a git submodule. To initialize the submodule and have the coding standard available for use, run
git submodule init.
Once PHP_CodeSniffer is installed and the Joomla! Coding Standards are downloaded, you can now check your code against the standard. The exact command to be run will vary based on the installed coding standards definition, therefore we suggest copying the command from the package's
Some editors support PHP_CodeSniffer as a plugin or a built in feature. It will allow you to see if your code matches the Joomla! standard directly in your editor. You can find configuration files for many editors from this repository: https://github.com/joomla/coding-standards/tree/master/Joomla/IDE. Download the repository content via the Zip button and import the appropriate
.xml file into your editor.
Whether your pull request is a bug fix or introduces new classes or methods to the Framework, we ask that you include unit tests for your changes. We understand that not all users submitting pull requests will be proficient with PHPUnit. The maintainers and community as a whole are a helpful group and can help you with writing tests. PHPUnit, and any additional testing dependencies, is installed as part of a
composer install, helpful when you are cloning a package's git repository. Please see https://phpunit.de/manual/current/en/index.html for the full PHPUnit documentation.
For Framework 1.x releases, documentation for each package can be found in the
README.md file in the root of the repository. As of 2.0, each repository will have a dedicated
docs directory structure at a minimum uses the following format:
classes- This directory contains documentation about the package's classes, interfaces, and traits, including summaries of the object's purpose and example uses
index.md- This is a file which will be used as a navigational menu when the package documentation is integrated into this site
overview.md- This is an overview of the package and its use
v1-to-v2-update.md- This file will highlight backward compatibility breaking changes in each package while migrating from 1.x to 2.0
The documentation files use GitHub Flavored Markdown. When contributing new features to existing packages, please add notes about the new features to the existing
README.md file in the packages you change or add new files to the
docs directory (depending on the branch you are submitting the change to). When submitting new packages, documentation in the form of a
README.md file will be required with your pull request. The package documentation should explain how a developer should should be able to get started using the code in the package. The documentation should give an explanation of the classes, interfaces, and/or traits, and provide several simple examples.