1==================== 2 Git Commit Rules 3==================== 4 5This is the first file you should be reading when contributing code via Git. 6We'll assume you're basically familiar with Git, but feel free to post 7your questions on the mailing list. Please have a look at 8http://git-scm.com/ for more detailed information on Git. 9 10PHP is developed through the efforts of a large number of people. 11Collaboration is a Good Thing(tm), and Git lets us do this. Thus, following 12some basic rules with regards to Git usage will:: 13 14 a. Make everybody happier, especially those responsible for maintaining 15 PHP itself. 16 17 b. Keep the changes consistently well documented and easily trackable. 18 19 c. Prevent some of those 'Oops' moments. 20 21 d. Increase the general level of good will on planet Earth. 22 23Having said that, here are the organizational rules:: 24 25 1. Respect other people working on the project. 26 27 2. Discuss any significant changes on the list before committing and get 28 confirmation from the release manager for the given branch. 29 30 3. Look at EXTENSIONS file to see who is the primary maintainer of 31 the code you want to contribute to. 32 33 4. If you "strongly disagree" about something another person did, don't 34 start fighting publicly - take it up in private email. 35 36 5. If you don't know how to do something, ask first! 37 38 6. Test your changes before committing them. We mean it. Really. 39 To do so use "make test". 40 41 7. For development use the --enable-debug switch to avoid memory leaks 42 and the --enable-maintainer-zts switch to ensure your code handles 43 TSRM correctly and doesn't break for those who need that. 44 45Currently we have the following branches in use:: 46 47 master The active development branch. 48 49 PHP-7.2 Is used to release the PHP 7.2.x series. This is a current 50 stable version and is open for bugfixes only. 51 52 PHP-7.1 Is used to release the PHP 7.1.x series. This is a current 53 stable version and is open for bugfixes only. 54 55 PHP-7.0 Is used to release the PHP 7.0.x series. This is an old 56 stable version and is open for security fixes only. 57 58 PHP-5.6 Is used to release the PHP 5.6.x series. This is an old 59 stable version and is open for security fixes only. 60 61 PHP-5.5 This branch is closed. 62 63 PHP-5.4 This branch is closed. 64 65 PHP-5.3 This branch is closed. 66 67 PHP-5.2 This branch is closed. 68 69 PHP-5.1 This branch is closed. 70 71 PHP-4.4 This branch is closed. 72 73 PHP-X.Y.Z These branches are used for the release managers for tagging 74 the releases, hence they are closed to the general public. 75 76The next few rules are more of a technical nature:: 77 78 1. All changes should first go to the lowest branch (i.e. 5.6) and then 79 get merged up to all other branches. If a change is not needed for 80 later branches (i.e. fixes for features which were dropped from later 81 branches) an empty merge should be done. 82 83 2. All news updates intended for public viewing, such as new features, 84 bug fixes, improvements, etc., should go into the NEWS file of *any 85 stable release* version with the given change. In other words, 86 news about a bug fix which went into PHP-5.4, PHP-5.5 and master 87 should be noted in both PHP-5.4/NEWS and PHP-5.5/NEWS but 88 not master, which is not a public released version yet. 89 90 3. Do not commit multiple files and dump all messages in one commit. If you 91 modified several unrelated files, commit each group separately and 92 provide a nice commit message for each one. See example below. 93 94 4. Do write your commit message in such a way that it makes sense even 95 without the corresponding diff. One should be able to look at it, and 96 immediately know what was modified. Definitely include the function name 97 in the message as shown below. 98 99 5. In your commit messages, keep each line shorter than 80 characters. And 100 try to align your lines vertically, if they wrap. It looks bad otherwise. 101 102 6. If you modified a function that is callable from PHP, prepend PHP to 103 the function name as shown below. 104 105 106The format of the commit messages is pretty simple. 107 108<max 79 characters short description>\n 109\n 110<long description, 79 chars per line> 111\n 112 113An Example from the git project (commit 2b34e486bc): 114 115pack-objects: Fix compilation with NO_PTHREDS 116 117It looks like commit 99fb6e04 (pack-objects: convert to use 118parse_options(), 2012-02-01) moved the #ifdef NO_PTHREDS around but 119hasn't noticed that the 'arg' variable no longer is available. 120 121If you fix some bugs, you should note the bug ID numbers in your 122commit message. Bug ID should be prefixed by "#" for easier access to 123bug report when developers are browsing CVS via LXR or Bonsai. 124 125Example: 126 127Fixed bug #14016 (pgsql notice handler double free crash bug.) 128 129When you change the NEWS file for a bug fix, then please keep the bugs 130sorted in decreasing order under the fixed version. 131 132You can use OpenGrok (http://lxr.php.net/) and gitweb (http://git.php.net/) 133to look at PHP Git repository in various ways. 134 135 136For further information on the process and further details please refer to 137https://wiki.php.net/vcs/gitworkflow and https://wiki.php.net/vcs/gitfaq 138 139Happy hacking, 140 141PHP Team 142
