Skip to content

docs: Fix Helloworld Quick Start and document uv non-project alternative#641

Open
Iwaniukooo11 wants to merge 3 commits into
a2aproject:mainfrom
Iwaniukooo11:mateusziwaniuk/helloworld-quickstart-docs-update
Open

docs: Fix Helloworld Quick Start and document uv non-project alternative#641
Iwaniukooo11 wants to merge 3 commits into
a2aproject:mainfrom
Iwaniukooo11:mateusziwaniuk/helloworld-quickstart-docs-update

Conversation

@Iwaniukooo11

Copy link
Copy Markdown
Member

Description

This PR resolves issue #635 where the root README Quick Start for the Python helloworld sample was conflicting with uv's parent project traversal.

Since helloworld does not contain a pyproject.toml file (by design, to favor standard requirements.txt / pip environments), running uv run inside the folder triggers resolution using the parent project's samples/python/pyproject.toml and locks the environment, leading to a ModuleNotFoundError on startup.

Changes

  1. Root README.md:
    • Updated Quick Start instructions to guide users to create a virtual environment (python -m venv .venv) and install dependencies using standard pip (pip install -r requirements.txt).
  2. samples/python/README.md:
    • Re-organized the main running instructions into distinct options: Option A (standard pip + virtualenv) and Option B (uv for pyproject.toml projects).
    • Added an alternative tips section explaining how to run standard requirements.txt samples with uv using non-project mode (uv venv and uv pip install).
    • Cleaned up trailing whitespace and ensured standard newline endings.

Verification

  • Verified both README files are clean of trailing whitespace.
  • Verified that running python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt builds the virtual environment with the correct SDK version (a2a-sdk>=1.1.0) and starts the server successfully.

@Iwaniukooo11 Iwaniukooo11 self-assigned this Jul 14, 2026
@Iwaniukooo11 Iwaniukooo11 added the documentation Improvements or additions to documentation label Jul 14, 2026

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the README documentation to provide alternative setup and execution instructions using standard pip and virtualenv (Option A) alongside the existing uv-based instructions (Option B). The review feedback points out that the instructions for running the host/test clients are missing in both options, and suggests adding these steps to ensure the guides are complete and actionable.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

Comment thread samples/python/README.md
Comment thread samples/python/README.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant