Strict version pinning at release time (Hard Freeze)

[krzywon]

Preamble

To reduce the risk of unexpected breakages from dependency updates, improve reproducibility, and provide a more stable experience for users, we propose to adopt strict version pinning at release time ("Hard Freeze"). This ensures users are able to install the tested and validated environment corresponding to each release.

Proposal

• During a release cycle, all dependencies shall be pinned to exact versions after the first code freeze.
• Each platform shall have a different set of pinned dependencies.
  • For the purpose of this ADR, different flavors of the same operating system (e.g. macOS ARM vs macOS Intel) shall be considered separate platforms, as this has the potential to affect the dependencies that are available to both platforms.
• The versions that each dependency is pinned on shall be determined by creating a fresh virtual environment, and installing the latest versions of all dependencies. Then, the pip freeze command should be used to determine the requirements-<platform>.txt text for each platform.
  • Alternately, pip freeze is run as part of the CI. The CI log from a successful build may be used to populate the platform-specific requirements file.
• PyPi distributions shall not be required to use pinned dependencies.

Changing pins during and after a release cycle

• Dependency pins should only be altered post code-freeze in very limited circumstances. Such as:
  • When a bug is spotted which is found to be related to a dependency, and where downgrading/upgrading the pin is found to resolve the issue. If possible, we should consider making changes to our code first if this can fix the issue before changing the dependency pinning.
  • Where a package is found to have some instability which can be rectified by downgrading to an older more stable version, or upgrading to a version which includes fixes to bugs which are specific to that package.
• Dependencies pins, where altered, should be altered for all platforms unless there is a strong reason to only alter them for a specific platform. If this is necessary, the release manager should consider the impact this may have on testing, as differing versions of dependencies could potentially lead to platform-specific bugs.
• Except in the limited cases noted above, dependency pins should not be changed between minor releases. All other releases may change modify dependency pinnings.
• The primary branch of the repository should hold no file with pinned dependencies. Prior to merging a release branch into the primary branch, either remove the dependency files or remove any pinned dependencies from the file.

CI

• Our CI should be configured so that, on the primary branch, builds should not use pinned dependencies.
  • The lone exception to this rule will be dependencies that introduce breaking changes that interfere with our ability to build functioning distros.
• Release branches should always use pinned dependencies for builds.

Revision Acceptance Date: Dec 18, 2025
Revision Number: 1
Original Suggestion: https://github.com/orgs/SasView/discussions/3245