feat(develop): Add Python SDK knowledge base (#12175)

Author: sentrivana

develop-docs/sdk/platform-specifics/javascript-sdks/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: JavaScript SDKs
 description: Information specific to developing Javascript based SDKs.
-sidebar_order: 7
+sidebar_order: 6
 ---
 
 This Section contains JavaScript SDK-specific information that's useful for developing new or extending existing JS SDKs as well as for ingest and product teams to understanding how the JS SDKs works and what data it sends.

develop-docs/sdk/platform-specifics/native-sdks/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Native SDKs
 description: Information specific to developing native SDKs.
-sidebar_order: 8
+sidebar_order: 7
 ---
 
 <PageGrid />

develop-docs/sdk/platform-specifics/python-sdk/backporting.mdx

@@ -0,0 +1,14 @@
+---
+title: Backporting
+description: How to backport to an earlier major.
+sidebar_order: 10
+---
+
+The last normal 1.x release was [1.45.0](https://github.com/getsentry/sentry-python/releases/tag/1.45.0) in April 2024. Development on 1.x has stopped — we are not backporting any features or bugfixes outside of security fixes.
+
+If there is a security issue in the SDK severe enough (use your judgement) that it needs a backport to 1.x (see for example [1.45.1](https://github.com/getsentry/sentry-python/releases/tag/1.45.1)):
+
+- Checkout the `1.x` branch
+- Port the fix into the `1.x` branch
+- Trigger a release. Make sure to set both “Use workflow from” and “Target branch to merge into” to `1.x`
+- Continue with the release process as usual

develop-docs/sdk/platform-specifics/python-sdk/ci.mdx

@@ -0,0 +1,23 @@
+---
+title: CI
+description: Our test setup and how our CI files are generated.
+sidebar_order: 20
+---
+
+The GitHub workflow files for testing specific integration groups (like AI, Web Frameworks, Databases, etc.) are generated by [this script](https://github.com/getsentry/sentry-python/blob/master/scripts/split-tox-gh-actions/split-tox-gh-actions.py). Essentially, the script scans our `tox.ini` and generates the group test CI YAML files in `.github/workflows`.
+
+There are multiple components to this:
+* `tox.ini` is where the configuration (what to test and what versions) is read from
+* `scripts/split-tox-gh-actions/split-tox-gh-actions.py` is the script that defines the [test groups](https://github.com/getsentry/sentry-python/blob/0f3e5db0c8aabcad0baf0e8b2d3e31e27e839b3e/scripts/split-tox-gh-actions/split-tox-gh-actions.py#L57) and generates the resulting YAML files
+* `scripts/split-tox-gh-actions/templates` contains the jinja2 template snippets used to generate the YAML files
+* `.github/workflows/test-integrations-*.yml` are the resulting workflow configuration YAMLs
+
+If you update any of the components without keeping the rest in sync, for instance by making a change in one of the `test-integrations-*.yml` files that is not reflected in the templates in `scripts/split-tox-gh-actions/templates`, CI will error out as it actually checks if everything is in sync, meaning it runs the `split-tox-gh-actions.py` script and compares the result with the committed YAMLs.
+
+## AWS Lambda Test Suite
+
+The AWS Lambda test suite will fail by default on new PRs. If you are an external contributor, this is not something you have to worry about, unless you've made changes actually affecting the AWS Lambda integration. It's a security precaution on our part.
+
+Sensitive test suites (currently only AWS Lambda) require maintainer review to ensure that tests do not compromise our secrets. This review must be repeated after any code revisions.
+
+Before running sensitive test suites, maintainers need to carefully check the PR. Then they will apply the `Trigger: tests using secrets` label. The label will be removed after any code changes to enforce our policy requiring maintainers to review all code revisions before running sensitive tests.

develop-docs/sdk/platform-specifics/python-sdk/feature-branches.mdx

@@ -0,0 +1,22 @@
+---
+title: Feature Branches
+description: How-to for syncing long-running feature branches.
+sidebar_order: 30
+---
+
+Sometimes we have long-running feature branches that can't be merged into `master` yet because they contain breaking changes (e.g. `sentry-sdk-2.0`, `potel-base`). They have to be kept in sync with `master` though.
+
+You might be tempted to branch off the feature branch and do the merge there, maybe make a PR so that you can double check the changes in the UI and make sure CI is green. In that case you need to make sure you **don't actually commit the merge from another branch** — the merge commit needs to be directly on the feature branch, otherwise `git` doesn't set the parent commits for the merge commit properly and the feature branch will still have unresolved conflicts (even though you literally just resolved them).
+
+## How to sync so that merge conflicts are recognized as resolved
+
+If you still want the nice GH diff and have CI run on your changes:
+
+- check out the feature branch and `git merge master` into it
+- solve conflicts (while still on the feature branch)
+- commit the merge (still on the feature branch)
+- *(if you're already confident all is good, you can just short circuit and push now, otherwise:)*
+- then open a new branch from your feature branch `git checkout -b sync-feature-with-master`
+- push the new branch, make a PR, look at the nice diff in GitHub, see if the tests pass
+- if everything looks ok: don't merge the PR! this will not mark the merge conflicts as solved
+- instead, `git checkout` your feature branch (with the merge commit on top) and `push` it

develop-docs/sdk/platform-specifics/python-sdk/generating-api-docs.mdx

@@ -0,0 +1,47 @@
+---
+title: Generating API Docs
+description: How to deal with issues generating our API docs.
+sidebar_order: 40
+---
+
+## Problem
+
+`sphinx` (run as part of `make apidocs`) sometimes has cryptic circular import errors and causes CI to fail. This is because we run it with `TYPE_CHECKING` and while `mypy` statically checks types, `sphinx`  is dynamic and thus introduces circularity into type checking which is normally ok.
+
+```python
+sphinx.errors.SphinxWarning: autodoc: failed to import function 'api.capture_event' from module 'sentry_sdk'; the following exception was raised:
+cannot import name 'logger' from partially initialized module 'sentry_sdk.utils' (most likely due to a circular import) (/home/runner/work/sentry-python/sentry-python/sentry_sdk/utils.py)
+```
+
+See https://github.com/tox-dev/sphinx-autodoc-typehints?tab=readme-ov-file#dealing-with-circular-imports
+
+These circular import issues may surface not just in our SDK code but also in built-in Sphinx extensions. You might get something like this:
+
+```
+Extension error:
+Could not import extension sphinx.domains.c (exception: cannot import name 'ASTDeclaration' from partially initialized module 'sphinx.domains.c._ast' (most likely due to a circular import) (.venv/lib/python3.11/site-packages/sphinx/domains/c/_ast.py))
+```
+
+## Solution
+
+To solve this in SDK code, just use forward references, so instead of:
+
+```python
+from sentry_sdk.integrations import Integration
+
+def foo(integration):
+    # type: (Integration) -> None
+    pass
+```
+
+just use:
+
+```python
+import sentry_sdk
+
+def foo(integration):
+    # type: (sentry_sdk.integrations.Integration) -> None
+    pass
+```
+
+If the circular import is coming from an extension, add it to the [imports in conf.py](https://github.com/getsentry/sentry-python/blob/302457dec22bd105beb849e98324f653d8c7b5f0/docs/conf.py#L6-L12).

develop-docs/sdk/platform-specifics/python-sdk/index.mdx

@@ -0,0 +1,11 @@
+---
+title: Python SDK
+description: Information specific to developing the Python SDK.
+sidebar_order: 8
+---
+
+This section serves as a knowledge base for the Python SDK where we document
+common gotchas, seldom used processes, and in general stuff that comes up every
+now and then.
+
+<PageGrid></PageGrid>