Contributing to Poetry

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.

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 submitting a bug report #

• 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.

How do I submit a bug report? #

Bugs concerning Poetry and poetry-core should be submitted to the main issue tracker, using the correct issue template.

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.
• 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 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, 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 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 --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 as well as improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.

Before submitting a suggested enhancement #

• 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 a suggested enhancement? #

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

Documentation contributions #

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.

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.

Code contributions #

Picking an issue #

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 or start a Discussion.

Local development #

Poetry is developed using Poetry. Refer to the documentation to install Poetry in your local environment.

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 you will find helpful.

Next, you should install Poetry’s dependencies, and run the test suite to make sure everything is working as expected:

poetry install
poetry run pytest

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:

poetry run mypy

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 tool is used to install and run these tools, and requires one-time setup:

poetry run pre-commit install

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):

poetry run pre-commit run --all-files

Pull requests #

• 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 mergeable, 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.

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 #

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

When trying to reproduce issues, you often want to use multiple versions of Poetry at the same time. pipx makes this easy to do:

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'
pipx install --suffix @local '/path/to/local/clone/of/poetry'

# now you can use any of the chosen versions of Poetry with their configured suffix, e.g.
poetry@master --version

pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head