phpBB • Free and Open Source Forum Software

Get Involved

Audience

This document is intended for people wishing to help contribute to the development of phpBB. People who want to help us must be proficient in PHP, SQL, and XHTML and have a good understanding of the phpBB code base. We also expect you to have a basic understanding of version control (specifically Git) – if you do not possess these skills then you are probably not the person we are looking for.

Patches

Patches (or diffs) are a way of representing changes between text files (i.e. the differences). phpBB uses Git for version control and Git clients have the ability to generate suitably formatted patch files using its git format-patch command. If for whatever reason you are working outside of a phpBB Git repository then you can use the diff utility which is usually available on *NIX operating systems and is included in the UnxUtils and Cygwin software packages for Microsoft Windows.

We welcome patches from community members, however we only expect them to be for solutions to bugs and not feature additions. For community members providing patches to bugs credit will be given in the CHANGELOG if the patch is used, we may however choose not to use the provided patch. For a patch to be used we request that it follows the patch creation and submission guidelines we have provided below, code contributed in our patches must conform to the phpBB coding guidelines.

Creating Patches

We ask that all patches submitted to us are created using the following instructions to reduce the effort required to review them. When creating patches it is preferable if you create them at the phpBB root path (i.e where config.php is located), unless you are submitting patches for the test suite or other code not residing within the phpBB root directory. Please use a descriptive name for the patch such as bug-3454.diff or refactor-mcp.diff.

For work done inside a checkout of a phpBB Git repository simply using git format-patch base-branch (where base-branch could be develop-olympus or develop) will produce a suitably formatted patch file, called 0001-commit-message.patch in your current working directory.

If you are working outside of a Git repository for whatever reason you can generate a correctly formatted patch file with this command: diff -U3 > bug-12345.diff.

Note: we do not accept patches in MODX or MOD text file formats.

Submitting Patches

Now you have your freshly baked patch you need to get it to us so we can evaluate it.

Community Contributors

Community contributors should only be providing patches for bugs and as such should attach them to the bug tracker with a suitable name, such as bug-12345.diff.

Alternatively, patches may be pushed directly to GitHub. Patches should be formed in their own Git branch. Branches should be named "ticket/xxxx", where xxxx is the ID number of the bug in the tracker. For example, PHPBB3-1234 would be fixed by ticket/1234. After pushing the branch to GitHub, set the "Fix URL" field in the bug tracker to the GitHub diff page for your patch. For example http://github.com/naderman/phpbb3/compare/ticket/1234

Patch Review Process

Submitted patches are reviewed either by the development team or by a single developer depending on the nature of the patch. Generally bug fixes will be reviewed by a single developer.

Patches are checked for the following things, you should think about these things whilst creating your patches and ensure you check them before submission:

• Security
  • Does the patch introduce any security problems?
• Coding guidelines
  • Does your code conform to the phpBB guidelines?
  • Did you use the correct line endings? LF not CRLF
• Functionality
  • Does the patch work?
    • Does the patch handle invalid data?
    • Did you add proper error handling?
• Performance impact
  • Are the changes efficient?
    • Did you introduce SQL queries? Are they efficient?
• Code impact
  • Do the changes affect other sections of phpBB?
    • Did you check affected areas for correct functionality?
• Intellectual property
  • Do you own the work you are contributing?
    • You must not contribute work which is not your own.

Copyright

• Whole functions should include the name of the contributor within the function definition comment, using the @author statement.
• Small code sections are not documented with @author.
• Developers will include the author name of contributed patches in the CHANGELOG.
• Copyright is automatically assigned to the phpBB Group for everything committed.