Upgrade PromiseKit to 4.4.1

// FREEBIE

Checkouts/PromiseKit/.github/ISSUE_TEMPLATE.md

@@ -1,6 +1,6 @@
-* PromiseKit version: 
-* Xcode version: 
-* CocoaPods version: **delete line if not applicable**
-* Carthage version: **delete line if not applicable**
+* PromiseKit version: **major version is enough unless you have a build issue**
+* Xcode version: **only required for build issues**
+* CocoaPods version: **only required for build issues**
+* Carthage version: **only required for build issues**
 
 > Please format your code in triple backticks and delete this line before submitting your ticket. Failure to remove this line may result in mockery.

Checkouts/PromiseKit/.travis.yml

@@ -1,28 +1,129 @@
-language: objective-c
-osx_image: xcode8
+matrix:
+  include:
+    - os: osx
+      language: objective-c
+      osx_image: xcode9
+      env: SWFT=4.0 PLAT=macOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode9
+      env: SWFT=4.0 PLAT=iOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode9
+      env: SWFT=4.0 PLAT=tvOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode9
+      env: SWFT=4.0 PLAT=watchOS
+
+    - os: osx
+      language: objective-c
+      osx_image: xcode9
+      env: SWFT=3.2 PLAT=macOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode9
+      env: SWFT=3.2 PLAT=iOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode9
+      env: SWFT=3.2 PLAT=tvOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode9
+      env: SWFT=3.2 PLAT=watchOS
 
-env:
-  - PLATFORM=Mac
-  - PLATFORM=iOS NAME='iPhone SE'
-  - PLATFORM=tvOS NAME='Apple TV 1080p'
-  - PLATFORM=watchOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.3
+      env: SWFT=3.1 PLAT=macOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.3
+      env: SWFT=3.1 PLAT=iOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.3
+      env: SWFT=3.1 PLAT=tvOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.3
+      env: SWFT=3.1 PLAT=watchOS
+
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.2
+      env: SWFT=3.0 PLAT=macOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.2
+      env: SWFT=3.0 PLAT=iOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.2
+      env: SWFT=3.0 PLAT=tvOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.2
+      env: SWFT=3.0 PLAT=watchOS
+
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.1
+      env: SWFT=3.0 PLAT=macOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.1
+      env: SWFT=3.0 PLAT=iOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.1
+      env: SWFT=3.0 PLAT=tvOS
+    - os: osx
+      language: objective-c
+      osx_image: xcode8.1
+      env: SWFT=3.0 PLAT=watchOS
+
+    - os: linux
+      dist: trusty
+      sudo: required
+      services: docker
+      env: DOCKER_IMAGE=swift:3.1
+
+    #TODO please help us test Linux with Swift 3.0, 3.2 and 4.0
 
 before_install:
-  - if [ -n "$NAME" ]; then
+  - if [ "$TRAVIS_OS_NAME" == "linux" ]; then
+      docker pull $DOCKER_IMAGE;
+    fi;
+    case $PLAT in
+    iOS)
+      NAME="iPhone SE";;
+    tvOS)
+      NAME="Apple TV 1080p";;
+    watchOS)
+      NAME="Apple Watch - 38mm";;
+    esac;
+    if [ -n "$NAME" ]; then
       export UUID=$(instruments -s | ruby -e "ARGF.each_line{ |ln| ln =~ /$NAME .* \[(.*)\]/; if \$1; puts(\$1); exit; end }");
     fi
-
 script:
   - set -o pipefail;
-    case $PLATFORM in
-    Mac)
-      xcodebuild -scheme PromiseKit -enableCodeCoverage YES test | xcpretty;;
+    case $PLAT in
+    macOS)
+      xcodebuild -scheme PromiseKit -quiet build SWIFT_VERSION=$SWFT -enableCodeCoverage YES | xcpretty;
+      xcodebuild -scheme PromiseKit -quiet test;;
     iOS|tvOS)
-      open -a "simulator" --args -CurrentDeviceUDID "$UUID"
-      xcodebuild -scheme PromiseKit -destination "id=$UUID" -enableCodeCoverage YES test | xcpretty;;
+      open -b com.apple.iphonesimulator --args -CurrentDeviceUDID "$UUID";
+      xcodebuild -scheme PromiseKit -quiet -destination "id=$UUID" build SWIFT_VERSION=$SWFT -enableCodeCoverage YES | xcpretty;
+      xcodebuild -scheme PromiseKit -quiet -destination "id=$UUID" test;;
     watchOS)
-      xcodebuild -scheme PromiseKit -destination "name=Apple Watch - 38mm" | xcpretty;;
+      xcodebuild -scheme PromiseKit -quiet -destination "id=$UUID" -quiet clean build SWIFT_VERSION=$SWFT | xcpretty;;
+    *)
+      docker-compose run PromiseKit;;
     esac
-
 after_success:
-  - bash <(curl -s https://codecov.io/bash)
+  - if [ "$TRAVIS_OS_NAME" == "osx" ]; then
+      bash <(curl -s https://codecov.io/bash);
+    fi

Checkouts/PromiseKit/Documentation/Appendix.md

@@ -0,0 +1,69 @@
+# Common Misusage
+
+## Doubling Up Promises
+
+Don’t do this:
+
+```swift
+func toggleNetworkSpinnerWithPromise<T>(funcToCall: () -> Promise<T>) -> Promise<T> {
+    return Promise { fulfill, reject in
+        firstly {
+            setNetworkActivityIndicatorVisible(true)
+            return funcToCall()
+        }.then { result in
+            fulfill(result)
+        }.always {
+            setNetworkActivityIndicatorVisible(false)
+        }.catch { err in
+            reject(err)
+        }
+    }
+}
+```
+
+Do this:
+
+```swift
+func toggleNetworkSpinnerWithPromise<T>(funcToCall: () -> Promise<T>) -> Promise<T> {
+    return firstly {
+        setNetworkActivityIndicatorVisible(true)
+        return funcToCall()
+    }.always {
+        setNetworkActivityIndicatorVisible(false)
+    }
+}
+```
+
+You already *had* a promise, you don’t need to wrap it in another promise.
+
+
+## Optionals in Promises
+
+Mostly when we see `Promise<Item?>` it implies a misuse of promises, for
+example:
+
+```swift
+return firstly {
+    getItems()
+}.then { items -> Promise<[Item]?> in
+    guard !items.isEmpty else {
+        return Promise(value: nil)
+    }
+    return Promise(value: items)
+}
+```
+
+The second `then` chooses to return `nil` in some circumstances. This imposes
+the `nil` check on the consumer of this promise. Instead create an specific
+error type for this condition:
+
+```swift
+return firstly {
+    getItems()
+}.then { items -> Promise<[Item]> in
+    guard !items.isEmpty else {
+        throw MyError.emptyItems
+    }
+    return items
+}
+```