Proposal: API and SDK version labeling (open-telemetry#280)

* Proposal: API and SDK version labeling

## Problem Description

We assume that API specification will have a version number.
We also assume that SDK's will implement a particular API version.

Library authors may want to make multiple SDK releases that are
implementing a particular API version. For example, we may start
with API version 1.0.0 and make an SDK release 1.0.0 that
implements that particular API.

Later library authors may want to make a bug fix in the SDK and
release 1.0.1. Note that this release implements the same API
version, there are no changes from API perspective. Now we are in
a situation when API and SDK versions diverged.

This diverging seems inevitable because most likely API versions
will change much less frequently than library authors will want
to make SDK releases that implement those particular API versions.

## Proposed Solution

Both API and SDK will semantic version numbers. API and SDK
version numbers will not be strictly coupled. SDK is free to have
a separate version number with one limitation: major version
number of the SDK must be the same as the major version number of
the API that the SDK implements.

For example SDKs 0.1.0, 0.2.3, 0.7.0 can all implement API 0.1.0,
but SDK 1.0.0 cannot implement API 0.1.0.

This weak coupling of version numbers allows language library
authors to make patch and minor version SDK releases
independently without the need to coordinate version numbers with
API specification. The requirement to use the same major version
number is aimed to minimize the element of surprise and avoid
spilling SDK version numbers into next major version in case we
decide the policy starting from certain major version in the future.

Because API and SDK version numbers are not strictly coupled every
SDK release must clearly specify API version number that it
implements. Language library authors must include this information
in SDK release notes. For example the release notes may say:
"SDK 0.3.4, implements API 0.1.0".

## Alternate Solutions

Two other solutions were considered but saw less support:

1. Complete decouple SDK and API version numbers. SDK can use any
version, including a different version number. The downside of this
solution is that it can create a situation when in the future if we
decide version labeling policy it may be too late since there may
exist SDKs versions that spill into the next major version. To keep
our options open the major version number restriction was proposed.

2. Couple major and minor version numbers of SDK and API, only allow
SDK to freely change patch version number and always use 0 patch
number for API versions. The downside of this solution is that SDK
releases can only make patch releases if they implement the same
API or they have to break the semantic versioning rule and allow
significant changes while only incrementing patch number.

Implements open-telemetry#276 and open-telemetry#246

* PR fixes

specification/library-guidelines.md

@@ -97,6 +97,16 @@ Note that mocking is also possible by using SDK and a Mock `Exporter` without ne
 
 The mocking approach chosen will depend on the testing goals and at which point exactly it is desirable to intercept the telemetry data path during the test.
 
+## Version Labeling
+
+API and SDK packages must use semantic version numbering. API package version number and SDK package version number are decoupled and can be different (and they both can be also different from the Specification version number that they implement). API and SDK packages MUST be labeled with their own version number.
+
+This decoupling of version numbers allows language library authors to make API and SDK package releases independently without the need to coordinate and match version numbers with Specification.
+
+Because API and SDK package version numbers are not coupled every API and SDK package release MUST clearly mention Specification version number that they implement. In addition if a particular version of SDK package is only compatible with a specific version of API package then this compatibility information must be also published by language library authors. Language library authors MUST include this information in the release notes. For example SDK package release notes may say: "SDK 0.3.4, use with API 0.1.0, implements OpenTelemetry Specification 0.1.0".
+
+_TODO: how should third party library authors who use OpenTelemetry for instrumentation guide their end users to find the correct SDK package?_
+
 ## Performance and Blocking
 
 See the [Performance and Blocking](performance.md) specification for