From a68a2dedc1f48dcc48df3d37136ee78477b763bc Mon Sep 17 00:00:00 2001 From: Christian Noon Date: Wed, 20 Sep 2017 13:20:54 -0700 Subject: [PATCH] Added migration guide for Willow 5. --- Documentation/Willow 5.0 Migration Guide.md | 69 +++++++++++++++++++++ README.md | 1 + Willow.xcodeproj/project.pbxproj | 2 + 3 files changed, 72 insertions(+) create mode 100644 Documentation/Willow 5.0 Migration Guide.md diff --git a/Documentation/Willow 5.0 Migration Guide.md b/Documentation/Willow 5.0 Migration Guide.md new file mode 100644 index 0000000..e01bc5d --- /dev/null +++ b/Documentation/Willow 5.0 Migration Guide.md @@ -0,0 +1,69 @@ +# Willow 5.0 Migration Guide + +Willow 5.0 is the latest major release of Willow, a powerful, yet lightweight logging library for iOS, macOS, tvOS and watchOS written in Swift. +As a major release, following Semantic Versioning conventions, 5.0 introduces several API-breaking changes that one should be aware of. + +This guide is provided in order to ease the transition of existing applications using Willow 4.x to the latest APIs. + +## Requirements + +Willow 5.0 officially supports iOS 9.0+, macOS 10.11+, tvOS 9.0+, watchOS 2.0+, Xcode 9.0+ and Swift 4.0+. +If you'd like to use Willow in a project targeting Xcode 8.3 and Swift 3.1, use the latest tagged 3.x release. + +--- + +## Breaking API Changes + +Willow 5.0 contains very minor breaking changes on the log message string APIs. +Most of your Willow code will be able to remain the same. + +### Logger APIs + +Unfortunately, in the Willow 4.0.0 release, we missed the fact that multi-line escaping closures are ambiguous with different return types. +For example, the following call was ambiguous in Willow 4: + +```swift +log.event { + let value = 10 + return "Total value is: \(value)" +} +``` + +The only way to correct the ambiguity error is to declare the closure signature for the compiler: + +```swift +log.event { () -> String in + let value = 10 + return "Total value is: \(value)" +} +``` + +This was certainly not intended and was an unfortunate oversight on our part. +Single line closures did not exhibit the issue, but multi-line escaping closures certainly do. + +To resolve this issue in Willow 5, we've modified the log message string APIs to include the `Message` suffix. + +```swift +log.eventMessage { + let value = 10 + return "Total value is: \(value)" +} +``` + +The `LogMessage` APIs do not include the `Message` suffix which satisfies the compiler. +Sadly we were unable to make this change in a backwards compatible way. +However, it is a very simple change to make to migrate from Willow 4 to Willow 5. + +### Optional APIs + +The `Optional` extension APIs have also been updated to use the `Message` suffix for log message string APIs. + +```swift +var log: Logger? + +log.eventMessage { + let value = 10 + return "Total value is: \(value)" +} +``` + diff --git a/README.md b/README.md index 6cb77b0..8b68bad 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,7 @@ Willow is a powerful, yet lightweight logging library written in Swift. - [Willow 2.0 Migration Guide](https://github.com/Nike-Inc/Willow/blob/master/Documentation/Willow%202.0%20Migration%20Guide.md) - [Willow 3.0 Migration Guide](https://github.com/Nike-Inc/Willow/blob/master/Documentation/Willow%203.0%20Migration%20Guide.md) - [Willow 4.0 Migration Guide](https://github.com/Nike-Inc/Willow/blob/master/Documentation/Willow%204.0%20Migration%20Guide.md) +- [Willow 5.0 Migration Guide](https://github.com/Nike-Inc/Willow/blob/master/Documentation/Willow%205.0%20Migration%20Guide.md) ## Communication diff --git a/Willow.xcodeproj/project.pbxproj b/Willow.xcodeproj/project.pbxproj index fe9a5c1..e381b40 100644 --- a/Willow.xcodeproj/project.pbxproj +++ b/Willow.xcodeproj/project.pbxproj @@ -101,6 +101,7 @@ 4CD142361F572F6C002D6006 /* Willow 2.0 Migration Guide.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; name = "Willow 2.0 Migration Guide.md"; path = "Documentation/Willow 2.0 Migration Guide.md"; sourceTree = ""; }; 4CD142371F572F6C002D6006 /* Willow 3.0 Migration Guide.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; name = "Willow 3.0 Migration Guide.md"; path = "Documentation/Willow 3.0 Migration Guide.md"; sourceTree = ""; }; 4CD142381F572F6C002D6006 /* Willow 4.0 Migration Guide.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; name = "Willow 4.0 Migration Guide.md"; path = "Documentation/Willow 4.0 Migration Guide.md"; sourceTree = ""; }; + 4CF3EBD71F72FB5D00ECFA06 /* Willow 5.0 Migration Guide.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; name = "Willow 5.0 Migration Guide.md"; path = "Documentation/Willow 5.0 Migration Guide.md"; sourceTree = ""; }; 4CF89C8B1A6E2F60001BFDE1 /* Willow.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Willow.framework; sourceTree = BUILT_PRODUCTS_DIR; }; 4CF89C951A6E2F60001BFDE1 /* WillowTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = WillowTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; }; 4CFE82991A6C484A0002868E /* Willow.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Willow.framework; sourceTree = BUILT_PRODUCTS_DIR; }; @@ -224,6 +225,7 @@ 4CD142361F572F6C002D6006 /* Willow 2.0 Migration Guide.md */, 4CD142371F572F6C002D6006 /* Willow 3.0 Migration Guide.md */, 4CD142381F572F6C002D6006 /* Willow 4.0 Migration Guide.md */, + 4CF3EBD71F72FB5D00ECFA06 /* Willow 5.0 Migration Guide.md */, ); name = "Migration Guides"; sourceTree = "";