Add a deprecation notice and plan (#620)

* Add a deprecation notice and plan

* fix typos, provide more info in the README

DEPRECATION.md

@@ -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

README.md

@@ -1,5 +1,13 @@
 [![Build Status](https://travis-ci.org/grpc/grpc-swift.svg?branch=master)](https://travis-ci.org/grpc/grpc-swift)
 
+# ‼️ Deprecation Notice ‼️
+
+**gRPC Swift versions** `v0.x` **based on gRPC-Core will soon be replaced with a re-implementation based on [SwiftNIO](https://github.com/apple/swift-nio).** 
+
+**We strongly suggest that new projects use [the re-implementation from the `nio` branch](https://github.com/grpc/grpc-swift/tree/nio) which we consider to be production ready.** 
+
+**Please see [DEPRECATION.md](DEPRECATION.md) for more information.**
+
 # Swift gRPC
 
 This repository contains an experimental Swift gRPC API