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