docs(readme): normalize README structure#557
Conversation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (2)
WalkthroughRewrote README to a condensed 13-section layout (removed TOC, project-structure, verbose architecture prose, tests/releases sections), added AI Commands, adjusted API/Quick Start/Containers content, and introduced a new RELEASES.md describing v{SEMVER}-{COACH} release workflow, checklist, tagging, and Docker pull examples. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Assessment against linked issues
Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #557 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 3 3
Lines 114 114
=========================================
Hits 114 114
🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
RELEASES.md (2)
39-39: Add explicit reference to the valid coach list.The checklist item mentions validating the coach name and alphabetical order, but doesn't indicate where to find the authoritative list. Users need to know where to verify against.
📝 Proposed clarification
-- [ ] Coach name is valid and follows alphabetical order (see [famous coach list](CHANGELOG.md)) +- [ ] Coach name is valid and follows alphabetical order (see coach list in [CHANGELOG.md](CHANGELOG.md) or [`.github/workflows/python-cd.yml`](.github/workflows/python-cd.yml))🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@RELEASES.md` at line 39, The checklist item "Coach name is valid and follows alphabetical order (see [famous coach list](CHANGELOG.md))" lacks an explicit pointer to the authoritative list; update that checklist entry in RELEASES.md to explicitly reference the valid coach list location (e.g., "see 'Famous Coaches' section in CHANGELOG.md" or include a link/anchor to the exact section), so reviewers know to verify names against the "Famous Coaches" section in CHANGELOG.md and confirm alphabetical order.
3-3: Specify where to find the complete coach list.Line 3 references the "famous coach list" in CHANGELOG.md, but the actual list is hardcoded in
.github/workflows/python-cd.yml(lines 53-54). To prevent confusion and ensure consistency, consider adding an inline reference to the exact location or list the coaches directly in this document.📋 Proposed addition to clarify coach list location
-Releases follow the pattern `v{SEMVER}-{COACH}` (e.g., `v1.0.0-ancelotti`). Codenames are drawn alphabetically from the [famous coach list](CHANGELOG.md). +Releases follow the pattern `v{SEMVER}-{COACH}` (e.g., `v1.0.0-ancelotti`). Codenames are drawn alphabetically from the famous coach list (see [CHANGELOG.md](CHANGELOG.md) or [`.github/workflows/python-cd.yml`](.github/workflows/python-cd.yml) for the authoritative list).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@RELEASES.md` at line 3, Update RELEASES.md to point to the canonical coach list source by either adding a short sentence that the "famous coach list" is the hardcoded list used by the release CI (the GitHub Actions workflow named python-cd.yml) or by copying that list directly into RELEASES.md; reference the exact identifier "famous coach list" and the workflow name python-cd.yml so readers know where the authoritative list resides and avoid divergence.README.md (3)
213-222: Consider maintenance implications of duplicating Docker pull examples.Lines 213-222 duplicate the same Docker pull examples found in
RELEASES.md:65-74. While this improves user convenience by keeping relevant information in both locations, it creates a maintenance burden—any future changes to tag format or examples must be updated in both files.Consider either:
- Keeping the examples in both places if user convenience is the priority
- Referencing
RELEASES.mdfrom README for the full details and keeping only a minimal example hereExample minimal approach:
-Each release publishes multiple tags for flexibility: +Each release publishes multiple tags for flexibility. See [RELEASES.md](RELEASES.md) for complete documentation. ```bash # By semantic version (recommended for production) docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:1.0.0 - -# By coach name (memorable alternative) -docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:ancelotti - -# Latest release -docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:latest<details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@README.mdaround lines 213 - 222, The README currently duplicates the Docker
pull examples that exist in RELEASES.md; update README.md to avoid maintenance
drift by replacing the full three-line Docker pull block (the lines showing
"docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:1.0.0",
":ancelotti", and ":latest") with a minimal example (e.g., only the
semantic-version example) and add a one-line pointer/reference to RELEASES.md
for full tag examples and details; modify the README.md code block to contain
only the minimal example and a sentence like "See RELEASES.md for full tagging
options" so future tag format changes are centralized in RELEASES.md.</details> --- `278-280`: **Clarify what "AI Commands" are and how to use them.** The AI Commands subsection lists `/pre-commit` and `/pre-release` without explaining what these commands are, where to run them, or what tool interprets them (GitHub Copilot CLI, custom tooling, etc.). New contributors may be confused about how to use these. <details> <summary>📚 Proposed clarification</summary> ```diff | **AI Commands** | | +| _GitHub Copilot CLI commands for common workflows_ | | | `/pre-commit` | Runs linting, tests, and quality checks before committing | | `/pre-release` | Runs pre-release validation workflow |Or add a brief note above the table:
## Command Summary + +> 💡 **AI Commands** are GitHub Copilot CLI commands. Run them in your terminal with Copilot installed. | Command | Description |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 278 - 280, Add a short explanatory note above the "AI Commands" table that defines what "AI Commands" refers to (e.g., repository-provided chat/CLI commands or GitHub Copilot CLI), where to run them (local terminal, PR comment, or via GitHub Actions), and any prerequisites (installing the interpreting tool and authentication). Specifically reference the two commands `/pre-commit` and `/pre-release`, give one-line examples for how to invoke them (e.g., run locally with the tool or comment on a PR), and mention expected behavior (runs lint/tests or runs pre-release validation) so contributors know how and when to use them.
127-127: Clarify the distinction between FastAPI validation errors (422) and endpoint-specific 400 errors.Line 127 states "400 Bad Request (validation failed)", but FastAPI's Pydantic validation failures return
422 Unprocessable Entityby default, not 400. The 400 status code inroutes/player_route.py:214is raised specifically for squad_number mismatch on PUT operations, which is a semantic validation error, not a general schema validation failure.📝 Proposed clarification
-Error codes: `400 Bad Request` (validation failed) · `404 Not Found` (player not found) · `409 Conflict` (duplicate squad number on `POST`) +Error codes: `400 Bad Request` (squad number mismatch on `PUT`) · `404 Not Found` (player not found) · `409 Conflict` (duplicate squad number on `POST`) · `422 Unprocessable Entity` (schema validation failed)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 127, Update the README line that currently conflates general FastAPI/Pydantic validation (which returns 422 Unprocessable Entity) with endpoint-specific 400 errors: change the description to list 422 for schema/parameter validation errors and keep 400 for the semantic squad_number mismatch raised in the PUT handler (see the squad_number check in routes/player_route.py at the PUT logic around the code that raises 400). Ensure the README explicitly documents 422 for Pydantic validation failures and 400 for the endpoint's semantic validation (duplicate squad number on POST remains 409).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@RELEASES.md`:
- Line 48: The RELEASES.md shows an annotated tag example using "git tag -a
v1.0.0-ancelotti -m …" but the CD workflow only checks the tag name pattern
"v*.*.*-*" and not whether the tag is annotated; either update the CD workflow's
tag validation step to also detect and require annotated tags (inspect the ref
for an annotated tag object when the pipeline runs) or change RELEASES.md to say
annotation is optional and keep the "git tag" example as one option — update the
doc or the workflow accordingly so behavior and docs match.
---
Nitpick comments:
In `@README.md`:
- Around line 213-222: The README currently duplicates the Docker pull examples
that exist in RELEASES.md; update README.md to avoid maintenance drift by
replacing the full three-line Docker pull block (the lines showing "docker pull
ghcr.io/nanotaboada/python-samples-fastapi-restful:1.0.0", ":ancelotti", and
":latest") with a minimal example (e.g., only the semantic-version example) and
add a one-line pointer/reference to RELEASES.md for full tag examples and
details; modify the README.md code block to contain only the minimal example and
a sentence like "See RELEASES.md for full tagging options" so future tag format
changes are centralized in RELEASES.md.
- Around line 278-280: Add a short explanatory note above the "AI Commands"
table that defines what "AI Commands" refers to (e.g., repository-provided
chat/CLI commands or GitHub Copilot CLI), where to run them (local terminal, PR
comment, or via GitHub Actions), and any prerequisites (installing the
interpreting tool and authentication). Specifically reference the two commands
`/pre-commit` and `/pre-release`, give one-line examples for how to invoke them
(e.g., run locally with the tool or comment on a PR), and mention expected
behavior (runs lint/tests or runs pre-release validation) so contributors know
how and when to use them.
- Line 127: Update the README line that currently conflates general
FastAPI/Pydantic validation (which returns 422 Unprocessable Entity) with
endpoint-specific 400 errors: change the description to list 422 for
schema/parameter validation errors and keep 400 for the semantic squad_number
mismatch raised in the PUT handler (see the squad_number check in
routes/player_route.py at the PUT logic around the code that raises 400). Ensure
the README explicitly documents 422 for Pydantic validation failures and 400 for
the endpoint's semantic validation (duplicate squad number on POST remains 409).
In `@RELEASES.md`:
- Line 39: The checklist item "Coach name is valid and follows alphabetical
order (see [famous coach list](CHANGELOG.md))" lacks an explicit pointer to the
authoritative list; update that checklist entry in RELEASES.md to explicitly
reference the valid coach list location (e.g., "see 'Famous Coaches' section in
CHANGELOG.md" or include a link/anchor to the exact section), so reviewers know
to verify names against the "Famous Coaches" section in CHANGELOG.md and confirm
alphabetical order.
- Line 3: Update RELEASES.md to point to the canonical coach list source by
either adding a short sentence that the "famous coach list" is the hardcoded
list used by the release CI (the GitHub Actions workflow named python-cd.yml) or
by copying that list directly into RELEASES.md; reference the exact identifier
"famous coach list" and the workflow name python-cd.yml so readers know where
the authoritative list resides and avoid divergence.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 2f05a727-76a7-47fd-9e40-cece5cf4e691
📒 Files selected for processing (2)
README.mdRELEASES.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
|
Addressing the 4 dismissed nitpick comments from the review: README: Docker pull duplication (lines 213–222) — The full pull block in the Containers section is intentional. All six sibling repos follow the same pattern — the section is meant to be self-contained so a reader doesn't have to navigate to a separate file just to pull an image. README: AI Commands explanation (lines 278–280) — Adding a prose explanation would break consistency with the Java and TypeScript sibling repos, which have the same section without extra context. The commands are self-descriptive within this project's conventions. RELEASES.md: CD workflow reference (line 3) — RELEASES.md: Coach list pointer (line 39) — Fixed in the latest commit: the checklist item now explicitly references the "Release Naming Convention" section in |
1 participant
Closes #556
Summary
Method | Endpoint | Description | StatustableRELEASES.md— adds missing "Merge the Release PR" step (CD enforces reachable-from-master gate)🤖 Generated with Claude Code
This change is
Summary by CodeRabbit