docs: Update readme, migration guide (#2754)

MIGRATION_GUIDE.md

@@ -8,37 +8,34 @@ Looking to upgrade from Sentry SDK 1.x to 2.x? Here's a comprehensive list of wh
 
 ## Changed
 
+- Setting the parameter `propagate_hub` to `True` in `ThreadingIntegration(propagate_hub=True)` only works on Python 3.7+.
+- The Pyramid integration will not capture errors that might happen in `authenticated_userid()` in a custom `AuthenticationPolicy` class.
+- The method `need_code_loation` of the `MetricsAggregator` was renamed to `need_code_location`.
 - The `BackgroundWorker` thread used to process events was renamed from `raven-sentry.BackgroundWorker` to `sentry-sdk.BackgroundWorker`.
 - The `reraise` function was moved from `sentry_sdk._compat` to `sentry_sdk.utils`.
 - Moved the contents of `tracing_utils_py3.py` to `tracing_utils.py`. The `start_child_span_decorator` is now in `sentry_sdk.tracing_utils`.
 - The actual implementation of `get_current_span` was moved to `sentry_sdk.tracing_utils`. `sentry_sdk.get_current_span` is still accessible as part of the top-level API.
-- The Pyramid integration will not capture errors that might happen in `authenticated_userid()` in a custom `AuthenticationPolicy` class.
-- Setting the parameter `propagate_hub` to `True` in `ThreadingIntegration(propagate_hub=True)` only works on Python 3.7+.
-- The method `need_code_loation` of the `MetricsAggregator` was renamed to `need_code_location`.
 
 ## Removed
 
 - Removed support for Python 2 and Python 3.5. The SDK now requires at least Python 3.6.
 - Removed support for Celery 3.\*.
 - Removed support for Django 1.8, 1.9, 1.10.
 - Removed support for Flask 0.\*.
-- Removed `last_event_id()` top level API. The last event Id is still returned by `capture_event()`, `capture_exception()` and `capture_message()` but the top level api `sentry_sdk.last_event_id()` has been removed. 
-- `sentry_sdk._functools` was removed.
-- A number of compatibility utilities were removed from `sentry_sdk._compat`: the constants `PY2` and `PY33`; the functions `datetime_utcnow`, `utc_from_timestamp`, `implements_str`, `contextmanager`; and the aliases `text_type`, `string_types`, `number_types`, `int_types`, `iteritems`, `binary_sequence_types`.
+- Removed `last_event_id()` top level API. The last event ID is still returned by `capture_event()`, `capture_exception()` and `capture_message()` but the top level API `sentry_sdk.last_event_id()` has been removed.
+- Removed support for sending events to the `/store` endpoint. Everything is now sent to the `/envelope` endpoint. If you're on SaaS you don't have to worry about this, but if you're running Sentry yourself you'll need version `20.6.0` or higher of self-hosted Sentry.
 - The deprecated `with_locals` configuration option was removed. Use `include_local_variables` instead. See https://docs.sentry.io/platforms/python/configuration/options/#include-local-variables.
 - The deprecated `request_bodies` configuration option was removed. Use `max_request_body_size`. See https://docs.sentry.io/platforms/python/configuration/options/#max-request-body-size.
-- Removed `sentry_sdk.utils.Auth.store_api_url`.
-- `sentry_sdk.utils.Auth.get_api_url`'s now accepts a `sentry_sdk.consts.EndpointType` enum instead of a string as its only parameter. We recommend omitting this argument when calling the function, since the parameter's default value is the only possible `sentry_sdk.consts.EndpointType` value. The parameter exists for future compatibility.
-- Removed `tracing_utils_py2.py`. The `start_child_span_decorator` is now in `sentry_sdk.tracing_utils`.
+- Removed support for `user.segment`. It was also removed from the trace header as well as from the dynamic sampling context.
 - Removed support for the `install` method for custom integrations. Please use `setup_once` instead.
 - Removed `sentry_sdk.tracing.Span.new_span`. Use `sentry_sdk.tracing.Span.start_child` instead.
 - Removed `sentry_sdk.tracing.Transaction.new_span`. Use `sentry_sdk.tracing.Transaction.start_child` instead.
-- Removed support for `user.segment`. It was also removed from the trace header as well as from the dynamic sampling context.
+- Removed `sentry_sdk.utils.Auth.store_api_url`.
+- `sentry_sdk.utils.Auth.get_api_url`'s now accepts a `sentry_sdk.consts.EndpointType` enum instead of a string as its only parameter. We recommend omitting this argument when calling the function, since the parameter's default value is the only possible `sentry_sdk.consts.EndpointType` value. The parameter exists for future compatibility.
+- Removed `tracing_utils_py2.py`. The `start_child_span_decorator` is now in `sentry_sdk.tracing_utils`.
 
 ## Deprecated
 
-- Deprecated `sentry_sdk.transport.Transport.capture_event`. Please use `sentry_sdk.transport.Transport.capture_envelope`, instead.
-- Passing a function to `sentry_sdk.init`'s `transport` keyword argument has been deprecated. If you wish to provide a custom transport, please pass a `sentry_sdk.transport.Transport` instance or a subclass.
 - `profiler_mode` and `profiles_sample_rate` have been deprecated as `_experiments` options. Use them as top level options instead:
  ```python
  sentry_sdk.init(
@@ -47,3 +44,5 @@ Looking to upgrade from Sentry SDK 1.x to 2.x? Here's a comprehensive list of wh
  profiles_sample_rate=1.0,
  )
  ```
+- Deprecated `sentry_sdk.transport.Transport.capture_event`. Please use `sentry_sdk.transport.Transport.capture_envelope`, instead.
+- Passing a function to `sentry_sdk.init`'s `transport` keyword argument has been deprecated. If you wish to provide a custom transport, please pass a `sentry_sdk.transport.Transport` instance or a subclass.

README.md

@@ -76,7 +76,13 @@ See [the documentation](https://docs.sentry.io/platforms/python/integrations/) f
 - [Google Cloud Functions](https://docs.sentry.io/platforms/python/integrations/gcp-functions/)
 
 
-## Migrating From `raven-python`
+## Migrating
+
+### Migrating From `1.x` to `2.x`
+
+If you're on SDK version 1.x, we highly recommend updating to the 2.x major. To make the process easier we've prepared a [migration guide](https://docs.sentry.io/platforms/python/migration/) with the most common changes as well as a [detailed changelog](MIGRATION_GUIDE.md).
+
+### Migrating From `raven-python`
 
 The old `raven-python` client has entered maintenance mode and was moved [here](https://github.com/getsentry/raven-python).