GeezerVison is showing github.com — php-src/README.SUBMITTING_PATCH at master · mj/php-src

Expand file tree

README.SUBMITTING_PATCH

Copy path

More file actions

Latest commit

History

194 lines (149 loc) · 7.94 KB

README.SUBMITTING_PATCH

Copy path

File metadata and controls

194 lines (149 loc) · 7.94 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

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

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

Submitting Enhancements and Patches to PHP

==========================================

This document describes how to submit an enhancement or patch for PHP.

It's easy!

You don't need any login accounts or special access to download,

build, debug and begin submitting PHP or PECL code, tests or

documentation. Once you've followed this README and had several

patches accepted, commit privileges are often quickly granted.

An excellent article to read first is:

http://phpadvent.org/2008/less-whining-more-coding-by-elizabeth-smith

Online Forums

-------------

There are several IRC channels where PHP developers are often

available to discuss questions. They include #php.pecl and #php.doc

on the EFNet network and #winphp-dev on FreeNode.

PHP Patches

-----------

If you are fixing broken functionality in PHP C source code first

create a bug or identify an existing bug at http://bugs.php.net/. A

bug can be used to track the patch progress and prevent your changes

getting lost in the PHP mail archives.

If your change is large then create a Request For Comment (RFC) page

on http://wiki.php.net/rfc, discuss it with the extension maintainer,

and discuss it on the development mail list [email protected].

RFC Wiki accounts can be requested on

http://wiki.php.net/start?do=register. PHP extension maintainers can

be found in the EXTENSIONS file in the PHP source. Mail list

subscription is explained on http://php.net/mailing-lists.php.

Information on PHP internal C functions is at

http://php.net/internals, though this is considered incomplete.

Various external resources can be found on the web. See

https://wiki.php.net/internals for some references. A standard

printed reference is the book "Extending and Embedding PHP" by Sara

Golemon.

The preferred way to propose PHP patch is sending pull request from

GitHub: https://github.com/php/php-src

Fork the official PHP repository and send a pull request. A

notification will be sent to the pull request mailing list. Sending a

note to PHP Internals list ([email protected]) may help getting

more feedback and quicker turnaround. You can also add pull requests

to bug reports at http://bugs.php.net/.

If you are not using GitHub, attach your patch to a PHP bug and

consider sending a notification email about the change to

[email protected]. If the bug is for an extension, also CC the

extension maintainer. Explain what has been changed by your patch.

Test scripts should be included.

Please make the mail subject prefix "[PATCH]". If attaching a patch,

ensure it has a file extension of ".txt". This is because only MIME

attachments of type 'text/*' are accepted.

PHP Documentation Patches

-------------------------

If you are fixing incorrect PHP documentation first create a bug or

identify an existing bug at http://bugs.php.net/. A bug can be used

to track the patch progress and prevent your changes getting lost in

the PHP mail archives.

If your change is large, then first discuss it with the mail list

[email protected]. Subscription is explained on

http://php.net/mailing-lists.php.

Information on contributing to PHP documentation is at

http://php.net/dochowto and http://wiki.php.net/doc/howto

Attach the patch to the PHP bug and consider sending a notification

email about the change to [email protected]. Explain what has been

fixed/added/changed by your patch.

Please make the mail subject prefix "[PATCH]". Include the bug id(s)

which can be closed by your patch. If attaching a patch, ensure it

has a file extension of ".txt". This is because only MIME attachments

of type 'text/*' are accepted.

PECL Extension Patches: http://pecl.php.net/

--------------------------------------------

If you are fixing broken functionality in a PECL extension then create

a bug or identify an existing bug at http://bugs.php.net/. A bug

can be used to track the patch progress and prevent your changes

getting lost in the PHP mail archives.

If your change is large then create a Request For Comment (RFC) page

on http://wiki.php.net/rfc, discuss it with the extension maintainer,

and discuss it on the development mail list [email protected].

PECL mail list subscription is explained on

http://pecl.php.net/support.php. RFC Wiki accounts can be requested

on http://wiki.php.net/start?do=register

Information on PHP internal C functions is at

http://www.php.net/internals, though this is considered incomplete.

Various external resources can be found on the web. A standard

printed reference is the book "Extending and Embedding PHP" by Sara

Golemon.

Update any open bugs and add a link to the source of your patch. Send

the patch or pointer to the bug to [email protected]. Also CC

the extension maintainer. Explain what has been changed by your

patch. Test scripts should be included.

Please make the mail subject prefix "[PATCH] ...". Include the patch

as an attachment with a file extension of ".txt". This is because

only MIME attachments of type 'text/*' are accepted.

PEAR Package Patches: http://pear.php.net/

------------------------------------------

Information on contributing to PEAR is available at

http://pear.php.net/manual/en/developers-newmaint.php and

http://pear.php.net/manual/en/guide-developers.php

How to create your PHP, PHP Documentation or PECL patch

-------------------------------------------------------

PHP and most PECL packages use Git for revision control. Some PECL

packages use Subversion (SVN) Read http://www.php.net/git.php for help

on using Git to get and build PHP source code. We recommend to look

at our workflow on https://wiki.php.net/vcs/gitworkflow and our FAQ

https://wiki.php.net/vcs/gitfaq.

Generally we ask that bug fix patches work on the current stable PHP

development branches and on "master". New PHP features only need to

work on "master".

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:

git diff > your_patch.txt

For ease of review and later troubleshooting, submit individual

patches for each bug or feature.

Checklist for submitting your PHP or PECL code patch

----------------------------------------------------

- Update git source just before running your final 'diff' and

before testing.

- Add in-line comments and/or have external documentation ready.

Use only "/* */" style comments, not "//".

- Create test scripts for use with "make test".

- 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 your PHP tests.

- Rebuild PHP with --enable-maintainer-zts to check your patch

compiles on multi-threaded web servers.

- Review the patch once more just before submitting it.

What happens after submitting your PHP, PHP Documentation or PECL 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 send the patch to the right mail list?

- 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 what factors?

What happens when your PHP or PECL patch is applied

---------------------------------------------------

Your name will likely be included in the Git 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!