docs: document Poetry's own versioning scheme #7517
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
radoering
added
area/docs
|
Deploy preview for website ready! ✅ Preview Built with commit 30acf6b. |
|
Updating "how poetry the application is versioned" feels a lot less controversial than updating "how python projects should think about versioning in general" - the latter has been quite the can of worms! It's probably not the worst idea for poetry to revisit its wider stance on versioning. (Whatever the docs say, defaulting to upper bounds for everything is a strong commitment to believing in semantic versioning; I for one have mixed feelings about this). But do you intend that discussion to be in scope for this merge request? Or is this supposed to be limited to describing the policy for poetry's own version? |
|
The main purpose of this PR is to describe the policy for poetry's own version. However, it felt kind of contradictive to claim that strict semver doesn't work for us and advocate for semver some sections later. Thus, I tried to change the concerning parts of the docs to be more neutral. I agree that It might be the next step to change this default. (I'm not a big fan of this default myself.) However, I think this can be discussed later (not in the scope of this PR). |
|
Yeah, I'm not objecting exactly to anything here. Rather just cautioning that - for better or worse - it risks encouraging a discussion that has not happened for a while. eg I wouldn't be at all surprised to see someone showing up with an argument along the lines of "how come poetry is defaulting the world into semantic versioning when even your own docs don't encourage it any more?" |
radoering
force-pushed
the
doc-versioning-scheme
branch
from
91e217f
to
9d74fac
Compare
neersighted
reviewed
Mar 31, 2023
neersighted
previously approved these changes
Mar 31, 2023
radoering
force-pushed
the
doc-versioning-scheme
branch
from
9d74fac
to
32fe82e
Compare
radoering
force-pushed
the
doc-versioning-scheme
branch
from
32fe82e
to
30acf6b
Compare
neersighted
approved these changes
Mar 31, 2023
mwalbeck
pushed a commit
to mwalbeck/docker-python-poetry
that referenced
this pull request
May 23, 2023
This PR contains the following updates: | Package | Update | Change | |---|---|---| | [poetry](https://python-poetry.org/) ([source](https://github.com/python-poetry/poetry), [changelog](https://python-poetry.org/history/)) | minor | `1.4.2` -> `1.5.0` | --- ### Release Notes <details> <summary>python-poetry/poetry</summary> ### [`v1.5.0`](https://github.com/python-poetry/poetry/blob/HEAD/CHANGELOG.md#​150---2023-05-19) [Compare Source](python-poetry/poetry@1.4.2...1.5.0) ##### Added - **Introduce the new source priorities `explicit` and `supplemental`** ([#​7658](python-poetry/poetry#7658), [#​6879](python-poetry/poetry#6879)). - **Introduce the option to configure the priority of the implicit PyPI source** ([#​7801](python-poetry/poetry#7801)). - Add handling for corrupt cache files ([#​7453](python-poetry/poetry#7453)). - Improve caching of URL and git dependencies ([#​7693](python-poetry/poetry#7693), [#​7473](python-poetry/poetry#7473)). - Add option to skip installing directory dependencies ([#​6845](python-poetry/poetry#6845), [#​7923](python-poetry/poetry#7923)). - Add `--executable` option to `poetry env info` ([#​7547](python-poetry/poetry#7547)). - Add `--top-level` option to `poetry show` ([#​7415](python-poetry/poetry#7415)). - Add `--lock` option to `poetry remove` ([#​7917](python-poetry/poetry#7917)). - Add experimental `POETRY_REQUESTS_TIMEOUT` option ([#​7081](python-poetry/poetry#7081)). - Improve performance of wheel inspection by avoiding unnecessary file copy operations ([#​7916](python-poetry/poetry#7916)). ##### Changed - **Remove the old deprecated installer and the corresponding setting `experimental.new-installer`** ([#​7356](python-poetry/poetry#7356)). - **Introduce `priority` key for sources and deprecate flags `default` and `secondary`** ([#​7658](python-poetry/poetry#7658)). - Deprecate `poetry run <entry point>` if the entry point was not previously installed via `poetry install` ([#​7606](python-poetry/poetry#7606)). - Only write the lock file if the installation succeeds ([#​7498](python-poetry/poetry#7498)). - Do not write the unused package category into the lock file ([#​7637](python-poetry/poetry#7637)). ##### Fixed - Fix an issue where Poetry's internal pyproject.toml continually grows larger with empty lines ([#​7705](python-poetry/poetry#7705)). - Fix an issue where Poetry crashes due to corrupt cache files ([#​7453](python-poetry/poetry#7453)). - Fix an issue where the `Retry-After` in HTTP responses was not respected and retries were handled inconsistently ([#​7072](python-poetry/poetry#7072)). - Fix an issue where Poetry silently ignored invalid groups ([#​7529](python-poetry/poetry#7529)). - Fix an issue where Poetry does not find a compatible Python version if not given explicitly ([#​7771](python-poetry/poetry#7771)). - Fix an issue where the `direct_url.json` of an editable install from a git dependency was invalid ([#​7473](python-poetry/poetry#7473)). - Fix an issue where error messages from build backends were not decoded correctly ([#​7781](python-poetry/poetry#7781)). - Fix an infinite loop when adding certain dependencies ([#​7405](python-poetry/poetry#7405)). - Fix an issue where pre-commit hooks skip pyproject.toml files in subdirectories ([#​7239](python-poetry/poetry#7239)). - Fix an issue where pre-commit hooks do not use the expected Python version ([#​6989](python-poetry/poetry#6989)). - Fix an issue where an unclear error message is printed if the project name is the same as one of its dependencies ([#​7757](python-poetry/poetry#7757)). - Fix an issue where `poetry install` returns a zero exit status even though the build script failed ([#​7812](python-poetry/poetry#7812)). - Fix an issue where an existing `.venv` was not used if `in-project` was not set ([#​7792](python-poetry/poetry#7792)). - Fix an issue where multiple extras passed to `poetry add` were not parsed correctly ([#​7836](python-poetry/poetry#7836)). - Fix an issue where `poetry shell` did not send a newline to `fish` ([#​7884](python-poetry/poetry#7884)). - Fix an issue where `poetry update --lock` printed operations that were not executed ([#​7915](python-poetry/poetry#7915)). - Fix an issue where `poetry add --lock` did perform a full update of all dependencies ([#​7920](python-poetry/poetry#7920)). - Fix an issue where `poetry shell` did not work with `nushell` ([#​7919](python-poetry/poetry#7919)). - Fix an issue where subprocess calls failed on Python 3.7 ([#​7932](python-poetry/poetry#7932)). - Fix an issue where keyring was called even though the password was stored in an environment variable ([#​7928](python-poetry/poetry#7928)). ##### Docs - Add information about what to use instead of `--dev` ([#​7647](python-poetry/poetry#7647)). - Promote semantic versioning less aggressively ([#​7517](python-poetry/poetry#7517)). - Explain Poetry's own versioning scheme in the FAQ ([#​7517](python-poetry/poetry#7517)). - Update documentation for configuration with environment variables ([#​6711](python-poetry/poetry#6711)). - Add details how to disable the virtualenv prompt ([#​7874](python-poetry/poetry#7874)). - Improve documentation on whether to commit `poetry.lock` ([#​7506](python-poetry/poetry#7506)). - Improve documentation of `virtualenv.create` ([#​7608](python-poetry/poetry#7608)). ##### poetry-core ([`1.6.0`](https://github.com/python-poetry/poetry-core/releases/tag/1.6.0)) - Improve error message for invalid markers ([#​569](python-poetry/poetry-core#569)). - Increase robustness when deleting temporary directories on Windows ([#​460](python-poetry/poetry-core#460)). - Replace `tomlkit` with `tomli`, which changes the interface of some *internal* classes ([#​483](python-poetry/poetry-core#483)). - Deprecate `Package.category` ([#​561](python-poetry/poetry-core#561)). - Fix a performance regression in marker handling ([#​568](python-poetry/poetry-core#568)). - Fix an issue where wildcard version constraints were not handled correctly ([#​402](python-poetry/poetry-core#402)). - Fix an issue where `poetry build` created duplicate Python classifiers if they were specified manually ([#​578](python-poetry/poetry-core#578)). - Fix an issue where local versions where not handled correctly ([#​579](python-poetry/poetry-core#579)). </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNS44Mi4wIiwidXBkYXRlZEluVmVyIjoiMzUuODIuMCIsInRhcmdldEJyYW5jaCI6Im1hc3RlciJ9--> Reviewed-on: https://git.walbeck.it/walbeck-it/docker-python-poetry/pulls/717 Co-authored-by: renovate-bot <[email protected]> Co-committed-by: renovate-bot <[email protected]>
|
This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Some people expect poetry to adhere to strict semver, presumably because it used to promote semver (or even still promotes it in the docs). During the last releases, we realized that strict semver does not work well for poetry (anymore). Because of its large user base, even small changes not considered harmful can be breaking for somebody. Sticking to strict semver and always bumping the major version does not seem desirable/reasonable.
Since a versioning scheme that is more like Python's versioning than strict semver has emerged during the last releases and has been mentioned in the chat sometimes, we might as well document it somewhere. (I didn't come up with a better place than the FAQ.)
Further, if poetry itself does not adhere to strict semver, we shouldn't aggressively promote it in the docs.