From phpBB Development Wiki
- 1 phpBB from feature request to development process
- 2 Implementing a new feature
- 3 Glossary
- 4 See Also
phpBB from feature request to development process
This document outlines the process that is in place to propose new features that can be added to phpBB. phpBB uses this system to assure that a given feature is added as proposed and to make sure that feature requests are handled transparently by relying on community input.
I have this great idea for a new feature what should I do?
To get a new feature included in the phpBB system there are a couple of steps that need to be followed, these steps start by identifying the appropriate version for the new feature and end with either the proposed feature getting rejected somewhere in the process or the feature getting added for an upcoming release. As any new feature proposals will be reviewed by the community it is important to follow these steps and explain your idea as clearly as possible. Doing so will ensure two things
- A community member reviewing your proposal can quickly see what you are trying to achieve
- If a proposal gets accepted then the description will be used for the implementation. Failing to correctly describe the new feature might result in something getting added to phpBB that doesn't match with the feature you thought off.
Here is an example of a feature proposal that won't hold up long:
phpBB must have the kitchen sink feature because xyz software has that as well.
There are various problems with this example. For example it doesn't describe what the feature is supposed to do, you might say "But that is clear!" but everybody has a slightly different idea of what a kitchen sink looks like and therefore if a developer goes out to create this kitchen sink he most likely will end up with a different kitchen sink than the one you had in mind. Also phpBB isn't developed with a "we must compete with every other bulletin board in the market" mind set, therefore features won't be added just because a different forum software has that feature. Features get added because the phpBB community needs that feature, so make sure that you describe why your proposed feature will be useful for the phpBB community as a whole (not just because 'you' need it)
Step1: Identifying the appropriate version for this feature
The first step is to define the appropriate version for this feature. At any given point in the  phpBB development cycle there are four different phpBB releases where a feature can be proposed. Use the following rules to determine the correct version:
- Is the proposed feature a "minor" change that can't break anything (e.g a plugin) and you have the code for the change available?
- The feature can be submitted to the current stable branch by creating a ticket in the bug tracker for the next maintenance release.
- Is the proposed feature a "minor" change that potentially causes conflicts?
- Create an RFC for the current feature-frozen release.
- Is the proposed feature a "major" feature (new features/architectural changes)
- Create an RFC for the not yet feature-frozen release.
- If an implementation for an RFC for this release is finished before the upcoming feature branch gets its first Alpha release, then the release manager can decide to move this RFC up to this release and the code will be merged into that branch.
- The proposed feature requires major changes, major backward compatibility breaks for users (e.g a new ACP or change of frameworks)
- Create an RFC for the next major release.
So to summarize:
- To get something included in the stable bug fixes branch then it needs to be small and you need to be able to convince the development team it won’t break anything. Mainly this means plugins. You can discuss and propose these features here.
- To get something included in the next minor branch is slightly more complex. If the next feature release is feature-frozen (Which 3.1 currently is) then you should discuss it in the next non-feature frozen branch (Currently 3.2). However, if a patch is submitted by a member of the community and merged before the feature-frozen branch reaches alpha the feature will instead be included in the feature-frozen version (Currently 3.1).
- If it’s a major architectural change then it will be for the next major release (Currently 4.0).
Step2: Finalising the feature request
We've identified the target version before finalising the feature request because the target version determines how to continue. If it was determined that the target version is the current stable branch (this only happens in rare cases), go ahead and create a new ticket in the bug tracker and a pull request on GitHub for the code. A developer will handle these cases from the bug tracker and inform you about additional steps that might be required. In all other cases you need to file an RFC (short for Request for Comments), the RFC will be used to describe the wanted feature and to convince the (development) community why this feature would be a good addition to phpBB.
What is an RFC?
An RFC is a document describing the requested feature in as much detail as possible, the document describes the expected behavior, pros and cons of the change and if possible a (partial) implementation. Once the document is finalised it will be posted to the community which then can discuss the proposed change. This discussion will determine whether the (development) community agrees on the proposed change or would like some changes made to the draft. Further discussion of the draft will determine whether the proposed change will be accepted or rejected. The following diagram shows the life cycle of an RFC '(Diagram by the xp-framework)'
.-------------------. | | | v Draft -+-> Discussion -+-> Accepted -> Implemented -> Merged | | +---<---´ | v Rejected
The most common statuses an RFC will reach are:
- Draft, The RFC un-finalised document
- Discussion, The RFC is being discussed by the community
- Accepted, The RFC has been accepted but not yet implemented
- Rejected, The RFC has been rejected
- Implemented, The RFC has been implemented
- Merged, The RFC has been implemented and merged into the upcoming feature branch
My RFC has been discussed, what now?
Once an RFC is discussed by the community it will be marked `Rejected` or `Accepted` in most cases. If the RFC is marked rejected then the community feels that the proposed feature doesn't have any value to be added to the core product, if this is the case and you really need the proposed feature it is advisable to post a MOD request in the Modification forums on phpbb.com. If the RFC gets accepted then the RFC is ready for implementation. You should keep in mind that an RFC can be marked accepted for a given version, however, this doesn't necessarily mean that the feature will be implemented for this version. Accepted RFCs can be pushed back to a later feature release by the release manager or development team leader (as described before the other way around, 'by moving an RFC forward' can also occur).
Implementing a new feature
If an RFC went through the RFC process and gets accepted, work on implementing the RFC can begin. At this point the work of the RFC writer isn't over, as it is strongly advised to implement the feature yourself. If you don't want to do this, or if you aren't capable to do so, you'll need to find a developer who will want to implement the RFC. Don't expect that because the RFC is accepted a development team member, or other contributor, will jump in and implement the requested feature '(the accepted state is used to identify features that have received the go-ahead to be implemented)'. While implementing the feature you'll need to follow the phpBB development cycle.
The phpBB development cycle
The development cycle involves various steps, beginning with creating a ticket in the bug tracker for the appropriate project '(phpBB 3.x and 4.x use separate trackers)' and setting it to the appropriate target version. The ticket should be of the "bug type" feature and shortly describe the feature as well a link to the RFC '(which will be updated to contain a link to the newly created ticket)'. Once the ticket is created the developer can begin writing the code for the feature, this will be done by creating a new branch in his own fork of the phpBB project '(see this wiki article for more information on working with git and phpBB)'. Once the developer feels that he finished implementing the feature, he will create a pull request allowing the other phpBB developers to review/comment on the code. A pull request will automatically include any new commits to the branch so implementing the developer feedback requires you only to commit the requested changes. This process will repeat itself until the developers are satisfied that the provided patch is of efficient quality to be merged into the phpBB source. Once the code is merged the ticket will be closed and the status of the RFC changed to merged, at this point the new feature will be part of the feature release to which it was merged '(this usually will be the next feature release unless the first alpha of that version has been released before the merge)'.
If you don't have access to a GitHub account it is also possible to attach a patch to the ticket which then will be reviewed/committed by a developer.
- Maintenance release – A small bug fix release with possible small features in. Next to be released: 3.0.11
- Minor feature release – A release with larger features in. Next to be released: 3.1/
- Major feature release – A complete re-write. Next to be released: 4.0
- Feature Frozen – No more features will be added unless a patch is provided by the community before it reaches alpha.
- Olympus – 3.0.x Current Stable Branch (Feature Frozen)
- Ascraeus – 3.1.x Next minor release (Feature Frozen)
- Arsia – 3.2.x Next minor release (Not feature frozen)
- Rhea – 4.0.x Next major release (Not feature frozen)
- RFC – Request for Comments
- PR – Pull Request on Github