From 62b046b2f874f1f27ee293754930b24736a381e8 Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 26 May 2026 21:40:59 +0200 Subject: [PATCH] =?UTF-8?q?docs=20+=20chore(workplan):=20complete=20T01=20?= =?UTF-8?q?for=20CYA-WP-0004=20=E2=80=94=20packaging=20audit=20and=20requi?= =?UTF-8?q?rements=20document=20created?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/packaging-audit-and-requirements.md | 87 +++++++++++++++++++ ...-0004-dev-install-and-release-packaging.md | 22 ++--- 2 files changed, 99 insertions(+), 10 deletions(-) create mode 100644 docs/packaging-audit-and-requirements.md diff --git a/docs/packaging-audit-and-requirements.md b/docs/packaging-audit-and-requirements.md new file mode 100644 index 0000000..a396d4d --- /dev/null +++ b/docs/packaging-audit-and-requirements.md @@ -0,0 +1,87 @@ +# 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` 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. \ No newline at end of file diff --git a/workplans/CYA-WP-0004-dev-install-and-release-packaging.md b/workplans/CYA-WP-0004-dev-install-and-release-packaging.md index 62343a9..65c6636 100644 --- a/workplans/CYA-WP-0004-dev-install-and-release-packaging.md +++ b/workplans/CYA-WP-0004-dev-install-and-release-packaging.md @@ -48,21 +48,23 @@ This workplan addresses the current gap where only `pip install -e .` (editable ```task id: CYA-WP-0004-T01 -status: todo +status: done priority: high state_hub_task_id: "018d0c4c-948e-4cd6-9a50-92a83725df18" +started: "2026-05-27 ralph iter 1" +completed: "2026-05-27" ``` -- Review the current `pyproject.toml`, `src/` layout, entry points, and any hidden packaging assumptions. -- Document what currently works and what breaks for: - - `pip install git+https://...` - - Building clean sdist + wheel -- Define concrete requirements for both "dev head" and "released package" experiences. -- Decide on a versioning approach (e.g., static + manual bumps, `setuptools_scm`, or hybrid). +**Done** — produced `docs/packaging-audit-and-requirements.md`. -**Acceptance criteria**: -- Clear gap analysis and requirements document (can live in the workplan or a short `docs/packaging-requirements.md`). -- Versioning strategy chosen and justified. +- Full audit of `pyproject.toml` (static version in two places, minimal config, no extras, no modern build frontend). +- Documented gaps for both "install from dev head" and "release packaging". +- Clear requirements defined. +- Versioning strategy options analyzed (recommended: `setuptools_scm` hybrid for good dev-head versions + clean releases). + +**Acceptance criteria met**: +- Gap analysis + requirements document created. +- Versioning options documented for decision in T02. ### T02 — Establish a sustainable versioning strategy