Skip to content

Commit 769d30a

Browse files
Clarify Python dependency constraints (#18856)
Clarify Python dependency constraints Spawning from #18852 (comment) as I don't actually know the the exact rule of thumb. It's unclear to me what we care about exactly. Our [deprecation policy](https://element-hq.github.io/synapse/latest/deprecation_policy.html) mentions Debian oldstable support at-least for the version of SQLite. But then we only refer to Debian stable for the Twisted dependency.
1 parent 7ecfe8b commit 769d30a

File tree

2 files changed

+48
-11
lines changed

2 files changed

+48
-11
lines changed

changelog.d/18856.doc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Clarify Python dependency constraints in our deprecation policy.

docs/deprecation_policy.md

Lines changed: 47 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
1-
Deprecation Policy for Platform Dependencies
2-
============================================
1+
# Deprecation Policy
32

4-
Synapse has a number of platform dependencies, including Python, Rust,
5-
PostgreSQL and SQLite. This document outlines the policy towards which versions
6-
we support, and when we drop support for versions in the future.
3+
Synapse has a number of **platform dependencies** (Python, Rust, PostgreSQL, and SQLite)
4+
and **application dependencies** (Python and Rust packages). This document outlines the
5+
policy towards which versions we support, and when we drop support for versions in the
6+
future.
77

8-
9-
Policy
10-
------
8+
## Platform Dependencies
119

1210
Synapse follows the upstream support life cycles for Python and PostgreSQL,
1311
i.e. when a version reaches End of Life Synapse will withdraw support for that
@@ -26,8 +24,8 @@ The oldest supported version of SQLite is the version
2624
[provided](https://packages.debian.org/bullseye/libsqlite3-0) by
2725
[Debian oldstable](https://wiki.debian.org/DebianOldStable).
2826

29-
Context
30-
-------
27+
28+
### Context
3129

3230
It is important for system admins to have a clear understanding of the platform
3331
requirements of Synapse and its deprecation policies so that they can
@@ -50,4 +48,42 @@ the ecosystem.
5048
On a similar note, SQLite does not generally have a concept of "supported
5149
release"; bugfixes are published for the latest minor release only. We chose to
5250
track Debian's oldstable as this is relatively conservative, predictably updated
53-
and is consistent with the `.deb` packages released by Matrix.org.
51+
and is consistent with the `.deb` packages released by Matrix.org.
52+
53+
54+
## Application dependencies
55+
56+
For application-level Python dependencies, we often specify loose version constraints
57+
(ex. `>=X.Y.Z`) to be forwards compatible with any new versions. Upper bounds (`<A.B.C`)
58+
are only added when necessary to prevent known incompatibilities.
59+
60+
When selecting a minimum version, while we are mindful of the impact on downstream
61+
package maintainers, our primary focus is on the maintainability and progress of Synapse
62+
itself.
63+
64+
For developers, a Python dependency version can be considered a "no-brainer" upgrade once it is
65+
available in both the latest [Debian Stable](https://packages.debian.org/stable/) and
66+
[Ubuntu LTS](https://launchpad.net/ubuntu) repositories. No need to burden yourself with
67+
extra scrutiny or consideration at this point.
68+
69+
We aggressively update Rust dependencies. Since these are statically linked and managed
70+
entirely by `cargo` during build, they *can* pose no ongoing maintenance burden on others.
71+
This allows us to freely upgrade to leverage the latest ecosystem advancements assuming
72+
they don't have their own system-level dependencies.
73+
74+
75+
### Context
76+
77+
Because Python dependencies can easily be managed in a virtual environment, we are less
78+
concerned about the criteria for selecting minimum versions. The only thing of concern
79+
is making sure we're not making it unnecessarily difficult for downstream package
80+
maintainers. Generally, this just means avoiding the bleeding edge for a few months.
81+
82+
The situation for Rust dependencies is fundamentally different. For packagers, the
83+
concerns around Python dependency versions do not apply. The `cargo` tool handles
84+
downloading and building all libraries to satisfy dependencies, and these libraries are
85+
statically linked into the final binary. This means that from a packager's perspective,
86+
the Rust dependency versions are an internal build detail, not a runtime dependency to
87+
be managed on the target system. Consequently, we have even greater flexibility to
88+
upgrade Rust dependencies as needed for the project. Some distros (e.g. Fedora) do
89+
package Rust libraries, but this appears to be the outlier rather than the norm.

0 commit comments

Comments
 (0)