generated from coulomb/repo-seed
87 lines
3.5 KiB
Markdown
87 lines
3.5 KiB
Markdown
# Packaging Audit and Requirements (CYA-WP-0004 T01)
|
||
|
||
**Date:** 2026-05-27
|
||
**Workplan:** CYA-WP-0004
|
||
|
||
## Current State Audit
|
||
|
||
### Packaging Configuration
|
||
- **Build system**: `setuptools` (via `pyproject.toml`)
|
||
- **Version**: Hardcoded as `0.1.0` in two places:
|
||
- `pyproject.toml`
|
||
- `src/cya/__init__.py`
|
||
- **Entry point**: `cya = "cya.cli.main:run"` (correct)
|
||
- **Package discovery**: `src` layout via `[tool.setuptools.packages.find]`
|
||
- **Dependencies**: Minimal (`typer[standard]`, `rich`)
|
||
- **No**:
|
||
- `setuptools_scm` or dynamic versioning
|
||
- `[project.optional-dependencies]`
|
||
- `build` frontend usage
|
||
- `MANIFEST.in` or equivalent include rules
|
||
- `include-package-data` configuration
|
||
- Development/test extras
|
||
- `pyproject.toml` validation for `pip install git+...`
|
||
|
||
### Current Installation Experience
|
||
- Only documented method: `pip install -e .` (editable)
|
||
- `pip install git+https://...` is not reliable (version will be wrong, potential missing files)
|
||
- No released packages exist yet
|
||
|
||
### Gaps Identified
|
||
|
||
**For "Install from Dev Head":**
|
||
- No support for clean `pip install "git+https://github.com/worsch/can-you-assist.git@main"`
|
||
- Version will be stuck at 0.1.0 even on latest code (bad for debugging)
|
||
- Potential missing non-.py files in the sdist/wheel when installing from git
|
||
- No documented one-liner or Makefile target for the primary user
|
||
|
||
**For "Release Packaging":**
|
||
- No versioning strategy (how to bump, dev vs release versions)
|
||
- No process to build clean, reproducible sdist + wheel
|
||
- No `python -m build` usage
|
||
- No release checklist or automation (even lightweight)
|
||
- No way for others to `pip install can-you-assist` (or a future released name)
|
||
|
||
**General Technical Debt:**
|
||
- Version is duplicated in two places (violates DRY)
|
||
- No separation between build-time and runtime concerns
|
||
- No packaging tests or verification step
|
||
|
||
## Requirements for CYA-WP-0004
|
||
|
||
### Must-Have for Dev-Head Install
|
||
1. `pip install "git+https://github.com/worsch/can-you-assist.git"` (and `@main`, `@branch`) must produce a working `cya` with a dev-informative version.
|
||
2. The primary user must have a simple, documented way to stay on latest code.
|
||
3. Version must clearly indicate it is from development head (e.g., `0.2.0.devN+g<hash>` or similar).
|
||
|
||
### Must-Have for Release Packaging
|
||
1. A clear, repeatable process to cut a new version.
|
||
2. Ability to produce clean `sdist` + `wheel` using modern tools (`python -m build`).
|
||
3. Version must be single-source-of-truth.
|
||
4. Documentation in README + AGENTS.md for both installation methods.
|
||
|
||
### Nice-to-Have (in scope if low cost)
|
||
- Makefile targets for common operations (`make dev-install`, `make dist`, `make check-dist`)
|
||
- Basic CI step that verifies packaging works
|
||
- Optional dependencies (e.g., `[dev]`, `[test]`)
|
||
|
||
## Versioning Strategy Recommendation (for T02)
|
||
|
||
**Recommended approach: Hybrid using `setuptools_scm`**
|
||
|
||
- For development/git installs: Automatic versions like `0.3.0.dev14+g3f2a1b7.d20260527`
|
||
- For releases: Clean versions like `0.3.0`
|
||
- Single source of truth in git tags + `pyproject.toml` configuration
|
||
- Minimal changes to existing workflow
|
||
|
||
**Alternative (simpler but less powerful):** Keep static version + manual bumps + release checklist. Only use if `setuptools_scm` is deemed overkill.
|
||
|
||
**Decision needed in T02.**
|
||
|
||
## Next Steps
|
||
|
||
- T02 will decide and implement the versioning approach.
|
||
- T03 will focus on making git-based installs reliable.
|
||
- T04–T05 will focus on the release side.
|
||
|
||
This audit serves as the requirements baseline for the rest of the workplan. |