Contributing to the Joomla! Framework

Repository Structure

As of June 2017, the individual repositories in the Joomla! Framework GitHub organization are generally structured the same.

Branches

Most repositories have two branches representing the two major Framework versions; 1.x and 2.0.

File Structure

Joomla! Framework packages are PSR-4 compliant and follow a common filesystem structure.

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.

Issues/Pull Requests

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.

Security Issues

Security issues should be reported to the Joomla! Security Strike Team by either filling out the contact form or emailing [email protected].

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.

Versioning

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.

Coding Standards

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.

To run PHP_CodeSniffer with the Joomla! Coding Standards, you must download the standard. 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. For most packages, you can run ./vendor/bin/phpcs -p --report=full --extensions=php --standard=.travis/phpcs/Joomla/ruleset.xml src/ from the root of the package. This command is based on that found in the package's .travis.yml file and it is suggested you copy the phpcs command from there to run PHP_CodeSniffer with the same definition as we test against.

IDE Support

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/IDE. Download the repository content via the Zip button and import the appropriate .xml file into your editor.

Unit Testing

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.

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.

The docs directory structure at a minimum uses the following format:

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.