Skip to content

Commit a838f98

Browse files
jholveckjholveck
authored
docs: add Versioning chapter (#496)
* Add Versioning chapter to docs This clarifies the versioning philosophy for MSS. It's intended for developers as much as end users, so that contributors can be on the same page as the maintainer. * Add changelog entry * Update packaging test
1 parent 383b411 commit a838f98

File tree

4 files changed

+201
-0
lines changed

4 files changed

+201
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ See Git commit messages for full history.
44

55
## v10.2.0.dev0
66
(2026-xx-xx)
7+
- Add Versioning chapter to docs (#496)
78
- Add `is_primary`, `name`, and `unique_id` keys to Monitor dicts for primary monitor detection, device names, and stable per-monitor identification (#153)
89
- Add `primary_monitor` property to MSS base class for easy access to the primary monitor (#153)
910
- Windows: add primary monitor detection using `GetMonitorInfoW` API (#153)

‎docs/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ An ultra fast cross-platform multiple screenshots module in pure python using ct
4343
| support |
4444
| api |
4545
| developers |
46+
| versioning |
4647
| changelog |
4748
| where |
4849
+-------------------------+

‎docs/source/versioning.rst‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
Versioning
2+
==========
3+
4+
This document describes how changes are managed across MSS releases and
5+
what users can expect when upgrading.
6+
7+
MSS follows `Semantic Versioning <https://semver.org/>`_ (SemVer) with
8+
additional conventions described below.
9+
10+
These guidelines describe how changes are managed and reflect the
11+
project's intent. They are not a guarantee of behavior in all cases.
12+
13+
Overview
14+
--------
15+
16+
MSS version numbers follow the format :samp:`{major}.{minor}.{patch}`:
17+
18+
- **Major versions** introduce backward-incompatible changes.
19+
- **Minor versions** add new features or improvements without breaking
20+
existing documented usage.
21+
- **Patch versions** fix bugs and do not intentionally change the public
22+
API.
23+
24+
Patch and minor releases are intended to be backward-compatible with
25+
previous releases of the same major version. If a regression occurs, it
26+
is treated as a defect.
27+
28+
Public API
29+
----------
30+
31+
The public API consists of:
32+
33+
- Features documented in the official documentation (Sphinx docs built
34+
from :file:`docs/`), unless explicitly marked otherwise
35+
- Features demonstrated in official examples (:file:`docs/source/examples/`)
36+
or demos (:file:`demos/`), unless explicitly marked otherwise
37+
38+
Examples and demos are intended to show recommended usage patterns and
39+
are considered part of the public surface that users may reasonably rely
40+
on.
41+
42+
The following are **not** considered part of the public API:
43+
44+
- Undocumented symbols
45+
- Internal modules or backend-specific implementation details
46+
- Docstrings (which may reference internal behavior and are not yet
47+
fully audited)
48+
49+
Some currently accessible symbols may still be internal even if not
50+
prefixed with :code:`_`. These should not be relied upon and may change
51+
without notice.
52+
53+
Compatibility Rules
54+
-------------------
55+
56+
The following describes how changes are generally handled across
57+
versions.
58+
59+
Changes That Require a Major Version
60+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61+
62+
The following changes are treated as backward-incompatible:
63+
64+
- Removing public API symbols (functions, classes, attributes, etc.)
65+
- Removing keyword parameters
66+
- Making function arguments more restrictive than documented
67+
- Returning values outside documented types
68+
- Raising exceptions in cases where behavior was previously documented
69+
or clearly implied to succeed
70+
- Removing support for Python or operating system versions
71+
72+
Changes That Do Not Require a Major Version
73+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
74+
75+
The following changes are considered backward-compatible:
76+
77+
- Adding new optional or keyword parameters
78+
- Adding new functions, attributes, or data fields
79+
- Widening accepted parameter types
80+
- Narrowing return types within documented bounds
81+
- Raising exceptions for previously undefined or invalid inputs
82+
- Emitting or modifying warnings
83+
- Returning subclasses where a base class was previously returned
84+
- Changing exception messages (exception types remain stable)
85+
86+
Deprecation Policy
87+
------------------
88+
89+
When a feature is planned for removal:
90+
91+
- It is typically deprecated in a minor release before removal in a
92+
future major release
93+
- Deprecation notices are included in the documentation and release
94+
notes
95+
- :py:class:`DeprecationWarning` may be emitted where practical
96+
97+
In some cases, deprecated features may be removed from documentation
98+
before being removed from the code.
99+
100+
Feature Gating
101+
--------------
102+
103+
New functionality may be introduced behind explicit user opt-in
104+
mechanisms ("feature gates").
105+
106+
Behavior enabled only through an explicit opt-in is not considered a
107+
breaking change.
108+
109+
Hypothetical example of a gated feature::
110+
111+
with MSS() as sct:
112+
img = sct.grab(sct.primary_monitor)
113+
# returns ScreenShotCPU
114+
115+
with MSS(device="cuda") as sct:
116+
img = sct.grab(sct.primary_monitor)
117+
# returns ScreenShotCUDA
118+
119+
Because the new behavior is only enabled when explicitly requested, it
120+
does not affect existing usage.
121+
122+
Typing and Compatibility
123+
------------------------
124+
125+
Type annotations may evolve across major versions.
126+
127+
In some cases, type changes may occur that do not affect runtime
128+
behavior but may require updates for static type checking tools.
129+
130+
When evaluating such changes, considerations include:
131+
132+
- Likelihood of affecting real-world usage
133+
- Difficulty of adapting existing code
134+
- Overall benefit to the ecosystem
135+
136+
Runtime compatibility is generally prioritized over strict type
137+
stability.
138+
139+
In some limited cases, MSS may widen type annotations in a minor
140+
release to support a new feature that is only available through
141+
explicit user opt-in. This is only considered for gated features where
142+
the runtime behavior of existing code does not change and where
143+
type-checking support is added so that static analysis can still infer
144+
the narrower type in ordinary usage.
145+
146+
For example, this may be appropriate when overloads, generics, or other
147+
typing features allow type checkers to determine the correct return type
148+
based on the user's explicit configuration. MSS may use this approach
149+
when it is expected to avoid type-checking impact for the vast majority
150+
of users and when the added feature is important enough to justify the
151+
change.
152+
153+
Stability Guidelines
154+
--------------------
155+
156+
MSS aims to preserve documented behavior across releases. This includes
157+
the meaning of documented APIs, arguments, return values, and data
158+
fields.
159+
160+
Behavior that is undocumented, incidental, or implementation-specific
161+
should not be relied upon and may change between releases.
162+
163+
Internal strategies, backend selection, validation details, error
164+
messages, and other implementation details are not considered stable
165+
unless explicitly documented.
166+
167+
Widely used features receive greater stability consideration than niche
168+
or specialized functionality.
169+
170+
Writing Forward-Compatible Code
171+
-------------------------------
172+
173+
To minimize disruption when upgrading:
174+
175+
- Use documented public APIs only
176+
- Avoid relying on internal modules or backend-specific behavior
177+
- Prefer explicit, documented interfaces over implicit conventions
178+
- Expect stricter validation of inputs over time
179+
180+
Undocumented behavior should not be relied upon and may change without
181+
notice.
182+
183+
Philosophy
184+
----------
185+
186+
MSS aims to be:
187+
188+
- Easy to use for programmers of all experience levels
189+
- Suitable for a wide range of projects
190+
191+
Changes are made carefully, with the goal of improving functionality,
192+
performance, and maintainability while minimizing disruption.
193+
194+
When breaking changes are necessary, they are introduced deliberately
195+
and with advance notice where practical.
196+
197+
Where possible, compatibility layers may be provided to allow existing
198+
code to continue working during transitions.

‎src/tests/test_setup.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ def test_sdist() -> None:
6262
f"mss-{__version__}/docs/source/installation.rst",
6363
f"mss-{__version__}/docs/source/support.rst",
6464
f"mss-{__version__}/docs/source/usage.rst",
65+
f"mss-{__version__}/docs/source/versioning.rst",
6566
f"mss-{__version__}/docs/source/where.rst",
6667
f"mss-{__version__}/pyproject.toml",
6768
f"mss-{__version__}/src/mss/__init__.py",

0 commit comments

Comments
 (0)
⚡