adding instructions to port instrumentation

README.md

@@ -1,2 +1,40 @@
 # opentelemetry-auto-instr-python
-Auto-Instrumentation for Python (per OTEP 0001)
+The auto-instrumentation for Python (per [OTEP 0001](https://github.com/open-telemetry/oteps/blob/master/text/0001-telemetry-without-manual-instrumentation.md)) instruments each library in a separately installable package to ensure users only need to install the libraries that make sense for their use-case. This repository contains the code initially [donate by DataDog](https://www.datadoghq.com/blog/opentelemetry-instrumentation/) in the `reference` folder. All instrumentation that has been ported lives in the `instrumentors` directory.
+
+# porting ddtrace/contrib to instrumentors
+
+The steps below describe the process to port integrations from the reference directory containing the originally donated code to OpenTelemetry.
+
+1. Move the code into the instrumentors directory
+
+```
+git mv reference/ddtrace/contrib/jinja2 instrumentors/
+```
+
+2. Move the tests
+
+```
+git mv reference/tests/contrib/jinja2 instrumentors/jinja2/tests
+```
+
+3. Make the package installable: move source code to package path
+
+```bash
+mkdir -p instrumentors/jinja2/src/opentelemetry/ext/jinja2
+git mv instrumentors/jinja2/*.py instrumentors/jinja2/src/opentelemetry/ext/jinja2
+```
+
+4. Add `README.rst`, `setup.cfg` and `setup.py` files and update them accordingly
+
+```bash
+cp _template/* instrumentors/jinja2/
+```
+
+5. Add `version.py` file and update it accordingly
+
+```bash
+mv instrumentors/jinja2/version.py instrumentors/jinja2/src/opentelemetry/ext/jinja2/version.py
+```
+
+6. Fix relative import paths to using ddtrace package instead of using relative paths
+7. Update the code and tests to use the OpenTelemetry API

_template/README.rst

@@ -0,0 +1,23 @@
+OpenTelemetry <REPLACE ME> Tracing
+===========================
+
+|pypi|
+
+.. |pypi| image:: https://badge.fury.io/py/opentelemetry-ext-<REPLACE ME>.svg
+   :target: https://pypi.org/project/opentelemetry-ext-<REPLACE ME>/
+
+This library allows tracing requests made by the <REPLACE ME> library.
+
+Installation
+------------
+
+::
+
+    pip install opentelemetry-ext-<REPLACE ME>
+
+
+References
+----------
+
+* `OpenTelemetry SQLAlchemy Tracing <https://opentelemetry-python.readthedocs.io/en/latest/ext/<REPLACE ME>/<REPLACE ME>.html>`_
+* `OpenTelemetry Project <https://opentelemetry.io/>`_

_template/setup.cfg

@@ -0,0 +1,60 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+[metadata]
+# opentelemetry-ext plus the name of the library being instrument e.g
+# name = opentelemetry-ext-sqlalchemy
+name = "<REPLACE ME>"
+# a description of the instrumentation e.g
+# description = SQLAlchemy tracing for OpenTelemetry
+description = "<REPLACE ME>"
+long_description = file: README.rst
+long_description_content_type = text/x-rst
+author = OpenTelemetry Authors
+author_email = cncf-opentelemetry-contributors@lists.cncf.io
+# url of the instrumentation e.g
+# url = https://github.com/open-telemetry/opentelemetry-python-contrib/instrumentors/sqlalchemy
+url = "<REPLACE ME>"
+platforms = any
+license = Apache-2.0
+classifiers =
+    Development Status :: 4 - Beta
+    Intended Audience :: Developers
+    License :: OSI Approved :: Apache Software License
+    Programming Language :: Python
+    Programming Language :: Python :: 3
+    Programming Language :: Python :: 3.4
+    Programming Language :: Python :: 3.5
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+
+[options]
+python_requires = >=3.4
+package_dir=
+    =src
+packages=find_namespace:
+
+install_requires =
+    # add any package dependencies here
+    "<REPLACE ME>"
+
+[options.extras_require]
+test =
+    # add any test dependencies here
+    "<REPLACE ME>"
+
+[options.packages.find]
+where = src
+

_template/setup.py

@@ -0,0 +1,42 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+
+import setuptools
+
+BASE_DIR = os.path.dirname(__file__)
+VERSION_FILENAME = os.path.join(
+    # REPLACE ME: the path to the version file e.g
+    # BASE_DIR, "src", "opentelemetry", "ext", "sqlalchemy", "version.py"
+    BASE_DIR,
+    "src",
+    "opentelemetry",
+    "ext",
+    "<REPLACE ME>",
+    "version.py",
+)
+PACKAGE_INFO = {}
+with open(VERSION_FILENAME) as f:
+    exec(f.read(), PACKAGE_INFO)
+
+setuptools.setup(
+    version=PACKAGE_INFO["__version__"],
+    entry_points={
+        "opentelemetry_instrumentor": [
+            # REPLACE ME: the entrypoint for the instrumentor e.g
+            # "sqlalchemy = opentelemetry.ext.sqlalchemy:SQLAlchemyInstrumentor"
+            "<REPLACE ME> = opentelemetry.ext.<REPLACE>"
+        ]
+    },
+)

_template/version.py

@@ -0,0 +1,15 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+__version__ = "<REPLACE ME>"