===== How To Create an RFC =====

Newcomers to PHP core development should read [[https://blogs.oracle.com/opal/the-mysterious-php-rfc-process-and-how-you-can-change-the-web|The Mysterious PHP RFC Process and How You Can Change the Web]] before starting the RFC process.  

If you don't have the skills to fully implement your RFC and no-one volunteers to code it, there is little chance your RFC will be successful. To learn about PHP core development see [[internals:references|References about Maintaining and Extending PHP]].

It is a good idea to consider the [[https://github.com/php/policies/blob/main/release-process.rst|release process]] and how your proposal will fit into that timeline. Most new features are only introduced to a version before it reaches the Beta stage, which is generally scheduled around mid-August each year.

  - Email internals@lists.php.net to measure reaction to your intended proposal. State who would implement the feature, or whether the proposal is only a "concept". Proceed with an RFC if feedback is not negative or if a detailed RFC will clarify the proposal. Mail list subscription is at http://php.net/mailing-lists.php.  (Reminder: always [[https://github.com/php/php-src/blob/master/docs/mailinglist-rules.md | "bottom post"]] your replies. Never "top post".)
  - Get wiki RFC karma (this is only required if you don't have a VCS account for php.net. PHP developers can log on with their credentials and already have the necessary karma to create RFCs):
      - Register for a wiki account at https://wiki.php.net/start?do=register.
      - Email internals@lists.php.net requesting RFC karma for your wiki account. In the email, remind people about the RFC you plan to create. Note that RFC karma does not automatically give you karma to vote. See https://wiki.php.net/rfc/voting#rfc_proposer
  - Create the RFC:
      - Log into the wiki with your wiki account.
      - Navigate to a URL like https://wiki.php.net/RFC/my_RFC (use your feature name in the URL). 
      - Push the "Edit this page" button, fill out the supplied [[rfc:template|template]] and save.
      - Edit https://wiki.php.net/RFC and link your RFC under the "In Draft" status.
      - Write the RFC.
  - When your RFC is ready for discussion:
    - Change the status of your RFC page to "Under Discussion"
    - Change its section on https://wiki.php.net/RFC to "Under Discussion"
    - Send an email to internals@lists.php.net introducing your RFC.
  - Listen to the feedback, and try to answer/resolve all questions.  Update your RFC to document //all// the issues and discussions.  Cover both the positive and negative arguments. Put the RFC URL into all your replies.
  - When discussion ends, and a minimum period of two weeks has passed since you mailed internals@lists.php.net in step 4, consider one day heads up mail on the mailing list and then you can move your RFC to "Voting" status.  There should be //no// open questions in the RFC. Review https://wiki.php.net/RFC/voting#voting first. Consider whether the feature concept should be voted on before you invest time in implementation. Or perhaps an implementation is needed to show the feature is feasible; in this case, make it clear whether or not the current implementation is being voted on.
    - Update your RFC page to "Voting" status
    - Add the doodle voting macro, for example: <code>
<doodle title="RFC name here" auth="your_username_here" voteType="single" closed="false" closeon="2022-01-01T00:00:00Z">
   * Yes
   * No
</doodle></code>
    - Add the voting start and end dates to the text of the RFC, including the time and timezone that the voting will end.
    - Move your RFC on https://wiki.php.net/RFC to "Voting".
    - Send an email to internals@lists.php.net announcing the start of voting for your RFC. Start a new mail thread and put "[VOTE] {RFC Title}" in the subject. Set a deadline for voting; the minimum period is two weeks.
  - Based on the result of the votes and the discussion there are three possible outcomes:
    - Your RFC is accepted: update the status of your RFC page and its section on https://wiki.php.net/RFC to "Accepted" and close the vote via changing closed="false" to closed="true" in the voting macro. When the code is merged, update the RFC and section to state which PHP version the code was merged into. 
    - Your RFC is declined: update the status of your RFC page and its section on https://wiki.php.net/RFC to "Declined" and close the vote via changing closed="false" to closed="true" in the voting macro.
    - A serious issue with your RFC needs to be addressed: update the status of your RFC page and its section on https://wiki.php.net/RFC to "Under Discussion" and continue again from step 5.
   - When your feature is implemented in PHP, update the RFC with:
     - the version(s) it was merged to
     - a link to the git commit(s)
     - a link to the PHP manual entry for the feature
     - a link to the language specification section (if any)
    - Change the status of your RFC page to "Implemented"
    - Change its section on https://wiki.php.net/RFC to “Implemented” under the implemented PHP version. If the RFC requires adjustments in a future version, please keep an entry for it in the "Pending Implementation" section with a "PHP x.y: " prefix.


==== Notes ====

=== Open new RFCs rather than re-use existing documents ===

In general the status of an RFC should not be moved backwards to an earlier status. In practice there will be times when people accidentally open the voting too early, or some serious problem is found with an RFC during the voting phase, in those cases it's fine to move the status back until the problem is fixed. But as a rule, leaving each RFC document with a clear history of what happened to that RFC makes it easier to understand past discussions.

Also, we have rules about when RFCs are allowed to be put into voting. If a RFC document has been re-used there could be some confusion about when it is allowed to be put to a vote.

Leaving the previous RFC document intact, with the results of a vote if one was taken, leaves a clearer document trail than if the document has been recycled. 

It can also be useful to create a new RFC document when an RFC changes significantly during it's discussion. Although previous versions of documents are available through the wiki, finding where an RFC was re-written and trying to understand why it was, are quite difficult. Leaving the previous version intact, with a note pointing to the new version makes understanding discussion history much easier.

=== RFCs 'belong' to a single author ===

Although minor typos can be fixed by other people, any significant changes should be approved by the original RFC author.

If you wish to 'take over' an RFC, you need the express consent of the RFC author. If you can't get that consent, for example the person doesn't respond, then please open a new RFC document.


=== Don't list someone as an author without their express consent ===

There have been cases where someone has added someone's name as an author of an RFC, and this has caused drama as the person wasn't aware that they had been added.

If you want to credit someone for having done a large amount of work, e.g. when taking over an abandoned RFC, you can do that by adding the phrase 'based on work by' e.g. "Author: Danack, based on work Anthony Ferrara". Though people are free to ask for their name to be removed even in that case.

==== External Resources ====

  * [[https://blogs.oracle.com/opal/the-mysterious-php-rfc-process-and-how-you-can-change-the-web|The Mysterious PHP RFC Process and How You Can Change the Web]] by [[http://people.php.net/user.php?username=sixd|Christopher Jones (sixd)]]