From 8d9e697bb89a617f51f32803a0da90c6f844e439 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Randy=20D=C3=B6ring?= <30527984+radoering@users.noreply.github.com> Date: Fri, 31 Mar 2023 21:44:13 +0200 Subject: [PATCH 1/2] docs: promote semantic versioning less aggressively --- docs/faq.md | 17 ++++++++++++++--- docs/libraries.md | 7 ++++--- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 2a2051d294a..52e7a2be690 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -33,21 +33,32 @@ Once Poetry has cached the releases' information on your machine, the dependency will be much faster. {{% /note %}} -### Why are unbound version constraints a bad idea? +### Are unbound version constraints a bad idea? A version constraint without an upper bound such as `*` or `>=3.4` will allow updates to any future version of the dependency. This includes major versions breaking backward compatibility. Once a release of your package is published, you cannot tweak its dependencies anymore in case a dependency breaks BC – you have to do a new release but the previous one stays broken. +(Users can still work around the broken dependency by restricting it by themselves.) -The only good alternative is to define an upper bound on your constraints, +To avoid such issues you can define an upper bound on your constraints, which you can increase in a new release after testing that your package is compatible with the new major version of your dependency. -For example instead of using `>=3.4` you should use `^3.4` which allows all versions `<4.0`. +For example instead of using `>=3.4` you can use `^3.4` which allows all versions `<4.0`. The `^` operator works very well with libraries following [semantic versioning](https://semver.org). +However, when defining an upper bound, users of your package are not able to update +a dependency beyond the upper bound even if it does not break anything +and is fully compatible with your package. +You have to release a new version of your package with an increased upper bound first. + +If your package will be used as a library in other packages, it might be better to avoid +upper bounds and thus unnecessary dependency conflicts (unless you already know for sure +that the next release of the dependency will break your package). +If your package will be used as an application, it might be worth to define an upper bound. + ### Is tox supported? **Yes**. By using the [isolated builds](https://tox.readthedocs.io/en/latest/config.html#conf-isolated_build) `tox` provides, diff --git a/docs/libraries.md b/docs/libraries.md index ab56979540b..5ebe373cc94 100644 --- a/docs/libraries.md +++ b/docs/libraries.md @@ -19,10 +19,11 @@ This chapter will tell you how to make your library installable through Poetry. Poetry requires [PEP 440](https://peps.python.org/pep-0440)-compliant versions for all projects. -While Poetry does not enforce any release convention, it does encourage the use of +While Poetry does not enforce any release convention, it used to encourage the use of [semantic versioning](https://semver.org/) within the scope of -[PEP 440](https://peps.python.org/pep-0440/#semantic-versioning). This has many advantages for the end users -and allows them to set appropriate [version constraints]({{< relref "dependency-specification#version-constraints" >}}). +[PEP 440](https://peps.python.org/pep-0440/#semantic-versioning) and supports +[version constraints]({{< relref "dependency-specification/#caret-requirements" >}}) +that are especially suitable for semver. {{% note %}} From 30acf6b074833adff6694246c46053e3d13c2abd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Randy=20D=C3=B6ring?= <30527984+radoering@users.noreply.github.com> Date: Fri, 31 Mar 2023 21:44:50 +0200 Subject: [PATCH 2/2] docs: document Poetry's own versioning scheme --- docs/faq.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/faq.md b/docs/faq.md index 52e7a2be690..0a8b97b3075 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -33,6 +33,28 @@ Once Poetry has cached the releases' information on your machine, the dependency will be much faster. {{% /note %}} +### What kind of versioning scheme does Poetry use for itself? + +Poetry uses "major.minor.micro" version identifiers as mentioned in +[PEP 440](https://peps.python.org/pep-0440/#final-releases). + +Version bumps are done similar to Python's versioning: +* A major version bump (incrementing the first number) is only done for breaking changes + if a deprecation cycle is not possible and many users have to perform some manual steps + to migrate from one version to the next one. +* A minor version bump (incrementing the second number) may include new features as well + as new deprecations and drop features deprecated in an earlier minor release. +* A micro version bump (incrementing the third number) usually only includes bug fixes. + Deprecated features will not be dropped in a micro release. + +### Why does Poetry not adhere to semantic versioning? + +Because of its large user base, even small changes not considered relevant by most users +can turn out to be a breaking change for some users in hindsight. +Sticking to strict [semantic versioning](https://semver.org) and (almost) always bumping +the major version instead of the minor version does not seem desirable +since the minor version will not carry any meaning anymore. + ### Are unbound version constraints a bad idea? A version constraint without an upper bound such as `*` or `>=3.4` will allow updates to any future version of the dependency.