Add a Start Span section to the OT Shim. (open-telemetry#2228)

* Add a Start Span section to the OT Shim.

* Fix link.

* Another link fix.

* Revisit references information.

* Update specification/compatibility/opentracing.md

Co-authored-by: Yuri Shkuro <[email protected]>

Co-authored-by: Yuri Shkuro <[email protected]>
Co-authored-by: Joshua MacDonald <[email protected]>

specification/compatibility/opentracing.md

@@ -8,6 +8,7 @@
 * [Abstract](#abstract)
 * [Create an OpenTracing Tracer Shim](#create-an-opentracing-tracer-shim)
 * [Tracer Shim](#tracer-shim)
+  * [Start a new Span](#start-a-new-span)
   * [Inject](#inject)
   * [Extract](#extract)
 * [Span Shim and SpanContext Shim relationship](#span-shim-and-spancontext-shim-relationship)
@@ -23,6 +24,7 @@
 * [ScopeManager Shim](#scopemanager-shim)
   * [Activate a Span](#activate-a-span)
   * [Get the active Span](#get-the-active-span)
+* [Span References](#span-references)
 * [In-process propagation exceptions](#in-process-propagation-exceptions)
   * [Implicit and Explicit support mismatch](#implicit-and-explicit-support-mismatch)
 
@@ -96,6 +98,41 @@ See OpenTracing Propagation
 
 ## Tracer Shim
 
+### Start a new Span
+
+Parameters:
+
+- The operation name, a string.
+- An optional list of [Span references](#span-references).
+- An optional list of [tags](#set-tag).
+- An optional explicit start timestamp, a numeric value.
+
+For OpenTracing languages implementing the [ScopeManager](#scopemanager-shim)
+interface, the folllowing parameters are defined as well:
+
+- An optional boolean specifying whether the current `Span`
+  should be ignored as automatic parent.
+
+If a list of `Span` references is specified, the first `SpanContext`
+with **Child Of** type in the entire list is used as parent, else the
+the first `SpanContext` is used as parent. All values in the list
+MUST be added as [Link](../trace/api.md)s with the reference type value
+as a `Link` attribute, i.e. `opentracing.ref_type` set to `follows_from` or
+`child_of`.
+
+If an initial set of tags is specified, the values MUST be set at
+the creation time of the OpenTelemetry `Span`, as opposed to setting them
+after the `Span` is already created. This is done in order to make
+those values available to any pre-`Span`-creation hook, e.g. the reference
+SDK performs a [sampling](../trace/sdk.md#sampling) step that consults
+`Span` information, including the initial tags/attributes, to decide whether
+to sample or not.
+
+If an explicit start timestamp is specified, a conversion MUST be done to match the
+OpenTracing and OpenTelemetry units.
+
+The API MUST return an OpenTracing `Span`.
+
 ### Inject
 
 Parameters:
@@ -411,6 +448,26 @@ Span active() {
 }
 ```
 
+## Span References
+
+As defined in the
+[OpenTracing Specification](https://github.com/opentracing/specification/blob/master/specification.md#references-between-spans),
+a `Span` may reference zero or more other `SpanContext`s that are
+causally related. The reference information itself consists of a
+`SpanContext` and the reference type.
+
+OpenTracing defines two types of references:
+
+* **Child Of**: The parent `Span` depends o the child `Span`
+  in some capacity.
+* **Follows From**: The parent `Span` does not depend in any
+  way on the result of their child `Span`s.
+
+OpenTelemetry does not define strict equivalent semantics for these
+references. These reference types must not be confused with the
+[Link](../trace/api.md##specifying-links) functionality. This information
+is however preserved as the `opentracing.ref_type` attribute.
+
 ## In process Propagation exceptions
 
 ### Implicit and Explicit support mismatch