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. Except for the noted exceptions below, the master branch represents the stable 1.x branch and the 2.0-dev branch represents the upcoming 2.0 release.

Deprecated Packages

Several packages have been deprecated and will not be supported in the Framework 2.0 release. Unless noted, work had been in progress to update all packages for the Framework 2.0 release, including internal refactoring, however as these packages are now deprecated their 2.0-dev branches should be considered abandoned.

Abandoned Packages

Below are packages which are deprecated and no longer supported by the Framework Working Group and Joomla! project. Their repositories are in a read-only state and all maintenance is discontinued.

File Structure

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

NOTE The Crypt 1.x branch is still structured for PSR-0 support due to backward compatibility implications with migrating to PSR-4 and as such the branch has 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 the Framework team. 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 security@joomla.org.

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

The Framework repositories are using version 2.x of the Joomla! Coding Standards which is based on the 2.x branch of PHP_CodeSniffer. 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.

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 whether the repository uses the base definition or has a custom ruleset due to rule exemptions for that package, therefore we suggest copying the command from the package's .travis.yml file.

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/Joomla/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.