Contribution Guide

Legal

All of Typhoon is Licensed under Apache v2.0. By contributing to Typhoon you agree:

• To license the work under Apache v2.0
• That you have the right to assign this license - this is your original work, or you have permission from the owners to contribute.

Dependencies

We recommend using bundler to install all ruby dependencies, such as cocoapods.

bundle

Attribution and Copyright

All files MUST include the copyright header found in the repository: Copyright-Header.txt. Your help replacing any incorrect headers with this canonical one, as we propagate this requirement across the codebase, is greatly appreciated. We recommend the use of a code snippet with the abbreviation 'typhoon_header' to automate the insertion of this notice.

If you want, you can use a filter that will automatically check the header presence and include it if it is not already there for every file you add or modify. To enable this behaviour you should run this two commands in your working copy directory:

git config filter.typhoonheader.smudge 'cat'
git config filter.typhoonheader.clean '`git rev-parse --git-dir`/../Scripts/typhoonheader'

This two config entries register the filter that will add the right header for you.

Command-Line Build

Builds unit tests, integration tests and code coverage reports. Installs Typhoon documentation into Xcode.

Dependencies

We recommended installing CLI build dependencies using homebrew (http://brew.sh).

brew install gradle

brew install lcov

brew install appledoc

brew install doxygen
brew install graphviz

NB: Xcode 4.3+ requires command-line tools to be installed separately.

Building

gradle test

Code Style

The AppCode project included in the repository has a complete set of code styles that AppCode will help you to follow. There is also a StyleSettings.plist for ObjClean, but the Build Step is not in the project. You can execute the following command from the Typhoon main directory if you want to manually check:

/Applications/Objective-Clean.app/Contents/Resources/ObjClean.app/Contents/MacOS/ObjClean `pwd`

Here is a visual summary of the code style rules.

//
// HEADER COMMENT (use template)
//
                               // Use 4 spaces for indentation. No tabs.
                               // No trailing whitespace.
                               // No indentation for empty lines
                               // Use one blank lines around code structures.

void GlobalFunction(id a, id b, id c);
                               // No space between name and parenthesis
                               // Always spaces after commas


@interface Class (Category) : SuperClass <Protocol1, Protocol2>
                               // Space between class name and category parenthensis
                               // Spaces around colon between class and superclass
                               // Spaces before angle bracket of protocol declaration

                               // No extra indentation for members of @interface.

@property(nonatomic, assign) NSInteger a;
                               // No space between @property and parenthesis.
@property(nonatomic, strong) TyphoonClass* b;  
                               // No space between type and asterisk
                               // Space between asterisk and name

- (instancetype)init;          // Space between class/instance symbol and return type parenthesis
                               // No space between return type parenthesis and selector name

- (id)foo:(NSInteger)x bar:(CGFloat)y baz:(id)z;
                               // No space between selector colon and argument type parenthesis
                               // No space between argument type parenthesis and argument name

@end


@implementation TyphoonClass
                               // No extra indentation for members of @implementation
                               // No explicit @synthesize (if possible)

- (instancetype)init
{                              // Braces in the next line. No extra indentation.
    TyphoonGlobalFunction();   // No space between name and parenthesis.

    self = [super init];       // Spaces around assignment operators (=, +=, -=, ...)
    if (self)                  // Space between if/for/while/switch/@catch/@synchronize and parenthesis
    {
        _a = 7;
        _b = [[NSObject alloc] init];
                              // Space before chained message send: "alloc]  init]", not "alloc]init]"
    }

    return self;
}

- (id)foo:(NSInteger)x bar:(CGFloat)y baz:(id)z
{
    if (x == 0 || y < 3.0)     // Spaces around equality operators (==, !=)
                               // Spaces around relational operators (<, >, <=, =>)
                               // Spaces around logical operators (&&, ||)
    {
        NSInteger w = x & 0x1; // Spaces around bitwise operators (&, |, <<, >>)
        CGFloat v = y + 3.0;   // Spaces around mathematical operators (+, -, *, /)
        CGFloat u = x++;       // No spaces for unary operators (+, -, ++, --, !)

        NSInteger t = x == 7 ? 3 : 8;
                               // Spaces around ? and : ternary operator
        id s = z ?: self;      // No spaces between ? and : in shortcut ternary operator

        TyphoonClass* r = (TyphoonClass*) s;
                               // Space after typecast parenthesis

        id dict = @{ @1 : @"one", @2 : @"two" };
                              // Spaces around colons in dictionary literals
    }

    return nil;
}

@end

// End files with newline

In case of any doubt, the best thing is looking the code around the point that you are editing, and keep the style consistent.