[php-src]CONTRIBUTING.md

贡献php

每一位php开发者都可以贡献php，php的更新不会停止，每个release版本都需要做大量工作，参与的人越多越好。

合并请求（PR)

PHP欢迎大家通过PR来增加测试、修复bug和实现RFC的功能，但请确保PR包含适当的测试。

如果是修复bug，请将PR提交到bug影响的最低版本的活动分支，例如现在，最低版本的活动分支是php7.3，那么对应的Git分支就是PHP-7.3。同时请确保PR中附带一个bug tracker系统中对应的链接。

实现RFC新功能的PR应该直接从master拉去分支进行提交。

PR绝对不能从PHP-x.y.z分支拉取，因为这些是已发布的稳定版本。

如果你的PR和基础分支冲突了，请使用git rebase，不能使用git merge。

从php的官方仓库先fork在推送PR。新的PR会触发一个通知到邮件组，给php的内核邮件组发送说明或许能得到更快的回复，你也可以把PR报送到 bug reports。

Git access page可以帮助你从git获取PHP代码并完成构建，更推荐阅读下workflow 和FAQ.。

发现缺陷

Bug应该被提交到PHP bug tracker系统，如果是第一次提交，建议阅读下文章guide to reporting a bug.

实现新功能

新功能的PR通常都需要提交RFC，可以从PHP Wiki上看到之前大量的RFC。

创建RFC之前，需要同扩展的维护者和php内核邮件组进行充分的讨论，RFC wiki的账号注册可以通过https://wiki.php.net/start?do=register完成。php扩展维护这可以在php源码中ext文件夹查询，邮件组地址在mailing lists page查询。

关于如何提交RFC，可以阅读下The Mysterious PHP RFC Process。

编写测试

我们中意新的测试，php是一个巨大的工程，改善代码覆盖率对每一位php开发则都意义重大。

我们的QA网站详细的描述了如何编写测试

测试脚本帮助我们了解功能的变化，测试的全面性有助于维护php的版本稳定。

zend_parse_parameters, ZEND_PARSE_PARAMETERS()的失败条件不需要在编写测试了，这些参数解析的API已经被充分的测试过了，再增加测试只能徒增这块的复杂程度。

新增的测试再不应该包含 --CREDITS-- 部分，因为作者的身份已经被Git精准追踪了，如果有多名作者，可以再commit message中使用Co-authored-by来说明。

编写文档

贡献PHP手册有两种方式，你可以编辑php手册，然后使用在线编辑器发送匿名补丁，或者你可以从svn检出XML源代码，修改并构建，然后通过documentation mailing list发送补丁。

寻求帮助

如果你在贡献PHP中遇到问题，或者仅仅想和别人讨论下你正在进行的工作，你可以通过邮件联系内核邮件组取得联系，文档的问题则通过documentation mailing list。

尽管是一个非官方的频道，但是你也可以在 EFnet的#php.pecl频道找到很多php的核心开发者，#php.doc找到很多文档的作者。

php源码文件结构

php的源码中包括一些开发、维护阶段生成的一些文件。

