docs: remove ambiguity about pep440 and semver

Co-authored-by: Bjorn Neergaard <bjorn@neersighted.com>

docs/cli.md

@@ -593,22 +593,30 @@ This command shows the current version of the project or bumps the version of
 the project and writes the new version back to `pyproject.toml` if a valid
 the project and writes the new version back to `pyproject.toml` if a valid
 bump rule is provided.
 bump rule is provided.
 
 
-The new version should ideally be a valid [semver](https://semver.org/) string or a valid bump rule:
-`patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`, `prerelease`.
+The new version should be a valid [PEP 440](https://peps.python.org/pep-0440/)
+string or a valid bump rule: `patch`, `minor`, `major`, `prepatch`, `preminor`,
+`premajor`, `prerelease`.
+
+{{% note %}}
+
+If you would like to use semantic versioning for your project, please see
+[here]({{< relref "libraries#versioning" >}}).
+
+{{% /note %}}
 
 
 The table below illustrates the effect of these rules with concrete examples.
 The table below illustrates the effect of these rules with concrete examples.
 
 
-| rule       | before        | after         |
-| ---------- | ------------- | ------------- |
-| major      | 1.3.0         | 2.0.0         |
-| minor      | 2.1.4         | 2.2.0         |
-| patch      | 4.1.1         | 4.1.2         |
-| premajor   | 1.0.2         | 2.0.0-alpha.0 |
-| preminor   | 1.0.2         | 1.1.0-alpha.0 |
-| prepatch   | 1.0.2         | 1.0.3-alpha.0 |
-| prerelease | 1.0.2         | 1.0.3-alpha.0 |
-| prerelease | 1.0.3-alpha.0 | 1.0.3-alpha.1 |
-| prerelease | 1.0.3-beta.0  | 1.0.3-beta.1  |
+| rule       | before  | after   |
+| ---------- |---------|---------|
+| major      | 1.3.0   | 2.0.0   |
+| minor      | 2.1.4   | 2.2.0   |
+| patch      | 4.1.1   | 4.1.2   |
+| premajor   | 1.0.2   | 2.0.0a0 |
+| preminor   | 1.0.2   | 1.1.0a0 |
+| prepatch   | 1.0.2   | 1.0.3a0 |
+| prerelease | 1.0.2   | 1.0.3a0 |
+| prerelease | 1.0.3a0 | 1.0.3a1 |
+| prerelease | 1.0.3b0 | 1.0.3b1 |
 
 
 ### Options
 ### Options
 
 

docs/faq.md

@@ -106,3 +106,11 @@ The current project's Python requirement (>=3.7.0,<4.0.0) is not compatible with
 Usually you will want to match the Python requirement of your project with the upper bound of the failing dependency.
 Usually you will want to match the Python requirement of your project with the upper bound of the failing dependency.
 Alternative you can tell Poetry to install this dependency [only for a specific range of Python versions](/docs/dependency-specification/#multiple-constraints-dependencies),
 Alternative you can tell Poetry to install this dependency [only for a specific range of Python versions](/docs/dependency-specification/#multiple-constraints-dependencies),
 if you know that it's not needed in all versions.
 if you know that it's not needed in all versions.
+
+
+### Why does Poetry enforce PEP 440 versions?
+
+This is done so to be compliant with the broader Python ecosystem.
+
+For example, if Poetry builds a distribution for a project that uses a version that is not valid according to
+[PEP 440](https://peps.python.org/pep-0440), third party tools will be unable to parse the version correctly.

docs/libraries.md

@@ -17,11 +17,19 @@ This chapter will tell you how to make your library installable through Poetry.
 
 
 ## Versioning
 ## Versioning
 
 
-While Poetry does not enforce any convention regarding package versioning,
-it **strongly** recommends to follow [semantic versioning](https://semver.org).
+Poetry requires [PEP 440](https://peps.python.org/pep-0440)-compliant versions for all projects.
 
 
-This has many advantages for the end users and allows them to set appropriate
-[version constraints]({{< relref "dependency-specification#version-constraints" >}}).
+While Poetry does not enforce any release convention, it does 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" >}}).
+
+{{% note %}}
+
+As an example, `1.0.0-hotfix.1` is not compatible with [PEP 440](https://peps.python.org/pep-0440). You can instead
+choose to use `1.0.0-post1` or `1.0.0.post1`.
+
+{{% /note %}}
 
 
 ## Lock file
 ## Lock file
 
 

docs/pyproject.md

@@ -21,8 +21,14 @@ The name of the package. **Required**
 
 
 The version of the package. **Required**
 The version of the package. **Required**
 
 
-This should follow [semantic versioning](http://semver.org/). However it will not be enforced and you remain
-free to follow another specification.
+This should be a valid [PEP 440](https://peps.python.org/pep-0440/) string.
+
+{{% note %}}
+
+If you would like to use semantic versioning for your project, please see
+[here]({{< relref "libraries#versioning" >}}).
+
+{{% /note %}}
 
 
 ## description
 ## description