Feature Patches PDF Print E-mail

The Joomla code-base is used by millions of people around the world and we care a great deal about the quality of the code we release.  While code quality is not an exact science  we do require that code contributions to Joomla should be understandable, robust and complete.

Patches should be understandable.

Your patch should be understandable. If we can't work out what it does then it makes it very difficult to evaluate, and even more difficult to maintain in the future.
  • The code must follow our coding style guidelines.
  • The code must use the Joomla Framework API.  Do not submit patches that make direct calls to mysql_query() when the JDatabase library should be used for example.
  • Patches must be submitted in unified diff format.  Subversion generates unified diff patches natively so you should be able to use your favorite subversion client to create the patch.  More information can be found on the Joomla! documentation wiki on the Learn more about patch files page.
  • The code must be well commented.  There are no hard rules for comment requirements other than to make sure you have doc-blocks where appropriate and that you have comments to explain non-trivial code blocks.
  • Note the section of the subversion tree as well as the revision number your patch was created against.
Also, please discuss your work on one of the development mailing lists before submitting it. The maintainers can help you determine if your work is an architectural fit with the code-base and also provide general guidance.  Following these guidelines will help to ensure that everyone can understand your work and will increase the chance of it being added to the core code-base.

Patches should be robust.

As robustness can be interpreted in many ways, we would like you to test the patch thoroughly before you submit it.  Testing features with several browsers and in multiple server environments is also good practice to ensure that it works for all Joomla supported platforms.  Make sure to follow security best practices as well so that the code is as secure as we can make it.

Patches should be complete.

Something we also like to see is completeness. We will not accept feature patches that are half done, or where certain aspects of the feature are not functioning properly. Please make absolutely certain that all features are completed, tested and documented before you submit them.

Technical Requirements

You must be aware of the minimum technical requirements for the version of Joomla for which you are submitting a feature patch.

See http://www.joomla.org/about-joomla/technical-requirements.html

How To Submit A Feature Patch

Once you've actually done all the hard work of creating and testing your work, submitting the patch is quite easy. Register on Joomlacode.org so you can submit the feature patch on the Joomla 1.6 feature patch tracker.

Choose a descriptive patch title.

Please pick a good title for you patch.  Thinks like "Cool new feature" are not helpful when reviewing the patch.  Choose a reasonably descriptive name that tells us what you are modifying, for example:

"Add Save and New toolbar function to all Administrator components"
"Back-port JController::getInstance method from 1.6 to 1.5"
"com_content layout override for section view to provide a book table of contents like format"

Provide as much supporting information as possible.

It's a good idea to include as much supporting information and references as possible, such as links to mailing list discussions, forum posts, and so on.  You did start a discussion on the mailing lists about your feature didn't you?

Inform the development mailing list.

When you submit a feature patch, send a short mail to the relevant development mailing list to let everyone know about your work.  This will serve as the thread for people to comment on and review your patch.  You can either use the thread previously created to discuss your work or start a new one.

How Your Patch Gets Reviewed

Once your patch is submitted it will be reviewed by your peers.  The decision for what is accepted lies with a group of core maintainers and the development coordinators.  For non-trivial patches expect conversation about your work and be ready to explain your ideas.

Your patch is given a status of "Under Review".

When your patch is first submitted it has a status of "Open".  Once a maintainer has looked at your entry in the feature patch tracker, he or she will set the status to "Under Review" and assign the patch to him/herself so that it is obvious who is responsible for patch review.

An explanation of the different status states for a patch are as follows:
  • Open - The patch has been submitted, but has not yet begun the review process. This is the default status for every feature patch when submitted to the tracker.
  • Under Review - The patch has been picked up by a maintainer for review. This is the the point in which discussions would take place on the relevant development mailing list and code review would take place.
  • Denied - The feature patch has been denied. A short description of the reason can be found in the description field and a short notice will be posted on the mailing list where applicable.
  • Accepted - The patch has been accepted and is scheduled to be committed to the core code-base.  Time to start partying!
  • Implemented - The patch has been committed to the core code-base and is now part of Joomla.  When you update your copy of the subversion tree you will see your patch incorporated and your name added to the credits file.

Your patch will be assigned a priority.

Upon being set to "Under Review" status by a maintainer, your patch will also be given a priority.  The priority state helps maintainers process patches more efficiently in line with our goals and missions for the given release.

An explanation of the different priority states for a patch are as follows:

  • High - This is a patch we consider very important and should be reviewed as a priority.
  • Medium - This is the default setting for any newly submitted patch and just means that your patch is in the general pool for consideration.
  • Low - This is a patch that we think would good to include in a future version of Joomla, but is not necessarily a target for this release.
Please note that the priorities do not necessarily mean that reviews will happen faster.  It just affects the nominal order in which we devote resources to reviewing them.

Your patch will be discussed.

Once under review, your feature patch will be discussed on the mailing list by your peers and reviewed for code quality, understandability, robustness and completeness by the assigned maintainer.  A minimum of two maintainers are required to sign-off on a patch for it to be accepted, but the number of maintainers involved in review of your patch may vary depending upon the complexity and size of the submission.

A decision will be made.

After your patch has been sufficiently discussed a decision will be made about its acceptance.  If it is accepted it will be placed in the commit queue and its status will be adjusted accordingly in the tracker.  If it is denied a short reason will be given and its status will also be adjusted accordingly in the tracker.  Whatever the decision a follow-up email will be posted to the relevant mailing list describing the decision and reason.

Licensing

The Joomla code-base is licensed under the GNU General Public License (version 2 or later). When you submit a patch to the Joomla code-base you agree to license your changes under the GNU General Public License.

Copyright

Individual contributions to the Joomla code-base are copyright their respective authors. Open Source Matters, Inc. holds the copyright on the combined Joomla code-base.  Copyright notices are respected for any existing work incorporated into the Joomla code-base.

Attribution

When you submit a patch that modifies or extends existing code that is accepted by the maintainers, an entry into the credits file will be added for that release.  Entries in the credits file will also be added for new and replacement libraries or extensions.

Get Involved

Joomla is a great and growing open source project, and we are passionate about our values of freedom, equality, trust, community, collaboration and usability.  Getting involved in our development community will help you hone your skills, help us reach our goals and more importantly help ensure Joomla remains the best platform for digital publishing and collaboration into the future.

Getting involved is as easy as joining one or more of our public mailing lists.  Join the list(s) that best suit your interests and become a part of the community today!

Joomla General Development

This list is for discussing general topics surrounding Joomla development.  If you have questions or ideas about how to write software on the Joomla platform this is the place to get involved.

Join the discussion: http://groups.google.com/group/joomla-dev-general

Joomla CMS Development

This list is for discussing development of the Joomla content management system.  Discussions about the Joomla CMS core and its releases happen here.  If you want to contribute to the next release of the CMS join us here and get started.

Join the discussion: http://groups.google.com/group/joomla-dev-cms

Joomla Framework Development

If you want to work on expanding and perfecting the platform that Joomla is built on this is the mailing list for you.  This list is for discussing the research and development of the Joomla Framework and new technologies for it.

Join the discussion: http://groups.google.com/group/joomla-dev-framework