diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..d4c8debec --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,168 @@ +# Contributing to opentelemetry-python-contrib + +The Python special interest group (SIG) meets regularly. See the OpenTelemetry +[community](https://github.com/open-telemetry/community#python-sdk) repo for +information on this and other language SIGs. + +See the [public meeting notes](https://docs.google.com/document/d/1CIMGoIOZ-c3-igzbd6_Pnxx1SjAkjwqoYSUWxPY8XIs/edit) +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). + +See to the [community membership document](https://github.com/open-telemetry/community/blob/master/community-membership.md) +on how to become a [**Member**](https://github.com/open-telemetry/community/blob/master/community-membership.md#member), +[**Approver**](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver) +and [**Maintainer**](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer). + +## Find a Buddy and get Started Quickly! + +If you are looking for someone to help you find a starting point and be a resource for your first contribution, join our +Gitter and find a buddy! + +1. Join [Gitter.im](https://gitter.im) and join our [chat room](https://gitter.im/open-telemetry/opentelemetry-python). +2. Post in the room with an introduction to yourself, what area you are interested in (check issues marked "Help Wanted"), +and say you are looking for a buddy. We will match you with someone who has experience in that area. + +Your OpenTelemetry buddy is your resource to talk to directly on all aspects of contributing to OpenTelemetry: providing +context, reviewing PRs, and helping those get merged. Buddies will not be available 24/7, but is committed to responding during their normal contribution hours. + +## Development + +To quickly get up and running, you can use the `scripts/eachdist.py` tool that +ships with this project. First create a virtualenv and activate it. +Then run `python scripts/eachdist.py develop` to install all required packages +as well as the project's packages themselves (in `--editable` mode). +You can then run `scripts/eachdist.py test` to test everything or +`scripts/eachdist.py lint` to lint everything (fixing anything that is auto-fixable). + +Additionally, 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 py37-test-flask` to e.g. run the Flask 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 + +Everyone is welcome to contribute code to `opentelemetry-python-contrib` via GitHub +pull requests (PRs). + +To create a new PR, fork the project in GitHub and clone the upstream repo: + +```sh +$ git clone https://github.com/open-telemetry/opentelemetry-python-contrib.git +``` + +Add your fork as an origin: + +```sh +$ git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-python-contrib.git +``` + +Run tests: + +```sh +# make sure you have all supported versions of Python installed +$ pip install tox # only first time. +$ tox # execute in the root of the repository +``` + +Check out a new branch, make modifications and push the branch to your fork: + +```sh +$ git checkout -b feature +# edit files +$ git commit +$ git push fork feature +``` + +Open a pull request against the main `opentelemetry-python-contrib` repo. + +### How to Receive Comments + +* If the PR is not ready for review, please put `[WIP]` in the title, tag it + 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 PRs Merged + +A PR is considered to be **ready to merge** when: +* It has received two approvals from [Approvers](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver) + / [Maintainers](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer) + (at different companies). +* Major feedbacks are resolved. +* It has been open for review for at least one working day. This gives people + reasonable time to review. +* Trivial change (typo, cosmetic, doc, etc.) doesn't have to wait for one day. +* Urgent fix can take exception as long as it has been actively communicated. + +Any Approver / Maintainer can merge the PR once it is **ready to merge**. + +## Design Choices + +As with other OpenTelemetry clients, opentelemetry-python follows the +[opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification). + +It's especially valuable to read through the [library guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/library-guidelines.md). + +### Focus on Capabilities, Not Structure Compliance + +OpenTelemetry is an evolving specification, one where the desires and +use cases are clear, but the method to satisfy those uses cases are not. + +As such, contributions should provide functionality and behavior that +conforms to the specification, but the interface and structure is flexible. + +It is preferable to have contributions follow the idioms of the language +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 + +## Style Guide + +* 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). + +## Porting reference/ddtrace/contrib to instrumentation + +The steps below describe suggested steps to port integrations from the reference directory containing the originally donated code to OpenTelemetry. + +1. Move the code into the instrumentation directory + +``` +mkdir -p instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2 +git mv reference/ddtrace/contrib/jinja2 instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2 +``` + +2. Move the tests + +``` +git mv reference/tests/contrib/jinja2 instrumentation/opentelemetry-instrumentation-jinja2/tests +``` + +3. Add `README.rst`, `setup.cfg` and `setup.py` files and update them accordingly + +```bash +cp _template/* instrumentation/opentelemetry-instrumentation-jinja2/ +``` + +4. Add `version.py` file and update it accordingly + +```bash +mv instrumentation/opentelemetry-instrumentation-jinja2/version.py instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2/version.py +``` + +5. Fix relative import paths to using ddtrace package instead of using relative paths +6. Update the code and tests to use the OpenTelemetry API \ No newline at end of file diff --git a/README.md b/README.md index 5f3f669bc..97b06537b 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,56 @@ -# opentelemetry-auto-instr-python -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 [donated by DataDog](https://www.datadoghq.com/blog/opentelemetry-instrumentation/) in the `reference` folder. All instrumentation that has been ported lives in the `instrumentation` directory. +# opentelemetry-python-contrib +[![Gitter chat](https://img.shields.io/gitter/room/opentelemetry/opentelemetry-python)](https://gitter.im/open-telemetry/opentelemetry-python)[![Build status](https://travis-ci.org/open-telemetry/opentelemetry-python-contrib.svg?branch=master)](https://travis-ci.org/open-telemetry/opentelemetry-python-contrib) -# porting ddtrace/contrib to instrumentation +The Python auto-instrumentation libraries for [OpenTelemetry](https://opentelemetry.io/) (per [OTEP 0001](https://github.com/open-telemetry/oteps/blob/master/text/0001-telemetry-without-manual-instrumentation.md)) -The steps below describe the process to port integrations from the reference directory containing the originally donated code to OpenTelemetry. +### Installation -1. Move the code into the instrumentation directory +This repository includes installable packages for each instrumented library. 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. -``` -mkdir -p instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2 -git mv reference/ddtrace/contrib/jinja2 instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2 +**Please note** that these libraries are currently in _beta_, and shouldn't +generally be used in production environments. + +The +[`instrumentation/`](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/master/instrumentation) +directory includes OpenTelemetry instrumentation packages, which can be installed +separately as: + +```sh +pip install opentelemetry-instrumentation-{integration} ``` -2. Move the tests +To install the development versions of these packages instead, clone or fork +this repo and do an [editable +install](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs): -``` -git mv reference/tests/contrib/jinja2 instrumentation/opentelemetry-instrumentation-jinja2/tests +```sh +pip install -e ./ext/opentelemetry-ext-{integration} ``` -3. Add `README.rst`, `setup.cfg` and `setup.py` files and update them accordingly +## Contributing -```bash -cp _template/* instrumentation/opentelemetry-instrumentation-jinja2/ -``` +See [CONTRIBUTING.md](CONTRIBUTING.md) -4. Add `version.py` file and update it accordingly +We meet weekly on Thursday, and the time of the meeting alternates between 9AM PT and 4PM PT. The meeting is subject to change depending on contributors' availability. Check the [OpenTelemetry community calendar](https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com) for specific dates. -```bash -mv instrumentation/opentelemetry-instrumentation-jinja2/version.py instrumentation/opentelemetry-instrumentation-jinja2/src/opentelemetry/instrumentation/jinja2/version.py -``` +Meetings take place via [Zoom video conference](https://zoom.us/j/6729396170). + +Meeting notes are available as a public [Google doc](https://docs.google.com/document/d/1CIMGoIOZ-c3-igzbd6_Pnxx1SjAkjwqoYSUWxPY8XIs/edit). For edit access, get in touch on [Gitter](https://gitter.im/open-telemetry/opentelemetry-python). + +Approvers ([@open-telemetry/python-approvers](https://github.com/orgs/open-telemetry/teams/opentelemetry-python-contrib-approvers)): + +- [Chris Kleinknecht](https://github.com/c24t), Google +- [Hector Hernandez](https://github.com/hectorhdzg), Microsoft +- [Reiley Yang](https://github.com/reyang), Microsoft + +*Find more about the approver role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver).* + +Maintainers ([@open-telemetry/python-maintainers](https://github.com/orgs/open-telemetry/teams/opentelemetry-python-contrib-maintainers)): + +- [Alex Boten](https://github.com/codeboten), Lightstep +- [Carlos Alberto Cortez](https://github.com/carlosalberto), Lightstep + +*Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer).* -5. Fix relative import paths to using ddtrace package instead of using relative paths -6. Update the code and tests to use the OpenTelemetry API