Update CONTRIBUTING.md

Updated commit message section.
2026-09-20 17:30:41 +00:00 · 2013-03-12 13:40:18 -03:00
parent 445045565b
commit fd49bd2f2d
1 changed files with 113 additions and 29 deletions
@@ -33,43 +33,127 @@ Some things are difficult to unit test in a way that's worthwhile. For instance

 The style and format of your commit messages are very important to the health of the project. A good commit message helps not only users reading the release notes, but also your fellow Cappuccino developers as they review `git log` or `git blame` to figure out what you were doing.

-This is the preferred format of commit messages for complex changes:
+Commit messages should be in the following format:

-    [New:] <what's new.>
+    <type>: <summary>

-    [OPTIONAL DESCRIPTION ABOUT WHAT THIS THING DOES.]
+    <body>

-Or for fixes:
+    <footer>

-    Fixed: <what was fixed.>
+### Types

-    BEFORE
+Allowed `type` values are:

-    AFTER
+* **New** — A new feature has been implemented
+* **Fixed** — A bug has been fixed
+* **Docs** — Documentation has been added or tweaked
+* **Formatting** — Code has been reformatted to conform to style guidelines
+* **Test** — Test cases have been added
+* **Task** — A build task has been added or updated

-**Example:**
+### Message summary

-    nib2cib support for table view background colour.
+The summary is one of the most important parts of the commit message, because that is what we see when scanning through a list of commits, and it is also what we use to generate change logs.

-**Example:**
+The summary should be a **concise** description of the commit, preferably 72 characters or less (so we can see the entire description in github), beginning with a lowercase letter and with a terminating period. It should describe only the core issue addressed by the commit. If you find that the summary needs to be very long, your commit is probably too big! Smaller commits are better.
+
+For a `New` commit, the summary should answer the question, “What is new and where?” For a `Fixed` commit, the summary should answer the question, “What was fixed?”, for example “Window content view overlapped frame”. It should **not** answer the question, “What was done to fix it?” That belongs in the body.
+
+Do **not** simply reference another issue or pull request by number in the summary. First of all, we want to know what was actually changed and why, which may not be fully explained in the referenced issue. Second, github will not create a link to the referenced issue in the commit summary.
+
+### Message body
+
+The details of the commit go in the body. Specifically, the body should include the motivation for the change for `New`, `Fixed` and `Task` types. For `Fixed` commits, you should also contrast behavior before the commit with behavior after the commit.
+
+If the summary can completely express everything, there is no need for a message body.
+
+### Message footer
+
+If the commit closes an issue by fixing the bug, implementing a feature, or rendering it obsolete, or if it references an issue without closing it, that should be indicated in the message footer.
+
+Issues closed by a commit should be listed on a separate line in the footer with an appropriate prefix:
+
+- "Fixes" for `Fixed` commit types
+- "Closes" for all other commit types
+
+For example:
+
+    Fixes #1234
+
+or in the case of multiple issues, like this:
+
+    Fixes #1234, #2345
+
+Issues that a commit references without closing them should be listed on a separate line in the footer with the prefix "Refs", like this:
+
+    Refs #1234
+
+or in the case of multiple issues, like this:
+
+    Refs #1234, #2345
+
+If a commit changes the API or behavior in such a way that existing code may break, a description of the change, what might break, and how existing code should be modified **must** be noted in the footer like this:
+
+    BREAKING CHANGE:
+    The scroller orientation is no longer calculated from the size,
+    but is read from the xib during nib2cib.
+
+    All existing xibs should be regenerated by executing the following
+    within a project directory: `find . -name *.xib -exec nib2cib {} \;`
+
+### Examples
+
+    New: custom rendered pattern fill/stroke.
+
+    Canvas supports using another canvas as the source for a pattern fill
+    or stroke. We needed an API for this that fit into the rest of the
+    CGContext API.
+
+    CGContextCreatePatternContext returns a context into which any arbitrary
+    drawing can be done. This context can then be passed to CGContextSetFillPattern
+    or CGContextSetStrokePattern to render the drawing into the current drawing context.
+
+    Test app in Tests/Manual/PatternFillTest.
+
+***

    Fixed: CPAlert was a CPView.

