Return to README.GIT-RULES CVS log

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

Annotation of embedaddon/php/README.GIT-RULES, revision 1.1

1.1     ! misho       1: ====================
        !             2:   Git Commit Rules
        !             3: ====================
        !             4: 
        !             5: This is the first file you should be reading when contributing code via Git.
        !             6: We'll assume you're basically familiar with Git, but feel free to post
        !             7: your questions on the mailing list. Please have a look at
        !             8: http://git-scm.com/ for more detailed information on Git.
        !             9: 
        !            10: PHP is developed through the efforts of a large number of people.
        !            11: Collaboration is a Good Thing(tm), and Git lets us do this. Thus, following
        !            12: some basic rules with regards to Git usage will::
        !            13: 
        !            14:    a. Make everybody happier, especially those responsible for maintaining
        !            15:       Git 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: 
        !            23: Having 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-maintainer-zts switch to ensure your
        !            42:       code handles TSRM correctly and doesn't break for those who need that.
        !            43: 
        !            44: Currently we have the following branches in use::
        !            45: 
        !            46:   master    The active development branch. 
        !            47: 
        !            48:   PHP-5.4   Is used to release the PHP 5.4.x series. It still allows for
        !            49:             larger enhancements.
        !            50: 
        !            51:   PHP-5.3   Is used to release the PHP 5.3.x series. This is current 
        !            52:             stable version and is open for bugfixes only.
        !            53: 
        !            54:   PHP-5.2   Is used to release the PHP 5.2.x series. It is closed for 
        !            55:             changes now.
        !            56: 
        !            57:   PHP-5.1   This branch is closed.
        !            58: 
        !            59:   PHP-4.4   This branch is closed.
        !            60: 
        !            61: The next few rules are more of a technical nature::
        !            62: 
        !            63:    1. All changes should first go to the lowest branch (i.e. 5.3) and then 
        !            64:       get merged up to all other branches. If a change is not needed for
        !            65:       later branches (i.e. fixes for features which where dropped from later
        !            66:       branches) an empty merge should be done.
        !            67: 
        !            68:    2. All news updates intended for public viewing, such as new features,
        !            69:       bug fixes, improvements, etc., should go into the NEWS file of the
        !            70:       *first* to be released version with the given change. In other words
        !            71:       any NEWS file change only needs to done in one branch.
        !            72: 
        !            73:    3. Do not commit multiple file and dump all messages in one commit. If you
        !            74:       modified several unrelated files, commit each group separately and
        !            75:       provide a nice commit message for each one. See example below.
        !            76: 
        !            77:    4. Do write your commit message in such a way that it makes sense even
        !            78:       without the corresponding diff. One should be able to look at it, and
        !            79:       immediately know what was modified. Definitely include the function name
        !            80:       in the message as shown below.
        !            81: 
        !            82:    5. In your commit messages, keep each line shorter than 80 characters. And
        !            83:       try to align your lines vertically, if they wrap. It looks bad otherwise.
        !            84: 
        !            85:    6. If you modified a function that is callable from PHP, prepend PHP to
        !            86:       the function name as shown below.
        !            87: 
        !            88: 
        !            89: The format of the commit messages is pretty simple.
        !            90: 
        !            91: <max 79 characters short description>\n
        !            92: \n
        !            93: <long description, 79 chars per line>
        !            94: \n
        !            95: 
        !            96: An Example from the git project (commit 2b34e486bc):
        !            97: 
        !            98: pack-objects: Fix compilation with NO_PTHREDS
        !            99:   
        !           100: It looks like commit 99fb6e04 (pack-objects: convert to use
        !           101: parse_options(), 2012-02-01) moved the #ifdef NO_PTHREDS around but
        !           102: hasn't noticed that the 'arg' variable no longer is available.
        !           103: 
        !           104: If you fix some bugs, you should note the bug ID numbers in your
        !           105: commit message. Bug ID should be prefixed by "#" for easier access to
        !           106: bug report when developers are browsing CVS via LXR or Bonsai.
        !           107: 
        !           108: Example::
        !           109: 
        !           110:   Fixed bug #14016 (pgsql notice handler double free crash bug.)
        !           111: 
        !           112: When you change the NEWS file for a bug fix, then please keep the bugs
        !           113: sorted in decreasing order under the fixed version.
        !           114: 
        !           115: You can use OpenGrok (http://lxr.php.net/) and gitweb (http://git.php.net/)
        !           116: to look at PHP Git repository in various ways.
        !           117: 
        !           118: 
        !           119: For further information on the process and further details please refer to
        !           120: https://wiki.php.net/vcs/gitworkflow and https://wiki.php.net/vcs/gitfaq
        !           121: 
        !           122: Happy hacking,
        !           123: 
        !           124: PHP Team