phpBB • Creating Communities Worldwide

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 Subversion) – if you do not possess these skills then you are probably not the person we are looking for.

Junior Developers

Junior Developers (JDs) are community members who directly contribute to the phpBB code base through a mentored process managed by the development team. They are expected to have a comprehensive understanding of phpBB and provide high quality work.

JDs work on specific tasks and bugs assigned to them by the developers who then review their proposed solutions to ensure they are suitable to be incorporated into the code base. They commit their patches directly to the repository after they have been authorised by at least one developer.

Becoming a Junior Developer

How do I become a Junior Developer?

You cannot apply to become a JD, people applying will be frowned upon and ignored. JDs are chosen by the development team based on their activity in the community and prior work, for example by contributing positively to the bug tracker by filing helpful tickets, evaluating other tickets and posting patches containing suitable solutions. Participation in the forums is also taken into account, including behaviour.

Junior Developer Workflow

How do Junior Developers commit their code?

1. JD performs changes on code as normal.
2. He or she then prepares a patch for submission to the developers, which is uploaded and posted in the patch forum.
3. The patch is reviewed by the development team.
   • If the patch is rejected then the JD would return to step one making the necessary amendments as suggested by the developers.
4. The JD commits the patch to the SVN repository including in the commit message the name of the developer who approved the patch.
5. JD then marks the topic as solved upon a successful commit.

Commit Message

JD commit messages must include the name of the developer that has authorised the patch, on a separate line prefixed by Authorised by:, if this line is missing or improperly formatted the commit will be rejected. Some example commit messages are provided below.

1. Added super secret feature X
   
   Needs further testing, unit tests to be committed soon.
   
   Authorised by: acydburn

2. Fixed bug in memberlist #239485
   
   Authorised by: naderman

3. Added support for SQLite 3
   
   Authorised by: davidmj, acydburn

Patches

Patches (or diffs) are a way of representing changes between text files (i.e the differences). phpBB uses Subversion for version control and the subversion client has the ability to generate suitably formatted patch files using its svn diff command. If for whatever reason you are working outside of a phpBB SVN checkout 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 the phpBB SVN repository simply using svn diff > bug-12345.diff will produce a suitably formatted patch file, called bug-12345.diff. If you want to restrict the patch to certain files or directories at the end of the command, for example: svn diff includes/mcp/ includes/ucp/ common.php ucp.php adm/index.php > bug-12345.diff.

We suggest users of Microsoft Windows use TortoiseSVN for subversion repository handling. Patches can be made using the context menu, and choosing Create Patch in the TortoiseSVN sub menu.

If you are working outside of a Subversion checkout 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, how you do this is different depending on whether you are a JD or a community member.

Junior Developers

JDs patches should be submitted, as an attachment, to the patch forum in accordance with the JD workflow where it will be reviewed by a developer.

Note: JDs must add the relevant line into the docs/CHANGELOG.html file in their patch if they are working against the 3.0 branch.

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.

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 JD or contributor within the function definition comment, using the @author statement.
• Small code sections are not documented with @author.
• Changelog entry should include the name of the JD in brackets, developers will include the author name of contributed patches.
• Copyright is automatically assigned to the phpBB Group for everything committed.