Flesh out README, add release schedule (open-telemetry#127)

c24t · Oberon00 · commit 17bef26bd9f6 · 2019-09-10T10:06:18.000+02:00
* Flesh out README, add release schedule

* Update README.md

Co-Authored-By: Christian Neumüller &lt;christian.neumueller@dynatrace.com&gt;

* Update README.md

Co-Authored-By: Christian Neumüller &lt;christian.neumueller@dynatrace.com&gt;

* Add note about alpha/beta compatability, support

* Move development notes into contributing doc

* Add note about library, app dev API/SDK use
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,7 +8,26 @@ See the [public meeting notes](https://docs.google.com/document/d/1CIMGoIOZ-c3-i
 for a summary description of past meetings. To request edit access, join the
 meeting or get in touch on [Gitter](https://gitter.im/open-telemetry/opentelemetry-python).
 
-## Pull Request
+## Development
+
+This project uses [`tox`](https://tox.readthedocs.io) to automate some aspects
+of development, including testing against multiple Python versions.
+
+You can run:
+
+- `tox` to run all existing tox commands, including unit tests for all packages
+  under multiple Python versions
+- `tox -e docs` to regenerate the API docs
+- `tox -e test-api` and `tox -e test-sdk` to run the API and SDK unit tests
+- `tox -e py37-test-api` to e.g. run the the API unit tests under a specific
+  Python version
+- `tox -e lint` to run lint checks on all code
+
+See
+[`tox.ini`](https://github.com/open-telemetry/opentelemetry-python/blob/master/tox.ini)
+for more detail on available tox commands.
+
+## Pull Requests
 
 ### How to Send Pull Requests
 
@@ -52,7 +71,7 @@ Open a pull request against the main `opentelemetry-python` repo.
   as `work-in-progress`, or mark it as [`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
 * Make sure CLA is signed and CI is clear.
 
-### How to Get PR Merged
+### How to Get PRs Merged
 
 A PR is considered to be **ready to merge** when:
 * It has received two approvals from Collaborators/Maintainers (at different
@@ -85,10 +104,13 @@ rather than conform to specific API names or argument patterns in the spec.
 
 For a deeper discussion, see: https://github.com/open-telemetry/opentelemetry-specification/issues/165
 
-## Styleguide
+## Style Guide
 
-* docstrings should adhere to the Google styleguide as specified
-  with the [napolean extension](http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#google-vs-numpy) extension in [Sphinx](http://www.sphinx-doc.org/en/master/index.html).
+* docstrings should adhere to the [Google Python Style
+  Guide](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
+  as specified with the [napolean
+  extension](http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#google-vs-numpy)
+  extension in [Sphinx](http://www.sphinx-doc.org/en/master/index.html).
 
 ## Become a Collaborator
 
@@ -110,4 +132,4 @@ To become a Maintainer:
 * Become a Collaborator.
 * Demonstrate the ability and commitment.
 * Contact the Maintainers, express the willingness and commitment.
-* Acknowledged and approved by all the current Maintainers.
+* Acknowledged and approved by all the current Maintainers.
diff --git a/README.md b/README.md
@@ -8,7 +8,37 @@ The Python [OpenTelemetry](https://opentelemetry.io/) client.
 
 ## Installation
 
-## Usage
+This repository includes multiple installable packages. The `opentelemetry-api`
+package includes abstract classes and no-op implementations that comprise the OpenTelemetry API following
+[the
+specification](https://github.com/open-telemetry/opentelemetry-specification).
+The `opentelemetry-sdk` package is the reference implementation of the API.
+
+Libraries that produce telemetry data should only depend on `opentelemetry-api`,
+and defer the choice of the SDK to the application developer. Applications may
+depend on `opentelemetry-sdk` or another package that implements the API. 
+
+To install the API and SDK packages, fork or clone this repo and do an
+[editable
+install](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs)
+via `pip`:
+
+```sh
+pip install -e ./opentelemetry-api
+pip install -e ./opentelemetry-sdk
+```
+
+The
+[`ext/`](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext)
+directory includes OpenTelemetry integration packages, which can be installed
+separately as:
+
+```sh
+pip install -e ./ext/opentelemetry-ext-{integration}
+```
+
+## Quick Start
+
 ```python
 from opentelemetry import trace
 from opentelemetry.context import Context
@@ -28,4 +58,24 @@ with tracer.start_span('foo'):
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md)
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Release Schedule
+
+OpenTelemetry Python is under active development. Our goal is to release an
+_alpha_ version of the library at the end of September 2019. This release isn't
+guaranteed to conform to a specific version of the specification, and future
+releases will not attempt to maintain backwards compatibility with the alpha
+release.
+
+| Component                   | Version | Target Date       |
+| --------------------------- | ------- | ----------------- |
+| Tracing API                 | Alpha   | September 30 2019 |
+| Tracing SDK                 | Alpha   | September 30 2019 |
+| Metrics API                 | Alpha   | September 30 2019 |
+| Metrics SDK                 | Alpha   | September 30 2019 |
+| Jaeger Trace Exporter       | Alpha   | Unknown           |
+| Prometheus Metrics Exporter | Alpha   | Unknown           |
+| Context Propagation         | Alpha   | September 30 2019 |
+| OpenTracing Bridge          | Alpha   | Unknown           |
+| OpenCensus Bridge           | Alpha   | Unknown           |
