Skip to content

docs(readme): Updated readme so it does not look abandoned anymore. #1319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
antonpirker merged 6 commits into from
Feb 3, 2022
Merged

docs(readme): Updated readme so it does not look abandoned anymore. #1319

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e8f97f4
docs(readme): Updated readme so it does not look abandoned anymore.
antonpirker Jan 25, 2022
af680d1
Merge branch 'master' into antonpirker/update_readme
antonpirker Feb 2, 2022
20b0455
Updated contribution guide
antonpirker Feb 2, 2022
8aee47a
made links relative
antonpirker Feb 2, 2022
98fe4e0
Made more links relative
antonpirker Feb 2, 2022
cc2b3c1
grammar
antonpirker Feb 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 115 additions & 36 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,109 @@
# How to contribute to the Sentry Python SDK
# Contributing to Sentry SDK for Python

`sentry-sdk` is an ordinary Python package. You can install it with `pip
install -e .` into some virtualenv, edit the sourcecode and test out your
changes manually.
We welcome contributions to python-sentry by the community. See the [Contributing to Docs](https://docs.sentry.io/contributing/) page if you want to fix or update the documentation on the website.

## Community
## How to report a problem

The public-facing channels for support and development of Sentry SDKs can be found on [Discord](https://discord.gg/Ww9hbqr).
Please search the [issue tracker](https://github.com/getsentry/sentry-python/issues) before creating a new issue (a problem or an improvement request). Please also ask in our [Sentry Community on Discord](https://discord.com/invite/Ww9hbqr) before submitting a new issue. There is a ton of great people in our Discord community ready to help you!

## Running tests and linters
If you feel that you can fix or implement it yourself, please read a few paragraphs below to learn how to submit your changes.

Make sure you have `virtualenv` installed, and the Python versions you care
about. You should have Python 2.7 and the latest Python 3 installed.
## Submitting changes

We have a `Makefile` that is supposed to help people get started with hacking
on the SDK without having to know or understand the Python ecosystem. You don't
need to `workon` or `bin/activate` anything, the `Makefile` will do everything
for you. Run `make` or `make help` to list commands.
- Setup the development environment.
- Clone sentry-python and prepare necessary changes.
- Add tests for your changes to `tests/`.
- Run tests and make sure all of them pass.
- Submit a pull request, referencing any issues it addresses.

We will review your pull request as soon as possible.
Thank you for contributing!

## Development environment

### Clone the repo:

```bash
git clone git@github.com:getsentry/sentry-python.git
```

Make sure that you have Python 3 installed. Version 3.7 or higher is required to run style checkers on pre-commit. On macOS, we recommend using brew to install Python. For Windows, we recommend an official python.org release.

### Create a virtual environment:

```bash
cd sentry-python

python -m venv .env

source .env/bin/activate

pip install -e .
```

**Hint:** Sometimes you need a sample project to run your new changes to sentry-python. In this case install the sample project in the same virtualenv and you should be good to go because the ` pip install -e .` from above installed your local sentry-python in editable mode. So you can just hack away!

### Install coding style pre-commit hooks:

```bash
cd sentry-python

pip install -r linter-requirements.txt

pip install pre-commit

pre-commit install
```

That's it. You should be ready to make changes, run tests, and make commits! If you experience any problems, please don't hesitate to ping us in our [Discord Community](https://discord.com/invite/Ww9hbqr).

## Running tests

We have a `Makefile` to help people get started with hacking on the SDK
without having to know or understand the Python ecosystem.
Run `make` or `make help` to list commands.

So the simplest way to run tests is:

```bash
cd sentry-python

make tests
```

This will use [Tox](https://tox.wiki/en/latest/) to run our whole test suite
under Python 2.7 and Python 3.7.

Of course you can always run the underlying commands yourself, which is
particularly useful when wanting to provide arguments to `pytest` to run
specific tests. If you want to do that, we expect you to know your way around
Python development. To get started, clone the SDK repository, cd into it, set
up a virtualenv and run:
specific tests:

```bash
cd sentry-python

# This is "advanced mode". Use `make help` if you have no clue what's
# happening here!
# create virtual environment
python -m venv .env

pip install -e .
pip install -r test-requirements.txt
# activate virtual environment
source .env/bin/activate

pytest tests/
# install sentry-python
pip install -e .

# install requirements
pip install -r test-requirements.txt

# run tests
pytest tests/
```

If you want to run the tests for a specific integration you should do so by doing this:

```bash
pytest -rs tests/integrations/flask/
```

**Hint:** Tests of integrations need additional dependencies. The switch `-rs` will show you why tests where skipped and what dependencies you need to install for the tests to run. (You can also consult the [tox.ini](tox.ini) file to see what dependencies are installed for each integration)

## Releasing a new version

Expand All @@ -48,42 +121,48 @@ The usual release process goes like this:

1. Write the integration.

* Instrument all application instances by default. Prefer global signals/patches instead of configuring a specific instance. Don't make the user pass anything to your integration for anything to work. Aim for zero configuration.
- Instrument all application instances by default. Prefer global signals/patches instead of configuring a specific instance. Don't make the user pass anything to your integration for anything to work. Aim for zero configuration.

* Everybody monkeypatches. That means:
- Everybody monkeypatches. That means:

* Make sure to think about conflicts with other monkeypatches when monkeypatching.
- Make sure to think about conflicts with other monkeypatches when monkeypatching.

* You don't need to feel bad about it.
- You don't need to feel bad about it.

* Avoid modifying the hub, registering a new client or the like. The user drives the client, and the client owns integrations.
- Avoid modifying the hub, registering a new client or the like. The user drives the client, and the client owns integrations.

* Allow the user to disable the integration by changing the client. Check `Hub.current.get_integration(MyIntegration)` from within your signal handlers to see if your integration is still active before you do anything impactful (such as sending an event).
- Allow the user to disable the integration by changing the client. Check `Hub.current.get_integration(MyIntegration)` from within your signal handlers to see if your integration is still active before you do anything impactful (such as sending an event).

2. Write tests.

* Think about the minimum versions supported, and test each version in a separate env in `tox.ini`.
- Think about the minimum versions supported, and test each version in a separate env in `tox.ini`.

* Create a new folder in `tests/integrations/`, with an `__init__` file that skips the entire suite if the package is not installed.
- Create a new folder in `tests/integrations/`, with an `__init__` file that skips the entire suite if the package is not installed.

3. Update package metadata.

* We use `extras_require` in `setup.py` to communicate minimum version requirements for integrations. People can use this in combination with tools like Poetry or Pipenv to detect conflicts between our supported versions and their used versions programmatically.
- We use `extras_require` in `setup.py` to communicate minimum version requirements for integrations. People can use this in combination with tools like Poetry or Pipenv to detect conflicts between our supported versions and their used versions programmatically.

Do not set upper-bounds on version requirements as people are often faster in adopting new versions of a web framework than we are in adding them to the test matrix or our package metadata.
Do not set upper-bounds on version requirements as people are often faster in adopting new versions of a web framework than we are in adding them to the test matrix or our package metadata.

4. Write the [docs](https://github.com/getsentry/sentry-docs). Answer the following questions:

* What does your integration do? Split in two sections: Executive summary at top and exact behavior further down.
- What does your integration do? Split in two sections: Executive summary at top and exact behavior further down.

* Which version of the SDK supports which versions of the modules it hooks into?
- Which version of the SDK supports which versions of the modules it hooks into?

* One code example with basic setup.
- One code example with basic setup.

* Make sure to add integration page to `python/index.md` (people forget to do that all the time).
- Make sure to add integration page to `python/index.md` (people forget to do that all the time).

Tip: Put most relevant parts wrapped in `<!--WIZARD-->..<!--ENDWIZARD-->` tags for usage from within the Sentry UI.
Tip: Put most relevant parts wrapped in `<!--WIZARD-->..<!--ENDWIZARD-->` tags for usage from within the Sentry UI.

5. Merge docs after new version has been released (auto-deploys on merge).

6. (optional) Update data in [`sdk_updates.py`](https://github.com/getsentry/sentry/blob/master/src/sentry/sdk_updates.py) to give users in-app suggestions to use your integration. May not be applicable or doable for all kinds of integrations.

## Commit message format guidelines

See the documentation on commit messages here:

https://develop.sentry.dev/commit-messages/#commit-message-format
88 changes: 77 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,32 +6,98 @@

_Bad software is everywhere, and we're tired of it. Sentry is on a mission to help developers write better software faster, so we can get back to enjoying technology. If you want to join us [<kbd>**Check out our open positions**</kbd>](https://sentry.io/careers/)_

# sentry-python - Sentry SDK for Python
# Official Sentry SDK for Python

[![Build Status](https://travis-ci.com/getsentry/sentry-python.svg?branch=master)](https://travis-ci.com/getsentry/sentry-python)
[![PyPi page link -- version](https://img.shields.io/pypi/v/sentry-sdk.svg)](https://pypi.python.org/pypi/sentry-sdk)
[![Discord](https://img.shields.io/discord/621778831602221064)](https://discord.gg/cWnMQeA)

This is the next line of the Python SDK for [Sentry](http://sentry.io/), intended to replace the `raven` package on PyPI.
This is the official Python SDK for [Sentry](http://sentry.io/)

---

## Migrate From sentry-raven

The old `raven-python` client has entered maintenance mode and was moved [here](https://github.com/getsentry/raven-python).

If you're using `raven-python`, we recommend you to migrate to this new SDK. You can find the benefits of migrating and how to do it in our [migration guide](https://docs.sentry.io/platforms/python/migration/).

## Getting Started

### Install

```bash
pip install --upgrade sentry-sdk
```

### Configuration

```python
from sentry_sdk import init, capture_message
import sentry_sdk

init("https://mydsn@sentry.io/123")
sentry_sdk.init(
"https://12927b5f211046b575ee51fd8b1ac34f@o1.ingest.sentry.io/1",

capture_message("Hello World") # Will create an event.
# Set traces_sample_rate to 1.0 to capture 100%
# of transactions for performance monitoring.
# We recommend adjusting this value in production.
traces_sample_rate=1.0,
)
```

raise ValueError() # Will also create an event.
### Usage

```python
from sentry_sdk import capture_message
capture_message("Hello World") # Will create an event in Sentry.

raise ValueError() # Will also create an event in Sentry.
```

- To learn more about how to use the SDK [refer to our docs](https://docs.sentry.io/platforms/python/)
- Are you coming from raven-python? [Use this cheatsheet](https://docs.sentry.io/platforms/python/migration/)
- Are you coming from raven-python? [Use this migration guide](https://docs.sentry.io/platforms/python/migration/)
- To learn about internals use the [API Reference](https://getsentry.github.io/sentry-python/)

# Contributing to the SDK
## Integrations

- [Django](https://docs.sentry.io/platforms/python/guides/django/)
- [Flask](https://docs.sentry.io/platforms/python/guides/flask/)
- [Bottle](https://docs.sentry.io/platforms/python/guides/bottle/)
- [AWS Lambda](https://docs.sentry.io/platforms/python/guides/aws-lambda/)
- [Google Cloud Functions](https://docs.sentry.io/platforms/python/guides/gcp-functions/)
- [WSGI](https://docs.sentry.io/platforms/python/guides/wsgi/)
- [ASGI](https://docs.sentry.io/platforms/python/guides/asgi/)
- [AIOHTTP](https://docs.sentry.io/platforms/python/guides/aiohttp/)
- [RQ (Redis Queue)](https://docs.sentry.io/platforms/python/guides/rq/)
- [Celery](https://docs.sentry.io/platforms/python/guides/celery/)
- [Chalice](https://docs.sentry.io/platforms/python/guides/chalice/)
- [Falcon](https://docs.sentry.io/platforms/python/guides/falcon/)
- [Quart](https://docs.sentry.io/platforms/python/guides/quart/)
- [Sanic](https://docs.sentry.io/platforms/python/guides/sanic/)
- [Tornado](https://docs.sentry.io/platforms/python/guides/tornado/)
- [Tryton](https://docs.sentry.io/platforms/python/guides/tryton/)
- [Pyramid](https://docs.sentry.io/platforms/python/guides/pyramid/)
- [Logging](https://docs.sentry.io/platforms/python/guides/logging/)
- [Apache Airflow](https://docs.sentry.io/platforms/python/guides/airflow/)
- [Apache Beam](https://docs.sentry.io/platforms/python/guides/beam/)
- [Apache Spark](https://docs.sentry.io/platforms/python/guides/pyspark/)

## Contributing to the SDK

Please refer to [CONTRIBUTING.md](CONTRIBUTING.md).

## Getting help/support

If you need help setting up or configuring the Python SDK (or anything else in the Sentry universe) please head over to the [Sentry Community on Discord](https://discord.com/invite/Ww9hbqr). There is a ton of great people in our Discord community ready to help you!

## Resources

Please refer to [CONTRIBUTING.md](https://github.com/getsentry/sentry-python/blob/master/CONTRIBUTING.md).
- [![Documentation](https://img.shields.io/badge/documentation-sentry.io-green.svg)](https://docs.sentry.io/quickstart/)
- [![Forum](https://img.shields.io/badge/forum-sentry-green.svg)](https://forum.sentry.io/c/sdks)
- [![Discord](https://img.shields.io/discord/621778831602221064)](https://discord.gg/Ww9hbqr)
- [![Stack Overflow](https://img.shields.io/badge/stack%20overflow-sentry-green.svg)](http://stackoverflow.com/questions/tagged/sentry)
- [![Twitter Follow](https://img.shields.io/twitter/follow/getsentry?label=getsentry&style=social)](https://twitter.com/intent/follow?screen_name=getsentry)

# License
## License

Licensed under the BSD license, see [`LICENSE`](https://github.com/getsentry/sentry-python/blob/master/LICENSE)
Licensed under the BSD license, see [`LICENSE`](LICENSE)