docs: add usage guide for contributors on existing Poetry projects (#8131)

[nothing-991]

Hey everyone! 👋

I added a new section to the documentation for people who want to contribute to a project that already uses Poetry.

Right now, the basic usage guide mostly covers creating new projects, which can be a bit confusing if you just want to get started contributing to an existing project.

What’s included:

• How to install all project dependencies (poetry install)
• How to activate the virtual environment (poetry shell)
• How to run commands within the environment (poetry run <command>)
• How to add new dependencies if needed (poetry add <package-name> or dev dependencies)
• A pointer to the existing “Basic Usage” guide for creating new projects

This change is purely documentation, so it won’t affect how Poetry works—just makes it easier for newcomers to contribute.

Fixes / relates to issue: #8131

Summary by Sourcery

Documentation:

• Add a contributor-focused section explaining how to install dependencies, use the virtual environment, run commands, and manage dependencies in existing Poetry-managed projects.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Adds a new documentation subsection to the basic usage guide that explains how contributors should work with an existing Poetry-managed project, including installing dependencies, using the virtual environment, running commands, and adding dependencies, with links back to project creation docs.

Flow diagram for contributor setup workflow with an existing Poetry project

flowchart TD
  A[Contributor clones project that uses Poetry] --> B[Navigate to project directory]
  B --> C[Run poetry install to create virtualenv and install dependencies]
  C --> D{How to work in the environment?}
  D --> E[Activate subshell with poetry shell]
  D --> F[Run individual commands with poetry run command]
  E --> G[Develop, run tests, and tools inside subshell]
  F --> G
  G --> H{Need new dependency?}
  H --> I[Add runtime dependency with poetry add package_name]
  H --> J[Add dev dependency to dev group if project uses one]
  H --> K[Edit pyproject.toml directly if project guidelines require]
  I --> L[Poetry updates pyproject.toml and lock file]
  J --> L
  K --> L
  L --> M[Continue contributing using project environment]
  A -.-> N[If goal is a new project, follow Basic Usage project creation docs]

Loading

File-Level Changes

Change	Details	Files
Introduce a contributor-focused subsection explaining workflow for existing Poetry projects.	Add a new heading describing usage of Poetry in an existing project for contributors. Explain that contributors normally do not reinitialize Poetry and rely on the existing pyproject.toml configuration. Describe installing all project dependencies and dev dependencies using Poetry, including virtual environment creation behavior. Describe two ways of working inside the environment: activating a shell or running individual commands via Poetry. Outline how to add new runtime and development-only dependencies and note that some projects may prefer manual pyproject.toml edits. Add guidance pointing readers back to the project creation and initialization sections when starting a new project instead of contributing to an existing one.	docs/basic-usage.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• The new contributor section is very high-level prose; consider adding a few concrete command examples (e.g., poetry install, poetry shell, poetry run pytest, poetry add <package> --group dev) as code blocks to make it immediately actionable for readers.
• There is a minor wording/formatting issue in “pyproject.tomlfile” where a space is missing before “file”; a quick pass for similar small typos in the new section would improve readability.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The new contributor section is very high-level prose; consider adding a few concrete command examples (e.g., `poetry install`, `poetry shell`, `poetry run pytest`, `poetry add <package> --group dev`) as code blocks to make it immediately actionable for readers.
- There is a minor wording/formatting issue in “`pyproject.toml`file” where a space is missing before “file”; a quick pass for similar small typos in the new section would improve readability.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[nothing-991]

I’ve added the suggested command examples and fixed the minor typo. Ready for review again.