Skip to content

environment-setup.md

Latest commit

 

History

History
156 lines (105 loc) · 3.39 KB

environment-setup.md

File metadata and controls

156 lines (105 loc) · 3.39 KB
Raw

Environment Setup

This guide walks you through setting up a development environment for the darnit project, from a fresh clone to running tests.

Prerequisites

You'll need the following tools installed:

Tool Minimum Version Purpose
Python 3.11+ Runtime (project targets 3.11/3.12)
uv Latest Dependency management and task runner
Git 2.x Version control
GitHub CLI (gh) Latest GitHub API access for integration tests

Platform: macOS and Linux are the primary development platforms. Windows users should use WSL (Windows Subsystem for Linux).

Installing Prerequisites

Python 3.11+:

# macOS (Homebrew)
brew install python@3.12

# Ubuntu/Debian
sudo apt install python3.12 python3.12-venv

# Verify
python3 --version

uv:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify
uv --version

GitHub CLI:

# macOS
brew install gh

# Ubuntu/Debian
# See https://github.com/cli/cli/blob/trunk/docs/install_linux.md

# Verify
gh --version

Fork and Clone

This project uses a fork-based workflow. All contributions come through pull requests from your fork.

1. Fork the repository

Go to github.com/kusari-oss/darnit and click Fork.

2. Clone your fork

git clone https://github.com/YOUR-USERNAME/darnit.git
cd darnit

3. Add the upstream remote

git remote add upstream https://github.com/kusari-oss/darnit.git

4. Verify remotes

git remote -v

Expected output:

origin    https://github.com/YOUR-USERNAME/darnit.git (fetch)
origin    https://github.com/YOUR-USERNAME/darnit.git (push)
upstream  https://github.com/kusari-oss/darnit.git (fetch)
upstream  https://github.com/kusari-oss/darnit.git (push)

Install Dependencies

uv sync

This installs all packages in the workspace (darnit, darnit-baseline, darnit-testchecks) in development mode with all dependencies.

Authenticate GitHub CLI

Many integration tests and audit commands use the GitHub API. Authenticate the CLI:

gh auth login

Follow the prompts to authenticate. You can verify with:

gh auth status

Verify Your Setup

Run these commands to confirm everything works:

Run all tests

uv run pytest tests/ --ignore=tests/integration/ -q

Expected: all tests pass.

Run the linter

uv run ruff check .

Expected: no errors.

Validate spec sync

uv run python scripts/validate_sync.py --verbose

Expected: all checks pass.

If any of these fail, see the Troubleshooting Guide.

Staying Up to Date

Before starting new work, always sync with upstream:

git fetch upstream
git rebase upstream/main

This keeps your fork's history clean and avoids merge conflicts.

Next Steps