Skip to content

Commit 59a67d3

Browse files
sentrivanacleptricszokeasaurusrex
authored
Update CONTRIBUTING.md (#2411)
 --------- Co-authored-by: Michi Hoffmann <[email protected]> Co-authored-by: Daniel Szoke <[email protected]>
1 parent 963e0d5 commit 59a67d3

File tree

1 file changed

+79
-83
lines changed

1 file changed

+79
-83
lines changed

‎CONTRIBUTING.md

+79-83
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,63 @@
11
# Contributing to Sentry SDK for Python
22

3-
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.
3+
We welcome contributions to `sentry-python` by the community.
44

5-
## How to report a problem
5+
This file outlines the process to contribute to the SDK itself. For contributing to the documentation, please see the [Contributing to Docs](https://docs.sentry.io/contributing/) page.
66

7-
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!
7+
## How to Report a Problem
88

9-
If you feel that you can fix or implement it yourself, please read a few paragraphs below to learn how to submit your changes.
9+
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 are a ton of great people in our Discord community ready to help you!
1010

11-
## Submitting changes
1211

13-
- Setup the development environment.
14-
- Clone sentry-python and prepare necessary changes.
12+
## Submitting Changes
13+
14+
- Fork the `sentry-python` repo and prepare your changes.
1515
- Add tests for your changes to `tests/`.
1616
- Run tests and make sure all of them pass.
17-
- Submit a pull request, referencing any issues it addresses.
17+
- Submit a pull request, referencing any issues your changes address. Please follow our [commit message format](https://develop.sentry.dev/commit-messages/#commit-message-format) when naming your pull request.
1818

19-
We will review your pull request as soon as possible.
20-
Thank you for contributing!
19+
We will review your pull request as soon as possible. Thank you for contributing!
2120

22-
## Development environment
21+
## Development Environment
2322

24-
### Clone the repo:
23+
### Set up Python
2524

26-
```bash
27-
git clone [email protected]:getsentry/sentry-python.git
28-
```
25+
Make sure that you have Python 3 installed. Version 3.7 or higher is required to run style checkers on pre-commit.
26+
27+
On macOS, we recommend using `brew` to install Python. For Windows, we recommend an official [python.org](https://www.python.org/downloads/) release.
28+
29+
### Fork and Clone the Repo
2930

30-
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.
31+
Before you can contribute, you will need to [fork the `sentry-python` repository](https://github.com/getsentry/sentry-python/fork). Then, clone the forked repository to your local development environment.
3132

32-
### Create a virtual environment:
33+
### Create a Virtual Environment
34+
35+
To keep your Python development environment and packages separate from the ones
36+
used by your operation system, create a virtual environment:
3337

3438
```bash
3539
cd sentry-python
3640

3741
python -m venv .venv
42+
```
3843

44+
Then, activate your virtual environment with the following command. You will need to repeat this step every time you wish to work on your changes for `sentry-python`.
45+
46+
```bash
3947
source .venv/bin/activate
4048
```
4149

42-
### Install `sentry-python` in editable mode
50+
### Install `sentry-python` in Editable Mode
51+
52+
Install `sentry-python` in [editable mode](https://pip.pypa.io/en/latest/topics/local-project-installs/#editable-installs). This will make any changes you make to the SDK code locally immediately effective without you having to reinstall or copy anything.
4353

4454
```bash
4555
pip install -e .
4656
```
4757

48-
**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.
58+
**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.
4959

50-
### Install coding style pre-commit hooks:
60+
### Install Coding Style Pre-commit Hooks
5161

5262
This will make sure that your commits will have the correct coding style.
5363

@@ -63,7 +73,7 @@ pre-commit install
6373

6474
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).
6575

66-
## Running tests
76+
## Running Tests
6777

6878
To run the tests, first setup your development environment according to the instructions above. Then, install the required packages for running tests with the following command:
6979
```bash
@@ -81,103 +91,89 @@ If you would like to run the tests for a specific integration, use a command sim
8191
pytest -rs tests/integrations/flask/ # Replace "flask" with the specific integration you wish to test
8292
```
8393

84-
**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)
85-
86-
## Releasing a new version
87-
88-
(only relevant for Sentry employees)
89-
90-
Prerequisites:
91-
92-
- All the changes that should be release must be in `master` branch.
93-
- Every commit should follow the [Commit Message Format](https://develop.sentry.dev/commit-messages/#commit-message-format) convention.
94-
- CHANGELOG.md is updated automatically. No human intervention necessary.
95-
96-
Manual Process:
97-
98-
- On GitHub in the `sentry-python` repository go to "Actions" select the "Release" workflow.
99-
- Click on "Run workflow" on the right side, make sure the `master` branch is selected.
100-
- Set "Version to release" input field. Here you decide if it is a major, minor or patch release. (See "Versioning Policy" below)
101-
- Click "Run Workflow"
94+
**Hint:** Tests of integrations need additional dependencies. The switch `-rs` will show you why tests were 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)
10295

103-
This will trigger [Craft](https://github.com/getsentry/craft) to prepare everything needed for a release. (For more information see [craft prepare](https://github.com/getsentry/craft#craft-prepare-preparing-a-new-release)) At the end of this process a release issue is created in the [Publish](https://github.com/getsentry/publish) repository. (Example release issue: https://github.com/getsentry/publish/issues/815)
96+
## Adding a New Integration
10497

105-
Now one of the persons with release privileges (most probably your engineering manager) will review this Issue and then add the `accepted` label to the issue.
98+
1. Write the integration.
10699

107-
There are always two persons involved in a release.
100+
- 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.
108101

109-
If you are in a hurry and the release should be out immediatly there is a Slack channel called `#proj-release-approval` where you can see your release issue and where you can ping people to please have a look immediatly.
102+
- Everybody monkeypatches. That means:
110103

111-
When the release issue is labeled `accepted` [Craft](https://github.com/getsentry/craft) is triggered again to publish the release to all the right platforms. (See [craft publish](https://github.com/getsentry/craft#craft-publish-publishing-the-release) for more information). At the end of this process the release issue on GitHub will be closed and the release is completed! Congratulations!
104+
- Make sure to think about conflicts with other monkeypatches when monkeypatching.
112105

113-
There is a sequence diagram visualizing all this in the [README.md](https://github.com/getsentry/publish) of the `Publish` repository.
106+
- You don't need to feel bad about it.
114107

115-
### Versioning Policy
108+
- Make sure your changes don't break end user contracts. The SDK should never alter the expected behavior of the underlying library or framework from the user's perspective and it shouldn't have any side effects.
116109

117-
This project follows [semver](https://semver.org/), with three additions:
118-
119-
- Semver says that major version `0` can include breaking changes at any time. Still, it is common practice to assume that only `0.x` releases (minor versions) can contain breaking changes while `0.x.y` releases (patch versions) are used for backwards-compatible changes (bugfixes and features). This project also follows that practice.
110+
- Avoid modifying the hub, registering a new client or the like. The user drives the client, and the client owns integrations.
120111

121-
- All undocumented APIs are considered internal. They are not part of this contract.
112+
- Allow the user to turn off 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).
122113

123-
- Certain features (e.g. integrations) may be explicitly called out as "experimental" or "unstable" in the documentation. They come with their own versioning policy described in the documentation.
114+
2. Write tests.
124115

125-
We recommend to pin your version requirements against `1.x.*` or `1.x.y`.
126-
Either one of the following is fine:
116+
- Consider the minimum versions supported, and test each version in a separate env in `tox.ini`.
127117

128-
```
129-
sentry-sdk>=1.0.0,<2.0.0
130-
sentry-sdk==1.5.0
131-
```
118+
- Create a new folder in `tests/integrations/`, with an `__init__` file that skips the entire suite if the package is not installed.
132119

133-
A major release `N` implies the previous release `N-1` will no longer receive updates. We generally do not backport bugfixes to older versions unless they are security relevant. However, feel free to ask for backports of specific commits on the bugtracker.
120+
3. Update package metadata.
134121

135-
## Adding a new integration (checklist)
122+
- 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.
136123

137-
1. Write the integration.
124+
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.
138125

139-
- 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.
126+
4. Write the [docs](https://github.com/getsentry/sentry-docs). Follow the structure of [existing integration docs](https://docs.sentry.io/platforms/python/integrations/). And, please **make sure to add your integration to the table in `python/integrations/index.md`** (people often forget this step 🙂).
140127

141-
- Everybody monkeypatches. That means:
128+
5. Merge docs after new version has been released. The docs are built and deployed after each merge, so your changes should go live in a few minutes.
142129

143-
- Make sure to think about conflicts with other monkeypatches when monkeypatching.
130+
6. (optional, if possible) 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. This step will only apply to some integrations.
144131

145-
- You don't need to feel bad about it.
132+
## Releasing a New Version
146133

147-
- Avoid modifying the hub, registering a new client or the like. The user drives the client, and the client owns integrations.
134+
_(only relevant for Sentry employees)_
148135

149-
- 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).
136+
### Prerequisites
150137

151-
2. Write tests.
138+
- All the changes that should be released must be on the `master` branch.
139+
- Every commit should follow the [Commit Message Format](https://develop.sentry.dev/commit-messages/#commit-message-format) convention.
140+
- CHANGELOG.md is updated automatically. No human intervention is necessary, but you might want to consider polishing the changelog by hand to make it more user friendly by grouping related things together, adding small code snippets and links to docs, etc.
152141

153-
- Think about the minimum versions supported, and test each version in a separate env in `tox.ini`.
142+
### Manual Process
154143

155-
- Create a new folder in `tests/integrations/`, with an `__init__` file that skips the entire suite if the package is not installed.
144+
- On GitHub in the `sentry-python` repository, go to "Actions" and select the "Release" workflow.
145+
- Click on "Run workflow" on the right side, and make sure the `master` branch is selected.
146+
- Set the "Version to release" input field. Here you decide if it is a major, minor or patch release. (See "Versioning Policy" below)
147+
- Click "Run Workflow".
156148

157-
3. Update package metadata.
149+
This will trigger [Craft](https://github.com/getsentry/craft) to prepare everything needed for a release. (For more information, see [craft prepare](https://github.com/getsentry/craft#craft-prepare-preparing-a-new-release).) At the end of this process a release issue is created in the [Publish](https://github.com/getsentry/publish) repository. (Example release issue: https://github.com/getsentry/publish/issues/815)
158150

159-
- 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.
151+
Now one of the persons with release privileges (most probably your engineering manager) will review this issue and then add the `accepted` label to the issue.
160152

161-
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.
153+
There are always two persons involved in a release.
162154

163-
4. Write the [docs](https://github.com/getsentry/sentry-docs). Answer the following questions:
155+
If you are in a hurry and the release should be out immediately, there is a Slack channel called `#proj-release-approval` where you can see your release issue and where you can ping people to please have a look immediately.
164156

165-
- What does your integration do? Split in two sections: Executive summary at top and exact behavior further down.
157+
When the release issue is labeled `accepted`, [Craft](https://github.com/getsentry/craft) is triggered again to publish the release to all the right platforms. (See [craft publish](https://github.com/getsentry/craft#craft-publish-publishing-the-release) for more information.) At the end of this process the release issue on GitHub will be closed and the release is completed! Congratulations!
166158

167-
- Which version of the SDK supports which versions of the modules it hooks into?
159+
There is a sequence diagram visualizing all this in the [README.md](https://github.com/getsentry/publish) of the `Publish` repository.
168160

169-
- One code example with basic setup.
161+
### Versioning Policy
170162

171-
- Make sure to add integration page to `python/index.md` (people forget to do that all the time).
163+
This project follows [semver](https://semver.org/), with three additions:
172164

173-
Tip: Put most relevant parts wrapped in `<!--WIZARD-->..<!--ENDWIZARD-->` tags for usage from within the Sentry UI.
165+
- Semver says that major version `0` can include breaking changes at any time. Still, it is common practice to assume that only `0.x` releases (minor versions) can contain breaking changes while `0.x.y` releases (patch versions) are used for backwards-compatible changes (bugfixes and features). This project also follows that practice.
174166

175-
5. Merge docs after new version has been released (auto-deploys on merge).
167+
- All undocumented APIs are considered internal. They are not part of this contract.
176168

177-
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.
169+
- Certain features (e.g. integrations) may be explicitly called out as "experimental" or "unstable" in the documentation. They come with their own versioning policy described in the documentation.
178170

179-
## Commit message format guidelines
171+
We recommend to pin your version requirements against `1.x.*` or `1.x.y`.
172+
Either one of the following is fine:
180173

181-
See the documentation on commit messages here:
174+
```
175+
sentry-sdk>=1.0.0,<2.0.0
176+
sentry-sdk==1.5.0
177+
```
182178

183-
https://develop.sentry.dev/commit-messages/#commit-message-format
179+
A major release `N` implies the previous release `N-1` will no longer receive updates. We generally do not backport bugfixes to older versions unless they are security relevant. However, feel free to ask for backports of specific commits on the bugtracker.

0 commit comments

Comments
 (0)