embedaddon/php/README.SUBMITTING_PATCH - annotate

Return to README.SUBMITTING_PATCH CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php

Annotation of embedaddon/php/README.SUBMITTING_PATCH, revision 1.1.1.1

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:
53:
54: PHP Documentation Patches
55: -------------------------
56: If you are fixing incorrect PHP documentation first create a bug or
57: identify an existing bug at http://bugs.php.net/. A bug can be used
58: to track the patch progress and prevent your changes getting lost in
59: the PHP mail archives.
60:
61: If your change is large, then first discuss it with the mail list
62: phpdoc@lists.php.net. Subscription is explained on
63: http://www.php.net/mailing-lists.php.
64:
65: Information on contributing to PHP documentation is at
66: http://php.net/dochowto and http://wiki.php.net/doc/howto
67:
68: Attach the patch to the PHP bug and consider sending a notification
69: email about the change to phpdoc@lists.php.net. Explain what has been
70: fixed/added/changed by your patch.
71:
72: Please make the mail subject prefix "[PATCH]". Include the bug id(s)
73: which can be closed by your patch. If attaching a patch, ensure it
74: has a file extension of ".txt". This is because only MIME attachments
75: of type 'text/*' are accepted.
76:
77:
78: PECL Extension Patches: http://pecl.php.net/
79: --------------------------------------------
80: If you are fixing broken functionality in a PECL extension then create
81: a bug or identify an existing bug at http://pecl.php.net/bugs/. A bug
82: can be used to track the patch progress and prevent your changes
83: getting lost in the PHP mail archives.
84:
85: If your change is large then create a Request For Comment (RFC) page
86: on http://wiki.php.net/rfc, discuss it with the extension maintainer,
87: and discuss it on the development mail list pecl-dev@lists.php.net.
88: PECL mail list subscription is explained on
89: http://pecl.php.net/support.php. RFC Wiki accounts can be requested
90: on http://wiki.php.net/start?do=register
91:
92: Information on PHP internal C functions is at
93: http://www.php.net/internals, though this is considered incomplete.
94: Various external resources can be found on the web. A standard
95: printed reference is the book "Extending and Embedding PHP" by Sara
96: Golemon.
97:
98: Update any open bugs and add a link to the source of your patch. Send
99: the patch or pointer to the bug to pecl-dev@lists.php.net. Also CC
100: the extension maintainer. Explain what has been changed by your
101: patch. Test scripts should be included.
102:
103: Please make the mail subject prefix "[PATCH] ...". Include the patch
104: as an attachment with a file extension of ".txt". This is because
105: only MIME attachments of type 'text/*' are accepted.
106:
107:
108: PEAR Package Patches: http://pear.php.net/
109: ------------------------------------------
110: Information on contributing to PEAR is available at
111: http://pear.php.net/manual/en/developers-newmaint.php and
112: http://pear.php.net/manual/en/guide-developers.php
113:
114:
115: How to create your PHP, PHP Documentation or PECL patch
116: -------------------------------------------------------
117: PHP and PECL use Subversion (SVN) for revision control. Read
118: http://www.php.net/svn.php for help on using SVN to get and build PHP
119: source code. We recommend using a Sparse Directory checkout described
120: in http://wiki.php.net/vcs/svnfaq. If you are new to SVN, read
121: http://svnbook.red-bean.com.
122:
123: Generally we ask that bug fix patches work on the current stable PHP
124: development branches and on "trunk". New PHP features only need to
125: work on "trunk".
126:
127: Read CODING_STANDARDS before you start working.
128:
129: After modifying the source see README.TESTING and
130: http://qa.php.net/write-test.php for how to test. Submitting test
131: scripts helps us to understand what functionality has changed. It is
132: important for the stability and maintainability of PHP that tests are
133: comprehensive.
134:
135: After testing is finished, create a patch file using the command:
136:
137: svn diff > your_patch.txt
138:
139: For ease of review and later troubleshooting, submit individual
140: patches for each bug or feature.
141:
142:
143: Checklist for submitting your PHP or PECL code patch
144: ----------------------------------------------------
145: - Update SVN source just before running your final 'diff' and
146: before testing.
147: - Add in-line comments and/or have external documentation ready.
148: Use only "/* */" style comments, not "//".
149: - Create test scripts for use with "make test".
150: - Run "make test" to check your patch doesn't break other features.
151: - Rebuild PHP with --enable-debug (which will show some kinds of
152: memory errors) and check the PHP and web server error logs after
153: running your PHP tests.
154: - Rebuild PHP with --enable-maintainer-zts to check your patch
155: compiles on multi-threaded web servers.
156: - Review the patch once more just before submitting it.
157:
158:
159: What happens after submitting your PHP, PHP Documentation or PECL patch
160: -----------------------------------------------------------------------
161: If your patch is easy to review and obviously has no side-effects,
162: it might be committed relatively quickly.
163:
164: Because PHP is a volunteer-driven effort more complex patches will
165: require patience on your side. If you do not receive feedback in a
166: few days, consider resubmitting the patch. Before doing this think
167: about these questions:
168:
169: - Did I send the patch to the right mail list?
170: - Did I review the mail list archives to see if these kind of
171: changes had been discussed before?
172: - Did I explain my patch clearly?
173: - Is my patch too hard to review? Because of what factors?
174:
175:
176: What happens when your PHP or PECL patch is applied
177: ---------------------------------------------------
178: Your name will likely be included in the SVN commit log. If your
179: patch affects end users, a brief description and your name might be
180: added to the NEWS file.
181:
182: Thank you for patching PHP!

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>