Update contribution guide (getsentry#1346)

antonpirker · web-flow · commit 39ab78fb639a · 2022-02-21T15:19:47.000Z
* docs(python): Added 'how to create a release' to contribution guide.

* docs(python): added link to new integration checklist and moved migration section below integrations section
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -37,14 +37,20 @@ cd sentry-python
 python -m venv .env
 
 source .env/bin/activate
+```
+
+### Install `sentry-python` in editable mode
 
+```bash
 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!
+**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.
 
 ### Install coding style pre-commit hooks:
 
+This will make sure that your commits will have the correct coding style.
+
 ```bash
 cd sentry-python
 
@@ -107,15 +113,52 @@ pytest -rs tests/integrations/flask/
 
 ## Releasing a new version
 
-We use [craft](https://github.com/getsentry/craft#python-package-index-pypi) to
-release new versions. You need credentials for the `getsentry` PyPI user, and
-must have `twine` installed globally.
+(only relevant for Sentry employees)
+
+Prerequisites:
+
+- All the changes that should be release must be in `master` branch.
+- Every commit should follow the [Commit Message Format](https://develop.sentry.dev/commit-messages/#commit-message-format) convention.
+- CHANGELOG.md is updated automatically. No human intervention necessary.
+
+Manual Process:
+
+- On GitHub in the `sentry-python` repository go to "Actions" select the "Release" workflow.
+- Click on "Run workflow" on the right side, make sure the `master` branch is selected.
+- Set "Version to release" input field. Here you decide if it is a major, minor or patch release. (See "Versioning Policy" below)
+- Click "Run Workflow"
+
+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)
+
+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.
+
+There are always two persons involved in a release.
 
-The usual release process goes like this:
+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.
+
+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!
+
+There is a sequence diagram visualizing all this in the [README.md](https://github.com/getsentry/publish) of the `Publish` repository.
+
+### Versioning Policy
+
+This project follows [semver](https://semver.org/), with three additions:
+
+- 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.
+
+- All undocumented APIs are considered internal. They are not part of this contract.
+
+- 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.
+
+We recommend to pin your version requirements against `1.x.*` or `1.x.y`.
+Either one of the following is fine:
+
+```
+sentry-sdk>=1.0.0,<2.0.0
+sentry-sdk==1.5.0
+```
 
-1. Go through git log and write new entry into `CHANGELOG.md`, commit to master
-2. `craft p a.b.c`
-3. `craft pp a.b.c`
+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.
 
 ## Adding a new integration (checklist)
 
diff --git a/README.md b/README.md
@@ -16,12 +16,6 @@ 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
@@ -60,6 +54,8 @@ raise ValueError()  # Will also create an event in Sentry.
 
 ## Integrations
 
+(If you want to create a new integration have a look at the [Adding a new integration checklist](CONTRIBUTING.md#adding-a-new-integration-checklist).)
+
 - [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/)
@@ -82,6 +78,12 @@ raise ValueError()  # Will also create an event in Sentry.
 - [Apache Beam](https://docs.sentry.io/platforms/python/guides/beam/)
 - [Apache Spark](https://docs.sentry.io/platforms/python/guides/pyspark/)
 
+## 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/).
+
 ## Contributing to the SDK
 
 Please refer to [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -90,26 +92,6 @@ Please refer to [CONTRIBUTING.md](CONTRIBUTING.md).
 
 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!
 
-## Versioning Policy
-
-This project follows [semver](https://semver.org/), with three additions:
-
-- 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.
-
-- All undocumented APIs are considered internal. They are not part of this contract.
-
-- 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.
-
-We recommend to pin your version requirements against `1.x.*` or `1.x.y`.
-Either one of the following is fine:
-
-```
-sentry-sdk>=1.0.0,<2.0.0
-sentry-sdk==1.5.0
-```
-
-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.
-
 ## Resources
 
 - [![Documentation](https://img.shields.io/badge/documentation-sentry.io-green.svg)](https://docs.sentry.io/quickstart/)
diff --git a/tox.ini b/tox.ini
@@ -306,6 +306,12 @@ commands =
     {py3.5,py3.6,py3.7,py3.8,py3.9}-flask-{0.10,0.11,0.12}: pip install pytest<5
     {py3.6,py3.7,py3.8,py3.9}-flask-{0.11}: pip install Werkzeug<2
 
+    ; https://github.com/pallets/flask/issues/4455
+    {py3.7,py3.8,py3.9,py3.10}-flask-{0.11,0.12,1.0,1.1}: pip install "itsdangerous>=0.24,<2.0" "markupsafe<2.0.0"
+    ;"itsdangerous >= 0.24, < 2.0",
+;itsdangerous==1.1.0
+;markupsafe==1.1.1
+
     ; https://github.com/more-itertools/more-itertools/issues/578
     py3.5-flask-{0.10,0.11,0.12}: pip install more-itertools<8.11.0
 
