Docs/add quickstart expected results

docs/quickstart_clone_and_ci.md

@@ -43,6 +43,22 @@ git clone https://github.com/michalmaj/modern-python-project-guide.git
 cd modern-python-project-guide
 ```
 
+### Expected result
+
+You should now be inside the cloned repository directory.
+
+Check the current repository state:
+
+```bash
+git status
+```
+
+A clean clone should usually show:
+
+```bash
+working tree clean
+```
+
 ## 2. Install uv
 
 If `uv` is not installed yet, install it first.
@@ -98,6 +114,20 @@ This file stores the Python version used by the project.
 
 It helps `uv` install and use the correct Python version.
 
+### Expected result
+
+A project managed with `uv` should usually contain:
+
+```text
+pyproject.toml
+uv.lock
+.python-version
+```
+
+If one of these files is missing, check the project documentation.
+
+Not every repository uses the same setup, but this guide relies on these files.
+
 ## 4. Sync the local environment
 
 After cloning a project, run:
@@ -106,6 +136,20 @@ After cloning a project, run:
 uv sync
 ```
 
+### Expected result
+
+The local environment should be created or updated.
+
+You should usually see:
+
+```text
+.venv/
+```
+
+This directory is local to your machine.
+
+It should stay ignored by Git.
+
 This creates or updates the local virtual environment.
 
 The environment is usually created in:
@@ -182,6 +226,18 @@ uv run ruff format --check .
 uv run pytest
 ```
 
+### Expected result
+
+If the project is set up correctly:
+
+- Ruff linting should pass,
+- Ruff formatting check should pass,
+- pytest should pass.
+
+If one command fails, read the error message before changing anything.
+
+The error usually tells you what needs to be fixed.
+
 ## 7. When to run uv sync again
 
 Run:
@@ -318,6 +374,23 @@ This workflow runs on:
 - pull requests targeting `main`,
 - pushes to `main`.
 
+### Expected result
+
+After this workflow is committed and pushed to GitHub, pull requests should show a CI check.
+
+A successful run means that GitHub was able to:
+
+- install `uv`,
+- install the requested Python version,
+- sync dependencies from the lockfile,
+- run Ruff linting,
+- check formatting,
+- run tests.
+
+A green CI check does not replace review.
+
+It only confirms that the automated checks passed.
+
 ## 11. Why CI uses the same commands
 
 The CI workflow should run the same checks that developers run locally:

docs/quickstart_uv.md

@@ -55,13 +55,19 @@ Pin the Python version:
 uv python pin 3.12
 ```
 
-This creates:
+### Expected result
+
+At this point, the project should contain:
 
 ```text
 pyproject.toml
 .python-version
 ```
 
+The `pyproject.toml` file describes the Python project.
+
+The `.python-version` file stores the Python version selected for the project.
+
 ## 3. Create the package structure
 
 Create a basic `src/` layout:
@@ -112,6 +118,20 @@ Add `ruff`:
 uv add --group dev ruff
 ```
 
+### Expected result
+
+The project should now contain development dependencies in `pyproject.toml`.
+
+You should also see or update:
+
+```text
+uv.lock
+```
+
+The `uv.lock` file records the exact resolved dependency versions.
+
+Do not edit `uv.lock` manually.
+
 These tools are development dependencies.
 
 They are needed while working on the project, but they are not runtime dependencies of the package.
@@ -128,6 +148,14 @@ uv add rich
 
 This adds `rich` to the project dependencies.
 
+### Expected result
+
+The runtime dependency should appear in the `[project]` dependencies section of `pyproject.toml`.
+
+Development tools such as `pytest` and Ruff should stay in the development dependency group.
+
+This separation keeps runtime dependencies and development tools easy to understand.
+
 Use runtime dependencies only when the actual package needs them.
 
 Do not add test or linting tools as runtime dependencies.
@@ -196,6 +224,19 @@ def test_add_returns_sum() -> None:
     assert result == 5
 ```
 
+### Expected result
+
+The project should now contain:
+
+```text
+src/example_project/calculator.py
+tests/test_calculator.py
+```
+
+The source file contains the function.
+
+The test file verifies the expected behavior.
+
 ## 8. Sync the environment
 
 Run:
@@ -204,6 +245,18 @@ Run:
 uv sync
 ```
 
+### Expected result
+
+After syncing, the project should have a local virtual environment:
+
+```text
+.venv/
+```
+
+The `.venv/` directory is generated locally.
+
+It should not be committed to Git.
+
 This creates or updates the local virtual environment.
 
 It installs the project dependencies and development dependencies needed for the current project setup.
@@ -242,6 +295,22 @@ Format files automatically:
 uv run ruff format .
 ```
 
+### Expected result
+
+If everything is configured correctly:
+
+- `uv run pytest` should pass,
+- `uv run ruff check .` should pass,
+- `uv run ruff format --check .` should pass.
+
+If the formatting check fails, run:
+
+```bash
+uv run ruff format .
+```
+
+Then run the checks again.
+
 ## 10. Lock dependencies
 
 `uv` updates `uv.lock` when dependencies change.