From 9c2ccef2ee8931c49c958db033a8913f496a627f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Maj?= Date: Sat, 26 Sep 2026 12:32:11 +0200 Subject: [PATCH] docs: standardize project terminology --- CONTRIBUTING.md | 13 +++++++++++++ README.md | 2 +- docs/02_uv.md | 4 ++-- docs/ROADMAP.md | 9 +++------ docs/cheatsheet.md | 2 +- docs/common_questions.md | 2 +- docs/example_pull_request.md | 6 +++--- docs/from_script_to_project.md | 4 ++-- docs/markdown_review.md | 4 ++-- docs/quickstart_uv.md | 4 ++-- docs/troubleshooting.md | 4 ++-- 11 files changed, 32 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f921848..f28c70e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -169,6 +169,19 @@ merging are disabled to keep that history consistent. After a pull request is merged, GitHub deletes its remote branch automatically. Delete the corresponding local branch after updating `main`. +## Documentation terminology + +Use the official spelling of tool names: `uv` and pytest are lowercase, while +Ruff is capitalized in prose. Keep command names and configuration keys in code +format. + +Call the ordered set of core chapters the **main learning path**. Call the +supporting quickstarts, troubleshooting pages, and focused guides +**reference material**. + +When a documentation example reproduces this repository's `pyproject.toml`, +keep its dependency constraints aligned with the real configuration. + ## Local checks Before opening a pull request with code changes, run the local quality checks: diff --git a/README.md b/README.md index 09d1b7c..8185309 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![CI](https://github.com/michalmaj/modern-python-project-guide/actions/workflows/ci.yml/badge.svg)](https://github.com/michalmaj/modern-python-project-guide/actions/workflows/ci.yml) A practical, beginner-friendly guide to building a clean Python project with -`uv`, `pytest`, Ruff, `pyproject.toml`, GitHub Actions, and a pull request based +`uv`, `pytest`, Ruff, `pyproject.toml`, GitHub Actions, and a pull-request-based workflow. This repository is both a tutorial and a working example. It introduces each diff --git a/docs/02_uv.md b/docs/02_uv.md index 6cdd436..cce7289 100644 --- a/docs/02_uv.md +++ b/docs/02_uv.md @@ -102,8 +102,8 @@ Examples: ```bash uv init --package uv sync -uv add pytest --dev -uv add ruff --dev +uv add --group dev pytest +uv add --group dev ruff uv run pytest uv run ruff check . uv run ruff format . diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 11df0c5..a5f99b8 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -122,15 +122,12 @@ These parts are already included in the repository. - [x] Separate the main learning path from reference material - [x] Add previous and next navigation to the core chapters - [x] Review commit history and self-review coverage in the existing guides +- [x] Standardize terminology and dependency examples across the documentation ## Next These are good candidates for upcoming small pull requests. -### Documentation polish - -- [ ] Review terminology consistency - ### Repository polish - [ ] Add issue templates only if the repository starts receiving external feedback @@ -141,7 +138,7 @@ These are good candidates for upcoming small pull requests. - [ ] Consider `Makefile` as an optional convenience layer - [ ] Consider `just` as an alternative task runner -Task runners should not replace the basic commands in the first learning path. +Task runners should not replace the basic commands in the main learning path. They should be introduced only as convenience wrappers after the underlying commands are clear. @@ -193,7 +190,7 @@ They may be added later as separate chapters. ## Not planned for the first version -These are deliberately excluded from the first learning path: +These are deliberately excluded from the main learning path: - Docker, - publishing to PyPI, diff --git a/docs/cheatsheet.md b/docs/cheatsheet.md index 679fe57..50535e9 100644 --- a/docs/cheatsheet.md +++ b/docs/cheatsheet.md @@ -4,7 +4,7 @@ This page is a quick command reference. It does not explain every concept in detail. -For explanations, use the full guide and quickstarts. +For explanations, use the main learning path and quickstarts. ## Project setup diff --git a/docs/common_questions.md b/docs/common_questions.md index 12c37fb..2a692ef 100644 --- a/docs/common_questions.md +++ b/docs/common_questions.md @@ -211,7 +211,7 @@ This repository focuses on the Python project foundation first: Docker can be introduced later when there is a clear reason for it. -Adding it too early would make the guide heavier without helping the core learning path. +Adding it too early would make the guide heavier without helping the main learning path. ## Why not add pre-commit? diff --git a/docs/example_pull_request.md b/docs/example_pull_request.md index 47b8c78..e198528 100644 --- a/docs/example_pull_request.md +++ b/docs/example_pull_request.md @@ -120,7 +120,7 @@ The `Why` section explains the motivation. Good example: ```text -Readers who already understand the concepts may want a compact command reference instead of searching through the full guide. +Readers who already understand the concepts may want a compact command reference instead of searching through the main learning path. ``` Bad example: @@ -217,7 +217,7 @@ Summary: Adds a command cheatsheet for common project, uv, Ruff, pytest, Git, and CI commands. Why: -Readers who already understand the concepts may want a compact command reference instead of searching through the full guide and quickstarts. +Readers who already understand the concepts may want a compact command reference instead of searching through the main learning path and quickstarts. Changes: - Adds docs/cheatsheet.md @@ -351,4 +351,4 @@ I understand why it changed. I know how it was checked. ``` -If the reviewer has to guess, improve the pull request description before asking for review. \ No newline at end of file +If the reviewer has to guess, improve the pull request description before asking for review. diff --git a/docs/from_script_to_project.md b/docs/from_script_to_project.md index cbe1224..64ddcea 100644 --- a/docs/from_script_to_project.md +++ b/docs/from_script_to_project.md @@ -247,8 +247,8 @@ build-backend = "uv_build" [dependency-groups] dev = [ - "pytest>=8.0.0", - "ruff>=0.11.0", + "pytest>=9.0.3", + "ruff>=0.15.12", ] [tool.pytest.ini_options] diff --git a/docs/markdown_review.md b/docs/markdown_review.md index 0e178d9..e8c5cde 100644 --- a/docs/markdown_review.md +++ b/docs/markdown_review.md @@ -336,7 +336,7 @@ Examples of topics that should not be pushed into the foundation too early: These topics may be useful later. -They should not distract from the first learning path. +They should not distract from the main learning path. ## Check tone @@ -405,4 +405,4 @@ The maintainer checks correctness. The reader checks clarity. -A good documentation change should satisfy both. \ No newline at end of file +A good documentation change should satisfy both. diff --git a/docs/quickstart_uv.md b/docs/quickstart_uv.md index c305739..7bebe34 100644 --- a/docs/quickstart_uv.md +++ b/docs/quickstart_uv.md @@ -184,8 +184,8 @@ build-backend = "uv_build" [dependency-groups] dev = [ - "pytest>=8.0.0", - "ruff>=0.11.0", + "pytest>=9.0.3", + "ruff>=0.15.12", ] [tool.pytest.ini_options] diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 7e91bda..8b201b4 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -170,8 +170,8 @@ Check that `pyproject.toml` contains something similar to: ```toml [dependency-groups] dev = [ - "pytest>=8.0.0", - "ruff>=0.11.0", + "pytest>=9.0.3", + "ruff>=0.15.12", ] ```