# Development Workflow

This document is the detailed contributor workflow guide.

## Environment Setup

```powershell
$env:UV_CACHE_DIR='.uv-cache'
uv sync --extra dev
```

Useful optional environment variables:

```powershell
$env:AWS_PROFILE='free'
$env:AWS_REGION='eu-south-2'
$env:AWSPIPE_HOME="$PWD\.awspipe-home"
```

## Day-to-Day Commands

```powershell
uv run pytest
uv run awspipe tables
uv run awspipe inspect aws_vpc
uv run awspipe query "select * from aws_account" --profile free --region eu-south-2
uv run awspipe cache clear
```

## Non-Live Validation

Run `uv run pytest` after changes. The current suite covers SQL parsing, backend cache behavior, AWS session handling, provider normalization, CLI behavior, and path fallback behavior.

If you change docs only, still verify command names and file references against the current source tree.

## Packaging And Publishing

Build the distributables locally before publishing:

```powershell
$env:UV_CACHE_DIR='.uv-cache'
uv build
```

Validate the generated metadata and long description:

```powershell
$env:UV_CACHE_DIR='.uv-cache'
uvx twine check dist/*
```

Upload to TestPyPI first when changing packaging or README content:

```powershell
$env:UV_CACHE_DIR='.uv-cache'
uv publish --index testpypi
```

Publish to PyPI after TestPyPI succeeds:

```powershell
$env:UV_CACHE_DIR='.uv-cache'
uv publish
```

Release checklist:

- ensure `src/awspipe/__init__.py` contains the intended version
- run `uv run pytest`
- run `uv build`
- run `uvx twine check dist/*`
- verify `README.md` still makes sense when read outside the repository context
- publish to TestPyPI before the first real PyPI release or after metadata changes

## Live Validation

Use `docs/testing-live-aws.md` for the full runbook.

Important reminders:

- live validation may create billable AWS resources
- use a disposable naming suffix
- prefer the documented fixture set
- always clean up before finishing
- if using a `login_session` profile, make sure the login cache is still valid

## Completion and Git Workflow

- Finish the implementation and validation work first.
- Report the outcome to the user before any git publishing step.
- Ask for confirmation before creating a commit and before pushing, unless the user already explicitly requested both actions for the current task.
- When committing, keep the working tree limited to the intended task changes.

## Which Doc to Update

- `README.md`: operator and end-user usage
- `AGENTS.md`: brief repo entrypoint and doc index
- `docs/architecture.md`: high-level runtime architecture
- `docs/codebase-map.md`: source layout and change paths
- `docs/libraries-and-dependencies.md`: dependency rationale and gotchas
- `docs/extending-awspipe.md`: provider/table extension workflow
- `docs/testing-live-aws.md`: live AWS test runbook

## Release Hygiene for Small Changes

- keep docs in sync with the actual CLI commands
- avoid adding hidden behavior without documenting it
- when auth behavior changes, update every doc that mentions profiles or validation
- when cache behavior changes, re-check both the user docs and the contributor docs
