A new process to propose features

Have you ever wondered how new features make it into the Joomla core? While in the past, Joomla followed the paradigm "write the code, then we look at it and make a decision," Joomla today has a professional process that supports the "think first, then implement" strategy.

Many contributors were frustrated when they suggested a feature or even wrote a pull request for Joomla that was rejected or - even worse - ignored. Other features were integrated into the core, even though they were badly designed from an architectural point of view, simply because we did not dare to reject a contribution from someone who was highly respected in the project. This resulted in a decrease in the number of contributors and a codebase that is not as extensible as it could be.

This has to change, so we created an RfC process with a clearly defined workflow. Anyone can propose features. Only two things are required: a description of the feature (summary) and the reason why it should be considered at all (why bother?). A proposal then goes through different phases.

Pre-Draft

The preliminary draft phase's goal is to determine whether a majority of Joomla is even interested in a specific feature.

Whoever is interested in the feature can participate in the discussion. It doesn't matter where the discussion occurs, as long as access is open to those interested. This includes an informal discussion on official Joomla discussion media about whether the idea makes sense and is within the scope of Joomla's goals or not.

Once these parties have decided to continue, they will form a Working Group. A Working Group consists of at least

• an editor

• Team Leader from the Production Department, who acts as a sponsor

• at least one other person. That may include Team Leaders or team members as well as members of the general Community.

It is not necessary for the proposal to be fully developed at this stage, although this is permissible. At the very least, it must include an explanation of the problem to be solved, the justification, and basic information on the general approach. Further revision and extension are expected only during the drafting phase. This is to prevent too much energy being put into features whose chance of being adopted is close to zero.

The Community or the Team Leaders of the Production Department (depending on how specific a proposal is) will decide whether or not the proposal should be pursued further.

If the vote is positive, the proposal officially enters the draft phase. The proposal is given its own RfC number.

The Working Group can, of course, continue to work on the proposal throughout the voting period.

Draft

The aim of the draft phase is to discuss and refine a feature proposal to such an extent that it can be considered for review by the Team Leaders of the Production Department.

During the draft phase, the members of the Working Group can make any changes they deem appropriate via pull requests, comments on GitHub, the mailing list, IRC, and similar tools. Changes here are not limited by strict rules, and fundamental rewrites are possible if supported by the editor. Alternative approaches can be suggested and discussed at any time. If the editor and the sponsor are convinced that an alternative proposal is superior to the original proposal, the alternative may replace the original proposal. The members of the Working Group are expected to remain committed throughout the draft phase. Discussions are public, and everyone, regardless of their Joomla affiliation, is welcome to make constructive contributions. During this phase, the editor has the final authority over changes to the proposed specification.

The Production Department Coordinator will ensure that the Working Group is provided with the necessary resources to work on the specification, such as a dedicated GitHub repository, mailing list, forum area, and similar tools.

All findings obtained during the draft phase, such as possible alternative approaches, their implications, advantages, and disadvantages, etc., and the reasons for choosing the proposed approach must be summarised in the meta-document. This rule is intended to prevent discussions from going round in circles or alternative proposals from reappearing after a decision has been taken.

If the editor and the sponsor agree that the proposal is ready and that the meta-document is objective and complete, the editor may conduct a readiness vote within the Working Group to determine whether the specification is essentially complete and ready for the next phase.

If the vote is positive, the proposal formally enters the review phase. If not, it will remain in the drafting phase.

Review

The review phase is an opportunity for the Community to experiment with a reasonably defined objective to assess the proposal's feasibility. In this phase, the sponsor is the final authority for changes to the specification and for any decision to move the proposal forward or backward; however, the editor can veto proposed changes that they believe will harm the specification's design.

Only bug fixes and editorial changes (wording, typing errors, clarifications, etc.) to the specification are now allowed. Major changes are not permitted at this stage. If it becomes apparent that major changes are necessary, the specification must be moved back to the draft phase. Any incompatible change that would require a significant adaptation effort for the implementations is considered a substantial change. Small to moderate incompatible changes do not necessarily require a return to the draft phase.

If a proposal is not returned to the draft stage, it must remain at the review stage for at least four weeks until

• the user interface has been defined, and the manual (help) page has been written for the functionality suggested in the feature RfC.

• For interface definitions, two independent practical test implementations can be demonstrated, ideally as examples in the RfC repository. The responsibility for finding such trial implementations and presenting them to the Production Department's Team Leaders lies with the Working Group and, in particular, with the editor and sponsor. Since not all specifications are PHP interfaces where the definition of "implementation" is self-evident, the sponsor should decide when this is the case to the best of his knowledge. Any member of the Team Leaders of the Production Department may object to a particular trial implementation as irrelevant or insufficient for valid reasons.

Once four weeks have elapsed, and the user interface and help page and – if applicable – two viable trial implementations can be demonstrated, the sponsor may call for an acceptance vote. If the acceptance vote fails, the specification remains in the review phase.

Accepted

If the adoption vote is positive, the proposal will officially become an accepted feature. At this point, the Working Group is automatically formally dissolved, but the contribution of the editor (or a nominated person, who will be notified to the Production Department Coordinator) may be called upon in the future in the event of typing errors, changes, or errors in the specification.

In the case of feature RfCs, a development team is formed within the Production Department, usually including the members of the disbanded Working Group.

Implemented

An implemented feature is a feature that has been developed, tested, and merged for the next available major or minor version.

Project Referendum

The editor of a feature in the draft or revision phase may at any time request a non-binding referendum of the Team Leaders of the Production Department on the current status of a feature. Such a referendum may be called several times in the course of the further development of the Feature. The Team Leaders of the Production Department may also request such a referendum as a condition for an acceptance vote. The results of the referendum are not binding, but the Working Group and the Production Team Leaders are expected to take due account of the results.