Skip to content

Commit 7e493b4

Browse files
authored
docs: Update CONTRIBUTING.md (#4870)
### Description Removed hub mention, some obsolete/unclear instructions, added a note about defensiveness, toxgen. #### Issues <!-- * resolves: #1234 * resolves: LIN-1234 --> #### Reminders - Please add tests to validate your changes, and lint your code using `tox -e linters`. - Add GH Issue ID _&_ Linear ID (if applicable) - PR title should use [conventional commit](https://develop.sentry.dev/engineering-practices/commit-messages/#type) style (`feat:`, `fix:`, `ref:`, `meta:`) - For external contributors: [CONTRIBUTING.md](https://github.com/getsentry/sentry-python/blob/master/CONTRIBUTING.md), [Sentry SDK development docs](https://develop.sentry.dev/sdk/), [Discord community](https://discord.gg/Ww9hbqr)
1 parent ceefa69 commit 7e493b4

File tree

1 file changed

+9
-20
lines changed

1 file changed

+9
-20
lines changed

CONTRIBUTING.md

Lines changed: 9 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ We test against a number of Python language and library versions, which are auto
7878

7979
The tox CLI tool is required to run the tests locally. Follow [the installation instructions](https://tox.wiki/en/latest/installation.html) for tox. Dependencies are installed for you when you run the command below, but _you_ need to bring an appropriate Python interpreter.
8080

81-
[Pyenv](https://github.com/pyenv/pyenv) is a cross-platform utility for managing Python versions. You can also use a conventional package manager, but not all versions may be distributed in the package manager of your choice. For macOS, Versions 3.8 and up can be installed with Homebrew.
81+
[Pyenv](https://github.com/pyenv/pyenv) is a cross-platform utility for managing Python versions. You can also use a conventional package manager, but not all versions may be distributed in the package manager of your choice. For macOS, versions 3.8 and up can be installed with Homebrew.
8282

8383
An environment consists of the Python major and minor version and the library name and version. The exception to the rule is that you can provide `common` instead of the library information. The environments tied to a specific library usually run the corresponding test suite, while `common` targets all tests but skips those that require uninstalled dependencies.
8484

@@ -109,29 +109,20 @@ tox -p auto -o -e <tox_env> -- <pytest_args>
109109
## Adding a New Integration
110110

111111
1. Write the integration.
112-
113-
- 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.
114-
115-
- Everybody monkeypatches. That means:
116-
117-
- Make sure to think about conflicts with other monkeypatches when monkeypatching.
118-
119-
- You don't need to feel bad about it.
120-
112+
- Instrument all application instances by default. Prefer global signals/patches.
113+
- Don't make the user pass anything to your integration for anything to work. Aim for zero configuration.
114+
- Everybody monkeypatches. That means you don't need to feel bad about it.
121115
- 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.
122-
123-
- Avoid modifying the hub, registering a new client or the like. The user drives the client, and the client owns integrations.
124-
125-
- 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).
116+
- Be defensive. Don't assume the code you're patching will stay the same forever, especially if it's an internal function. Allow for future variability whenever it makes sense.
117+
- Avoid registering a new client or the like. The user drives the client, and the client owns integrations.
118+
- Allow the user to turn off the integration by changing the client. Check `sentry_sdk.get_client().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).
126119

127120
2. Write tests.
128-
129-
- Consider the minimum versions supported, and test each version in a separate env in `tox.ini`.
130-
121+
- Consider the minimum versions supported, and document in `_MIN_VERSIONS` in `integrations/__init__.py`.
131122
- Create a new folder in `tests/integrations/`, with an `__init__` file that skips the entire suite if the package is not installed.
123+
- Add the test suite to the script generating our test matrix. See [`scripts/populate_tox/README.md`](https://github.com/getsentry/sentry-python/blob/master/scripts/populate_tox/README.md#add-a-new-test-suite).
132124

133125
3. Update package metadata.
134-
135126
- 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.
136127

137128
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.
@@ -140,8 +131,6 @@ tox -p auto -o -e <tox_env> -- <pytest_args>
140131

141132
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.
142133

143-
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.
144-
145134
## Releasing a New Version
146135

147136
_(only relevant for Python SDK core team)_

0 commit comments

Comments
 (0)