<php-src>/
 ├─ .git/                           # Git configuration and source directory
 ├─ TSRM/                           # Thread Safe Resource Manager
 └─ Zend/                           # Zend Engine
    ├─ zend_vm_execute.h            # Generated by `Zend/zend_vm_gen.php`
    ├─ zend_vm_opcodes.c            # Generated by `Zend/zend_vm_gen.php`
    ├─ zend_vm_opcodes.h            # Generated by `Zend/zend_vm_gen.php`
    └─ ...
 ├─ appveyor/                       # Appveyor CI service files
 └─ build/                          # *nix build system files
    ├─ ax_*.m4                      # https://github.com/autoconf-archive/autoconf-archive
    ├─ config.guess                 # https://git.savannah.gnu.org/cgit/config.git
    ├─ config.sub                   # https://git.savannah.gnu.org/cgit/config.git
    ├─ libtool.m4                   # https://git.savannah.gnu.org/cgit/libtool.git
    ├─ ltmain.sh                    # https://git.savannah.gnu.org/cgit/libtool.git
    ├─ shtool                       # https://www.gnu.org/software/shtool/
    └─ ...
 ├─ docs/                           # PHP internals and repository documentation
 └─ ext/                            # PHP core extensions
    └─ bcmath/
       ├─ libbcmath/                # Forked and maintained in php-src
       └─ ...
    └─ curl/
       ├─ sync-constants.php        # The curl symbols checker
       └─ ...
    └─ date/
       └─ lib/                      # Bundled datetime library https://github.com/derickr/timelib
          ├─ parse_date.c           # Generated by re2c 0.15.3
          ├─ parse_iso_intervals.c  # Generated by re2c 0.15.3
          └─ ...
       └─ ...
    └─ ffi/
       ├─ ffi_parser.c              # Generated by https://github.com/dstogov/llk
       └─ ...
    └─ fileinfo/
       ├─ libmagic/                 # Modified libmagic https://github.com/file/file
       ├─ data_file.c               # Generated by `ext/fileinfo/create_data_file.php`
       ├─ libmagic.patch            # Modifications patch from upstream libmagic
       ├─ magicdata.patch           # Modifications patch from upstream libmagic
       └─ ...
    └─ gd/
       ├─ libgd/                    # Bundled and modified GD library https://github.com/libgd/libgd
       └─ ...
    └─ mbstring/
       ├─ libmbfl/                  # Forked and maintained in php-src
       ├─ unicode_data.h            # Generated by `ext/mbstring/ucgendat/ucgendat.php`
       └─ ...
    └─ pcre/
       ├─ pcre2lib/                 # https://www.pcre.org/
       └─ ...
    └─ pdo_mysql/
       ├─ php_pdo_mysql_sqlstate.h  # Generated by `ext/pdo_mysql/get_error_codes.php`
       └─ ...
    └─ skeleton/                    # Skeleton for developing new extensions with `ext/ext_skel.php`
       └─ ...
    └─ standard/
       └─ html_tables/
          ├─ mappings/              # https://www.unicode.org/Public/MAPPINGS/
          └─ ...
       ├─ credits_ext.h             # Generated by `scripts/dev/credits`
       ├─ credits_sapi.h            # Generated by `scripts/dev/credits`
       ├─ html_tables.h             # Generated by `ext/standard/html_tables/html_table_gen.php`
       └─ ...
    └─ tokenizer/
       ├─ tokenizer_data.c          # Generated by `ext/tokenizer/tokenizer_data_gen.sh`
       └─ ...
    └─ zend_test                    # For testing internal APIs. Not needed for regular builds.
       └─ ...
    └─ zip/                         # Bundled https://github.com/pierrejoye/php_zip
       └─ ...
    └─ ...
 └─ main/                           # Binding that ties extensions, SAPIs, and engine together
    ├─ streams/                     # Streams layer subsystem
    ├─ php_version.h                # Generated by release managers using `configure`
    └─ ...
 ├─ pear/                           # PEAR installation
 └─ sapi/                           # PHP SAPI modules
    └─ cli/
       ├─ mime_type_map.h           # Generated by `sapi/cli/generate_mime_type_map.php`
       └─ ...
    └─ ...
 ├─ scripts/                        # php-config, phpize and internal development scripts
 ├─ tests/                          # Core features tests
 ├─ travis/                         # Travis CI service files
 └─ win32/                          # Windows build system files
    ├─ cp_enc_map.c                 # Generated by `win32/cp_enc_map_gen.exe`
    └─ ...
 └─ ...

Php内核

PHP内核相关的C函数可以参考References about Maintaining and Extending PHP。内核相关的内容可以在网上找到，推荐的参考书籍为 Sara Golemon编写的《Extending adn Embedding PHP》。

PECL扩展

修复PECL的缺陷需要在bugs.php.net上提bug。Bug可以用来追踪php的更新，某些pecl扩展也有自己的bug追踪机制和贡献流程。

如果你的改动很大，则需要提供RFC，并和扩展的维护者进行讨论，也需要和pecl开发邮件组针对该扩展进行讨论。邮件组具体见PECL support page。

修复Bug的时候请附上相关联系信息，发送patch或者邮件到pecl开发邮件组，并抄送扩展维护者。说明清楚你为什么这样修改，并附上测试。

提交贡献之前的自检

• 开始工作之前请阅读Coding standards。
• 在最终的diff和testing之前请更新主干分支的代码。
• 编写注释或者文档（可以两个都有），使用/* */ 注释，不要使用 //.
• 为make test 编写测试。
• 运行make test确保你的改动没有破坏已有的特性。
• 使用–eanble-debug重新编译php，检查是否有内存问题，再使用php测试脚本来检查在php在web server模式下是否有问题
• 使用–enable-zts来检查是否是否很好的支持线程安全的php。
• 提交代码之前，再一次review你的改动。

