add OpenCensus migration path

specification/compatibility/opencensus.md

@@ -6,6 +6,76 @@ The OpenTelemetry project aims to provide backwards compatibility with the
 [OpenCensus](https://opencensus.io) project in order to ease migration of
 instrumented codebases.
 
+## Migration Path
+
+### Breaking Changes when migrating to OpenTelemetry
+
+Migrating from OpenCensus to OpenTelemetry may require breaking changes to the telemetry produced
+because of:
+
+* Different or new semantic conventions for names and attributes (e.g. [`grpc.test.EchoService/Echo`](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/gRPC.md#grpc-trace) vs [`rpc.server.duration`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.12.0/semantic_conventions/trace/rpc.yaml#L64))
+* Data model differences (e.g. OpenCensus supports [SumOfSquaredDeviations](https://github.com/census-instrumentation/opencensus-proto/blob/v0.3.0/src/opencensus/proto/metrics/v1/metrics.proto#L195), OTLP does not)
+* Instrumentation API feature differences (e.g. OpenCensus supports [context-based attributes](https://github.com/census-instrumentation/opencensus-specs/blob/master/stats/Record.md#recording-stats)), OTel does not)
+* Differences between equivalent OC and OTel exporters (e.g. the OpenTelemetry Prometheus exporter [adds type and unit suffixes](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#metric-metadata-1); OpenCensus [does not](https://github.com/census-ecosystem/opencensus-go-exporter-prometheus/blob/v0.4.1/prometheus.go#L227))
+
+This migration path groups most breaking changes into the installation of bridges. This gives
+users control over introducing the initial breaking change, and makes subsequent migrations of
+instrumentation (including in third-party libraries) non-breaking.
+
+### Migration Plans
+
+#### Migrating from the OpenCensus Agent and Protocol
+
+Starting with a deployment of the OC agent, using the OC protocol, migrate by:
+
+1. Deploy the OpenTelemetry collector with OpenCensus and OTLP receivers and equivalent processors and exporters.
+2. **breaking**: For each workload sending the OC protocol, change to sending to the OpenTelemetry collector's OpenCensus receiver.
+3. Remove the deployment of the OC Agent
+4. For each workload, migrate the application from OpenCensus to OpenTelemetry, following the guidance below, and use the OTLP exporter
+
+#### Migrating an Application using Bridges
+
+Starting with an application using entirely OpenCensus instrumention for traces and metrics, it can be migrated by:
+
+1. Migrate the exporters (SDK)
+    1. Install the OpenTelemetry SDK, with an equivalent exporter
+    2. Install equivalent OpenTelemetry resource detectors
+    3. Install OpenTelemetry propagators for OpenCensus' `TextFormat` and `BinaryPropagator` formats.
+    4. **breaking**: Install the metrics and trace bridges
+    5. Remove initialization of OpenCensus exporters
+2. Migrate the instrumentation (API)
+    1. **breaking**: For OpenCensus instrumentation packages, migrate to the OpenTelemetry equivalent.
+    2. For external dependencies, wait for it to migrate to OpenTelemetry, and update the dependency.
+    3. For instrumentation which is part of the application, migrate it following the "library" guidance below.
+3. Clean up: Remove the metrics and trace bridges
+
+#### Migrating Libraries using OC Instrumentation
+
+##### In-place Migration
+
+Libraries which want a simple migration can choose to replace instrumentation in-place.
+
+Starting with a library using OpenCensus Instrumentation:
+
+1. Annouce to users the library's transition from OpenCensus to OpenTelemetry, and recommend users adopt OC bridges.
+2. Change unit tests to use the OC bridges, and use OpenTelemetry unit testing frameworks.
+3. After a notification period, migrate instrumentation line-by-line to OpenTelemetry. The notification period should be long for popular libraries.
+4. Remove the OC bridge from unit tests.
+
+##### Migration via Config
+
+Libraries which are eager to add native OpenTelemetry instrumentation sooner, and/or want to
+provide extended support for OpenCensus may choose to provide users the option to use OpenCensus
+instrumentation _or_ OpenTelemetry instrumentation.
+
+Starting with a library using OpenCensus Instrumentation:
+
+1. Change unit tests to use the OC bridges, and use OpenTelemetry unit testing frameworks.
+2. Add configuration allowing users to enable OpenTelemetry instrumentation and disable OpenCensus instrumentation.
+3. Add OpenTelemetry instrumentation gated by the configuration, and tested using the same sets of unit tests.
+4. After a notification period, switch to using OpenTelemetry instrumentation by default.
+5. After a deprecation period, remove the option to use OpenCensus instrumentation.
+
 ## Trace Bridge
 
 **Status**: [Experimental, Feature Freeze](../document-status.md)