Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
258 lines (182 loc) · 5.58 KB

CONTRIBUTING.md

File metadata and controls

258 lines (182 loc) · 5.58 KB
Raw

Contributing Guide

Thank you for your interest in this project.

This repository is built step by step as a practical guide to modern Python project development. The goal is not only to show the final project structure, but also to demonstrate a clean and realistic development workflow.

Main idea

Every meaningful change should be small, focused, and easy to review.

This project uses a simple workflow:

create a branch → make a small change → commit → push → open a pull request → review → merge

Branches

Do not commit directly to main. Create a separate branch for each meaningful change. Recommended branch name format:

<type>/<short-description>

Examples:

docs/add-project-roadmap
docs/add-contributing-guide
chore/configure-uv
test/add-text-statistics-tests
ci/add-github-actions-workflow

Use short, descriptive names.

Good branch names:

docs/add-pull-request-guide
chore/configure-ruff
test/add-basic-tests

Avoid vague branch names:

changes
updates
stuff
fixes
new-files

Commits

Use small, readable commits.

Recommended commit message format:

<type>: <short description>

Examples:

docs: add project roadmap
docs: add contributing guide
chore: configure uv project
test: add tests for text statistics
ci: add GitHub Actions workflow

Common commit types:

docs     - documentation changes
chore    - project setup, configuration, maintenance
feat     - new functionality
test     - tests
fix      - bug fixes
ci       - continuous integration changes
refactor - code changes without changing behavior

Good commit messages:

docs: add contributing guide
chore: configure ruff
test: add whitespace normalization tests

Avoid unclear commit messages:

update
fix
changes
work
final
final2

Pull requests

Every meaningful change should be introduced through a pull request.

A good pull request should:

  • have a clear title,
  • describe what changed,
  • explain why the change was made,
  • be small enough to review comfortably,
  • include tests or documentation when needed.

Good pull request title examples:

docs: add contributing guide
chore: configure uv project
ci: add GitHub Actions workflow

Avoid vague pull request titles:

Update files
Some changes
Work in progress

Review mindset

A pull request is not only a technical step.

It is also a communication tool.

When opening a pull request, try to make the reviewer’s job easy:

  • keep the change focused,
  • avoid unrelated edits,
  • explain non-obvious decisions,
  • mention follow-up work if needed.

Merging pull requests

The main branch is protected.

Before a pull request can be merged:

  • the branch must be up to date with main,
  • the Quality checks CI check must pass,
  • review conversations must be resolved.

This repository uses merge commits. On GitHub, choose:

Create a merge commit

Merge commits preserve the focused commits from the branch and make the pull request boundary visible in the project history. Squash merging and rebase 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.

When relevant documentation files change, the separate Documentation workflow publishes the reviewed site after the merge. This deployment is not a pull request check and does not replace the required Quality checks status.

Documentation terminology

Use the official spelling of tool names: uv, pytest, mypy, rumdl, and pre-commit are lowercase, while Ruff and MkDocs are 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

Install the repository's fast pre-commit hooks once in each clone:

uv run pre-commit install

To check every tracked file manually, run:

uv run pre-commit run --all-files

Hooks provide quick feedback, but they do not replace the complete checks below.

Preview documentation changes with uv run mkdocs serve when navigation or rendering matters. Stop the local server with Ctrl+C.

Before opening a pull request with code changes, run the local quality checks:

uv run ruff check .
uv run ruff format --check .
uv run rumdl check .
uv run mkdocs build --strict
uv run pytest --cov=text_toolkit --cov-report=term-missing
uv run mypy
uv build --no-sources

If formatting fails, run:

uv run ruff format .

Then repeat the checks:

uv run ruff check .
uv run ruff format --check .
uv run rumdl check .
uv run mkdocs build --strict
uv run pytest --cov=text_toolkit --cov-report=term-missing
uv run mypy
uv build --no-sources

For documentation-only changes, code checks may not always be necessary.

However, review the rendered Markdown on GitHub after opening the pull request.

The goal is to catch simple issues locally before CI runs on GitHub.

Project philosophy

This repository should stay beginner-friendly, but not careless.

The goal is to teach professional habits without overwhelming the reader.

That means:

  • simple examples,
  • clear explanations,
  • small changes,
  • readable history,
  • realistic development practices.

Advanced tools should be introduced only when the basic workflow is already clear.