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.

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. Please run this script before committing your work or sending requests. This is the same script the build server runs, so running locally will minimize the chance of breakage and any subsequent impact on the productivity of your fellow developers.

Dependencies

We recommended installing CLI build dependencies using HomeBrew (http://brew.sh) or MacPorts (https://www.macports.org/) and Ruby gems.

brew install lcov
brew install groovy
brew install doxygen
brew install graphviz
gem install xcpretty

. . and now run

build.sh

This performs:

• iOS tests
• OSX tests
• generates test coverage report

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.

Core Team

• Jasper Blues (Founder / Project Lead) - [email protected]
• Aleksey Garbarev, Principal Developer
• Robert Gilliam - [email protected]
• Daniel Rodríguez Troitiño
• Erik Sundin

With contributions from:

• César Estébanez Tascón : Circular Dependencies fixes.
• Bryn Cooke : Late injections & story board integration.
• Jeffrey Roberts, Mobile Software Engineer at Riot Games, previous contributor to Swiz for ActionScript : Advice, feedback and testing.
• José González Gómez, Mobile and cloud developer at OPEN input : Feedback; testing, support for property placeholders in initializers.
• Sergio Padrino Recio : Performance improvements.
• Josh Ervine : Feedback and support for TyphoonFactoryProviders.
• Your name here!!!!!!!

(If you've sent a pull request and didn't get a mention. . . sorry! Please let us know and we'll correct it).

---