python-poetry / python-poetry/poetry

"Basic Usage" guide may include specific instructions for existing poetry projects

Open
#8,131 2 comments 0 reactions 1 assignee View on GitHub

@Secrus is already working on this.

Since Sep 25, 2024.

area/docs status/triage
Dominant language
Python
Stars
34.3k
Forks
2.5k
Avg merge
2d 19h
Merged PRs (30d)
30

Description

  • I have searched the issues of this repo and believe that this is not a duplicate.

Background

I am very new to poetry. I bumped into a first project I want to contribute to which uses poetry. So, to contribute to that project, I needed/wanted to learn on how to use poetry in the first place.

Issue

Currently, the basic usage guide seems targeted to users who discovered poetry and want to apply it to a project of their own (either a completely new one or an already existing one).
That is different from when you first bump into a project, which already uses poetry, which IMO may happen more often.

So I think it makes sense to build another variant of a "basic usage" guide targeted to "users" which only want to contribute to a project using poetry, as most parts of the current "basic usage" don't apply to them. IMO it should answer following questions:

  • Can poetry help you to set up a venv with all listed requirements?
    • yes
  • How can you use it?
    • poetry install && poetry shell (mind shell will open a new subshell because …)
  • What if I want to add another requirement?
    • poetry add or edit pyproject.toml manually
  • Any other parts I might have missed which might be important to "users" as well
  • What if I want to set up a new project?
    • link to the current basic usage guide

Alternative Solution

Maybe its good enough to add just a small section with an header explaining which parts of basic usage are most relevant if trying to use poetry on an already existing and configured project.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.