Contributing to the Joomla Platform
Anyone can contribute new features to Joomla. The Production Leadership Team (PLT) is responsible for deciding which features are included into each version.
Developers intending to contribute code to the Joomla! core should sign the Joomla! Contributor Agreement. Please note that the AGPL will be shortly removed from the list of approved licenses.
Following that, the general steps for contributing to the Joomla! Platform include the following:
- Discuss new features or other major changes on the Joomla Platform mailing list (https://groups.google.com/forum/#!forum/joomla-dev-platform) to get feedback from your peers.
- If features affect downstream usage, such as impacting the Joomla CMS, it's appropriate to discuss platform changes on the Joomla Development CMS mailing list as well. In this case, it may be appropriate to list a feature patch on the Joomla CMS Feature Tracker (please use the category Platform for any platform features submitted in this way).
- Establish an account on https://github.com.
- Fork the joomla-platform repository and clone a copy to your local computer.
- Develop in a branch (see tips below), making sure to keep up to date with the main platform-platform repository.
- When your ready for review, make a pull request (see additional instructions below).
You can also find suggestions and rated ideas at the Joomla Idea Pool http://ideas.joomla.org. If you are experienced in writing unit tests, then you can use the coverage report (http://developer.joomla.org/coverage/joomla.html) as a guide to where help is most needed. The latest build information can be found at http://build.joomla.org:8080/job/platform/ and this gives a number of reports from which you can determine where improvements to code style compliance and architectural design improvements can be made.
Example applications can be found at https://github.com/joomla/joomla-platform-examples and developers are most welcome to contribute here as well.
Pull requests must be made against the staging branch in the joomla-platform repository. When a pull request is merged, it sets of the automated testing system and, if that is successful, it merges the changes in the master branch. If the testing system fails for any reason, the staging branch is left as is, but it does not copy the changes to the master branch, thus ensuring that the code in master always passes all automated testing.
To make a pull request, go to the main page of your repository on github. Then, switch to the branch you were working in and then click the "Pull request" button near the top of the page. On the next screen, make sure the request is to staging in the "Base branch" section.
The changelog is complied and updated semi-automatically from time to time. The description of the pull request is used in the changelog so try to make that as informative as possible when you make the pull request.
In order to make the code reviewer's life a little easier, it's a good idea to, if you can, run the unit test suite to ensure your code doesn't break the platform. Even better, when you are adding new code, features or behaviours, it is also of great assistance to see if there is an existing unit test you can modify to test your changes. New tests written for code previously not covered by the unit test suite are also greatly appreciated.
The Joomla platform include a work-in-progress standard for PHP Code Sniffer. You can find it in the /build/phpcs/ folder. You can install PHP Code Sniffer locally with PEAR, and then copy (or soft link) the Joomla standard into the PHP Code Sniffer standards folder. If you aren't able to set up PHP Code Sniffer, here are some basic guidelines for the most common mistakes we see:
- Use real tabs for indenting code.
- Use real spaces for alignment within DocBlocks.
- Put 2 spaces after an @return tag, and 3 after an @param tag and line up all the other tags based on those.
- Line up the $variable in an @param tag 2 spaces after the longest variable type.
- Line up the variable description 2 spaces after the longest $variable name.
- Put a comment space after the block of @param tags.
- Always use a @return tag except on constructors and destructors. Use void if there is no return value.
- Put a space after the @return tag and then line up any subsequent tags (@since, @throws, etc) in alphabetical order.
- Always include an @since tag in function, class and class method DocBlocks.
- Curly braces go on new lines for all code block constructs (if, foreach, switch, etc).
Also remember to trim any trailing white space from your code before you submit it. Most IDE's have a setting to do this automatically when you save a file.
The GitHub issue tracker has some limitations. Because of this, any pull request that is not completely ready or complete at the time of review will be closed with a comment. This has nothing to do with whether the pull request is necessarily good or bad, just incomplete, and the fact that we have no convenient way (yet) of tracking "in progress" contributions. Follow any instructions given and then reopen the pull request by leaving a comment containing the word "reopen". (ie: 'Changes have been made. Please reopen.') Our Joomla-Jenkins bot will recognize this and automatically reopen the request for you within a few minutes.
Please note: Closed pull requests do not update. When you make the requested changes and push them to your repo, you will not see the change reflected on the pull request until it is reopened.
The power of git is the ability to use branches as "layers" of different ideas yet maintaining the one repository.
When making contributions, you should make a branch for each "kind" of thing you are doing. For example, if you are working on a particular bug, you would create a branch for that (you can always delete the branch later on when the bug is fixed). If you are working on documentation in the /docs/ folder, you might create a "documentation" branch. If you are wanting to test someone else's work, you would probably create a new branch for that work, disposing of it when you don't need it any more.
Also remember that when you make a pull request, it is done against one of your branches. After you make the pull request, you can still work on that branch, adding commits and pushing them to github. They will continue to form part of the pull request until such time as one of the Platform Maintainers merges the pull request.
To list the branches available in your local repository:
git branch
To create a new branch, or change to an existing branch:
git branch documentation
To update your local repository branch from the master (stable) branch of the Joomla Platform on github (this assumes that 'joomla' is set up as a "remote" in your local repository):
git pull joomla master
To push your branch to your repository on github:
git push origin documentation
To list the remote aliases configured in your local repository:
git remote -v