xref: /PHP-7.2/README.SUBMITTING_PATCH (revision 902d39a3)
1Submitting Enhancements and Patches to PHP
2==========================================
3
4This document describes how to submit an enhancement or patch for PHP.
5It's easy!
6
7You don't need any login accounts or special access to download,
8build, debug and begin submitting PHP or PECL code, tests or
9documentation.  Once you've followed this README and had several
10patches accepted, commit privileges are often quickly granted.
11
12An excellent article to read first is:
13http://phpadvent.org/2008/less-whining-more-coding-by-elizabeth-smith
14
15
16Online Forums
17-------------
18There are several IRC channels where PHP developers are often
19available to discuss questions.  They include #php.pecl and #php.doc
20on the EFNet network and #winphp-dev on FreeNode.
21
22
23PHP Patches
24-----------
25If you are fixing broken functionality in PHP C source code first
26create a bug or identify an existing bug at http://bugs.php.net/.  A
27bug can be used to track the patch progress and prevent your changes
28getting lost in the PHP mail archives.
29
30If your change is large then create a Request For Comment (RFC) page
31on http://wiki.php.net/rfc, discuss it with the extension maintainer,
32and discuss it on the development mail list internals@lists.php.net.
33RFC Wiki accounts can be requested on
34http://wiki.php.net/start?do=register.  PHP extension maintainers can
35be found in the EXTENSIONS file in the PHP source.  Mail list
36subscription is explained on http://php.net/mailing-lists.php.
37
38Information on PHP internal C functions is at
39http://php.net/internals, though this is considered incomplete.
40Various external resources can be found on the web.  See
41https://wiki.php.net/internals for some references.  A standard
42printed reference is the book "Extending and Embedding PHP" by Sara
43Golemon.
44
45The preferred way to propose PHP patch is sending pull request from
46GitHub: https://github.com/php/php-src
47
48Fork the official PHP repository and send a pull request. A
49notification will be sent to the pull request mailing list. Sending a
50note to PHP Internals list (internals@lists.php.net) may help getting
51more feedback and quicker turnaround.  You can also add pull requests
52to bug reports at http://bugs.php.net/.
53
54If you are not using GitHub, attach your patch to a PHP bug and
55consider sending a notification email about the change to
56internals@lists.php.net.  If the bug is for an extension, also CC the
57extension maintainer.  Explain what has been changed by your patch.
58Test scripts should be included.
59
60Please make the mail subject prefix "[PATCH]".  If attaching a patch,
61ensure it has a file extension of ".txt".  This is because only MIME
62attachments of type 'text/*' are accepted.
63
64
65
66PHP Documentation Patches
67-------------------------
68If you are fixing incorrect PHP documentation first create a bug or
69identify an existing bug at http://bugs.php.net/.  A bug can be used
70to track the patch progress and prevent your changes getting lost in
71the PHP mail archives.
72
73If your change is large, then first discuss it with the mail list
74phpdoc@lists.php.net.  Subscription is explained on
75http://php.net/mailing-lists.php.
76
77Information on contributing to PHP documentation is at
78http://php.net/dochowto and http://wiki.php.net/doc/howto
79
80Attach the patch to the PHP bug and consider sending a notification
81email about the change to phpdoc@lists.php.net.  Explain what has been
82fixed/added/changed by your patch.
83
84Please make the mail subject prefix "[PATCH]".  Include the bug id(s)
85which can be closed by your patch.  If attaching a patch, ensure it
86has a file extension of ".txt".  This is because only MIME attachments
87of type 'text/*' are accepted.
88
89
90PECL Extension Patches: http://pecl.php.net/
91--------------------------------------------
92If you are fixing broken functionality in a PECL extension then create
93a bug or identify an existing bug at http://bugs.php.net/.  A bug
94can be used to track the patch progress and prevent your changes
95getting lost in the PHP mail archives.
96
97If your change is large then create a Request For Comment (RFC) page
98on http://wiki.php.net/rfc, discuss it with the extension maintainer,
99and discuss it on the development mail list pecl-dev@lists.php.net.
100PECL mail list subscription is explained on
101http://pecl.php.net/support.php.  RFC Wiki accounts can be requested
102on http://wiki.php.net/start?do=register
103
104Information on PHP internal C functions is at
105http://www.php.net/internals, though this is considered incomplete.
106Various external resources can be found on the web.  A standard
107printed reference is the book "Extending and Embedding PHP" by Sara
108Golemon.
109
110Update any open bugs and add a link to the source of your patch.  Send
111the patch or pointer to the bug to pecl-dev@lists.php.net.  Also CC
112the extension maintainer.  Explain what has been changed by your
113patch.  Test scripts should be included.
114
115Please make the mail subject prefix "[PATCH] ...".  Include the patch
116as an attachment with a file extension of ".txt".  This is because
117only MIME attachments of type 'text/*' are accepted.
118
119
120PEAR Package Patches: http://pear.php.net/
121------------------------------------------
122Information on contributing to PEAR is available at
123http://pear.php.net/manual/en/developers-newmaint.php and
124http://pear.php.net/manual/en/guide-developers.php
125
126
127How to create your PHP, PHP Documentation or PECL patch
128-------------------------------------------------------
129PHP and most PECL packages use Git for revision control. Some PECL
130packages use Subversion (SVN) Read http://www.php.net/git.php for help
131on using Git to get and build PHP source code.  We recommend to look
132at our workflow on https://wiki.php.net/vcs/gitworkflow and our FAQ
133https://wiki.php.net/vcs/gitfaq.
134
135Generally we ask that bug fix patches work on the current stable PHP
136development branches and on "master".  New PHP features only need to
137work on "master".
138
139Read CODING_STANDARDS before you start working.
140
141After modifying the source see README.TESTING and
142http://qa.php.net/write-test.php for how to test.  Submitting test
143scripts helps us to understand what functionality has changed.  It is
144important for the stability and maintainability of PHP that tests are
145comprehensive.
146
147After testing is finished, create a patch file using the command:
148
149  git diff > your_patch.txt
150
151For ease of review and later troubleshooting, submit individual
152patches for each bug or feature.
153
154
155Checklist for submitting your PHP or PECL code patch
156----------------------------------------------------
157 - Update git source just before running your final 'diff' and
158   before testing.
159 - Add in-line comments and/or have external documentation ready.
160   Use only "/* */" style comments, not "//".
161 - Create test scripts for use with "make test".
162 - Run "make test" to check your patch doesn't break other features.
163 - Rebuild PHP with --enable-debug (which will show some kinds of
164   memory errors) and check the PHP and web server error logs after
165   running your PHP tests.
166 - Rebuild PHP with --enable-maintainer-zts to check your patch
167   compiles on multi-threaded web servers.
168 - Review the patch once more just before submitting it.
169
170
171What happens after submitting your PHP, PHP Documentation or PECL patch
172-----------------------------------------------------------------------
173If your patch is easy to review and obviously has no side-effects,
174it might be committed relatively quickly.
175
176Because PHP is a volunteer-driven effort more complex patches will
177require patience on your side.  If you do not receive feedback in a
178few days, consider resubmitting the patch.  Before doing this think
179about these questions:
180
181 - Did I send the patch to the right mail list?
182 - Did I review the mail list archives to see if these kind of
183   changes had been discussed before?
184 - Did I explain my patch clearly?
185 - Is my patch too hard to review? Because of what factors?
186
187
188What happens when your PHP or PECL patch is applied
189---------------------------------------------------
190Your name will likely be included in the Git commit log.  If your
191patch affects end users, a brief description and your name might be
192added to the NEWS file.
193
194Thank you for patching PHP!
195