You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+9-20Lines changed: 9 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -78,7 +78,7 @@ We test against a number of Python language and library versions, which are auto
78
78
79
79
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.
80
80
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.
82
82
83
83
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.
- 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.
121
115
- 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).
126
119
127
120
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`.
131
122
- 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).
132
124
133
125
3. Update package metadata.
134
-
135
126
- 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.
136
127
137
128
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.
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.
142
133
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.
0 commit comments