xref: /PHP-7.4/CONTRIBUTING.md (revision 9458f7e2)
1# Contributing to PHP
2
3Anybody who programs in PHP can be a contributing member of the community that
4develops and deploys it; the task of deploying PHP, documentation and associated
5websites is a never ending one. With every release, or release candidate comes a
6wave of work, which takes a lot of organization and co-ordination.
7
8You don't need any special access to download, build, debug and begin submitting
9PHP or PECL code, tests or documentation. Once you've followed this guide and
10had several contributions accepted, commit privileges are often quickly granted.
11
12## Index
13
14* [Pull requests](#pull-requests)
15* [Filing bugs](#filing-bugs)
16* [Feature requests](#feature-requests)
17* [Writing tests](#writing-tests)
18* [Writing documentation](#writing-documentation)
19* [Getting help](#getting-help)
20* [PHP source code directory structure](#php-source-code-directory-structure)
21* [PHP internals](#php-internals)
22* [PECL extensions](#pecl-extensions)
23* [Checklist for submitting contribution](#checklist-for-submitting-contribution)
24* [What happens after submitting contribution?](#what-happens-after-submitting-contribution)
25* [What happens when your contribution is applied?](#what-happens-when-your-contribution-is-applied)
26* [Git commit rules](#git-commit-rules)
27* [Copyright and license headers](#copyright-and-license-headers)
28
29## Pull requests
30
31PHP welcomes pull requests to [add tests](#writing-tests), fix bugs and to
32implement RFCs. Please be sure to include tests as appropriate!
33
34If you are fixing a bug, then please submit your PR against the lowest actively
35supported branch of PHP that the bug affects (only green branches on
36[the supported version page](https://www.php.net/supported-versions.php) are
37supported). For example, at the time of writing, the lowest supported version is
38PHP 7.3, which corresponds to the `PHP-7.3` branch in Git. Please also make sure
39you add a link to the PR in the bug on [the bug tracker](https://bugs.php.net/).
40
41Pull requests implementing RFCs should be submitted against `master`.
42
43Pull requests should *never* be submitted against `PHP-x.y.z` branches, as these
44are only used for release management.
45
46If your pull request exhibits conflicts with the base branch, please resolve
47them by using `git rebase` instead of `git merge`.
48
49Fork the official PHP repository and send a pull request. A notification will be
50sent to the pull request mailing list. Sending a note to PHP Internals list
51(internals@lists.php.net) may help getting more feedback and quicker turnaround.
52You can also add pull requests to [bug reports](https://bugs.php.net/).
53
54Read [Git access page](https://www.php.net/git.php) for help on using Git to get
55and build PHP source code. We recommend to look at our
56[workflow](https://wiki.php.net/vcs/gitworkflow) and our
57[FAQ](https://wiki.php.net/vcs/gitfaq).
58
59## Filing bugs
60
61Bugs can be filed on the [PHP bug tracker](https://bugs.php.net/). If this is
62the first time you've filed a bug, we suggest reading the
63[guide to reporting a bug](https://bugs.php.net/how-to-report.php).
64
65Where possible, please include a self-contained reproduction case!
66
67## Feature requests
68
69Feature requests are generally submitted in the form of
70[Requests for Comments (RFC)](https://wiki.php.net/rfc/howto), ideally
71accompanied by [pull requests](#pull-requests). You can find the extremely large
72list of RFCs that have been previously considered on the
73[PHP Wiki](https://wiki.php.net/rfc).
74
75To create a RFC, discuss it with the extension maintainer, and discuss it on the
76development mailing list internals@lists.php.net. RFC Wiki accounts can be
77requested on https://wiki.php.net/start?do=register. PHP extension maintainers
78can be found in the [EXTENSIONS](/EXTENSIONS) file in the PHP source code
79repository. Mailing list subscription is explained on the
80[mailing lists page](https://www.php.net/mailing-lists.php).
81
82You may also want to read
83[The Mysterious PHP RFC Process](https://blogs.oracle.com/opal/entry/the_mysterious_php_rfc_process)
84for additional notes on the best way to approach submitting an RFC.
85
86## Writing tests
87
88We love getting new tests! PHP is a huge project and improving code coverage is
89a huge win for every PHP user.
90
91[Our QA site includes a page detailing how to write test cases.](https://qa.php.net/write-test.php)
92
93Submitting test scripts helps us to understand what functionality has changed.
94It is important for the stability and maintainability of PHP that tests are
95comprehensive.
96
97Failure conditions of `zend_parse_parameters`, `ZEND_PARSE_PARAMETERS()` and
98similar functions should not be tested. These parameter parsing APIs are already
99extensively tested, and additional tests only complicate future modifications.
100
101For newly created tests, a `--CREDITS--` section should no longer be included,
102as test authorship is already accurately tracked by Git. If multiple authors
103should be credited, the `Co-authored-by` tag in the commit message may be used.
104
105## Writing documentation
106
107There are two ways to contribute to the PHP manual. You can edit the manual and
108send patches anonymously via [the online editor](https://edit.php.net/), or you
109can check the XML source out from Subversion and edit that and build it
110[per the instructions on the documentation site](http://doc.php.net/tutorial/).
111Patches created that way should be sent to the
112[documentation mailing list](mailto:phpdoc@lists.php.net).
113
114## Getting help
115
116If you are having trouble contributing to PHP, or just want to talk to a human
117about what you're working on, you can contact us via the
118[internals mailing list](mailto:internals@lists.php.net), or the
119[documentation mailing list](mailto:phpdoc@lists.php.net) for documentation
120issues.
121
122Although not a formal channel, you can also find a number of core developers on
123the #php.pecl channel on [EFnet](http://www.efnet.org/). Similarly, many
124documentation writers can be found on #php.doc. Windows development IRC channel
125is available at #winphp-dev on FreeNode.
126
127## PHP source code directory structure
128
129PHP source code also includes several files generated during development and
130several parts where maintenance is happening upstream in their respective
131locations.
132
133```bash
134<php-src>/
135 ├─ .git/                           # Git configuration and source directory
136 ├─ TSRM/                           # Thread Safe Resource Manager
137 └─ Zend/                           # Zend Engine
138    ├─ zend_vm_execute.h            # Generated by `Zend/zend_vm_gen.php`
139    ├─ zend_vm_opcodes.c            # Generated by `Zend/zend_vm_gen.php`
140    ├─ zend_vm_opcodes.h            # Generated by `Zend/zend_vm_gen.php`
141    └─ ...
142 ├─ appveyor/                       # Appveyor CI service files
143 └─ build/                          # *nix build system files
144    ├─ ax_*.m4                      # https://github.com/autoconf-archive/autoconf-archive
145    ├─ config.guess                 # https://git.savannah.gnu.org/cgit/config.git
146    ├─ config.sub                   # https://git.savannah.gnu.org/cgit/config.git
147    ├─ libtool.m4                   # https://git.savannah.gnu.org/cgit/libtool.git
148    ├─ ltmain.sh                    # https://git.savannah.gnu.org/cgit/libtool.git
149    ├─ shtool                       # https://www.gnu.org/software/shtool/
150    └─ ...
151 ├─ docs/                           # PHP internals and repository documentation
152 └─ ext/                            # PHP core extensions
153    └─ bcmath/
154       ├─ libbcmath/                # Forked and maintained in php-src
155       └─ ...
156    └─ curl/
157       ├─ sync-constants.php        # The curl symbols checker
158       └─ ...
159    └─ date/
160       └─ lib/                      # Bundled datetime library https://github.com/derickr/timelib
161          ├─ parse_date.c           # Generated by re2c 0.15.3
162          ├─ parse_iso_intervals.c  # Generated by re2c 0.15.3
163          └─ ...
164       └─ ...
165    └─ ffi/
166       ├─ ffi_parser.c              # Generated by https://github.com/dstogov/llk
167       └─ ...
168    └─ fileinfo/
169       ├─ libmagic/                 # Modified libmagic https://github.com/file/file
170       ├─ data_file.c               # Generated by `ext/fileinfo/create_data_file.php`
171       ├─ libmagic.patch            # Modifications patch from upstream libmagic
172       ├─ magicdata.patch           # Modifications patch from upstream libmagic
173       └─ ...
174    └─ gd/
175       ├─ libgd/                    # Bundled and modified GD library https://github.com/libgd/libgd
176       └─ ...
177    └─ mbstring/
178       ├─ libmbfl/                  # Forked and maintained in php-src
179       ├─ unicode_data.h            # Generated by `ext/mbstring/ucgendat/ucgendat.php`
180       └─ ...
181    └─ pcre/
182       ├─ pcre2lib/                 # https://www.pcre.org/
183       └─ ...
184    └─ pdo_mysql/
185       ├─ php_pdo_mysql_sqlstate.h  # Generated by `ext/pdo_mysql/get_error_codes.php`
186       └─ ...
187    └─ skeleton/                    # Skeleton for developing new extensions with `ext/ext_skel.php`
188       └─ ...
189    └─ standard/
190       └─ html_tables/
191          ├─ mappings/              # https://www.unicode.org/Public/MAPPINGS/
192          └─ ...
193       ├─ credits_ext.h             # Generated by `scripts/dev/credits`
194       ├─ credits_sapi.h            # Generated by `scripts/dev/credits`
195       ├─ html_tables.h             # Generated by `ext/standard/html_tables/html_table_gen.php`
196       └─ ...
197    └─ tokenizer/
198       ├─ tokenizer_data.c          # Generated by `ext/tokenizer/tokenizer_data_gen.sh`
199       └─ ...
200    └─ xmlrpc/
201       ├─ libxmlrpc/                # Forked and maintained in php-src
202       └─ ...
203    └─ zend_test                    # For testing internal APIs. Not needed for regular builds.
204       └─ ...
205    └─ zip/                         # Bundled https://github.com/pierrejoye/php_zip
206       └─ ...
207    └─ ...
208 └─ main/                           # Binding that ties extensions, SAPIs, and engine together
209    ├─ streams/                     # Streams layer subsystem
210    ├─ php_version.h                # Generated by release managers using `configure`
211    └─ ...
212 ├─ pear/                           # PEAR installation
213 └─ sapi/                           # PHP SAPI modules
214    └─ cli/
215       ├─ mime_type_map.h           # Generated by `sapi/cli/generate_mime_type_map.php`
216       └─ ...
217    └─ ...
218 ├─ scripts/                        # php-config, phpize and internal development scripts
219 ├─ tests/                          # Core features tests
220 ├─ travis/                         # Travis CI service files
221 └─ win32/                          # Windows build system files
222    ├─ cp_enc_map.c                 # Generated by `win32/cp_enc_map_gen.exe`
223    └─ ...
224 └─ ...
225```
226
227## PHP internals
228
229For information on PHP internal C functions see
230[References about Maintaining and Extending PHP](https://wiki.php.net/internals/references).
231Various external resources can be found on the web. A standard printed reference
232is the book "Extending and Embedding PHP" by Sara Golemon.
233
234## PECL extensions
235
236If you are fixing broken functionality in a [PECL](https://pecl.php.net)
237extension then create a bug or identify an existing bug at
238[bugs.php.net](https://bugs.php.net). A bug can be used to track the change
239progress and prevent your changes getting lost in the PHP mail archives. Some
240PECL extensions have their own bug tracker locations and different contributing
241procedures.
242
243If your change is large then create a
244[Request for Comments (RFC)](https://wiki.php.net/rfc), discuss it with the
245extension maintainer, and discuss it on the development mailing list
246pecl-dev@lists.php.net depending on the extension. PECL mailing list
247subscription is explained on the
248[PECL support page](https://pecl.php.net/support.php).
249
250Update any open bugs and add a link to the source of your change. Send the patch
251or pointer to the bug to pecl-dev@lists.php.net. Also CC the extension
252maintainer. Explain what has been changed by your patch. Test scripts should be
253included.
254
255## Checklist for submitting contribution
256
257- Read [Coding standards](/CODING_STANDARDS.md) before you start working.
258- Update git source just before running your final `diff` and before testing.
259- Add in-line comments and/or have external documentation ready. Use only
260  `/* */` style comments, not `//`.
261- Create test scripts for use with `make test`.
262- Run `make test` to check your change doesn't break other features.
263- Rebuild PHP with `--enable-debug` which will show some kinds of memory errors
264  and check the PHP and web server error logs after running your PHP tests.
265- Rebuild PHP with `--enable-maintainer-zts` to check your change compiles on
266  multi-threaded web servers.
267- Review the change once more just before submitting it.
268
269## What happens after submitting contribution?
270
271If your change is easy to review and obviously has no side-effects, it might be
272committed relatively quickly.
273
274Because PHP is a volunteer-driven effort more complex changes will require
275patience on your side. If you do not receive feedback in a few days, consider
276bumping. Before doing this think about these questions:
277
278- Did I send the patch to the right mailing list?
279- Did I review the mailing list archives to see if these kind of changes had
280  been discussed before?
281- Did I explain my change clearly?
282- Is my change too hard to review? Because of what factors?
283
284## What happens when your contribution is applied?
285
286Your name will likely be included in the Git commit log. If your change affects
287end users, a brief description and your name might be added to the [NEWS](/NEWS)
288file.
289
290## Git commit rules
291
292This section refers to contributors that have Git push access and make commit
293changes themselves. We'll assume you're basically familiar with Git, but feel
294free to post your questions on the mailing list. Please have a look at the more
295detailed [information on Git](https://git-scm.com/).
296
297PHP is developed through the efforts of a large number of people. Collaboration
298is a Good Thing(tm), and Git lets us do this. Thus, following some basic rules
299with regards to Git usage will:
300
301* Make everybody happier, especially those responsible for maintaining PHP
302  itself.
303* Keep the changes consistently well documented and easily trackable.
304* Prevent some of those 'Oops' moments.
305* Increase the general level of good will on planet Earth.
306
307Having said that, here are the organizational rules:
308
3091. Respect other people working on the project.
310
3112. Discuss any significant changes on the list before committing and get
312   confirmation from the release manager for the given branch.
313
3143. Look at [EXTENSIONS](/EXTENSIONS) file to see who is the primary maintainer
315   of the code you want to contribute to.
316
3174. If you "strongly disagree" about something another person did, don't start
318   fighting publicly - take it up in private email.
319
3205. If you don't know how to do something, ask first!
321
3226. Test your changes before committing them. We mean it. Really. To do so use
323   `make test`.
324
3257. For development use the `--enable-debug` switch to avoid memory leaks and the
326   `--enable-maintainer-zts` switch to ensure your code handles TSRM correctly
327   and doesn't break for those who need that.
328
329Currently we have the following branches in use:
330
331| Branch    |           |
332| --------- | --------- |
333| master    | Active development branch for PHP 8.0, which is open for backwards incompatible changes and major internal API changes. |
334| PHP-7.4   | Is used to release the PHP 7.4.x series. This is a current stable version and is open for bugfixes only. |
335| PHP-7.3   | Is used to release the PHP 7.3.x series. This is a current stable version and is open for bugfixes only. |
336| PHP-7.2   | Is used to release the PHP 7.2.x series. This is an old stable version and is open for security fixes only. |
337| PHP-7.1   | This branch is closed. |
338| PHP-7.0   | This branch is closed. |
339| PHP-5.6   | This branch is closed. |
340| PHP-5.5   | This branch is closed. |
341| PHP-5.4   | This branch is closed. |
342| PHP-5.3   | This branch is closed. |
343| PHP-5.2   | This branch is closed. |
344| PHP-5.1   | This branch is closed. |
345| PHP-4.4   | This branch is closed. |
346| PHP-X.Y.Z | These branches are used for the release managers for tagging the releases, hence they are closed to the general public. |
347
348The next few rules are more of a technical nature:
349
3501. All non-security bugfix changes should first go to the lowest bugfix branch
351   (i.e. 7.3) and then get merged up to all other branches. All security fixes
352   should go to the lowest security fixes branch (i.e 7.2). If a change is not
353   needed for later branches (i.e. fixes for features which were dropped from
354   later branches) an empty merge should be done.
355
3562. All news updates intended for public viewing, such as new features, bug
357   fixes, improvements, etc., should go into the NEWS file of *any stable
358   release* version with the given change. In other words, news about a bug fix
359   which went into PHP-5.4, PHP-5.5 and master should be noted in both
360   PHP-5.4/NEWS and PHP-5.5/NEWS but not master, which is not a public released
361   version yet.
362
3633. Do not commit multiple files and dump all messages in one commit. If you
364   modified several unrelated files, commit each group separately and provide a
365   nice commit message for each one. See example below.
366
3674. Do write your commit message in such a way that it makes sense even without
368   the corresponding diff. One should be able to look at it, and immediately
369   know what was modified. Definitely include the function name in the message
370   as shown below.
371
3725. In your commit messages, keep each line shorter than 80 characters. And try
373   to align your lines vertically, if they wrap. It looks bad otherwise.
374
3756. If you modified a function that is callable from PHP, prepend PHP to the
376   function name as shown below.
377
378The format of the commit messages is pretty simple.
379
380    <max 79 characters short description>\n
381    \n
382    <long description, 79 chars per line>
383    \n
384
385An Example from the git project (commit 2b34e486bc):
386
387    pack-objects: Fix compilation with NO_PTHREDS
388
389    It looks like commit 99fb6e04 (pack-objects: convert to use parse_options(),
390    2012-02-01) moved the #ifdef NO_PTHREDS around but hasn't noticed that the
391    'arg' variable no longer is available.
392
393If you fix some bugs, you should note the bug ID numbers in your commit message.
394Bug ID should be prefixed by `#`.
395
396Example:
397
398    Fixed bug #14016 (pgsql notice handler double free crash bug.)
399
400When you change the NEWS file for a bug fix, then please keep the bugs sorted in
401decreasing order under the fixed version.
402
403You can use [gitweb](https://git.php.net/) to look at PHP Git repository in
404various ways.
405
406## Copyright and license headers
407
408New source code files should include the following header block:
409
410```c
411/*
412  +----------------------------------------------------------------------+
413  | PHP Version 7                                                        |
414  +----------------------------------------------------------------------+
415  | Copyright (c) The PHP Group                                          |
416  +----------------------------------------------------------------------+
417  | This source file is subject to version 3.01 of the PHP license,      |
418  | that is bundled with this package in the file LICENSE, and is        |
419  | available through the world-wide-web at the following url:           |
420  | https://www.php.net/license/3_01.txt                                 |
421  | If you did not receive a copy of the PHP license and are unable to   |
422  | obtain it through the world-wide-web, please send a note to          |
423  | license@php.net so we can mail you a copy immediately.               |
424  +----------------------------------------------------------------------+
425  | Author:                                                              |
426  +----------------------------------------------------------------------+
427*/
428```
429
430Thank you for contributing to PHP!
431