|
|
@@ -0,0 +1,85 @@
|
|
|
+# gRPC Swift 0.x deprecation
|
|
|
+
|
|
|
+## What is this document?
|
|
|
+
|
|
|
+This document outlines the current plan to deprecate the `0.x` release series of gRPC Swift.
|
|
|
+
|
|
|
+## What is happening?
|
|
|
+
|
|
|
+gRPC Swift versions `v0.x` based on gRPC-Core will soon be replaced with a re-implementation based on [SwiftNIO][nio].
|
|
|
+
|
|
|
+We strongly suggest that new projects use [the re-implementation from the `nio` branch][nio-branch] which we consider to be production ready.
|
|
|
+
|
|
|
+In the coming weeks this branch (currently `master`) containing the `0.x` releases will be renamed `cgrpc`. The `nio` branch containing the [new implementation][nio-branch] will subsequently be renamed to `master` and become the default branch. A `1.0.0` tag will also be created.
|
|
|
+
|
|
|
+Version | Branch Now | Branch After Deprecation
|
|
|
+--------|------------|-------------------------
|
|
|
+`0.x` | `master` | `cgrpc`
|
|
|
+`1.x` | `nio` | `master`
|
|
|
+
|
|
|
+## What is it being replaced with?
|
|
|
+
|
|
|
+We have rewritten gRPC Swift on top of [SwiftNIO][nio], an open-source asynchronous event-driven networking framework created by Apple. Our implementation will be written in Swift and will not wrap the gRPC Core C library.
|
|
|
+
|
|
|
+## Why is this happening?
|
|
|
+
|
|
|
+There are a number of reasons we have rewritten gRPC Swift:
|
|
|
+
|
|
|
+- The `0.x` releases are built on top of a C interface to the gRPC Core library provided by the [gRPC project][grpc]. This led to a number of memory safety issues and is easy to hold incorrectly.
|
|
|
+- Network connectivity changes (e.g. LTE to WiFi, 3G to LTE, etc.) are not handled well by the networking stack in the gRPC Core C library. [Network.framework][network-framework] (where available, see below) alleviates this problem and has integration with [SwiftNIO][nio].
|
|
|
+- [SwiftNIO][nio] has gained a lot of traction in the Swift on Server community due to its performance. We believe we can leverage this to improve the performance and stability of gRPC Swift.
|
|
|
+- Vendoring copies of the gRPC Core library and BoringSSL is a source of frustration for developers and users.
|
|
|
+
|
|
|
+## What will happen to the `0.x` releases?
|
|
|
+
|
|
|
+We will continue to patch the `cgrpc` branch for security fixes and serious bugs only. There will be no feature development on the `cgrpc` branch and the version of the gRPC Core library will not be updated (unless necessary for a security fix).
|
|
|
+
|
|
|
+## When is this happening?
|
|
|
+
|
|
|
+We plan to deprecate versions `0.x` and tag version `1.0.0` by the end of 2019.
|
|
|
+
|
|
|
+## Which Swift versions will be supported for `1.x`?
|
|
|
+
|
|
|
+Swift 5.0 and later.
|
|
|
+
|
|
|
+## Which platforms will be supported for `1.x`?
|
|
|
+
|
|
|
+We have the same [platform support as SwiftNIO][nio-platforms]. That is:
|
|
|
+
|
|
|
+* macOS 10.12+, iOS 10+
|
|
|
+* macOS 10.14+, iOS 12+, or tvOS 12+ (with [Network.framework][network-framework] support via [NIO Transport Services][nio-ts])
|
|
|
+* Ubuntu 14.04+
|
|
|
+
|
|
|
+## Which package managers will be supported for `1.x`?
|
|
|
+
|
|
|
+We will provide support for Swift Package Manager as we believe that its integration with Xcode is the most convenient way to manage packages.
|
|
|
+
|
|
|
+CocoaPods support is _not_ currently planned. However, we may provide support if there is significant community interest.
|
|
|
+
|
|
|
+Carthage will _not_ be supported as it has been the source of a [number][carthage0] [of][carthage1] [issues][carthage2] [in][carthage3] [the][carthage4] [past][carthage5].
|
|
|
+
|
|
|
+## Can I try this out now?
|
|
|
+
|
|
|
+Absolutely! Head over to the `nio` [branch][nio-branch] and check out the [quick-start guide][quick-start] or [basic tutorial][basic-tutorial].
|
|
|
+
|
|
|
+## I can't find a feature I used in `0.x`, can you help?
|
|
|
+
|
|
|
+If there’s something you can't find that was in the previous implementation or if anything is unclear then _please_ reach out to us by filing an issue. We also have a [dedicated space in the Swift forums][forums] for the project.
|
|
|
+
|
|
|
+
|
|
|
+[nio]: https://github.com/apple/swift-nio
|
|
|
+[nio-branch]: https://github.com/grpc/grpc-swift/tree/nio
|
|
|
+[nio-platforms]: https://github.com/apple/swift-nio#supported-platforms
|
|
|
+[nio-ts]: https://github.com/apple/swift-nio-transport-services
|
|
|
+[network-framework]: https://developer.apple.com/documentation/network
|
|
|
+[grpc]: https://github.com/grpc/grpc
|
|
|
+[quick-start]: https://github.com/grpc/grpc-swift/blob/nio/docs/quick-start.md
|
|
|
+[basic-tutorial]: https://github.com/grpc/grpc-swift/blob/nio/docs/basic-tutorial.md
|
|
|
+[readme]: https://github.com/grpc/grpc-swift/blob/nio/README.md
|
|
|
+[forums]: https://forums.swift.org/c/related-projects/grpc-swift
|
|
|
+[carthage0]: https://github.com/grpc/grpc-swift/issues/329
|
|
|
+[carthage1]: https://github.com/grpc/grpc-swift/issues/449
|
|
|
+[carthage2]: https://github.com/grpc/grpc-swift/issues/495
|
|
|
+[carthage3]: https://github.com/grpc/grpc-swift/issues/507
|
|
|
+[carthage4]: https://github.com/grpc/grpc-swift/issues/604
|
|
|
+[carthage5]: https://github.com/grpc/grpc-swift/issues/615
|
George Barnett