Docs: readme and licenses

.gitignore

@@ -3,8 +3,13 @@
 (.*/)?\#[^/]*\#$
 *.swp
 
+# Python
 *.pyc
 
+# Ruby
+.ruby-version
+Gemfile.lock
+
 # MacOS
 .DS_Store
 

CONTRIBUTING.md

@@ -1,34 +1,52 @@
-# calabash-xcuitest-server
+## Contributing
 
-## Adding New Routes
+***All pull requests should be based off the `develop` branch.***
+
+The Calabash iOS Toolchain uses git-flow.
+
+See these links for information about git-flow and git best practices.
+
+Please see this [post](http://chris.beams.io/posts/git-commit/) for tips
+on how to make a good commit messages.
+
+##### Git Flow Step-by-Step guide
+
+* https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
+
+##### Git Best Practices
+
+* http://justinhileman.info/article/changing-history/
+
+##### git-flow command line tool
+
+We don't use the git-flow tools, but this is useful anyway.
+
+* http://danielkummer.github.io/git-flow-cheatsheet/
+
+## Start a Feature
+
+Start your work on a feature branch based off develop.
 
-To add a new route, simply create a new object that implements the
-`<CBRouteProvider>` protocol defined in `CBProtocols.h`. Implement the following
-method:
-```Objective-C
-+ (NSArray<CBRoute *> *)getRoutes;
 ```
+# If you don't already have the develop branch
+$ git fetch origin
+$ git co -t origin/develop
+
+# If you already have the develop branch
+$ git co develop
+$ git pull origin develop
+$ git co -b feature/my-new-feature
 
-Generally the method definition should be something like:
-```Objective-C
-+ (NSArray<CBRoute *> *)getRoutes {
-    return @[
-
-        [CBRoute get:@"/foo/bar/calabash" withBlock:^(RouteRequest *request, RouteResponse *response) {
-            [response respondWithString:@"qux"];
-        }],
-        
-        [CBRoute post:@"/baz/bar/calabash" withBlock:^(RouteRequest *request, RouteResponse *response) {
-            NSDictionary *requestData = DATA_TO_JSON(request.body);
-            NSString *param = requestData[@"key"];
-            [Foo theBarBaz:param];
-            
-            [response respondWithJSON:@{ @"status" : @"success!" }];
-        }],
-        ...
-    ];
-}
+# Publish your branch and make a pull-request on `develop`
+$ git push -u origin feature/my-new-feature
 ```
 
-The route will automatically be picked up via objc runtime reflection. You can confirm
-by reading the console logs.
+**Contributors should not change the version.**
+
+## Testing
+
+TBD
+
+## Releasing
+
+TBD

Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gem "xcpretty", "~> 0.2"
+

LICENSE

@@ -0,0 +1 @@
+epl-v10.html

README.md

@@ -1,10 +1,89 @@
-# calabash-xcuitest-server
+| master  | develop | [versioning](VERSIONING.md) | [license](LICENSE) | [contributing](CONTRIBUTING.md)|
+|---------|---------|-----------------------------|--------------------|--------------------------------|
+|[![Build Status](https://travis-ci.org/calabash/calabash-xcuitest-server.svg?branch=master)](https://travis-ci.org/calabash/calabash-xcuitest-server)| [![Build Status](https://travis-ci.org/calabash/calabash-xcuitest-server.svg?branch=develop)](https://travis-ci.org/calabash/calabash-xcuitest-server)| [![Version](https://img.shields.io/badge/version-1.0.0-green.svg)](https://img.shields.io/badge/version-1.0.0-green.svg) |[![License](https://img.shields.io/badge/licence-Eclipse-blue.svg)](http://opensource.org/licenses/EPL-1.0) | [![Contributing](https://img.shields.io/badge/contrib-gitflow-orange.svg)](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow/)|
 
-Open xcuitest_serverUITests.m in Xcode.
-Start the `testRunner` test
+## The Calabus Driver
 
-The device IP:Portp will be output in the device log.
 
-```shell
-curl <device_ip:port>/health
+### Building
+
+Requires Xcode 7 and iOS 9 or higher.
+
+Requires ruby >= 2.0.  The latest ruby release is preferred.
+
+```
+$ git clone [email protected]:calabash/calabash-xcuitest-server.git
+$ cd calabash-xcuitest-server
+$ bundle update
+$ make app
+$ make ipa
+```
+
+To build with an alternative Xcode:
+
+```
+$ DEVELOPER_DIR=/Xcode/7.2b2/Xcode-beta.app make < rule >
+```
+
+If you have build errors, see the xcpretty section below.
+
+Maintainers must install the calabash/calabash-resign private repo. Details are below.
+
+### Code Signing
+
+If you are a maintainer, you _must_ install the codesign tool.
+
+* https://github.com/calabash/calabash-codesign
+
+If see messages like this:
+
+```
+iPhone Developer: ambiguous matches
+```
+
+then you must either:
+
+1. `$ CODE_SIGN_IDENTITY="< cert name >" make ipa-cal` (preferred)
+2. Update the Xcode project with a specific Code Signing entity.  **DO
+   NOT CHECK THESE CHANGES INTO GIT.**
+
+Maintainers should be using the Calabash.keychain (calabash/calabash-codesign).
+
+### Testing
+
+TBD
+
+### Contributing
+
+* The Calabash iOS Toolchain uses git-flow.
+* Contributors should not bump the version.
+* See the [CONTRIBUTING.md](CONTRIBUTING.md) guide.
+* There is a style guide: [STYLE\_GUIDE.md](STYLE\_GUIDE.md).
+* Pull-requests with unit tests will be merged faster.
+* Pull-requests with Cucumber integration tests will be merged even faster.
+
+### Releasing
+
+See the [CONTRIBUTING.md](CONTRIBUTING.md) document for instructions.
+
+### xcpretty
+
+https://github.com/supermarin/xcpretty
+
+We use xcpretty to make builds faster and to reduce the amount of
+logging.  Travis CI, for example, has a limit on the number of lines of
+logging that can be generated; xcodebuild breaks this limit.
+
+The only problem with xcpretty is that it does not report build errors
+very well.  If you encounter an issue with any of the make rules, run
+without xcpretty:
+
 ```
+$ XCPRETTY=0 make ipa
+```
+
+### Licenses
+
+Calabash iOS Server uses several third-party sources.  You can find the
+licenses for these sources in the third-party-licenses directory.
+

STYLE_GUIDE.md

@@ -0,0 +1,14 @@
+### Objective-C
+
+1. Use spaces, not tabs.
+2. Indents should be 4 spaces.
+3. As much as possible, limit each line to no more than 80 characters.
+4. Use Unicode UTF-8 and Unix newlines.
+
+When in doubt, refer to this guide:
+
+* https://github.com/raywenderlich/objective-c-style-guide
+
+If you are making a change to file, limit the number of style changes to as close to zero as possible so the diff can be easily read.
+
+One strategy is to make your changes, submit the PR, have it accepted, then make a style commit onto develop.

VERSIONING.md

@@ -0,0 +1,17 @@
+## Versioning
+
+Calabash tries very hard to comply with Semantic Versioning [1] rules.
+
+However, the semantic versioning spec is incompatible with RubyGem's patterns for pre-release gems.
+
+> "But returning to the practical: No release version of SemVer is compatible with Rubygems." - _David Kellum_ [2]
+
+Calabash version numbers will be in this form:
+
+```
+<major>.<minor>.<patch>[.pre<N>]
+```
+
+- [1] http://semver.org/
+- [2] http://gravitext.com/2012/07/22/versioning.html
+