-
Notifications
You must be signed in to change notification settings - Fork 18
/
README.SUBMITTING_PATCH
136 lines (101 loc) · 5.02 KB
/
README.SUBMITTING_PATCH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
Submitting Patches to PHP
=========================
This document describes how to submit a patch for PHP. Creating a
patch for PHP is easy!
You don't need any login accounts or special access to download,
build, debug and begin submitting PHP code, tests or documentation for
inclusion in PHP. Once you've followed this README and had several
patches accepted, PHP commit privileges are often quickly granted.
An excellent article to read first is:
http://phpadvent.org/2008/less-whining-more-coding-by-elizabeth-smith
Prework
-------
If you are fixing broken functionality then create a bug or identify
an existing bug at http://bugs.php.net/. This can be used to track
the patch progress and prevent your changes getting lost in the PHP
mail archives.
If your code change is large then first discuss it with the extension
maintainer and/or a development mail list. Extension maintainers can
be found in the EXTENSIONS file in the PHP source. Use the
internals@lists.php.net mail list to discuss changes to the base PHP
code. Use pecl-dev@lists.php.net for changes to code that is only
available from PECL (http://pecl.php.net/). Use pear-dev@lists.php.net
for PEAR modules (http://pear.php.net/). Mail list subscription is
explained on http://www.php.net/mailing-lists.php.
If a PHP or PECL patch affects user-functionality or makes significant
internal changes then create a simple RFC on http://wiki.php.net/rfc
before starting discussion. This RFC can be used for initial
discussion and later for documentation. Wiki accounts can be requested
on http://wiki.php.net/start?do=register
There are several IRC channels where PHP developers are often
available to discuss questions. They include #php.pecl on the EFNet
network and #php-dev-win on FreeNode.
How to create your patch
------------------------
PHP uses Subversion (SVN) for revision control. Read
http://www.php.net/svn.php for help on using SVN to get and build PHP
source code. We recommend using a Sparse Directory checkout described
in http://wiki.php.net/vcs/svnfaq. If you are new to SVN, read
http://svnbook.red-bean.com.
Generally we ask that patches work on the current stable PHP
development branch and on "trunk".
Read CODING_STANDARDS before you start working.
After modifying the source see README.TESTING and
http://qa.php.net/write-test.php for how to test. Submitting test
scripts helps us to understand what functionality has changed. It is
important for the stability and maintainability of PHP that tests are
comprehensive.
After testing is finished, create a patch file using the command:
svn diff > your_patch.txt
For ease of review and later troubleshooting, submit individual
patches for each bug or feature.
Checklist for submitting your patch
-----------------------------------
- Update SVN source just before running your final 'diff' and
before testing.
- Run "make test" to check your patch doesn't break other features.
- Rebuild PHP with --enable-debug (which will show some kinds of
memory errors) and check the PHP and web server error logs after
running the PHP tests.
- Rebuild PHP with --enable-maintainer-zts to check your patch compiles
on multi-threaded web servers.
- Create test scripts for use with "make test".
- Add in-line comments and/or have external documentation ready.
- Review the patch once more just before submitting it.
Where to send your patch
------------------------
If you are patching PHP C source then email the patch to
internals@lists.php.net
If you patching a PECL extension then send the patch to
pecl-dev@lists.php.net
If you are patching PEAR then send the patch to
pear-dev@lists.php.net
The mail can be CC'd to the extension maintainer (see EXTENSIONS).
Please make the subject prefix "[PATCH]".
Include the patch as an attachment. Note: only MIME attachments of
type 'text/*' are accepted. The easiest way to accomplish this is to
make the file extension '.txt'.
Explain what has been fixed/added/changed by your patch. Test scripts
should be included in the email.
Include the bug id(s) which can be closed by your patch.
Finally, update any open bugs and add a link to the source of your
patch.
What happens after you submit your patch
----------------------------------------
If your patch is easy to review and obviously has no side-effects,
it might be committed relatively quickly.
Because PHP is a volunteer-driven effort more complex patches will
require patience on your side. If you do not receive feedback in a few
days, consider resubmitting the patch. Before doing this think about
these questions:
- Did I review the mail list archives to see if these kind of
changes had been discussed before?
- Did I explain my patch clearly?
- Is my patch too hard to review? Because of which factors?
- Are there any unwanted white space changes?
What happens when your patch is applied
---------------------------------------
Your name will be included together with your email address in the SVN
commit log. If your patch affects end users, a brief description
and your name might be added to the NEWS file.
Thank you for patching PHP!