Annotation of embedaddon/php/README.SUBMITTING_PATCH, revision 1.1.1.2
1.1 misho 1: Submitting Enhancements and Patches to PHP
2: ==========================================
3:
4: This document describes how to submit an enhancement or patch for PHP.
5: It's easy!
6:
7: You don't need any login accounts or special access to download,
8: build, debug and begin submitting PHP, PECL or PEAR code, tests or
9: documentation. Once you've followed this README and had several
10: patches accepted, commit privileges are often quickly granted.
11:
12: An excellent article to read first is:
13: http://phpadvent.org/2008/less-whining-more-coding-by-elizabeth-smith
14:
15:
16: Online Forums
17: -------------
18: There are several IRC channels where PHP developers are often
19: available to discuss questions. They include #php.pecl, #php.doc and
20: #pear on the EFNet network and #php-dev-win on FreeNode.
21:
22:
23: PHP Patches
24: -----------
25: If you are fixing broken functionality in PHP C source code first
26: create a bug or identify an existing bug at http://bugs.php.net/. A
27: bug can be used to track the patch progress and prevent your changes
28: getting lost in the PHP mail archives.
29:
30: If your change is large then create a Request For Comment (RFC) page
31: on http://wiki.php.net/rfc, discuss it with the extension maintainer,
32: and discuss it on the development mail list internals@lists.php.net.
33: RFC Wiki accounts can be requested on
34: http://wiki.php.net/start?do=register. PHP extension maintainers can
35: be found in the EXTENSIONS file in the PHP source. Mail list
36: subscription is explained on http://www.php.net/mailing-lists.php.
37:
38: Information on PHP internal C functions is at
39: http://www.php.net/internals, though this is considered incomplete.
40: Various external resources can be found on the web. A standard
41: printed reference is the book "Extending and Embedding PHP" by Sara
42: Golemon.
43:
44: Attach the patch to the PHP bug and consider sending a notification
45: email about the change to internals@lists.php.net. Also CC the
46: extension maintainer. Explain what has been changed by your patch.
47: Test scripts should be included.
48:
49: Please make the mail subject prefix "[PATCH]". If attaching a patch,
50: ensure it has a file extension of ".txt". This is because only MIME
51: attachments of type 'text/*' are accepted.
52:
1.1.1.2 ! misho 53: The preferred way to propose PHP patch is sending pull request from
! 54: github.
! 55:
! 56: https://github.com/php/php-src
! 57:
! 58: Fork the official PHP repository and send a pull request. A
! 59: notification will be sent to the pull request mailing list. Sending a
! 60: note to PHP Internals list (internals@lists.php.net) may help getting
! 61: more feedback and quicker turnaround. You can also add pull requests
! 62: to bug reports at http://bugs.php.net/.
! 63:
1.1 misho 64:
65: PHP Documentation Patches
66: -------------------------
67: If you are fixing incorrect PHP documentation first create a bug or
68: identify an existing bug at http://bugs.php.net/. A bug can be used
69: to track the patch progress and prevent your changes getting lost in
70: the PHP mail archives.
71:
72: If your change is large, then first discuss it with the mail list
73: phpdoc@lists.php.net. Subscription is explained on
74: http://www.php.net/mailing-lists.php.
75:
76: Information on contributing to PHP documentation is at
77: http://php.net/dochowto and http://wiki.php.net/doc/howto
78:
79: Attach the patch to the PHP bug and consider sending a notification
80: email about the change to phpdoc@lists.php.net. Explain what has been
81: fixed/added/changed by your patch.
82:
83: Please make the mail subject prefix "[PATCH]". Include the bug id(s)
84: which can be closed by your patch. If attaching a patch, ensure it
85: has a file extension of ".txt". This is because only MIME attachments
86: of type 'text/*' are accepted.
87:
88:
89: PECL Extension Patches: http://pecl.php.net/
90: --------------------------------------------
91: If you are fixing broken functionality in a PECL extension then create
92: a bug or identify an existing bug at http://pecl.php.net/bugs/. A bug
93: can be used to track the patch progress and prevent your changes
94: getting lost in the PHP mail archives.
95:
96: If your change is large then create a Request For Comment (RFC) page
97: on http://wiki.php.net/rfc, discuss it with the extension maintainer,
98: and discuss it on the development mail list pecl-dev@lists.php.net.
99: PECL mail list subscription is explained on
100: http://pecl.php.net/support.php. RFC Wiki accounts can be requested
101: on http://wiki.php.net/start?do=register
102:
103: Information on PHP internal C functions is at
104: http://www.php.net/internals, though this is considered incomplete.
105: Various external resources can be found on the web. A standard
106: printed reference is the book "Extending and Embedding PHP" by Sara
107: Golemon.
108:
109: Update any open bugs and add a link to the source of your patch. Send
110: the patch or pointer to the bug to pecl-dev@lists.php.net. Also CC
111: the extension maintainer. Explain what has been changed by your
112: patch. Test scripts should be included.
113:
114: Please make the mail subject prefix "[PATCH] ...". Include the patch
115: as an attachment with a file extension of ".txt". This is because
116: only MIME attachments of type 'text/*' are accepted.
117:
118:
119: PEAR Package Patches: http://pear.php.net/
120: ------------------------------------------
121: Information on contributing to PEAR is available at
122: http://pear.php.net/manual/en/developers-newmaint.php and
123: http://pear.php.net/manual/en/guide-developers.php
124:
125:
126: How to create your PHP, PHP Documentation or PECL patch
127: -------------------------------------------------------
128: PHP and PECL use Subversion (SVN) for revision control. Read
129: http://www.php.net/svn.php for help on using SVN to get and build PHP
130: source code. We recommend using a Sparse Directory checkout described
131: in http://wiki.php.net/vcs/svnfaq. If you are new to SVN, read
132: http://svnbook.red-bean.com.
133:
134: Generally we ask that bug fix patches work on the current stable PHP
135: development branches and on "trunk". New PHP features only need to
136: work on "trunk".
137:
138: Read CODING_STANDARDS before you start working.
139:
140: After modifying the source see README.TESTING and
141: http://qa.php.net/write-test.php for how to test. Submitting test
142: scripts helps us to understand what functionality has changed. It is
143: important for the stability and maintainability of PHP that tests are
144: comprehensive.
145:
146: After testing is finished, create a patch file using the command:
147:
148: svn diff > your_patch.txt
149:
150: For ease of review and later troubleshooting, submit individual
151: patches for each bug or feature.
152:
153:
154: Checklist 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:
170: What happens after submitting your PHP, PHP Documentation or PECL patch
171: -----------------------------------------------------------------------
172: If your patch is easy to review and obviously has no side-effects,
173: it might be committed relatively quickly.
174:
175: Because PHP is a volunteer-driven effort more complex patches will
176: require patience on your side. If you do not receive feedback in a
177: few days, consider resubmitting the patch. Before doing this think
178: about 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:
187: What happens when your PHP or PECL patch is applied
188: ---------------------------------------------------
189: Your name will likely be included in the SVN commit log. If your
190: patch affects end users, a brief description and your name might be
191: added to the NEWS file.
192:
193: Thank you for patching PHP!
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.SUBMITTING_PATCH CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php