Skip to content

Developer Setup Guide

Complete workstation setup for new contributors to the XO-Data platform.

Prerequisites

Python 3.12+

Verify your Python version:

python3 --version

If you need Python 3.12+, install via python.org or your system package manager.

uv (Python package manager)

All dependency management in this repo uses uv. Never use pip directly.

macOS / Linux:

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

macOS (Homebrew):

brew install uv

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

Verify: uv --version

GitHub CLI (gh)

Required for all project management operations (issues, PRs, labels, project fields).

macOS (Homebrew):

brew install gh

Other platforms: See cli.github.com/manual/installation.

Verify: gh --version

GitHub CLI Authentication

1. Authenticate

gh auth login

Follow the prompts: select GitHub.com, choose HTTPS, and authenticate via browser.

2. Add GitHub Projects scopes

The default login does not include the scopes needed to read and write GitHub Projects (org-level). After logging in, run:

gh auth refresh -h github.com -s read:project,project

This opens a browser to approve the additional scopes. These are required for any gh project command.

3. Verify

gh auth status

Expected output includes github.com with Token scopes: ..., project, read:project.

Repo Setup

1. Clone

git clone <repository-url>
cd xo-data

2. Install dependencies

uv sync

This installs all workspace packages and their dependencies.

3. Configure git hooks

python build.py

This installs nbstripout, which strips Jupyter notebook outputs on commit. Pass mac, linux, or win explicitly if auto-detection fails.

Environment Variables

Create a .env file at the repo root (never commit this file):

# Snowflake
SNOWFLAKE_ACCOUNT=
SNOWFLAKE_USER=
SNOWFLAKE_PASSWORD=
SNOWFLAKE_WAREHOUSE=

# AWS
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=

# Gladly
GLADLY_API_USER=
GLADLY_API_TOKEN=
GLADLY_ORG=

Ask a team member for the values. The .env file is gitignored — never commit credentials.

Verification

After setup, confirm everything works:

# Type checking (run per package)
uv run ty check packages/xo-core
uv run ty check packages/xo-foundry

# Linting
uv run ruff check packages/xo-core
uv run ruff check packages/xo-foundry

# GitHub CLI
gh repo view xtendops-developers/xo-data --json name,owner
gh project list --owner xtendops-developers

All three uv run commands should pass with zero errors. The gh commands should return repo and project data without auth errors.

Coming Soon

The following sections will be added as the team documents these procedures:

  • Snowflake CLI (snow) — Local query access, connection profile setup → see bootstrap-setup.md
  • AWS CLI — Local S3 access for pipeline development
  • dbt profiles — Local dbt runs against dev databases → see dbt-development-workflow.md
  • IDE setup — VS Code extensions, Claude Code configuration
  • xo-bosun CLI — Monorepo tooling

Next Steps

Once your environment is set up:

  • Read GitHub Projects Workflow for the issue and PR workflow
  • Read .claude/CLAUDE.md for Claude Code conventions in this repo
  • Run uv sync --package xo-foundry if working on Airflow DAGs
  • Run uv sync --package analytics if working on analytics notebooks