Contributing

Short guide for working on v8x.

Environment Setup

Use the Installation Guide for CLI installation. For repository development, follow the root project setup instructions in the source tree.

Run tests:

just unit

Project Structure (CLI)

v8x/
    main.py        # Entry (Typer)
    auth.py        # Auth + persona
    cache.py       # Token cache helpers
    client.py      # HTTP helpers
    gql_client.py  # GraphQL client factory
    config.py      # Settings + profiles
    constants.py   # Paths & consts
    exceptions.py  # Error hierarchy
    schemas.py     # Pydantic models
    format.py      # Output formatting

Adding a Command

import typer
from v8x.config import attach_settings

app = typer.Typer()

@app.command()
@attach_settings
async def ping(ctx: typer.Context):
        """Simple connectivity check."""
        typer.echo(ctx.obj.settings.api_base_url)

Register the sub-app in main.py.

Standards

• Python 3.12+
• Type hints required
• --json for structured output where useful
• Minimal side effects in library functions

Testing

just lint

just typecheck

just unit

just integration

Write focused tests for each new command (happy + error path).

Logging & Errors

• Use Abort (if provided) for user-facing failures
• Add -v to surface debug logs when diagnosing
• Avoid leaking tokens or raw tracebacks

Submitting Changes

1. Branch
2. Update / add tests
3. Lint & type check (if configured)
4. Write concise PR description

Release (Internal)

• Bump version (pyproject.toml)
• Update CHANGELOG
• Tag & publish

Communication

Open issues with steps, expected vs actual, environment info.

---

Thanks for contributing.