提交贡献之后

如果你的改动评审简单、容易接受，那应该很快会得到反馈。

因为PHP是一个开源者自驱的项目，所以你需要更多的耐心。如果几天之后仍没有反馈，那么在跳脚之前请先思考一下几个问题：

• 我发送的邮件组正确么？
• 这些改动是否被讨论过？
• 我把我的改动阐明的清除么？
• 我的改动是否很难review？如果是的话，原因是什么呢？

如果你的贡献被接受，将会发生什么？

你的大名将记录在Git commit log中，如果你的改动影响到了开发者，那么将在NEWS文件里简短的介绍下你。

Git提交规则

这部分涉及拥有push权限的贡献者如何自己提交改动。我们假设你熟悉Git的基本操作，但是在邮件中提出问题已经很熟练。请阅读一下 information on Git 以获得更多信息。
PHP是由海量开发则一起努力开发的。协作尤为重要，Git帮助我们去完成协作，我们希望你遵守一下几条基本规则：

1. 让每个人都开心，特别是那些负责维护PHP的开发者。
2. 保持良好的文档和可追踪性。
3. 合常理的工作，尽量不要有别人惊讶的动作。
4. 保持善良

说完了这些，下面介绍一下组织规则：

1. 尊重他人的工作。
2. 在提交和确认之前和别人充分讨论。
3. 在EXTENSIONS文件中找到你所贡献模块的负责人。
4. 如果和别人有明显的分歧，不要公开争论，先尝试发邮件沟通。
5. 如果你不知道该怎么做，先问清楚。
6. 在提交之前请先测试你的改动，真的，用make test测试吧。
7. 提交之前使用–enable-debug来避免内存泄漏，使用–enable-zts来确保你的改动正确的处理了TSRM，以适用于需要线程安全的那些开发者。

目前已有的分支如下：

Branch
master	Active development branch for PHP 8.1, which is open for backwards incompatible changes and major internal API changes.
PHP-8.0	Is used to release the PHP 8.0.x series. This is a current stable version and is open for bugfixes only.
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.
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.
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.
PHP-7.1	This branch is closed.
PHP-7.0	This branch is closed.
PHP-5.6	This branch is closed.
PHP-5.5	This branch is closed.
PHP-5.4	This branch is closed.
PHP-5.3	This branch is closed.
PHP-5.2	This branch is closed.
PHP-5.1	This branch is closed.
PHP-4.4	This branch is closed.
PHP-X.Y.Z	These branches are used for the release managers for tagging the releases, hence they are closed to the general public.

下面几条是偏技术的要点：

1. 非安全性的缺陷修复应该首先合并到最低的缺陷修复分支（例如7.3），然后依次合并到高分支。所有安全性缺陷修复应该先提交到最低的安全性缺陷修复分支。如果在较高的分支中不需要这个改动，那么将不必合并这部分代码。
2. 所有新特性的更新都应该公开，应当记录在对应stable版本中的NEWS文件。
3. 不要在一次提交中提交所有文件，也不要把所有的提交信息汇总到一次提交中。如果你改动了几个不相关的文件，那么请为每个文件单独提交，单独给出提交信息，以便别人查看。
4. 提交信息应当与你的修改内容相关，最好让别人能一眼看出来你具体改动了什么。例如包括改动的函数名等。
5. 在提交信息中，每行最多80个字符，请保持良好的可读性。
6. 如果你定义了PHP的可调用函数，优先考虑带PHP的函数名。

版权和许可证头部

新增的源码都应该引入版权和许可证头部。

/*
  +----------------------------------------------------------------------+
  | Copyright (c) The PHP Group                                          |
  +----------------------------------------------------------------------+
  | This source file is subject to version 3.01 of the PHP license,      |
  | that is bundled with this package in the file LICENSE, and is        |
  | available through the world-wide-web at the following url:           |
  | https://www.php.net/license/3_01.txt                                 |
  | If you did not receive a copy of the PHP license and are unable to   |
  | obtain it through the world-wide-web, please send a note to          |
  | license@php.net so we can mail you a copy immediately.               |
  +----------------------------------------------------------------------+
  | Author:                                                              |
  +----------------------------------------------------------------------+
*/

感谢贡献PHP！