-    Before this fix, CPAlert subclassed CPView, causing an API mismatch with Cocoa and exposing unexpected methods in the public API which made no sense for a CPAlert such as autoresizing masks. It also lead to CPAlert mistakingly shadowing _window from its CPView superclass.
+    Previously, CPAlert subclassed CPView, causing an API mismatch
+    with Cocoa and exposing unexpected methods in the public API which
+    made no sense for a CPAlert, such as autoresizing masks. It also led
+    to CPAlert mistakingly shadowing _window from its CPView superclass.

-    This fix makes CPAlert inherit from CPObject as it should. The theming, which needs to be applied to a view, was moved to an internal view.
+    This commit makes CPAlert inherit from CPObject as it should. The theming,
+    which needs to be applied to a view, was moved to an internal view.

-The summary line concisely says what was fixed or improved by the commit. If it's an improvement or something new it optionally starts with "New:". If it's a bug fix it starts with "Fixed:".
+    Fixes #307

-For a 'new' change, the rest of the summary line answers the question *"What is new and where?"*. Optionally the summary can be followed with more detail about what's new and why it's great.
+***

-If the summary starts with "Fixed:" the rest of the summary line answers the question *"What was fixed?"*. E.g. "Fixed: the blargh had too many blurghs."
+    Fixed: CPScroller did not retrieve orientation from the xib.

-(Note it does NOT answer the question *"what was done to fix it?"* E.g. **WRONG:** "Fixed: removed 2 blurghs from the blargh." That would imply that your very change was what was fixed by itself, causing an infinite loop in the universe and ending the world as we know it.)
+    Previously, CPScrollers created from cibs calculated their orientation
+    (horizontal/vertical) based on their size. Unfortunately this did not
+    account for the unlikely case where a horizontal scroller's width < height,
+    and vice versa.

-The rest of the fix message is in a before / after form. The first part describes what the situation was before the fix and says why the fix was needed. The after part describes what change was made to rectify the situation and any implementation notes that might be useful to know for people reviewing it in the future.
+    Now the CPScroller's orientation is read from the xib and is guaranteed
+    to be correct.

-Naturally small or unimportant commits have less rigid requirements. If you can comfortably and easily describe the whole change in the summary only, go ahead. Maybe you fixed a tiny typo or did a minor refactoring.
+    Fixes #1027
+
+    BREAKING CHANGE:
+    The scroller orientation is no longer calculated from the size,
+    but is read from the xib during nib2cib.
+
+    All existing xibs should be regenerated by executing the following
+    within a project directory: `find . -name *.xib -exec nib2cib {} \;`
+
+***
+
+    Docs: Typo in CPWindow -minSize.

 ## Cappuccino Coding Style Guidelines

@@ -106,7 +190,7 @@ A case label should be indented once from its switch statement. The case stateme
        case barCondition:
            i++;
            break;
-            
+
        case bazCondition:
            i += 2;
            break;
@@ -123,7 +207,7 @@ A case label should be indented once from its switch statement. The case stateme
            i++;
            break;
        case bazCondition:  i += 2;
-                            break;             
+                            break;
        default:
            i--;
    }
@@ -220,7 +304,7 @@ Each statement should get its own line.
        y;
    x++;
    y++;
-    
+
    if (condition)
        doIt();

@@ -236,10 +320,10 @@ There should be blank lines around bracketed code blocks and control structures,

    var x,
        y;
-        
+
    x++;
    y++;
-    
+
    if (condition)
        doIt();
    else
@@ -247,7 +331,7 @@ There should be blank lines around bracketed code blocks and control structures,
        doSomethingElse();
        doMore();
    }
-    
+
    return x;

 ##### Wrong:
@@ -263,7 +347,7 @@ There should be blank lines around bracketed code blocks and control structures,
        doSomethingElse();
        doMore();
    }
-    return x;        
+    return x;

 ### Braces

@@ -382,12 +466,12 @@ Variable declarations should be created as needed, rather than up front ("hoiste
    - (BOOL)doSomething:(id)aFoo
    {
        var importantVariable = [aFoo message];
-        
+
        if (!importantVariable)
            return;

        var index = [aFoo count];
-        
+
        while (index--)
        {
            var innerVariable = [aFoo objectAtIndex:index];
@@ -457,7 +541,7 @@ Precede boolean values with words like "is" and "did".

    var isValid,
        didSendData;
-        
+
    - (BOOL)isEditable;
    - (BOOL)didReceiveResponse;

@@ -465,7 +549,7 @@ Precede boolean values with words like "is" and "did".

    var valid,
        sentData;
-        
+
    - (BOOL)editable;
    - (BOOL)receivedResponse;