Skip to content

Commit 8c03ee7

Browse files
authored
devdocs: Add notes on Python majors (#15053)
<!-- Use this checklist to make sure your PR is ready for merge. You may delete any sections you don't need. --> ## DESCRIBE YOUR PR Clarify our philosophy for new majors and include specific steps to consider when preparing a new major. Direct link to preview: https://develop-docs-git-ivana-devmajor.sentry.dev/sdk/platform-specifics/python-sdk/new-major/ Closes getsentry/sentry-python#4047 ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [x] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [x] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE <!-- Sentry employees and contractors can delete or ignore this section. --> Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > Adds a new docs page outlining considerations and concrete steps for preparing a new major of the Python SDK. > > - **Docs**: > - **New page**: `develop-docs/sdk/platform-specifics/python-sdk/new-major.mdx` detailing: > - Philosophy: prioritize migration ease, user-friendliness, and backward compatibility. > - Migration support: provide a dedicated migration guide with copy-pastable examples; test AI-assisted upgrades. > - Version support: guidance on dropping old Python/framework versions using data; use `scripts/update_integration_support.py` to detect new minimums. > - Required updates: adjust `_MIN_VERSIONS` in `sentry_sdk/integrations/__init__.py`, lower bounds in `extras_require` in `setup.py`, and affected integration docs. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit e0b47dc. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY -->
1 parent 4d5b047 commit 8c03ee7

File tree

1 file changed

+30
-0
lines changed

1 file changed

+30
-0
lines changed
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: New Major
3+
description: What to consider when preparing a new major.
4+
sidebar_order: 50
5+
---
6+
7+
Even if we decide to make a new major, it's important to prioritize user-friendliness, ease of migration, and backwards compatibility.
8+
9+
Upgrading requires effort. Every major increases the chances of folks staying on an older version forever.
10+
11+
Don't break existing APIs for a minor maintenance benefit on your end.
12+
13+
14+
## Making Migrating Easier
15+
16+
Create a [migration guide](https://docs.sentry.io/platforms/python/migration/). Include easily understandable and copy-pastable examples wherever possible.
17+
18+
Many folks might try to upgrade using AI. Try it out yourself on an example project. Consider adding rules specifically for migrating.
19+
20+
21+
## Dropping Version Support
22+
23+
When making a new major, consider whether we should drop support for an old Python version. There is data in Looker you can use to make an informed decision.
24+
25+
Investigate if we should drop support for old versions of frameworks and libraries. This is not feasible to do by hand as there's too many. For this purpose there is a small script in `scripts/update_integration_support.py` that automatically detects the effective lowest supported version based on our tests and package metadata. You can run the script after removing support for an old Python version, and it should automatically detect which minimum versions are no longer supported.
26+
27+
In order to fully specify the new minimum versions:
28+
- Update `_MIN_VERSIONS` in `sentry_sdk/integrations/__init__.py`
29+
- Update the lower bounds in `extras_require` in `setup.py`, if specified
30+
- Update the documentation pages for the affected integrations (usually, the lowest supported version is mentioned at the bottom)

0 commit comments

Comments
 (0)