Deprecate tmux versions below 3.2a

[tony]

Deprecate tmux versions below 3.2a

Summary

• Add deprecation warning (FutureWarning) for tmux versions below 3.2a
• Introduce TMUX_SOFT_MIN_VERSION constant for deprecation threshold
• Prepare for future hard minimum version bump

Motivation

tmux 3.2a was released in April 2021 and is the version shipped with Ubuntu 22.04 LTS. Older versions (3.1 and below) are only found on EOL platforms like Ubuntu 20.04. Deprecating these versions allows libtmux to:

• Remove legacy compatibility code in future releases
• Take advantage of newer tmux features (e.g., format-defaults, extended hooks, display-menu APIs)
• Align supported versions with actively maintained distributions

Changes

Source (src/libtmux/common.py)

• TMUX_SOFT_MIN_VERSION: New constant set to "3.2a" - the deprecation threshold
• _version_deprecation_checked: Module-level flag ensuring warning fires only once per process
• _check_deprecated_version(): New helper function that emits a FutureWarning when tmux version is below 3.2a
• get_version(): Now calls _check_deprecated_version() to trigger warning on first version check

Environment Variable

Users can suppress the warning by setting:

export LIBTMUX_SUPPRESS_VERSION_WARNING=1

Tests (tests/test_common.py)

Added parametrized tests using NamedTuple fixture pattern:

• test_version_deprecation_warning - 5 parametrized cases covering deprecated versions, current versions, and env var suppression
• test_version_deprecation_warns_once - Verifies warning only fires once per process
• test_version_deprecation_via_get_version - Integration test verifying warning through full get_version() call chain

Documentation

• docs/quickstart.md: Updated Requirements section with version recommendations and deprecation note
• CHANGES: Added Deprecations and Internal sections for 0.48.x

Future Work

In a future release (e.g., 0.49.0 or 0.50.0):

• Bump TMUX_MIN_VERSION from "1.8" to "3.2a"
• Remove _check_deprecated_version() helper and TMUX_SOFT_MIN_VERSION
• Remove tests that mock old version values

See Also

This facilitates upcoming changes:

• Improved option management, add hook management #516
• Waiter 0.1 #594
• asyncio experiment: Wrapper method approach #603 / asyncio experiment: Async-first approach #604

[codecov]

Codecov Report

❌ Patch coverage is 80.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 46.45%. Comparing base (204785b) to head (4ed7b79).
⚠️ Report is 9 commits behind head on master.

Files with missing lines	Patch %	Lines
src/libtmux/common.py	80.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #606      +/-   ##
==========================================
+ Coverage   46.21%   46.45%   +0.23%     
==========================================
  Files          19       19              
  Lines        1876     1890      +14     
  Branches      294      297       +3     
==========================================
+ Hits          867      878      +11     
- Misses        894      897       +3     
  Partials      115      115              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}