From a8e879c53fa954ff51736eff3f9cdb8e26256337 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Tue, 26 Mar 2019 00:00:36 +0100 Subject: Join README.GIT-RULES and CONTRIBUTING.md This patch joins two very much related pieces of docs together in a single file dedicated to all sorts of contributing info. Some more changes: - Branches info copied from the current master branch - LXR and bonsai info removed - Duplicated info reduced a bit - Security branch updated to 7.1 - Refactor intro for Git commit rules - Updated README.GIT-RULES file usage in win32/build/confutils.js - Refactored configure.ac --- CONTRIBUTING.md | 117 +++++++++++++++++++++++++++++++++++++ README.GIT-RULES | 146 ----------------------------------------------- README.RELEASE_PROCESS | 2 +- README.md | 1 - configure.ac | 2 +- win32/build/confutils.js | 4 +- 6 files changed, 121 insertions(+), 151 deletions(-) delete mode 100644 README.GIT-RULES diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4459e53298..1a0cd4a3fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,6 +23,7 @@ had several contributions accepted, commit privileges are often quickly granted. * [Checklist for submitting contribution](#checklist-for-submitting-contribution) * [What happens after submitting contribution?](#what-happens-after-submitting-contribution) * [What happens when your contribution is applied?](#what-happens-when-your-contribution-is-applied) +* [Git commit rules](#git-commit-rules) ## Pull requests @@ -277,4 +278,120 @@ Your name will likely be included in the Git commit log. If your change affects end users, a brief description and your name might be added to the [NEWS](/NEWS) file. +## Git commit rules + +This section refers to contributors that have Git push access and make commit +changes themselves. We'll assume you're basically familiar with Git, but feel +free to post your questions on the mailing list. Please have a look at the more +detailed [information on Git](https://git-scm.com/). + +PHP is developed through the efforts of a large number of people. Collaboration +is a Good Thing(tm), and Git lets us do this. Thus, following some basic rules +with regards to Git usage will: + +* Make everybody happier, especially those responsible for maintaining PHP + itself. +* Keep the changes consistently well documented and easily trackable. +* Prevent some of those 'Oops' moments. +* Increase the general level of good will on planet Earth. + +Having said that, here are the organizational rules: + +1. Respect other people working on the project. + +2. Discuss any significant changes on the list before committing and get + confirmation from the release manager for the given branch. + +3. Look at [EXTENSIONS](/EXTENSIONS) file to see who is the primary maintainer + of the code you want to contribute to. + +4. If you "strongly disagree" about something another person did, don't start + fighting publicly - take it up in private email. + +5. If you don't know how to do something, ask first! + +6. Test your changes before committing them. We mean it. Really. To do so use + `make test`. + +7. For development use the `--enable-debug` switch to avoid memory leaks and the + `--enable-maintainer-zts` switch to ensure your code handles TSRM correctly + and doesn't break for those who need that. + +Currently we have the following branches in use: + +| Branch | | +| --------- | --------- | +| master | Active development branch for PHP 8.0, which is open for backwards incompatible changes and major internal API changes. | +| PHP-7.4 | Active development branch for PHP 7.4, which is open for new features and minor internal API changes. | +| PHP-7.3 | Is used to release the PHP 7.3.x series. This is a current stable version and is open for bugfixes only. | +| PHP-7.2 | Is used to release the PHP 7.2.x series. This is a current stable version and is open for bugfixes only. | +| PHP-7.1 | Is used to release the PHP 7.1.x series. This is an old stable version and is open for security fixes only. | +| PHP-7.0 | This branch is closed. | +| PHP-5.6 | This branch is closed. | +| PHP-5.5 | This branch is closed. | +| PHP-5.4 | This branch is closed. | +| PHP-5.3 | This branch is closed. | +| PHP-5.2 | This branch is closed. | +| PHP-5.1 | This branch is closed. | +| PHP-4.4 | This branch is closed. | +| PHP-X.Y.Z | These branches are used for the release managers for tagging the releases, hence they are closed to the general public. | + +The next few rules are more of a technical nature: + +1. All non-security bugfix changes should first go to the lowest bugfix branch + (i.e. 7.2) and then get merged up to all other branches. All security fixes + should go to the lowest security fixes branch (i.e 7.1). If a change is not + needed for later branches (i.e. fixes for features which were dropped from + later branches) an empty merge should be done. + +2. All news updates intended for public viewing, such as new features, bug + fixes, improvements, etc., should go into the NEWS file of *any stable + release* version with the given change. In other words, news about a bug fix + which went into PHP-5.4, PHP-5.5 and master should be noted in both + PHP-5.4/NEWS and PHP-5.5/NEWS but not master, which is not a public released + version yet. + +3. Do not commit multiple files and dump all messages in one commit. If you + modified several unrelated files, commit each group separately and provide a + nice commit message for each one. See example below. + +4. Do write your commit message in such a way that it makes sense even without + the corresponding diff. One should be able to look at it, and immediately + know what was modified. Definitely include the function name in the message + as shown below. + +5. In your commit messages, keep each line shorter than 80 characters. And try + to align your lines vertically, if they wrap. It looks bad otherwise. + +6. If you modified a function that is callable from PHP, prepend PHP to the + function name as shown below. + +The format of the commit messages is pretty simple. + + \n + \n + + \n + +An Example from the git project (commit 2b34e486bc): + + pack-objects: Fix compilation with NO_PTHREDS + + It looks like commit 99fb6e04 (pack-objects: convert to use parse_options(), + 2012-02-01) moved the #ifdef NO_PTHREDS around but hasn't noticed that the + 'arg' variable no longer is available. + +If you fix some bugs, you should note the bug ID numbers in your commit message. +Bug ID should be prefixed by `#`. + +Example: + + Fixed bug #14016 (pgsql notice handler double free crash bug.) + +When you change the NEWS file for a bug fix, then please keep the bugs sorted in +decreasing order under the fixed version. + +You can use [gitweb](https://git.php.net/) to look at PHP Git repository in +various ways. + Thank you for contributing to PHP! diff --git a/README.GIT-RULES b/README.GIT-RULES deleted file mode 100644 index 7c58f968b1..0000000000 --- a/README.GIT-RULES +++ /dev/null @@ -1,146 +0,0 @@ -==================== - Git Commit Rules -==================== - -This is the first file you should be reading when contributing code via Git. -We'll assume you're basically familiar with Git, but feel free to post -your questions on the mailing list. Please have a look at -http://git-scm.com/ for more detailed information on Git. - -PHP is developed through the efforts of a large number of people. -Collaboration is a Good Thing(tm), and Git lets us do this. Thus, following -some basic rules with regards to Git usage will:: - - a. Make everybody happier, especially those responsible for maintaining - PHP itself. - - b. Keep the changes consistently well documented and easily trackable. - - c. Prevent some of those 'Oops' moments. - - d. Increase the general level of good will on planet Earth. - -Having said that, here are the organizational rules:: - - 1. Respect other people working on the project. - - 2. Discuss any significant changes on the list before committing and get - confirmation from the release manager for the given branch. - - 3. Look at EXTENSIONS file to see who is the primary maintainer of - the code you want to contribute to. - - 4. If you "strongly disagree" about something another person did, don't - start fighting publicly - take it up in private email. - - 5. If you don't know how to do something, ask first! - - 6. Test your changes before committing them. We mean it. Really. - To do so use "make test". - - 7. For development use the --enable-debug switch to avoid memory leaks - and the --enable-maintainer-zts switch to ensure your code handles - TSRM correctly and doesn't break for those who need that. - -Currently we have the following branches in use:: - - master The active development branch. - - PHP-7.3 Is used to release the PHP 7.3.x series. This is a current - non stable version and is open for bugfixes and minor improvements - only. - - PHP-7.2 Is used to release the PHP 7.2.x series. This is a current - stable version and is open for bugfixes only. - - PHP-7.1 Is used to release the PHP 7.1.x series. This is an old - stable version and is open for security fixes only. - - PHP-7.0 Is used to release the PHP 7.0.x series. This is an old - stable version and is open for security fixes only. - - PHP-5.6 Is used to release the PHP 5.6.x series. This is an old - stable version and is open for security fixes only. - - PHP-5.5 This branch is closed. - - PHP-5.4 This branch is closed. - - PHP-5.3 This branch is closed. - - PHP-5.2 This branch is closed. - - PHP-5.1 This branch is closed. - - PHP-4.4 This branch is closed. - - PHP-X.Y.Z These branches are used for the release managers for tagging - the releases, hence they are closed to the general public. - -The next few rules are more of a technical nature:: - - 1. All non-security bugfix changes should first go to the lowest bugfix - branch (i.e. 7.2) and then get merged up to all other branches. - All security fixes should go to the lowest security fixes branch (i.e 5.6). - If a change is not needed for later branches (i.e. fixes for features - which were dropped from later branches) an empty merge should be done. - - 2. All news updates intended for public viewing, such as new features, - bug fixes, improvements, etc., should go into the NEWS file of *any - stable release* version with the given change. In other words, - news about a bug fix which went into PHP-5.4, PHP-5.5 and master - should be noted in both PHP-5.4/NEWS and PHP-5.5/NEWS but - not master, which is not a public released version yet. - - 3. Do not commit multiple files and dump all messages in one commit. If you - modified several unrelated files, commit each group separately and - provide a nice commit message for each one. See example below. - - 4. Do write your commit message in such a way that it makes sense even - without the corresponding diff. One should be able to look at it, and - immediately know what was modified. Definitely include the function name - in the message as shown below. - - 5. In your commit messages, keep each line shorter than 80 characters. And - try to align your lines vertically, if they wrap. It looks bad otherwise. - - 6. If you modified a function that is callable from PHP, prepend PHP to - the function name as shown below. - - -The format of the commit messages is pretty simple. - -\n -\n - -\n - -An Example from the git project (commit 2b34e486bc): - -pack-objects: Fix compilation with NO_PTHREDS - -It looks like commit 99fb6e04 (pack-objects: convert to use -parse_options(), 2012-02-01) moved the #ifdef NO_PTHREDS around but -hasn't noticed that the 'arg' variable no longer is available. - -If you fix some bugs, you should note the bug ID numbers in your -commit message. Bug ID should be prefixed by "#" for easier access to -bug report when developers are browsing CVS via LXR or Bonsai. - -Example: - -Fixed bug #14016 (pgsql notice handler double free crash bug.) - -When you change the NEWS file for a bug fix, then please keep the bugs -sorted in decreasing order under the fixed version. - -You can use OpenGrok (http://lxr.php.net/) and gitweb (http://git.php.net/) -to look at PHP Git repository in various ways. - - -For further information on the process and further details please refer to -https://wiki.php.net/vcs/gitworkflow and https://wiki.php.net/vcs/gitfaq - -Happy hacking, - -PHP Team diff --git a/README.RELEASE_PROCESS b/README.RELEASE_PROCESS index b50cac4843..211d68d5e0 100644 --- a/README.RELEASE_PROCESS +++ b/README.RELEASE_PROCESS @@ -338,7 +338,7 @@ Forking a new release branch Add a commit on master after the branch point clearing the NEWS, UPGRADING and UPGRADING.INTERNALS files, updating the version in configure.ac (run ./configure to automatically update main/php_versions.h, too) and Zend/zend.h. - Also list the new branch in README.GIT-RULES. + Also list the new branch in CONTRIBUTING.md. Example: http://git.php.net/?p=php-src.git;a=commit;h=a63c99b Push the new branch and the commit just added to master. diff --git a/README.md b/README.md index 28ebd1fae4..45706d2425 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,6 @@ contribute: - [Contributing to PHP](/CONTRIBUTING.md) - [PHP coding standards](/CODING_STANDARDS) -- [Git rules](/README.GIT-RULES) - [Mailinglist rules](/README.MAILINGLIST_RULES) - [PHP release process](/README.RELEASE_PROCESS) diff --git a/configure.ac b/configure.ac index e79be39572..3e51518195 100644 --- a/configure.ac +++ b/configure.ac @@ -8,7 +8,7 @@ dnl Basic autoconf initialization, generation of config.nice. dnl ------------------------------------------------------------------------- AC_PREREQ([2.68]) -AC_INIT(README.GIT-RULES) +AC_INIT([main/php_version.h]) AC_CONFIG_AUX_DIR([build]) AC_PRESERVE_HELP_ORDER diff --git a/win32/build/confutils.js b/win32/build/confutils.js index e238e51e99..4fe111a8fb 100644 --- a/win32/build/confutils.js +++ b/win32/build/confutils.js @@ -106,7 +106,7 @@ if (MODE_PHPIZE) { WScript.Quit(10); } } else { - if (!FSO.FileExists("README.GIT-RULES")) { + if (!FSO.FileExists("main\\php_version.h")) { STDERR.WriteLine("Must be run from the root of the php source"); WScript.Quit(10); } @@ -115,7 +115,7 @@ if (MODE_PHPIZE) { var CWD = WshShell.CurrentDirectory; if (typeof(CWD) == "undefined") { - CWD = FSO.GetParentFolderName(FSO.GetAbsolutePathName("README.GIT-RULES")); + CWD = FSO.GetParentFolderName(FSO.GetParentFolderName(FSO.GetAbsolutePathName("main\\php_version.h"))); } /* defaults; we pick up the precise versions from configure.ac */ -- cgit v1.2.1