xref: /PHP-7.4/CONTRIBUTING.md (revision 9458f7e2)
181f4a7dfSAdam Harvey# Contributing to PHP
281f4a7dfSAdam Harvey
381f4a7dfSAdam HarveyAnybody who programs in PHP can be a contributing member of the community that
4886b2a22SPeter Kokotdevelops and deploys it; the task of deploying PHP, documentation and associated
5886b2a22SPeter Kokotwebsites is a never ending one. With every release, or release candidate comes a
6886b2a22SPeter Kokotwave of work, which takes a lot of organization and co-ordination.
7886b2a22SPeter Kokot
8886b2a22SPeter KokotYou don't need any special access to download, build, debug and begin submitting
9886b2a22SPeter KokotPHP or PECL code, tests or documentation. Once you've followed this guide and
10886b2a22SPeter Kokothad several contributions accepted, commit privileges are often quickly granted.
11886b2a22SPeter Kokot
12886b2a22SPeter Kokot## Index
13886b2a22SPeter Kokot
14886b2a22SPeter Kokot* [Pull requests](#pull-requests)
15886b2a22SPeter Kokot* [Filing bugs](#filing-bugs)
16886b2a22SPeter Kokot* [Feature requests](#feature-requests)
17886b2a22SPeter Kokot* [Writing tests](#writing-tests)
18886b2a22SPeter Kokot* [Writing documentation](#writing-documentation)
19886b2a22SPeter Kokot* [Getting help](#getting-help)
20886b2a22SPeter Kokot* [PHP source code directory structure](#php-source-code-directory-structure)
21886b2a22SPeter Kokot* [PHP internals](#php-internals)
22886b2a22SPeter Kokot* [PECL extensions](#pecl-extensions)
23886b2a22SPeter Kokot* [Checklist for submitting contribution](#checklist-for-submitting-contribution)
24886b2a22SPeter Kokot* [What happens after submitting contribution?](#what-happens-after-submitting-contribution)
25886b2a22SPeter Kokot* [What happens when your contribution is applied?](#what-happens-when-your-contribution-is-applied)
26a8e879c5SPeter Kokot* [Git commit rules](#git-commit-rules)
2763ef554fSPeter Kokot* [Copyright and license headers](#copyright-and-license-headers)
2881f4a7dfSAdam Harvey
2981f4a7dfSAdam Harvey## Pull requests
3081f4a7dfSAdam Harvey
3181f4a7dfSAdam HarveyPHP welcomes pull requests to [add tests](#writing-tests), fix bugs and to
3281f4a7dfSAdam Harveyimplement RFCs. Please be sure to include tests as appropriate!
3381f4a7dfSAdam Harvey
3419a692b7SNikita PopovIf you are fixing a bug, then please submit your PR against the lowest actively
3519a692b7SNikita Popovsupported branch of PHP that the bug affects (only green branches on
36886b2a22SPeter Kokot[the supported version page](https://www.php.net/supported-versions.php) are
37886b2a22SPeter Kokotsupported). For example, at the time of writing, the lowest supported version is
38250416ccSChristoph M. BeckerPHP 7.3, which corresponds to the `PHP-7.3` branch in Git. Please also make sure
39886b2a22SPeter Kokotyou add a link to the PR in the bug on [the bug tracker](https://bugs.php.net/).
4019a692b7SNikita Popov
4119a692b7SNikita PopovPull requests implementing RFCs should be submitted against `master`.
4219a692b7SNikita Popov
43886b2a22SPeter KokotPull requests should *never* be submitted against `PHP-x.y.z` branches, as these
44886b2a22SPeter Kokotare only used for release management.
4519a692b7SNikita Popov
46886b2a22SPeter KokotIf your pull request exhibits conflicts with the base branch, please resolve
47886b2a22SPeter Kokotthem by using `git rebase` instead of `git merge`.
48886b2a22SPeter Kokot
49886b2a22SPeter KokotFork the official PHP repository and send a pull request. A notification will be
50886b2a22SPeter Kokotsent to the pull request mailing list. Sending a note to PHP Internals list
51886b2a22SPeter Kokot(internals@lists.php.net) may help getting more feedback and quicker turnaround.
52886b2a22SPeter KokotYou can also add pull requests to [bug reports](https://bugs.php.net/).
53886b2a22SPeter Kokot
54886b2a22SPeter KokotRead [Git access page](https://www.php.net/git.php) for help on using Git to get
55886b2a22SPeter Kokotand build PHP source code. We recommend to look at our
56886b2a22SPeter Kokot[workflow](https://wiki.php.net/vcs/gitworkflow) and our
57886b2a22SPeter Kokot[FAQ](https://wiki.php.net/vcs/gitfaq).
5881f4a7dfSAdam Harvey
5981f4a7dfSAdam Harvey## Filing bugs
6081f4a7dfSAdam Harvey
6181f4a7dfSAdam HarveyBugs can be filed on the [PHP bug tracker](https://bugs.php.net/). If this is
6281f4a7dfSAdam Harveythe first time you've filed a bug, we suggest reading the
6381f4a7dfSAdam Harvey[guide to reporting a bug](https://bugs.php.net/how-to-report.php).
6481f4a7dfSAdam Harvey
6581f4a7dfSAdam HarveyWhere possible, please include a self-contained reproduction case!
6681f4a7dfSAdam Harvey
6781f4a7dfSAdam Harvey## Feature requests
6881f4a7dfSAdam Harvey
6981f4a7dfSAdam HarveyFeature requests are generally submitted in the form of
70886b2a22SPeter Kokot[Requests for Comments (RFC)](https://wiki.php.net/rfc/howto), ideally
71886b2a22SPeter Kokotaccompanied by [pull requests](#pull-requests). You can find the extremely large
72886b2a22SPeter Kokotlist of RFCs that have been previously considered on the
7381f4a7dfSAdam Harvey[PHP Wiki](https://wiki.php.net/rfc).
7481f4a7dfSAdam Harvey
75886b2a22SPeter KokotTo create a RFC, discuss it with the extension maintainer, and discuss it on the
76886b2a22SPeter Kokotdevelopment mailing list internals@lists.php.net. RFC Wiki accounts can be
77886b2a22SPeter Kokotrequested on https://wiki.php.net/start?do=register. PHP extension maintainers
78886b2a22SPeter Kokotcan be found in the [EXTENSIONS](/EXTENSIONS) file in the PHP source code
79886b2a22SPeter Kokotrepository. Mailing list subscription is explained on the
80886b2a22SPeter Kokot[mailing lists page](https://www.php.net/mailing-lists.php).
81886b2a22SPeter Kokot
82886b2a22SPeter KokotYou may also want to read
8381f4a7dfSAdam Harvey[The Mysterious PHP RFC Process](https://blogs.oracle.com/opal/entry/the_mysterious_php_rfc_process)
8481f4a7dfSAdam Harveyfor additional notes on the best way to approach submitting an RFC.
8581f4a7dfSAdam Harvey
8681f4a7dfSAdam Harvey## Writing tests
8781f4a7dfSAdam Harvey
8881f4a7dfSAdam HarveyWe love getting new tests! PHP is a huge project and improving code coverage is
8981f4a7dfSAdam Harveya huge win for every PHP user.
9081f4a7dfSAdam Harvey
91886b2a22SPeter Kokot[Our QA site includes a page detailing how to write test cases.](https://qa.php.net/write-test.php)
92886b2a22SPeter Kokot
93886b2a22SPeter KokotSubmitting test scripts helps us to understand what functionality has changed.
94886b2a22SPeter KokotIt is important for the stability and maintainability of PHP that tests are
95886b2a22SPeter Kokotcomprehensive.
9681f4a7dfSAdam Harvey
977514b5d9SNikita PopovFailure conditions of `zend_parse_parameters`, `ZEND_PARSE_PARAMETERS()` and
987514b5d9SNikita Popovsimilar functions should not be tested. These parameter parsing APIs are already
997514b5d9SNikita Popovextensively tested, and additional tests only complicate future modifications.
1007514b5d9SNikita Popov
1017514b5d9SNikita PopovFor newly created tests, a `--CREDITS--` section should no longer be included,
1027514b5d9SNikita Popovas test authorship is already accurately tracked by Git. If multiple authors
1037514b5d9SNikita Popovshould be credited, the `Co-authored-by` tag in the commit message may be used.
1047514b5d9SNikita Popov
1050c50f497SAdam Harvey## Writing documentation
1060c50f497SAdam Harvey
1070c50f497SAdam HarveyThere are two ways to contribute to the PHP manual. You can edit the manual and
1080c50f497SAdam Harveysend patches anonymously via [the online editor](https://edit.php.net/), or you
1090c50f497SAdam Harveycan check the XML source out from Subversion and edit that and build it
1100c50f497SAdam Harvey[per the instructions on the documentation site](http://doc.php.net/tutorial/).
1110c50f497SAdam HarveyPatches created that way should be sent to the
1120c50f497SAdam Harvey[documentation mailing list](mailto:phpdoc@lists.php.net).
1130c50f497SAdam Harvey
11481f4a7dfSAdam Harvey## Getting help
11581f4a7dfSAdam Harvey
11681f4a7dfSAdam HarveyIf you are having trouble contributing to PHP, or just want to talk to a human
11781f4a7dfSAdam Harveyabout what you're working on, you can contact us via the
1180c50f497SAdam Harvey[internals mailing list](mailto:internals@lists.php.net), or the
1190c50f497SAdam Harvey[documentation mailing list](mailto:phpdoc@lists.php.net) for documentation
1200c50f497SAdam Harveyissues.
12181f4a7dfSAdam Harvey
12281f4a7dfSAdam HarveyAlthough not a formal channel, you can also find a number of core developers on
1230c50f497SAdam Harveythe #php.pecl channel on [EFnet](http://www.efnet.org/). Similarly, many
124886b2a22SPeter Kokotdocumentation writers can be found on #php.doc. Windows development IRC channel
125886b2a22SPeter Kokotis available at #winphp-dev on FreeNode.
126949becb1SPeter Kokot
127949becb1SPeter Kokot## PHP source code directory structure
128949becb1SPeter Kokot
129949becb1SPeter KokotPHP source code also includes several files generated during development and
130949becb1SPeter Kokotseveral parts where maintenance is happening upstream in their respective
131949becb1SPeter Kokotlocations.
132949becb1SPeter Kokot
133949becb1SPeter Kokot```bash
134949becb1SPeter Kokot<php-src>/
135949becb1SPeter Kokot ├─ .git/                           # Git configuration and source directory
136beb58ca1SPeter Kokot ├─ TSRM/                           # Thread Safe Resource Manager
137949becb1SPeter Kokot └─ Zend/                           # Zend Engine
138949becb1SPeter Kokot    ├─ zend_vm_execute.h            # Generated by `Zend/zend_vm_gen.php`
139949becb1SPeter Kokot    ├─ zend_vm_opcodes.c            # Generated by `Zend/zend_vm_gen.php`
140949becb1SPeter Kokot    ├─ zend_vm_opcodes.h            # Generated by `Zend/zend_vm_gen.php`
141949becb1SPeter Kokot    └─ ...
142949becb1SPeter Kokot ├─ appveyor/                       # Appveyor CI service files
143949becb1SPeter Kokot └─ build/                          # *nix build system files
144beb58ca1SPeter Kokot    ├─ ax_*.m4                      # https://github.com/autoconf-archive/autoconf-archive
1457e445ef3SPeter Kokot    ├─ config.guess                 # https://git.savannah.gnu.org/cgit/config.git
1467e445ef3SPeter Kokot    ├─ config.sub                   # https://git.savannah.gnu.org/cgit/config.git
147949becb1SPeter Kokot    ├─ libtool.m4                   # https://git.savannah.gnu.org/cgit/libtool.git
1487e445ef3SPeter Kokot    ├─ ltmain.sh                    # https://git.savannah.gnu.org/cgit/libtool.git
149949becb1SPeter Kokot    ├─ shtool                       # https://www.gnu.org/software/shtool/
150949becb1SPeter Kokot    └─ ...
151fbb8ada0SPeter Kokot ├─ docs/                           # PHP internals and repository documentation
152949becb1SPeter Kokot └─ ext/                            # PHP core extensions
153949becb1SPeter Kokot    └─ bcmath/
154949becb1SPeter Kokot       ├─ libbcmath/                # Forked and maintained in php-src
155949becb1SPeter Kokot       └─ ...
156949becb1SPeter Kokot    └─ curl/
157949becb1SPeter Kokot       ├─ sync-constants.php        # The curl symbols checker
158949becb1SPeter Kokot       └─ ...
159949becb1SPeter Kokot    └─ date/
160949becb1SPeter Kokot       └─ lib/                      # Bundled datetime library https://github.com/derickr/timelib
161949becb1SPeter Kokot          ├─ parse_date.c           # Generated by re2c 0.15.3
162949becb1SPeter Kokot          ├─ parse_iso_intervals.c  # Generated by re2c 0.15.3
163949becb1SPeter Kokot          └─ ...
164949becb1SPeter Kokot       └─ ...
16504a9d6b9SPeter Kokot    └─ ffi/
16604a9d6b9SPeter Kokot       ├─ ffi_parser.c              # Generated by https://github.com/dstogov/llk
16704a9d6b9SPeter Kokot       └─ ...
168949becb1SPeter Kokot    └─ fileinfo/
169949becb1SPeter Kokot       ├─ libmagic/                 # Modified libmagic https://github.com/file/file
170949becb1SPeter Kokot       ├─ data_file.c               # Generated by `ext/fileinfo/create_data_file.php`
171949becb1SPeter Kokot       ├─ libmagic.patch            # Modifications patch from upstream libmagic
172949becb1SPeter Kokot       ├─ magicdata.patch           # Modifications patch from upstream libmagic
173949becb1SPeter Kokot       └─ ...
174949becb1SPeter Kokot    └─ gd/
175949becb1SPeter Kokot       ├─ libgd/                    # Bundled and modified GD library https://github.com/libgd/libgd
176949becb1SPeter Kokot       └─ ...
177949becb1SPeter Kokot    └─ mbstring/
178949becb1SPeter Kokot       ├─ libmbfl/                  # Forked and maintained in php-src
179949becb1SPeter Kokot       ├─ unicode_data.h            # Generated by `ext/mbstring/ucgendat/ucgendat.php`
180949becb1SPeter Kokot       └─ ...
181949becb1SPeter Kokot    └─ pcre/
182949becb1SPeter Kokot       ├─ pcre2lib/                 # https://www.pcre.org/
183949becb1SPeter Kokot       └─ ...
18441ac1d49SPeter Kokot    └─ pdo_mysql/
18541ac1d49SPeter Kokot       ├─ php_pdo_mysql_sqlstate.h  # Generated by `ext/pdo_mysql/get_error_codes.php`
18641ac1d49SPeter Kokot       └─ ...
187949becb1SPeter Kokot    └─ skeleton/                    # Skeleton for developing new extensions with `ext/ext_skel.php`
188949becb1SPeter Kokot       └─ ...
189949becb1SPeter Kokot    └─ standard/
190949becb1SPeter Kokot       └─ html_tables/
191949becb1SPeter Kokot          ├─ mappings/              # https://www.unicode.org/Public/MAPPINGS/
192949becb1SPeter Kokot          └─ ...
193949becb1SPeter Kokot       ├─ credits_ext.h             # Generated by `scripts/dev/credits`
194949becb1SPeter Kokot       ├─ credits_sapi.h            # Generated by `scripts/dev/credits`
195949becb1SPeter Kokot       ├─ html_tables.h             # Generated by `ext/standard/html_tables/html_table_gen.php`
196949becb1SPeter Kokot       └─ ...
197949becb1SPeter Kokot    └─ tokenizer/
198949becb1SPeter Kokot       ├─ tokenizer_data.c          # Generated by `ext/tokenizer/tokenizer_data_gen.sh`
199949becb1SPeter Kokot       └─ ...
200949becb1SPeter Kokot    └─ xmlrpc/
201949becb1SPeter Kokot       ├─ libxmlrpc/                # Forked and maintained in php-src
202949becb1SPeter Kokot       └─ ...
203949becb1SPeter Kokot    └─ zend_test                    # For testing internal APIs. Not needed for regular builds.
204949becb1SPeter Kokot       └─ ...
205949becb1SPeter Kokot    └─ zip/                         # Bundled https://github.com/pierrejoye/php_zip
206949becb1SPeter Kokot       └─ ...
207949becb1SPeter Kokot    └─ ...
208949becb1SPeter Kokot └─ main/                           # Binding that ties extensions, SAPIs, and engine together
209949becb1SPeter Kokot    ├─ streams/                     # Streams layer subsystem
210949becb1SPeter Kokot    ├─ php_version.h                # Generated by release managers using `configure`
211949becb1SPeter Kokot    └─ ...
212949becb1SPeter Kokot ├─ pear/                           # PEAR installation
213949becb1SPeter Kokot └─ sapi/                           # PHP SAPI modules
214949becb1SPeter Kokot    └─ cli/
215949becb1SPeter Kokot       ├─ mime_type_map.h           # Generated by `sapi/cli/generate_mime_type_map.php`
216949becb1SPeter Kokot       └─ ...
217949becb1SPeter Kokot    └─ ...
218949becb1SPeter Kokot ├─ scripts/                        # php-config, phpize and internal development scripts
219949becb1SPeter Kokot ├─ tests/                          # Core features tests
220949becb1SPeter Kokot ├─ travis/                         # Travis CI service files
221949becb1SPeter Kokot └─ win32/                          # Windows build system files
222949becb1SPeter Kokot    ├─ cp_enc_map.c                 # Generated by `win32/cp_enc_map_gen.exe`
223949becb1SPeter Kokot    └─ ...
224949becb1SPeter Kokot └─ ...
225949becb1SPeter Kokot```
226886b2a22SPeter Kokot
227886b2a22SPeter Kokot## PHP internals
228886b2a22SPeter Kokot
229886b2a22SPeter KokotFor information on PHP internal C functions see
230886b2a22SPeter Kokot[References about Maintaining and Extending PHP](https://wiki.php.net/internals/references).
231886b2a22SPeter KokotVarious external resources can be found on the web. A standard printed reference
232886b2a22SPeter Kokotis the book "Extending and Embedding PHP" by Sara Golemon.
233886b2a22SPeter Kokot
234886b2a22SPeter Kokot## PECL extensions
235886b2a22SPeter Kokot
236886b2a22SPeter KokotIf you are fixing broken functionality in a [PECL](https://pecl.php.net)
237886b2a22SPeter Kokotextension then create a bug or identify an existing bug at
238886b2a22SPeter Kokot[bugs.php.net](https://bugs.php.net). A bug can be used to track the change
239886b2a22SPeter Kokotprogress and prevent your changes getting lost in the PHP mail archives. Some
240886b2a22SPeter KokotPECL extensions have their own bug tracker locations and different contributing
241886b2a22SPeter Kokotprocedures.
242886b2a22SPeter Kokot
243886b2a22SPeter KokotIf your change is large then create a
244886b2a22SPeter Kokot[Request for Comments (RFC)](https://wiki.php.net/rfc), discuss it with the
245886b2a22SPeter Kokotextension maintainer, and discuss it on the development mailing list
246886b2a22SPeter Kokotpecl-dev@lists.php.net depending on the extension. PECL mailing list
247886b2a22SPeter Kokotsubscription is explained on the
248886b2a22SPeter Kokot[PECL support page](https://pecl.php.net/support.php).
249886b2a22SPeter Kokot
250886b2a22SPeter KokotUpdate any open bugs and add a link to the source of your change. Send the patch
251886b2a22SPeter Kokotor pointer to the bug to pecl-dev@lists.php.net. Also CC the extension
252886b2a22SPeter Kokotmaintainer. Explain what has been changed by your patch. Test scripts should be
253886b2a22SPeter Kokotincluded.
254886b2a22SPeter Kokot
255886b2a22SPeter Kokot## Checklist for submitting contribution
256886b2a22SPeter Kokot
257f45b61b8SPeter Kokot- Read [Coding standards](/CODING_STANDARDS.md) before you start working.
258886b2a22SPeter Kokot- Update git source just before running your final `diff` and before testing.
259886b2a22SPeter Kokot- Add in-line comments and/or have external documentation ready. Use only
260886b2a22SPeter Kokot  `/* */` style comments, not `//`.
261886b2a22SPeter Kokot- Create test scripts for use with `make test`.
262886b2a22SPeter Kokot- Run `make test` to check your change doesn't break other features.
263886b2a22SPeter Kokot- Rebuild PHP with `--enable-debug` which will show some kinds of memory errors
264886b2a22SPeter Kokot  and check the PHP and web server error logs after running your PHP tests.
265886b2a22SPeter Kokot- Rebuild PHP with `--enable-maintainer-zts` to check your change compiles on
266886b2a22SPeter Kokot  multi-threaded web servers.
267886b2a22SPeter Kokot- Review the change once more just before submitting it.
268886b2a22SPeter Kokot
269886b2a22SPeter Kokot## What happens after submitting contribution?
270886b2a22SPeter Kokot
271886b2a22SPeter KokotIf your change is easy to review and obviously has no side-effects, it might be
272886b2a22SPeter Kokotcommitted relatively quickly.
273886b2a22SPeter Kokot
274886b2a22SPeter KokotBecause PHP is a volunteer-driven effort more complex changes will require
275886b2a22SPeter Kokotpatience on your side. If you do not receive feedback in a few days, consider
276886b2a22SPeter Kokotbumping. Before doing this think about these questions:
277886b2a22SPeter Kokot
278886b2a22SPeter Kokot- Did I send the patch to the right mailing list?
279886b2a22SPeter Kokot- Did I review the mailing list archives to see if these kind of changes had
280886b2a22SPeter Kokot  been discussed before?
281886b2a22SPeter Kokot- Did I explain my change clearly?
282886b2a22SPeter Kokot- Is my change too hard to review? Because of what factors?
283886b2a22SPeter Kokot
284886b2a22SPeter Kokot## What happens when your contribution is applied?
285886b2a22SPeter Kokot
286886b2a22SPeter KokotYour name will likely be included in the Git commit log. If your change affects
287886b2a22SPeter Kokotend users, a brief description and your name might be added to the [NEWS](/NEWS)
288886b2a22SPeter Kokotfile.
289886b2a22SPeter Kokot
290a8e879c5SPeter Kokot## Git commit rules
291a8e879c5SPeter Kokot
292a8e879c5SPeter KokotThis section refers to contributors that have Git push access and make commit
293a8e879c5SPeter Kokotchanges themselves. We'll assume you're basically familiar with Git, but feel
294a8e879c5SPeter Kokotfree to post your questions on the mailing list. Please have a look at the more
295a8e879c5SPeter Kokotdetailed [information on Git](https://git-scm.com/).
296a8e879c5SPeter Kokot
297a8e879c5SPeter KokotPHP is developed through the efforts of a large number of people. Collaboration
298a8e879c5SPeter Kokotis a Good Thing(tm), and Git lets us do this. Thus, following some basic rules
299a8e879c5SPeter Kokotwith regards to Git usage will:
300a8e879c5SPeter Kokot
301a8e879c5SPeter Kokot* Make everybody happier, especially those responsible for maintaining PHP
302a8e879c5SPeter Kokot  itself.
303a8e879c5SPeter Kokot* Keep the changes consistently well documented and easily trackable.
304a8e879c5SPeter Kokot* Prevent some of those 'Oops' moments.
305a8e879c5SPeter Kokot* Increase the general level of good will on planet Earth.
306a8e879c5SPeter Kokot
307a8e879c5SPeter KokotHaving said that, here are the organizational rules:
308a8e879c5SPeter Kokot
309a8e879c5SPeter Kokot1. Respect other people working on the project.
310a8e879c5SPeter Kokot
311a8e879c5SPeter Kokot2. Discuss any significant changes on the list before committing and get
312a8e879c5SPeter Kokot   confirmation from the release manager for the given branch.
313a8e879c5SPeter Kokot
314a8e879c5SPeter Kokot3. Look at [EXTENSIONS](/EXTENSIONS) file to see who is the primary maintainer
315a8e879c5SPeter Kokot   of the code you want to contribute to.
316a8e879c5SPeter Kokot
317a8e879c5SPeter Kokot4. If you "strongly disagree" about something another person did, don't start
318a8e879c5SPeter Kokot   fighting publicly - take it up in private email.
319a8e879c5SPeter Kokot
320a8e879c5SPeter Kokot5. If you don't know how to do something, ask first!
321a8e879c5SPeter Kokot
322a8e879c5SPeter Kokot6. Test your changes before committing them. We mean it. Really. To do so use
323a8e879c5SPeter Kokot   `make test`.
324a8e879c5SPeter Kokot
325a8e879c5SPeter Kokot7. For development use the `--enable-debug` switch to avoid memory leaks and the
326a8e879c5SPeter Kokot   `--enable-maintainer-zts` switch to ensure your code handles TSRM correctly
327a8e879c5SPeter Kokot   and doesn't break for those who need that.
328a8e879c5SPeter Kokot
329a8e879c5SPeter KokotCurrently we have the following branches in use:
330a8e879c5SPeter Kokot
331a8e879c5SPeter Kokot| Branch    |           |
332a8e879c5SPeter Kokot| --------- | --------- |
333a8e879c5SPeter Kokot| master    | Active development branch for PHP 8.0, which is open for backwards incompatible changes and major internal API changes. |
334*9458f7e2SChristoph M. Becker| 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. |
335a8e879c5SPeter Kokot| 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. |
336250416ccSChristoph M. Becker| 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. |
337250416ccSChristoph M. Becker| PHP-7.1   | This branch is closed. |
338a8e879c5SPeter Kokot| PHP-7.0   | This branch is closed. |
339a8e879c5SPeter Kokot| PHP-5.6   | This branch is closed. |
340a8e879c5SPeter Kokot| PHP-5.5   | This branch is closed. |
341a8e879c5SPeter Kokot| PHP-5.4   | This branch is closed. |
342a8e879c5SPeter Kokot| PHP-5.3   | This branch is closed. |
343a8e879c5SPeter Kokot| PHP-5.2   | This branch is closed. |
344a8e879c5SPeter Kokot| PHP-5.1   | This branch is closed. |
345a8e879c5SPeter Kokot| PHP-4.4   | This branch is closed. |
346a8e879c5SPeter Kokot| PHP-X.Y.Z | These branches are used for the release managers for tagging the releases, hence they are closed to the general public. |
347a8e879c5SPeter Kokot
348a8e879c5SPeter KokotThe next few rules are more of a technical nature:
349a8e879c5SPeter Kokot
350a8e879c5SPeter Kokot1. All non-security bugfix changes should first go to the lowest bugfix branch
351250416ccSChristoph M. Becker   (i.e. 7.3) and then get merged up to all other branches. All security fixes
352250416ccSChristoph M. Becker   should go to the lowest security fixes branch (i.e 7.2). If a change is not
353a8e879c5SPeter Kokot   needed for later branches (i.e. fixes for features which were dropped from
354a8e879c5SPeter Kokot   later branches) an empty merge should be done.
355a8e879c5SPeter Kokot
356a8e879c5SPeter Kokot2. All news updates intended for public viewing, such as new features, bug
357a8e879c5SPeter Kokot   fixes, improvements, etc., should go into the NEWS file of *any stable
358a8e879c5SPeter Kokot   release* version with the given change. In other words, news about a bug fix
359a8e879c5SPeter Kokot   which went into PHP-5.4, PHP-5.5 and master should be noted in both
360a8e879c5SPeter Kokot   PHP-5.4/NEWS and PHP-5.5/NEWS but not master, which is not a public released
361a8e879c5SPeter Kokot   version yet.
362a8e879c5SPeter Kokot
363a8e879c5SPeter Kokot3. Do not commit multiple files and dump all messages in one commit. If you
364a8e879c5SPeter Kokot   modified several unrelated files, commit each group separately and provide a
365a8e879c5SPeter Kokot   nice commit message for each one. See example below.
366a8e879c5SPeter Kokot
367a8e879c5SPeter Kokot4. Do write your commit message in such a way that it makes sense even without
368a8e879c5SPeter Kokot   the corresponding diff. One should be able to look at it, and immediately
369a8e879c5SPeter Kokot   know what was modified. Definitely include the function name in the message
370a8e879c5SPeter Kokot   as shown below.
371a8e879c5SPeter Kokot
372a8e879c5SPeter Kokot5. In your commit messages, keep each line shorter than 80 characters. And try
373a8e879c5SPeter Kokot   to align your lines vertically, if they wrap. It looks bad otherwise.
374a8e879c5SPeter Kokot
375a8e879c5SPeter Kokot6. If you modified a function that is callable from PHP, prepend PHP to the
376a8e879c5SPeter Kokot   function name as shown below.
377a8e879c5SPeter Kokot
378a8e879c5SPeter KokotThe format of the commit messages is pretty simple.
379a8e879c5SPeter Kokot
380a8e879c5SPeter Kokot    <max 79 characters short description>\n
381a8e879c5SPeter Kokot    \n
382a8e879c5SPeter Kokot    <long description, 79 chars per line>
383a8e879c5SPeter Kokot    \n
384a8e879c5SPeter Kokot
385a8e879c5SPeter KokotAn Example from the git project (commit 2b34e486bc):
386a8e879c5SPeter Kokot
387a8e879c5SPeter Kokot    pack-objects: Fix compilation with NO_PTHREDS
388a8e879c5SPeter Kokot
389a8e879c5SPeter Kokot    It looks like commit 99fb6e04 (pack-objects: convert to use parse_options(),
390a8e879c5SPeter Kokot    2012-02-01) moved the #ifdef NO_PTHREDS around but hasn't noticed that the
391a8e879c5SPeter Kokot    'arg' variable no longer is available.
392a8e879c5SPeter Kokot
393a8e879c5SPeter KokotIf you fix some bugs, you should note the bug ID numbers in your commit message.
394a8e879c5SPeter KokotBug ID should be prefixed by `#`.
395a8e879c5SPeter Kokot
396a8e879c5SPeter KokotExample:
397a8e879c5SPeter Kokot
398a8e879c5SPeter Kokot    Fixed bug #14016 (pgsql notice handler double free crash bug.)
399a8e879c5SPeter Kokot
400a8e879c5SPeter KokotWhen you change the NEWS file for a bug fix, then please keep the bugs sorted in
401a8e879c5SPeter Kokotdecreasing order under the fixed version.
402a8e879c5SPeter Kokot
403a8e879c5SPeter KokotYou can use [gitweb](https://git.php.net/) to look at PHP Git repository in
404a8e879c5SPeter Kokotvarious ways.
405a8e879c5SPeter Kokot
40663ef554fSPeter Kokot## Copyright and license headers
40763ef554fSPeter Kokot
40863ef554fSPeter KokotNew source code files should include the following header block:
40963ef554fSPeter Kokot
41063ef554fSPeter Kokot```c
41163ef554fSPeter Kokot/*
41263ef554fSPeter Kokot  +----------------------------------------------------------------------+
41363ef554fSPeter Kokot  | PHP Version 7                                                        |
41463ef554fSPeter Kokot  +----------------------------------------------------------------------+
41563ef554fSPeter Kokot  | Copyright (c) The PHP Group                                          |
41663ef554fSPeter Kokot  +----------------------------------------------------------------------+
41763ef554fSPeter Kokot  | This source file is subject to version 3.01 of the PHP license,      |
41863ef554fSPeter Kokot  | that is bundled with this package in the file LICENSE, and is        |
41963ef554fSPeter Kokot  | available through the world-wide-web at the following url:           |
42063ef554fSPeter Kokot  | https://www.php.net/license/3_01.txt                                 |
42163ef554fSPeter Kokot  | If you did not receive a copy of the PHP license and are unable to   |
42263ef554fSPeter Kokot  | obtain it through the world-wide-web, please send a note to          |
42363ef554fSPeter Kokot  | license@php.net so we can mail you a copy immediately.               |
42463ef554fSPeter Kokot  +----------------------------------------------------------------------+
42563ef554fSPeter Kokot  | Author:                                                              |
42663ef554fSPeter Kokot  +----------------------------------------------------------------------+
42763ef554fSPeter Kokot*/
42863ef554fSPeter Kokot```
42963ef554fSPeter Kokot
430886b2a22SPeter KokotThank you for contributing to PHP!
431