Projects, packaging and CI

Versions and version ranges

Most packages use semantic versioning: MAJOR.MINOR.PATCH, such as 2.31.4. Think of changes to a house:

• PATCH goes up for bug fixes that change nothing else, like fixing a dripping tap.
• MINOR goes up for new features that don't break existing code, like adding a room.
• MAJOR goes up for breaking changes, like moving the front door. Upgrading may need code changes.

Dependencies say which versions they accept with a specifier:

Ranges let your project pick up bug fixes. But they mean two installs on different days can get different versions, and "it works on my machine" follows.

A recipe might say "flour". A lockfile names the exact brand and bag. It records the exact version of every package, including the packages your packages need. Commit it, and everyone (including CI and production) installs the same thing. uv is a fast modern tool that manages environments, pyproject.toml and uv.lock together:

uv init shop-report          # create a project
uv add requests              # add a dependency (updates pyproject.toml and uv.lock)
uv run pytest                # run a command inside the project's environment
uv sync                      # install exactly what the lockfile says

In plain words: pyproject.toml says what you'll accept, and the lockfile records what you actually got.

Automatic checks: format, lint, type-check

Before an editor sees a document, it's been through a spell-checker. Three tools catch problems before a human reviewer has to:

• A formatter rewrites code into one consistent style. ruff format (or Black) ends all arguments about spaces and line breaks.
• A linter flags likely bugs and bad patterns: unused imports, undefined names, a bare except:, a mutable default argument. ruff check runs hundreds of rules in a blink.
• A type checker (mypy, pyright) checks the type hints.

ruff format .            # fix formatting
ruff check . --fix       # find (and fix what it safely can) lint problems
mypy src                 # check types
pytest                   # run the tests

A pre-commit hook runs some of these automatically before every commit, so mistakes never reach the repository.

Continuous integration

Continuous integration (CI) means a server runs your checks on every push and every pull request. If anything fails, the change is marked red and can't be merged. Here's a typical GitHub Actions workflow, a YAML file in .github/workflows/:

name: CI
on: [push, pull_request]            # when to run

jobs:
  test:
    runs-on: ubuntu-latest           # a fresh virtual machine each time
    strategy:
      matrix:
        python-version: ["3.12", "3.13"]   # run the job once per version
    steps:
      - uses: actions/checkout@v4                 # get the code
      - uses: astral-sh/setup-uv@v6               # install uv
      - run: uv sync --python ${{ matrix.python-version }}
      - run: uv run ruff check .
      - run: uv run mypy src
      - run: uv run pytest

The fresh machine matters. A recipe tested in an empty kitchen proves it lists everything you need. A clean machine proves the project works from a clean checkout, with only what the lockfile and README say. With branch protection, the repository refuses to merge a pull request until these checks pass.

Continuous delivery (CD) is the next step: every change that passes CI is released automatically, or ready to release with one click. Phase 11 covers deployment.

versions = ["1.10.0", "1.9.3", "1.2.0", "2.0.0"]

print(sorted(versions))                      # as text: wrong!
as_tuples = lambda v: tuple(int(p) for p in v.split("."))
print(sorted(versions, key=as_tuples))       # as numbers: right
print(as_tuples("1.10.0") > as_tuples("1.9.3"))

print("3.10" > "3.9", (3, 10) > (3, 9))

Versions are not text

Here's a bug that's bitten many teams.

print("1.10.0" > "1.9.0")
print((1, 10, 0) > (1, 9, 0))

Compared as text, 1.10.0 comes before 1.9.0, since the character 1 sorts before 9. It's the same reason file names sort as "file10" before "file2". Compare them as numbers, part by part. Use a proper library for this in real code, such as packaging.version.

Why lockfiles matter

pyproject.toml says what you need in general: "requests, version 2 or later". A lockfile records exactly what got installed, down to every package's package. Commit it.

Without it, a new teammate installs on Tuesday and gets a newer version of some library than you have. Their code fails, yours doesn't, and you both lose an afternoon to "works on my machine". With a lockfile, everyone gets the same thing, CI included. You upgrade on purpose, when you're ready to test it.

CI isn't only for big teams

If you work alone, CI is still the cheapest safety net you can have. It runs your tests on every push on a clean machine, so it catches the files you forgot to commit and the setup steps you only ever did by hand. It takes one small file to set up, and it works without being asked.

Keep secrets out of both pyproject.toml and the workflow file, since both are committed and anyone who can read the code can read them. GitHub Actions has a separate secrets store. Use that, and refer to it by name.

Start small

You don't buy a full workshop to hang one shelf. A new project needs surprisingly little: a README, pyproject.toml, a src folder, a tests folder and one CI file. You can add the rest when a real need shows up, rather than copying a huge template you don't understand.