Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: remove ambiguity about pep440 and semver #5576

Merged
merged 1 commit into from
May 9, 2022
Merged

docs: remove ambiguity about pep440 and semver #5576

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 21 additions & 13 deletions docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
8 changes: 8 additions & 0 deletions docs/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 8 additions & 2 deletions docs/pyproject.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down