diff --git a/.github/ISSUE_TEMPLATE/---bug-report.md b/.github/ISSUE_TEMPLATE/---bug-report.md index d4e1f01f68b..fc88f3abb04 100644 --- a/.github/ISSUE_TEMPLATE/---bug-report.md +++ b/.github/ISSUE_TEMPLATE/---bug-report.md @@ -8,26 +8,25 @@ assignees: '' --- - -- [ ] I am on the [latest](https://github.com/python-poetry/poetry/releases/latest) Poetry version. -- [ ] I have searched the [issues](https://github.com/python-poetry/poetry/issues) of this repo and believe that this is not a duplicate. -- [ ] If an exception occurs when executing a command, I executed it again in debug mode (`-vvv` option). + +- **Poetry version**: +- **Python version**: +- **OS version and name**: +- **pyproject.toml**: - - -- **OS version and name**: -- **Poetry version**: -- **Link of a [Gist](https://gist.github.com/) with the contents of your pyproject.toml file**: + +- [ ] I am on the [latest](https://github.com/python-poetry/poetry/releases/latest) stable Poetry version, installed using a recommended method. +- [ ] I have searched the [issues](https://github.com/python-poetry/poetry/issues) of this repo and believe that this is not a duplicate. +- [ ] I have consulted the [FAQ](https://python-poetry.org/docs/faq/) and [blog](https://python-poetry.org/blog/) for any relevant entries or release notes. +- [ ] If an exception occurs when executing a command, I executed it again in debug mode (`-vvv` option) and have included the output below. ## Issue - + + diff --git a/.github/ISSUE_TEMPLATE/---documentation.md b/.github/ISSUE_TEMPLATE/---documentation.md index 0c11c39d722..2afab223c9f 100644 --- a/.github/ISSUE_TEMPLATE/---documentation.md +++ b/.github/ISSUE_TEMPLATE/---documentation.md @@ -1,6 +1,6 @@ --- -name: "\U0001F4DA Documentation" -about: Did you find errors, problems, or anything unintelligible in the docs (https://python-poetry.org/docs)? +name: "\U0001F4DA Documentation Issue" +about: Did you find errors, omissions, or anything unintelligible in the documentation? title: '' labels: area/docs, status/triage assignees: '' @@ -8,15 +8,14 @@ assignees: '' --- - + - [ ] I have searched the [issues](https://github.com/python-poetry/poetry/issues) of this repo and believe that this is not a duplicate. ## Issue - + + diff --git a/.github/ISSUE_TEMPLATE/---everything-else.md b/.github/ISSUE_TEMPLATE/---everything-else.md deleted file mode 100644 index eef2ca31c95..00000000000 --- a/.github/ISSUE_TEMPLATE/---everything-else.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: "\U0001F5C3 Everything Else" -about: For questions and issues that do not fall in any of the other categories. This - can include questions about Poetry's roadmap. For support questions, please post - on StackOverflow. -title: '' -labels: status/triage -assignees: '' - ---- - - - - - -- [ ] I have searched the [issues](https://github.com/python-poetry/poetry/issues) of this repo and believe that this is not a duplicate. -- [ ] I have searched the [documentation](https://python-poetry.org/docs/) and believe that my question is not covered. - -## Issue - diff --git a/.github/ISSUE_TEMPLATE/---feature-request.md b/.github/ISSUE_TEMPLATE/---feature-request.md index 24011a09659..45e0475f62c 100644 --- a/.github/ISSUE_TEMPLATE/---feature-request.md +++ b/.github/ISSUE_TEMPLATE/---feature-request.md @@ -1,6 +1,6 @@ --- name: "\U0001F381 Feature Request" -about: Do you have ideas for new features and improvements? +about: Do you have ideas for new features or improvements? title: '' labels: kind/feature, status/triage assignees: '' @@ -8,16 +8,16 @@ assignees: '' --- - + - [ ] I have searched the [issues](https://github.com/python-poetry/poetry/issues) of this repo and believe that this is not a duplicate. -- [ ] I have searched the [documentation](https://python-poetry.org/docs/) and believe that my question is not covered. +- [ ] I have searched the [FAQ](https://python-poetry.org/docs/faq/) and general [documentation](https://python-poetry.org/docs/) and believe that my question is not already covered. ## Feature Request - + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 82577fb2a8a..6e78d3ce6fe 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,7 +1,11 @@ # Ref: https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser -blank_issues_enabled: true +blank_issues_enabled: false contact_links: +- name: 'πŸ’¬ Discussions' + url: https://github.com/python-poetry/poetry/discussions + about: | + Ask questions about using Poetry, Poetry's features and roadmap, or get support and feedback for your usage of Poetry. - name: 'πŸ’¬ Discord Server' url: https://discordapp.com/invite/awxPgve about: | - Chat with the community, ask questions and learn about best practices. + Chat with the community and Poetry maintainers about both the usage of and development of the project. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 80a4b1ccb0e..00000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,251 +0,0 @@ - - -# Contributing to Poetry - -First off, thanks for taking the time to contribute! - -The following is a set of guidelines for contributing to Poetry on GitHub. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request. - -#### Table of contents - -[How to contribute](#how-to-contribute) - - * [Reporting bugs](#reporting-bugs) - * [Suggesting enhancements](#suggesting-enhancements) - * [Contributing to documentation](#contributing-to-documentation) - * [Contributing to code](#contributing-to-code) - * [Issue triage](#issue-triage) - * [Git workflow](#git-workflow) - - -## How to contribute - -### Reporting bugs - -This section guides you through submitting a bug report for Poetry. -Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports. - -Before creating bug reports, please check [this list](#before-submitting-a-bug-report) to be sure that you need to create one. When you are creating a bug report, please include as many details as possible. Fill out the [required template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---bug-report.md), the information it asks helps the maintainers resolve the issue faster. - -> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. - -#### Before submitting a bug report - -* **Check the [FAQs on the official website](https://python-poetry.org/docs/faq)** for a list of common questions and problems. -* **Check that your issue does not already exist in the [issue tracker](https://github.com/python-poetry/poetry/issues)**. - -#### How do I submit a bug report? - -Bugs are tracked on the [official issue tracker](https://github.com/python-poetry/poetry/issues) where you can create a new one and provide the following information by filling in [the template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---bug-report.md). - -Explain the problem and include additional details to help maintainers reproduce the problem: - -* **Use a clear and descriptive title** for the issue to identify the problem. -* **Describe the exact steps which reproduce the problem** in as many details as possible. -* **Provide your pyproject.toml file** in a [Gist](https://gist.github.com) after removing potential private information (like private package repositories). -* **Provide specific examples to demonstrate the steps to reproduce the issue**. Include links to files or GitHub projects, or copy-paste-able snippets, which you use in those examples. -* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. -* **Explain which behavior you expected to see instead and why.** -* **If the problem is an unexpected error being raised**, execute the corresponding command in **debug** mode (the `-vvv` option). - -Provide more context by answering these questions: - -* **Did the problem start happening recently** (e.g. after updating to a new version of Poetry) or was this always a problem? -* If the problem started happening recently, **can you reproduce the problem in an older version of Poetry?** What's the most recent version in which the problem doesn't happen? -* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens. - -Include details about your configuration and environment: - -* **Which version of Poetry are you using?** You can get the exact version by running `poetry -V` in your terminal. -* **Which Python version Poetry has been installed for?** Execute the `poetry debug info` to get the information. -* **What's the name and version of the OS you're using**? - - -### Suggesting enhancements - -This section guides you through submitting an enhancement suggestion for Poetry, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions. - -Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-an-enhancement-suggestion). Fill in [the template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---feature-request.md), including the steps that you imagine you would take if the feature you're requesting existed. - -#### Before submitting an enhancement suggestion - -* **Check the [FAQs on the official website](https://python-poetry.org/docs/faq)** for a list of common questions and problems. -* **Check that your issue does not already exist in the [issue tracker](https://github.com/python-poetry/poetry/issues)**. - -#### How do I submit an Enhancement suggestion? - -Enhancement suggestions are tracked on the [official issue tracker](https://github.com/python-poetry/poetry/issues) where you can create a new one and provide the following information: - -* **Use a clear and descriptive title** for the issue to identify the suggestion. -* **Provide a step-by-step description of the suggested enhancement** in as many details as possible. -* **Provide specific examples to demonstrate the steps**.. -* **Describe the current behavior** and **explain which behavior you expected to see instead** and why. - -### Contributing to documentation - -One of the simplest ways to get started contributing to a project is through improving documentation. Poetry is constantly evolving, this means that sometimes our documentation has gaps. You can help by -adding missing sections, editing the existing content so it is more accessible or creating new content (tutorials, FAQs, etc). - -> **Note:** A great way to understand Poetry's design and how it all fits together, is to add FAQ entries for commonly -> asked questions. Poetry members usually mark issues with [candidate/faq](https://github.com/python-poetry/poetry/issues?q=is%3Aissue+label%3Acandidate%2Ffaq+) to indicate that the issue either contains a response -> that explains how something works or might benefit from an entry in the FAQ. - -Issues pertaining to the documentation are usually marked with the [Documentation](https://github.com/python-poetry/poetry/labels/Documentation) label. - -### Contributing to code - -#### Picking an issue - -> **Note:** If you are a first time contributor, and are looking for an issue to take on, you might want to look for [Good First Issue](https://github.com/python-poetry/poetry/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22) -> labelled issues. We do our best to label such issues, however we might fall behind at times. So, ask us. - -If you would like to take on an issue, feel free to comment on the issue tagging `@python-poetry/triage`. We are more than happy to discuss solutions on the issue. If you would like help with navigating -the code base, join us on our [Discord Server](https://discordapp.com/invite/awxPgve). - -#### Local development - -You will need Poetry to start contributing on the Poetry codebase. Refer to the [documentation](https://python-poetry.org/docs/#introduction) to start using Poetry. - -> **Note:** Local development of Poetry requires Python 3.8 or newer. - -You will first need to clone the repository using `git` and place yourself in its directory: - -```bash -git clone git@github.com:python-poetry/poetry.git -cd poetry -``` - -> **Note:** We recommend that you use a personal [fork](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) for this step. If you are new to GitHub collaboration, -> you can refer to the [Forking Projects Guide](https://guides.github.com/activities/forking/). - -Now, you will need to install the required dependency for Poetry and be sure that the current -tests are passing on your machine: - -```bash -poetry install -poetry run pytest tests/ -``` - -Poetry uses [mypy](https://github.com/python/mypy) for typechecking, and the CI -will fail if it finds any errors. To run mypy locally: - -```bash -poetry run mypy -``` - -Poetry uses the [black](https://github.com/psf/black) coding style and you must ensure that your -code follows it. If not, the CI will fail and your Pull Request will not be merged. - -Similarly, the import statements are sorted with [isort](https://github.com/timothycrosley/isort) -and special care must be taken to respect it. If you don't, the CI will fail as well. - -To make sure that you don't accidentally commit code that does not follow the coding style, you can -install a pre-commit hook that will check that everything is in order: - -```bash -poetry run pre-commit install -``` - -You can also run it anytime using: - -```bash -poetry run pre-commit run --all-files -``` - -Your code must always be accompanied by corresponding tests, if tests are not present your code -will not be merged. - -#### Pull requests - -* Fill in [the required template](https://github.com/python-poetry/poetry/blob/master/.github/PULL_REQUEST_TEMPLATE.md) -* Be sure that your pull request contains tests that cover the changed or added code. -* If your changes warrant a documentation change, the pull request must also update the documentation. - -> **Note:** Make sure your branch is [rebased](https://docs.github.com/en/free-pro-team@latest/github/using-git/about-git-rebase) against the latest main branch. A maintainer might ask you to ensure the branch is -> up-to-date prior to merging your Pull Request if changes have conflicts. - -All pull requests, unless otherwise instructed, need to be first accepted into the main branch (`master`). - -### Issue triage - -> **Note:** If you have an issue that hasn't had any attention, you can ping us `@python-poetry/triage` on the issue. Please, give us reasonable time to get to your issue first, spamming us with messages -> does not help anyone. - -If you are helping with the triage of reported issues, this section provides some useful information to assist you in your contribution. - -#### Triage steps - -1. If `pyproject.toml` is missing or `-vvv` debug logs (with stack trace) is not provided and required, request that the issue author provides it. -1. Attempt to reproduce the issue with the reported Poetry version or request further clarification from the issue author. -1. Ensure the issue is not already resolved. You can attempt to reproduce using the latest preview release and/or poetry from the main branch. -1. If the issue cannot be reproduced, - 1. clarify with the issue's author, - 1. close the issue or notify `@python-poetry/triage`. -1. If the issue can be reproduced, - 1. comment on the issue confirming so - 1. notify `@python-poetry/triage`. - 1. if possible, identify the root cause of the issue. - 1. if interested, attempt to fix it via a pull request. - -#### Multiple versions - -Often times you would want to attempt to reproduce issues with multiple versions of `poetry` at the same time. For these use cases, the [pipx project](https://pypa.github.io/pipx/) is useful. - -You can set your environment up like so. - -```sh -pipx install --suffix @1.0.10 'poetry==1.0.10' -pipx install --suffix @1.1.0rc1 'poetry==1.1.0rc1' -pipx install --suffix @master 'poetry @ git+https://github.com/python-poetry/poetry' -``` - -> **Hint:** Do not forget to update your `poetry@master` installation in sync with upstream. - -For `@local` it is recommended that you do something similar to the following as editable installs are not supported for PEP 517 projects. - -```sh -# note this will not work for Windows, and we assume you have already run `poetry install` -cd /path/to/python-poetry/poetry -ln -sf $(poetry run which poetry) ~/.local/bin/poetry@local -``` - -> **Hint:** This mechanism can also be used to test pull requests. - -### Git Workflow - -All development work is performed against Poetry's main branch (`master`). All changes are expected to be submitted and accepted to this -branch. - -#### Release branch - -When a release is ready, the following are required before a release is tagged. - -1. A release branch with the prefix `release-`, eg: `release-1.1.0rc1`. -1. A pull request from the release branch to the main branch (`master`) if it's a minor or major release. Otherwise, to the bug fix branch (eg: `1.0`). - 1. The pull request description MUST include the change log corresponding to the release (eg: [#2971](https://github.com/python-poetry/poetry/pull/2971)). - 1. The pull request must contain a commit that updates [CHANGELOG.md](CHANGELOG.md) and bumps the project version (eg: [#2971](https://github.com/python-poetry/poetry/pull/2971/commits/824e7b79defca435cf1d765bb633030b71b9a780)). - 1. The pull request must have the `Release` label specified. - -Once the branch pull-request is ready and approved, a member of `@python-poetry/core` will, - -1. Tag the branch with the version identifier (eg: `1.1.0rc1`). -2. Merge the pull request once the release is created and assets are uploaded by the CI. - -> **Note:** In this case, we prefer a merge commit instead of squash or rebase merge. - -#### Bug fix branch - -Once a minor version (eg: `1.1.0`) is released, a new branch for the minor version (eg: `1.1`) is created for the bug fix releases. Changes identified -or acknowledged by the Poetry team as requiring a bug fix can be submitted as a pull requests against this branch. - -At the time of writing only issues meeting the following criteria may be accepted into a bug fix branch. Trivial fixes may be accepted on a -case-by-case basis. - -1. The issue breaks a core functionality and/or is a critical regression. -1. The change set does not introduce a new feature or changes an existing functionality. -1. A new minor release is not expected within a reasonable time frame. -1. If the issue affects the next minor/major release, a corresponding fix has been accepted into the main branch. - -> **Note:** This is subject to the interpretation of a maintainer within the context of the issue. diff --git a/README.md b/README.md index 647bb068aa1..534c9bf979c 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,18 @@ -# Poetry: Dependency Management for Python +# Poetry: Python packaging and dependency management made easy -[![Tests Status](https://github.com/python-poetry/poetry/workflows/Tests/badge.svg?branch=master&event=push)](https://github.com/python-poetry/poetry/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush) -[![Stable Version](https://img.shields.io/pypi/v/poetry?label=stable)](https://pypi.org/project/poetry/) -[![Pre-release Version](https://img.shields.io/github/v/release/python-poetry/poetry?label=pre-release&include_prereleases&sort=semver)](https://pypi.org/project/poetry/#history) -[![Downloads](https://img.shields.io/pypi/dm/poetry)](https://pypistats.org/packages/poetry) -[![Discord](https://img.shields.io/discord/487711540787675139?logo=discord)](https://discord.com/invite/awxPgve) +[![Stable Version](https://img.shields.io/pypi/v/poetry?label=stable)][PyPI Releases] +[![Pre-release Version](https://img.shields.io/github/v/release/python-poetry/poetry?label=pre-release&include_prereleases&sort=semver)][PyPI Releases] +[![Python Versions](https://img.shields.io/pypi/pyversions/poetry)][PyPI] +[![Download Stats](https://img.shields.io/pypi/dm/poetry)](https://pypistats.org/packages/poetry) +[![Discord](https://img.shields.io/discord/487711540787675139?logo=discord)][Discord] Poetry helps you declare, manage and install dependencies of Python projects, ensuring you have the right stack everywhere. -It requires Python 3.7+ to run. - ![Poetry Install](https://raw.githubusercontent.com/python-poetry/poetry/master/assets/install.gif) -## Documentation - -The [complete documentation](https://python-poetry.org/docs/) is available on the [official website](https://python-poetry.org). - -## Installation - -Instructions on how to install `poetry` can be found [here](https://python-poetry.org/docs/#installation). -You can also refer [here](https://python-poetry.org/docs/#enable-tab-completion-for-bash-fish-or-zsh) for -information on how to enable tab completion in your environment. - -## Introduction - -`poetry` is a tool to handle dependency installation as well as building and packaging of Python packages. -It only needs one file to do all of that: the new, [standardized](https://peps.python.org/pep-0518/) `pyproject.toml`. - -In other words, poetry uses `pyproject.toml` to replace `setup.py`, `requirements.txt`, `setup.cfg`, `MANIFEST.in` and `Pipfile`. +Poetry replaces `setup.py`, `requirements.txt`, `setup.cfg`, `MANIFEST.in` and `Pipfile` with a simple `pyproject.toml` +based project format. ```toml [tool.poetry] @@ -42,68 +26,89 @@ authors = [ "SΓ©bastien Eustace " ] -readme = "README.md" - repository = "https://github.com/python-poetry/poetry" homepage = "https://python-poetry.org" +# README file(s) are used as the package description +readme = ["README.md", "LICENSE"] + +# Keywords (translated to tags on the package index) keywords = ["packaging", "poetry"] [tool.poetry.dependencies] -python = "^3.8" # Compatible python versions must be declared here +# Compatible python versions must be declared here +python = "^3.8" +# Standard dependency with semver constraints aiohttp = "^3.8.1" -# Dependencies with extras -requests = { version = "^2.28", extras = ["security"] } # Python specific dependencies with prereleases allowed +requests = { version = "^2.28", extras = ["security"] } +# Version-specific dependencies with prereleases allowed tomli = { version = "^2.0.1", python = "<3.11", allow-prereleases = true } # Git dependencies cleo = { git = "https://github.com/python-poetry/cleo.git", branch = "master" } - -# Optional dependencies (extras) +# Optional dependencies (installed by extras) pendulum = { version = "^2.1.2", optional = true } -# Dependency groups +# Dependency groups are supported for organizing your dependencies [tool.poetry.group.dev.dependencies] pytest = "^7.1.2" pytest-cov = "^3.0" +# ...and can be installed only when explicitly requested +[tool.poetry.group.docs] +optional = true [tool.poetry.group.docs.dependencies] Sphinx = "^5.1.1" +# Python-style entrypoints and scripts are easily expressed [tool.poetry.scripts] my-script = "my_package:main" ``` -There are some things we can notice here: - -* It will try to enforce [semantic versioning]() as the best practice in version naming. -* You can specify the readme, included and excluded files: no more `MANIFEST.in`. -`poetry` will also use VCS ignore files (like `.gitignore`) to populate the `exclude` section. -* Keywords can be specified and will act as tags on the packaging site. -* The dependencies sections support caret, tilde, wildcard, inequality and multiple requirements. -* You must specify the python versions for which your package is compatible. - -`poetry` will also detect if you are inside a virtualenv and install the packages accordingly. -So, `poetry` can be installed globally and used everywhere. - -`poetry` also comes with a full-fledged dependency resolution library. +## Installation -## Why? +Poetry supports multiple installation methods, including a simple script found at [install.python-poetry.org]. For full +installation instructions, including advanced usage of the script, alternate install methods, and CI best practices, see +the full [installation documentation]. -Packaging systems and dependency management in Python are rather convoluted and hard to understand for newcomers. -Even for seasoned developers it might be cumbersome at times to create all files needed in a Python project: `setup.py`, -`requirements.txt`, `setup.cfg`, `MANIFEST.in` and `Pipfile`. +## Documentation -So I wanted a tool that would limit everything to a single configuration file to do: -dependency management, packaging and publishing. +[Documentation] for the current version of Poetry (as well as the development branch and recently out of support +versions) is available from the [official website]. -It takes inspiration in tools that exist in other languages, like `composer` (PHP) or `cargo` (Rust). +## Contribute -And, finally, I started `poetry` to bring another exhaustive dependency resolver to the Python community apart from -[Conda's](https://conda.io). +Poetry is a large, complex project always in need of contributors. For those new to the project, a list of +[suggested issues] to work on in Poetry and poetry-core is available. The full [contributing documentation] also +provides helpful guidance. ## Resources -* [Official Website](https://python-poetry.org) -* [Issue Tracker](https://github.com/python-poetry/poetry/issues) -* [Discord](https://discord.com/invite/awxPgve) +* [Releases][PyPI Releases] +* [Official Website] +* [Documentation] +* [Issue Tracker] +* [Discord] + + [PyPI]: https://pypi.org/project/poetry/ + [PyPI Releases]: https://pypi.org/project/poetry/#history + [Official Website]: https://python-poetry.org + [Documentation]: https://python-poetry.org/docs/ + [Issue Tracker]: https://github.com/python-poetry/poetry/issues + [Suggested Issues]: https://github.com/python-poetry/poetry/contribute + [Contributing Documentation]: https://python-poetry.org/docs/contributing + [Discord]: https://discord.com/invite/awxPgve + [install.python-poetry.org]: https://install.python-poetry.org + [Installation Documentation]: https://python-poetry.org/docs/#installation + +## Related Projects + +* [poetry-core](https://github.com/python-poetry/poetry-core): PEP 517 build-system for Poetry projects, and +dependency-free core functionality of the Poetry frontend +* [poetry-plugin-export](https://github.com/python-poetry/poetry-plugin-export): Export Poetry projects/lock files to +foreign formats like requirements.txt +* [poetry-plugin-bundle](https://github.com/python-poetry/poetry-plugin-bundle): Install Poetry projects/lock files to +external formats like virtual environments +* [install.python-poetry.org](https://github.com/python-poetry/install.python-poetry.org): The official Poetry +installation script +* [website](https://github.com/python-poetry/website): The official Poetry website and blog diff --git a/assets/install.gif b/assets/install.gif index 5a6b6950a95..c8dddae2e40 100644 Binary files a/assets/install.gif and b/assets/install.gif differ diff --git a/docs/basic-usage.md b/docs/basic-usage.md index 316be8799e1..be222b00b75 100644 --- a/docs/basic-usage.md +++ b/docs/basic-usage.md @@ -55,10 +55,16 @@ requires = ["poetry-core"] build-backend = "poetry.core.masonry.api" ``` -Poetry assumes your package contains a package with the same name as `tool.poetry.name`. -If this is not the case, populate `tool.poetry.packages` to specify your package or packages. +Poetry assumes your package contains a package with the same name as `tool.poetry.name` located in the root of your +project. If this is not the case, populate [`tool.poetry.packages`]({{< relref "pyproject#packages" >}}) to specify +your packages and their locations. -See [Packages]({{< relref "pyproject#packages" >}}) for more information. +Similarly, the traditional `MANIFEST.in` file is replaced by the `tool.poetry.readme`, `tool.poetry.include`, and +`tool.poetry.exclude` sections. `tool.poetry.exclude` is additionally implicitly populated by your `.gitignore`. For +full documentation on the project format, see the [pyproject section]({{< relref "pyproject" >}}) of the documentation. + +Poetry will require you to explicitly specify what versions of Python you intend to support, and its universal locking +will guarantee that your project is installable (and all dependencies claim support for) all supported Python versions. ### Initialising a pre-existing project @@ -92,17 +98,30 @@ $ poetry add pendulum It will automatically find a suitable version constraint **and install** the package and sub-dependencies. +Poetry supports a rich [dependency specification]({{< relref "dependency-specification" >}}) syntax, including caret, +tilde, wildcard, inequality and +[multiple constraints]({{< relref "dependency-specification#multiple-constraints-dependencies" >}}) requirements. ## Using your virtual environment -By default, poetry creates a virtual environment in `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows). -You can change the [`cache-dir`]({{< relref "configuration#cache-dir" >}} "cache-dir configuration documentation") value by editing the poetry config. -Additionally, you can use the [`virtualenvs.in-project`]({{< relref "configuration#virtualenvsin-project" >}} "#virtualenvs.in-project configuration documentation") configuration variable -to create virtual environment within your project directory. - +By default, Poetry creates a virtual environment in `{cache-dir}/virtualenvs`. +You can change the [`cache-dir`]({{< relref "configuration#cache-dir" >}} "cache-dir configuration documentation") value +by editing the Poetry configuration. +Additionally, you can use the +[`virtualenvs.in-project`]({{< relref "configuration#virtualenvsin-project" >}}) configuration variable to create +virtual environments within your project directory. There are several ways to run commands within this virtual environment. +{{% note %}} +**External virtual environment management** + +Poetry will detect and respect an existing virtual environment that has been externally activated. This is a powerful +mechanism that is intended to be an alternative to Poetry's built-in, simplified environment management. + +To take advantage of this, simply activate a virtual environment using your preferred method or tooling, before running +any Poetry commands that expect to manipulate an environment. +{{% /note %}} ### Using `poetry run` @@ -129,7 +148,6 @@ Therefore, Poetry has to create a sub-shell with the virtual environment activat in order for the subsequent commands to run from within the virtual environment. {{% /note %}} - Alternatively, to avoid creating a new shell, you can manually activate the virtual environment by running `source {path_to_venv}/bin/activate` (`{path_to_venv}\Scripts\activate.ps1` on Windows PowerShell). To get the path to your virtual environment run `poetry env info --path`. @@ -142,15 +160,14 @@ To deactivate this virtual environment simply use `deactivate`. | Manual Activation | `source {path_to_venv}/bin/activate` | `{path_to_venv}\Scripts\activate.ps1` | `deactivate` | | One-liner | `source $(poetry env info --path)/bin/activate` | | `deactivate` | - -### Version constraints +## Version constraints In our example, we are requesting the `pendulum` package with the version constraint `^2.1`. This means any version greater or equal to 2.1.0 and less than 3.0.0 (`>=2.1.0 <3.0.0`). -Please read [Dependency specification]({{< relref "dependency-specification" >}} "Dependency specification documentation") for more in-depth information on versions, -how versions relate to each other, and on the different ways you can specify dependencies. - +Please read [Dependency specification]({{< relref "dependency-specification" >}} "Dependency specification documentation") +for more in-depth information on versions, how versions relate to each other, and on the different ways you can specify +dependencies. {{% note %}} **How does Poetry download the right files?** @@ -158,13 +175,12 @@ how versions relate to each other, and on the different ways you can specify dep When you specify a dependency in `pyproject.toml`, Poetry first takes the name of the package that you have requested and searches for it in any repository you have registered using the `repositories` key. If you have not registered any extra repositories, or it does not find a package with that name in the -repositories you have specified, it falls back on PyPI. +repositories you have specified, it falls back to PyPI. -When Poetry finds the right package, it then attempts to find the best match -for the version constraint you have specified. +When Poetry finds the right package, it then attempts to find the best match for the version constraint you have +specified. {{% /note %}} - ## Installing dependencies To install the defined dependencies for your project, just run the [`install`]({{< relref "cli#install" >}}) command. @@ -184,7 +200,6 @@ When Poetry has finished installing, it writes all the packages and their exact locking the project to those specific versions. You should commit the `poetry.lock` file to your project repo so that all people working on the project are locked to the same versions of dependencies (more below). - ### Installing with `poetry.lock` This brings us to the second scenario. If there is already a `poetry.lock` file as well as a `pyproject.toml` file diff --git a/docs/contributing.md b/docs/contributing.md index ae2e9e314a8..fabd60d2fb2 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -7,275 +7,256 @@ layout: single menu: docs: weight: 100 ---- - +note: "Are you viewing this document on GitHub? For the best experience, view it on the website https://python-poetry.org/docs/contributing." +--- # Contributing to Poetry First off, thanks for taking the time to contribute! -The following is a set of guidelines for contributing to Poetry on GitHub. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request. - -#### Table of contents - -[How to contribute](#how-to-contribute) - - * [Reporting bugs](#reporting-bugs) - * [Suggesting enhancements](#suggesting-enhancements) - * [Contributing to documentation](#contributing-to-documentation) - * [Contributing to code](#contributing-to-code) - * [Issue triage](#issue-triage) - * [Git workflow](#git-workflow) - +The following is a set of guidelines for contributing to Poetry on GitHub. These are mostly guidelines, not rules. Use +your best judgement, and feel free to propose changes to this document in a pull request. ## How to contribute ### Reporting bugs This section guides you through submitting a bug report for Poetry. -Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports. - -Before creating bug reports, please check [this list](#before-submitting-a-bug-report) to be sure that you need to create one. When you are creating a bug report, please include as many details as possible. Fill out the [required template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---bug-report.md), the information it asks helps the maintainers resolve the issue faster. - -> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. +Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find +related reports. #### Before submitting a bug report -* **Check the [FAQs on the official website](https://python-poetry.org/docs/faq)** for a list of common questions and problems. -* **Check that your issue does not already exist in the [issue tracker](https://github.com/python-poetry/poetry/issues)**. +* **Check the [FAQ]** for a list of common questions and problems. +* **Check the [blog]** for release notes from recent releases, including steps for upgrading and known issues. +* **Check that your issue does not already exist** in the [issue tracker]. +* **Make sure your issue is really a bug, and is not a support request or question** better suited for [Discussions] +or [Discord]. + +{{% note %}} +If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and +include a link to the original issue in the body of your new one. +{{% /note %}} #### How do I submit a bug report? -Bugs are tracked on the [official issue tracker](https://github.com/python-poetry/poetry/issues) where you can create a new one and provide the following information by filling in [the template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---bug-report.md). +Bugs concerning Poetry and poetry-core should be submitted to the main [issue tracker], using the correct +[issue template]. -Explain the problem and include additional details to help maintainers reproduce the problem: +Explain the problem and make it easy for others to search for and understand: * **Use a clear and descriptive title** for the issue to identify the problem. * **Describe the exact steps which reproduce the problem** in as many details as possible. -* **Provide your pyproject.toml file** in a [Gist](https://gist.github.com) after removing potential private information (like private package repositories). -* **Provide specific examples to demonstrate the steps to reproduce the issue**. Include links to files or GitHub projects, or copy-paste-able snippets, which you use in those examples. -* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. +* **Describe the behavior you observed after following the steps** and point out how this is a bug. * **Explain which behavior you expected to see instead and why.** -* **If the problem is an unexpected error being raised**, execute the corresponding command in **debug** mode (the `-vvv` option). +* **If the problem involves an unexpected error being raised**, execute the problematic command in **debug** mode +(with `-vvv` flag). + +Provide detailed steps for reproduction of your issue: + +* **Provide your pyproject.toml file** in a [Gist](https://gist.github.com), pastebin, or example repository after +removing potential private information like private package repositories or names. +* **Provide specific examples to demonstrate the steps to reproduce the issue**. This could be an example repository, a +sequence of steps run in a container, or just a pyproject.toml for very simple cases. +* **Are you unable to reliably reproduce the issue?** If so, provide details about how often the problem happens +and under which conditions it normally happens. Provide more context by answering these questions: -* **Did the problem start happening recently** (e.g. after updating to a new version of Poetry) or was this always a problem? -* If the problem started happening recently, **can you reproduce the problem in an older version of Poetry?** What's the most recent version in which the problem doesn't happen? -* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens. +* **Did the problem start happening recently** (e.g. after updating to a new version of Poetry) or was this always a +problem? +* If the problem started happening recently, **can you reproduce the problem in an older version of Poetry?** What's the +most recent version in which the problem does not happen? +* **Is there anything exotic or unusual about your environment?** This could include use of special container images, +newer CPU architectures like Apple Silicon, or corporate proxies that intercept or modify your network traffic. Include details about your configuration and environment: -* **Which version of Poetry are you using?** You can get the exact version by running `poetry -V` in your terminal. -* **Which Python version Poetry has been installed for?** Execute the `poetry debug info` to get the information. -* **What's the name and version of the OS you're using**? +* **Which version of Poetry are you using?** You can get the exact version by running `poetry --version`. +* **What version of Python is being used to run Poetry?** Execute the `poetry debug info` to get this information. +* **What's the name and version of the OS you're using?** Examples include Ubuntu 22.04 or macOS 12.6. +To give others the best chance to understand and reproduce your issue, please be sure to put extra effort into your +reproduction steps. You can both rule out local configuration issues on your end, and ensure others can cleanly +reproduce your issue if attempt all reproductions in a pristine container (or VM), and provide the steps you performed +inside that container/VM in your issue report. ### Suggesting enhancements -This section guides you through submitting an enhancement suggestion for Poetry, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions. - -Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-an-enhancement-suggestion). Fill in [the template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---feature-request.md), including the steps that you imagine you would take if the feature you're requesting existed. +This section guides you through submitting an enhancement suggestion for Poetry, including completely new features as +well as improvements to existing functionality. Following these guidelines helps maintainers and the community +understand your suggestion and find related suggestions. -#### Before submitting an enhancement suggestion +#### Before submitting a suggested enhancement -* **Check the [FAQs on the official website](https://python-poetry.org/docs/faq)** for a list of common questions and problems. -* **Check that your issue does not already exist in the [issue tracker](https://github.com/python-poetry/poetry/issues)**. +* **Check the [FAQ]** for a list of common questions and problems. +* **Check that your issue does not already exist** in the [issue tracker]. -#### How do I submit an Enhancement suggestion? +#### How do I submit a suggested enhancement? -Enhancement suggestions are tracked on the [official issue tracker](https://github.com/python-poetry/poetry/issues) where you can create a new one and provide the following information: +Suggested enhancements concerning Poetry and poetry-core should be submitted to the main [issue tracker], using the +correct [issue template]. * **Use a clear and descriptive title** for the issue to identify the suggestion. -* **Provide a step-by-step description of the suggested enhancement** in as many details as possible. -* **Provide specific examples to demonstrate the steps**.. -* **Describe the current behavior** and **explain which behavior you expected to see instead** and why. +* **Provide a detailed description of the proposed enhancement**, with specific steps or examples when possible. +* **Describe the current behavior** and **explain which behavior you would like to see instead**, and why. -### Contributing to documentation +### Documentation contributions -One of the simplest ways to get started contributing to a project is through improving documentation. Poetry is constantly evolving, this means that sometimes our documentation has gaps. You can help by -adding missing sections, editing the existing content so it is more accessible or creating new content (tutorials, FAQs, etc). +One of the simplest ways to get started contributing to a project is through improving documentation. Poetry is +constantly evolving, and this means that sometimes our documentation has gaps. You can help by adding missing sections, +editing the existing content to be more accessible, or creating new content such as tutorials, FAQs, etc. {{% note %}} -A great way to understand Poetry's design and how it all fits together, is to add FAQ entries for commonly -asked questions. Poetry members usually mark issues with [candidate/faq](https://github.com/python-poetry/poetry/issues?q=is%3Aissue+label%3Acandidate%2Ffaq+) to indicate that the issue either contains a response -that explains how something works or might benefit from an entry in the FAQ. +Github [Discussions](https://github.com/python-poetry/poetry/discussions) and the +[kind/question label](https://github.com/python-poetry/poetry/labels/kind/question) are excellent sources for FAQ +candidates. {{% /note %}} -Issues pertaining to the documentation are usually marked with the [Documentation](https://github.com/python-poetry/poetry/labels/Documentation) label. +Issues pertaining to the documentation are usually marked with the [area/docs label], which will also trigger a preview +of the changes as rendered by this website. -### Contributing to code +### Code contributions #### Picking an issue {{% note %}} -If you are a first time contributor, and are looking for an issue to take on, you might want to look for [Good First Issue](https://github.com/python-poetry/poetry/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22) -labelled issues. We do our best to label such issues, however we might fall behind at times. So, ask us. +If you are a first time contributor, and are looking for an issue to take on, you might want to look for +at the [contributing page](https://github.com/python-poetry/poetry/contribute) for candidates. We do our best to curate +good issues for first-time contributors there, but do fall behind -- so if you don't see anything good, feel free to +ask. {{% /note %}} -If you would like to take on an issue, feel free to comment on the issue tagging `@python-poetry/triage`. We are more than happy to discuss solutions on the issue. If you would like help with navigating -the code base, join us on our [Discord Server](https://discordapp.com/invite/awxPgve). +If you would like to take on an issue, feel free to comment on the issue tagging `@python-poetry/triage`. +We are more than happy to discuss solutions on the issue. If you would like help with navigating the code base, are +looking for something to work on, or want feedback on a design or change, join us on our [Discord server][Discord] or +start a [Discussion][Discussions]. #### Local development -You will need Poetry to start contributing on the Poetry codebase. Refer to the [documentation](https://python-poetry.org/docs/#introduction) to start using Poetry. +Poetry is developed using Poetry. Refer to the [documentation] to install Poetry in your local environment. {{% note %}} -Local development of Poetry requires Python 3.8 or newer. +Poetry's development toolchain requires Python 3.8 or newer. {{% /note %}} -You will first need to clone the repository using `git` and place yourself in its directory: +You should first fork the Poetry repository and then clone it locally, so that you can make pull requests against the +project. If you are new to Git and pull request based development, GitHub provides a +[guide](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) you will find helpful. -```bash -git clone git@github.com:python-poetry/poetry.git -cd poetry -``` - -{{% note %}} -We recommend that you use a personal [fork](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) for this step. If you are new to GitHub collaboration, -you can refer to the [Forking Projects Guide](https://guides.github.com/activities/forking/). -{{% /note %}} - -Now, you will need to install the required dependency for Poetry and be sure that the current -tests are passing on your machine: +Next, you should install Poetry's dependencies, and run the test suite to make sure everything is working as expected: ```bash poetry install -poetry run pytest tests/ +poetry run pytest ``` -Poetry uses [mypy](https://github.com/python/mypy) for typechecking, and the CI -will fail if it finds any errors. To run mypy locally: +When you contribute to Poetry, automated tools will be run to make sure your code is suitable to be merged. Besides +pytest, you will need to make sure your code typechecks properly using [mypy](http://mypy-lang.org/): ```bash poetry run mypy ``` -Poetry uses the [black](https://github.com/psf/black) coding style and you must ensure that your -code follows it. If not, the CI will fail and your Pull Request will not be merged. - -Similarly, the import statements are sorted with [isort](https://github.com/timothycrosley/isort) -and special care must be taken to respect it. If you don't, the CI will fail as well. - -To make sure that you don't accidentally commit code that does not follow the coding style, you can -install a pre-commit hook that will check that everything is in order: +Finally, a great deal of linting tools are run on your code, to try and ensure consistent code style and root out common +mistakes. The [pre-commit](https://pre-commit.com/) tool is used to install and run these tools, and requires one-time +setup: ```bash poetry run pre-commit install ``` -You can also run it anytime using: +pre-commit will now run and check your code every time you make a commit. By default, it will only run on changed files, +but you can run it on all files manually (this may be useful if you altered the pre-commit config): ```bash poetry run pre-commit run --all-files ``` -Your code must always be accompanied by corresponding tests, if tests are not present your code -will not be merged. - #### Pull requests -* Fill in [the required template](https://github.com/python-poetry/poetry/blob/master/.github/PULL_REQUEST_TEMPLATE.md) -* Be sure that your pull request contains tests that cover the changed or added code. -* If your changes warrant a documentation change, the pull request must also update the documentation. +* Fill out the pull request body completely and describe your changes as accurately as possible. The pull request body +should be kept up to date as it will usually form the base for the final merge commit and the changelog entry. +* Be sure that your pull request contains tests that cover the changed or added code. Tests are generally required for +code be to be considered mergable, and code without passing tests will not be merged. +* Ensure your pull request passes the mypy and pre-commit checks. Remember that you can run these tools locally +instead of relying on remote CI. +* If your changes warrant a documentation change, the pull request must also update the documentation. Make sure to +review the documentation preview generated by CI for any rendering issues. {{% note %}} -Make sure your branch is [rebased](https://docs.github.com/en/free-pro-team@latest/github/using-git/about-git-rebase) against the latest main branch. A maintainer might ask you to ensure the branch is -up-to-date prior to merging your Pull Request if changes have conflicts. +Make sure your branch is [rebased](https://docs.github.com/en/get-started/using-git/about-git-rebase) against the latest +base branch. A maintainer might ask you to ensure the branch is up-to-date prior to merging your pull request +(especially if there have been CI changes on the base branch), and will also ask you to fix any conflicts. {{% /note %}} -All pull requests, unless otherwise instructed, need to be first accepted into the main branch (`master`). +All pull requests, unless otherwise instructed, need to be first accepted into the `master` branch. Maintainers will +generally decide if any backports to other branches are required, and carry them out as needed. ### Issue triage {{% note %}} -If you have an issue that hasn't had any attention, you can ping us `@python-poetry/triage` on the issue. Please, give us reasonable time to get to your issue first, spamming us with messages +If you have an issue that hasn't had any attention, you can ping us `@python-poetry/triage` on the issue. Please give us +reasonable time to get to your issue first, and avoid pinging any individuals directly, especially if they are not part +of the Poetry team. {{% /note %}} -If you are helping with the triage of reported issues, this section provides some useful information to assist you in your contribution. +If you are helping with the triage of reported issues, this section provides some useful information to assist you in +your contribution. #### Triage steps -1. If `pyproject.toml` is missing or `-vvv` debug logs (with stack trace) is not provided and required, request that the issue author provides it. -1. Attempt to reproduce the issue with the reported Poetry version or request further clarification from the issue author. -1. Ensure the issue is not already resolved. You can attempt to reproduce using the latest preview release and/or poetry from the main branch. -1. If the issue cannot be reproduced, - 1. clarify with the issue's author, - 1. close the issue or notify `@python-poetry/triage`. -1. If the issue can be reproduced, - 1. comment on the issue confirming so - 1. notify `@python-poetry/triage`. - 1. if possible, identify the root cause of the issue. - 1. if interested, attempt to fix it via a pull request. +1. Determine what area and versions of Poetry the issue is related to, and set the appropriate labels (e.g. +`version/x.x.x`, `area/docs`, `area/venv`), and remove the `status/triage` label. +2. If requested information (such as debug logs, pyproject.toml, etc.) is not provided and is relevant, request it from +the author. + 1. Set the `status/waiting-on-response` label while waiting to hear back from the author. +3. Attempt to reproduce the issue with the reported Poetry version or request further clarification from the author. +4. Ensure the issue is not already resolved. Try reproducing it on the latest stable release, the latest prerelease (if +present), and the development branch. +5. If the issue cannot be reproduced, + 1. request more reproduction steps and clarification from the issue's author, + 2. set the `status/needs-reproduction` label, + 3. close the issue if there is no reproduction forthcoming. +6. If the issue can be reproduced, + 1. comment on the issue confirming so, + 2. set the `status/confirmed` label, + 3. if possible, identify the root cause of the issue, + 4. if interested, attempt to fix it via a pull request. #### Multiple versions -Often times you would want to attempt to reproduce issues with multiple versions of `poetry` at the same time. For these use cases, the [pipx project](https://pypa.github.io/pipx/) is useful. - -You can set your environment up like so. +When trying to reproduce issues, you often want to use multiple versions of Poetry at the same time. +[pipx](https://pypa.github.io/pipx/) makes this easy to do: ```sh -pipx install --suffix @1.0.10 'poetry==1.0.10' -pipx install --suffix @1.1.0rc1 'poetry==1.1.0rc1' +pipx install --suffix @1.2.1 'poetry==1.2.1' +pipx install --suffix @1.3.0rc1 'poetry==1.3.0rc1' pipx install --suffix @master 'poetry @ git+https://github.com/python-poetry/poetry' -``` - -{{% note %}} -Do not forget to update your `poetry@master` installation in sync with upstream. -{{% /note %}} - -For `@local` it is recommended that you do something similar to the following as editable installs are not supported for PEP 517 projects. +pipx install --suffix @local '/path/to/local/clone/of/poetry' -```sh -# note this will not work for Windows, and we assume you have already run `poetry install` -cd /path/to/python-poetry/poetry -ln -sf $(poetry run which poetry) ~/.local/bin/poetry@local +# now you can use any of the chosen versions of Poetry with their configured suffix, e.g. +poetry@master --version ``` {{% note %}} -This mechanism can also be used to test pull requests. +Do not forget to `pipx upgrade poetry@master` before using it, to make sure you have the latest changes. {{% /note %}} -### Git Workflow - -All development work is performed against Poetry's main branch (`master`). All changes are expected to be submitted and accepted to this -branch. - -#### Release branch - -When a release is ready, the following are required before a release is tagged. - -1. A release branch with the prefix `release-`, eg: `release-1.1.0rc1`. -1. A pull request from the release branch to the main branch (`master`) if it's a minor or major release. Otherwise, to the bug fix branch (eg: `1.0`). - 1. The pull request description MUST include the change log corresponding to the release (eg: [#2971](https://github.com/python-poetry/poetry/pull/2971)). - 1. The pull request must contain a commit that updates [CHANGELOG.md](CHANGELOG.md) and bumps the project version (eg: [#2971](https://github.com/python-poetry/poetry/pull/2971/commits/824e7b79defca435cf1d765bb633030b71b9a780)). - 1. The pull request must have the `Release` label specified. - -Once the branch pull-request is ready and approved, a member of `@python-poetry/core` will, - -1. Tag the branch with the version identifier (eg: `1.1.0rc1`). -2. Merge the pull request once the release is created and assets are uploaded by the CI. - {{% note %}} -In this case, we prefer a merge commit instead of squash or rebase merge. +This mechanism can also be used to test pull requests by using GitHub's pull request remote refs: +```sh +pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head +``` {{% /note %}} -#### Bug fix branch - -Once a minor version (eg: `1.1.0`) is released, a new branch for the minor version (eg: `1.1`) is created for the bug fix releases. Changes identified -or acknowledged by the Poetry team as requiring a bug fix can be submitted as a pull requests against this branch. - -At the time of writing only issues meeting the following criteria may be accepted into a bug fix branch. Trivial fixes may be accepted on a -case-by-case basis. - -1. The issue breaks a core functionality and/or is a critical regression. -1. The change set does not introduce a new feature or changes an existing functionality. -1. A new minor release is not expected within a reasonable time frame. -1. If the issue affects the next minor/major release, a corresponding fix has been accepted into the main branch. - -{{% note %}} -This is subject to the interpretation of a maintainer within the context of the issue. -{{% /note %}} + [Blog]: {{< ref "/blog" >}} + [Documentation]: {{< ref "/docs" >}} + [FAQ]: {{< relref "faq" >}} + [Issue Tracker]: https://github.com/python-poetry/poetry/issues + [area/docs label]: https://github.com/python-poetry/poetry/labels/area/docs + [kind/question label]: https://github.com/python-poetry/poetry/labels/kind/question + [Issue Template]: https://github.com/python-poetry/poetry/issues/new/choose + [Discussions]: https://github.com/python-poetry/poetry/discussions + [Discord]: https://discord.com/invite/awxPgve