Skip to content

Commit

Permalink
docs: remove ambiguity about pep440 and semver
Browse files Browse the repository at this point in the history
Co-authored-by: Bjorn Neergaard <[email protected]>
abn and neersighted committed May 9, 2022
1 parent 4d7321e commit 0963366
Showing 4 changed files with 49 additions and 19 deletions.
34 changes: 21 additions & 13 deletions docs/cli.md
Original file line number Diff line number Diff line change
@@ -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
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.

| 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

8 changes: 8 additions & 0 deletions docs/faq.md
Original file line number Diff line number Diff line change
@@ -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.
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.


### 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.
16 changes: 12 additions & 4 deletions docs/libraries.md
Original file line number Diff line number Diff line change
@@ -17,11 +17,19 @@ This chapter will tell you how to make your library installable through Poetry.

## 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

10 changes: 8 additions & 2 deletions docs/pyproject.md
Original file line number Diff line number Diff line change
@@ -21,8 +21,14 @@ The name 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

0 comments on commit 0963366

Please sign in to comment.