diff --git a/README.md b/README.md index ac5c42a..0e72146 100644 --- a/README.md +++ b/README.md @@ -86,6 +86,12 @@ New to project tooling terms? Read the [Glossary](docs/glossary.md). +## Cheatsheet + +Need commands only? + +Read the [Command cheatsheet](docs/cheatsheet.md). + ## Why these tools? This guide uses a small set of tools that cover the basic needs of a modern Python project: diff --git a/docs/cheatsheet.md b/docs/cheatsheet.md new file mode 100644 index 0000000..e5504f1 --- /dev/null +++ b/docs/cheatsheet.md @@ -0,0 +1,294 @@ +# Command Cheatsheet + +This page is a quick command reference. + +It does not explain every concept in detail. + +For explanations, use the full guide and quickstarts. + +## Project setup + +Create a new project: + +```bash +mkdir example-python-project +cd example-python-project +uv init --bare --name example-python-project --python 3.12 +uv python pin 3.12 +``` + +Create a basic `src/` layout: + +```bash +mkdir -p src/example_project tests +touch src/example_project/__init__.py +touch src/example_project/calculator.py +touch tests/test_calculator.py +``` + +Windows PowerShell: + +```powershell +New-Item -ItemType Directory -Force src/example_project +New-Item -ItemType Directory -Force tests +New-Item -ItemType File -Force src/example_project/__init__.py +New-Item -ItemType File -Force src/example_project/calculator.py +New-Item -ItemType File -Force tests/test_calculator.py +``` + +## Dependencies + +Add a runtime dependency: + +```bash +uv add package-name +``` + +Example: + +```bash +uv add rich +``` + +Add a development dependency: + +```bash +uv add --group dev package-name +``` + +Examples: + +```bash +uv add --group dev pytest +uv add --group dev ruff +``` + +Sync the local environment: + +```bash +uv sync +``` + +Lock dependencies explicitly: + +```bash +uv lock +``` + +## Running tools + +Run tests: + +```bash +uv run pytest +``` + +Run Ruff linting: + +```bash +uv run ruff check . +``` + +Check formatting: + +```bash +uv run ruff format --check . +``` + +Format files: + +```bash +uv run ruff format . +``` + +Run all local checks: + +```bash +uv run ruff check . +uv run ruff format --check . +uv run pytest +``` + +## Fix formatting and recheck + +If formatting fails: + +```bash +uv run ruff format . +uv run ruff check . +uv run ruff format --check . +uv run pytest +``` + +## Clone an existing project + +```bash +git clone https://github.com/your-username/your-project.git +cd your-project +uv sync +``` + +Then run: + +```bash +uv run ruff check . +uv run ruff format --check . +uv run pytest +``` + +## Git workflow + +Update `main`: + +```bash +git switch main +git pull +``` + +Create a branch: + +```bash +git switch -c docs/example-change +``` + +Check changed files: + +```bash +git status +``` + +Stage a file: + +```bash +git add path/to/file.md +``` + +Commit: + +```bash +git commit -m "docs: describe example change" +``` + +Push the branch: + +```bash +git push -u origin docs/example-change +``` + +After the pull request is merged: + +```bash +git switch main +git pull +git branch -d docs/example-change +``` + +## Useful commit message examples + +Documentation: + +```text +docs: add project glossary +docs: explain pytest +docs: update README quickstarts +``` + +Project configuration: + +```text +chore: initialize uv project +chore: configure ruff +chore: add editorconfig +``` + +Tests: + +```text +test: add text statistics tests +``` + +CI: + +```text +ci: add GitHub Actions workflow +``` + +Feature code: + +```text +feat: add text toolkit package +``` + +## GitHub Actions CI + +Minimal CI workflow commands: + +```bash +uv python install +uv sync --locked +uv run ruff check . +uv run ruff format --check . +uv run pytest +``` + +CI should use: + +```bash +uv sync --locked +``` + +Local development usually uses: + +```bash +uv sync +``` + +## Files to commit + +Usually commit: + +```text +README.md +CONTRIBUTING.md +LICENSE +pyproject.toml +uv.lock +.python-version +.github/ +docs/ +src/ +tests/ +``` + +Do not commit: + +```text +.venv/ +__pycache__/ +.pytest_cache/ +.ruff_cache/ +.coverage +htmlcov/ +``` + +## Quick local checklist + +Before opening a pull request with code changes: + +```bash +git status +uv sync +uv run ruff check . +uv run ruff format --check . +uv run pytest +``` + +Before merging: + +```text +CI is green +PR title is clear +PR description explains what changed and why +Diff has been reviewed +No unrelated files are included +``` \ No newline at end of file