DEVELOPER.md¶

Prerequisites: Set Up Machine¶

View hidden files and folders
View file extensions
Git
VS Code (recommended)
uv

Fork and Clone Repository¶

Fork the repo.
Clone your repo to your machine and open it in VS Code.

Open a terminal and run the following commands.

git clone https://github.com/civic-interconnect/civic-lib-geo.git
cd civic-lib-geo

Dev 1. One-time setup¶

Open the repo directory in VS Code.
Open a terminal in VS Code (examples use PowerShell commands on Windows machine).

uv python pin 3.12
uv venv

.venv\Scripts\activate # Windows
# source .venv/bin/activate  # Mac/Linux/WSL

uv sync --extra dev --extra docs --upgrade
uv run pre-commit install

Dev 2. Validate Local Changes¶

git pull origin main
uvx pre-commit autoupdate
git add .
uvx ruff check . --fix
uvx ruff format .
uvx deptry .
uvx pyright
uv run pytest

Run the project hooks (twice, if needed):

uv run pre-commit run --all-files

DEV 3. Build and Inspect Package¶

uv build

$TMP = New-Item -ItemType Directory -Path ([System.IO.Path]::GetTempPath()) -Name ("wheel_" + [System.Guid]::NewGuid())
Expand-Archive dist\*.whl -DestinationPath $TMP.FullName
Get-ChildItem -Recurse $TMP.FullName | ForEach-Object { $_.FullName.Replace($TMP.FullName + '\','') }
Remove-Item -Recurse -Force $TMP

DEV 4. Build and Preview Docs¶

uv run mkdocs build --strict
uv run mkdocs serve

Verify local API docs at: http://localhost:8000 When done reviewing, use CTRL c or CMD c to quit.

DEV 5. Clean Artifacts (Optional)¶

Get-ChildItem -Path . -Recurse -Directory -Filter "*__pycache__*" | Remove-Item -Recurse -Force
Get-ChildItem -Path . -Recurse -Directory -Filter ".*_cache"  | Remove-Item -Recurse -Force
Get-ChildItem -Path "src" -Recurse -Directory -Name "*.egg-info" | Remove-Item -Recurse -Force
Remove-Item -Path "build", "dist", "site" -Recurse -Force

DEV 6. Test¶

Update CHANGELOG.md and pyproject.toml dependencies. Ensure CI passes.

uv run pre-commit run --all-files
uv run pytest -q

DEV 7. Git add-commit-push Changes¶

git add .
git commit -m "Prep vx.y.z"
git push -u origin main

DEV 8. Git tag and Push tag¶

Important: Wait for GitHub Actions from prior step to complete successfully (all green checks). If any fail, fix issues and push again before tagging.

git tag vx.y.z -m "x.y.z"
git push origin vx.y.z

A GitHub Action will build, publish to PyPI (Trusted Publishing), create a GitHub Release with artifacts, and deploy versioned docs with mike.

You do not need to run gh release create or upload files manually.