can-you-assist/workplans/CYA-WP-0004-dev-install-and-release-packaging.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
CYA-WP-0004	workplan	Developer Installation from Git and Release Distribution Packaging	capabilities	can-you-assist	active	grok	foerster-capabilities	2026-05-27	2026-05-27	7913b919-d76b-4374-bdc6-0330fe941666

CYA-WP-0004: Developer Installation from Git and Release Distribution Packaging

Goal

Enable two important installation and distribution experiences for can-you-assist (cya):

1. Easy installation from development head
   Anyone (especially the primary user and contributors) can install the absolute latest code directly from the git repository with a simple, reliable command, including all current features and fixes.

2. Repeatable release packaging
   Provide a clear, low-friction process to cut versions and produce installable distribution packages (sdist + wheel) that others can use via pip install without needing to clone the repository or understand the development setup.

This workplan addresses the current gap where only pip install -e . (editable development install) is supported, and there is no documented or automated path for either "bleeding edge" installs or proper releases.

Background & References

• Current packaging is minimal (pyproject.toml using setuptools with a static version = "0.1.0").
• Editable development install (pip install -e .) works and is documented in README and AGENTS.md.
• No support yet for pip install git+https://... in a robust way.
• No versioning strategy, no release process, no build frontend usage, and no distribution artifacts.
• The project has matured through CYA-WP-0001 (MVP), 0002 (Memory), and 0003 (Contextual Activation + Retrospection), making proper distribution increasingly important.
• AGENTS.md and README currently only document the editable development path.

Non-Goals (for this slice)

• Publishing packages to PyPI (the output of this workplan should be usable with a future PyPI publication step).
• Complex multi-platform CI matrix or release automation beyond a solid local + basic CI foundation.
• Supporting ancient Python versions or exotic packaging backends.
• Creating a full "release engineering" platform (this is scoped to getting reliable dev-head + released packages working).

Task Breakdown

T01 — Audit current packaging state and define requirements

id: CYA-WP-0004-T01
status: done
priority: high
state_hub_task_id: "018d0c4c-948e-4cd6-9a50-92a83725df18"
started: "2026-05-27 ralph iter 1"
completed: "2026-05-27"

Done — produced docs/packaging-audit-and-requirements.md.

• 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

id: CYA-WP-0004-T02
status: done
priority: high
state_hub_task_id: "0728680e-f9a9-4229-afcc-6c4d42d2e447"
started: "2026-05-27 ralph iter 2"
completed: "2026-05-27"

Done — implemented setuptools_scm hybrid approach.

• pyproject.toml now uses dynamic versioning with setuptools_scm.
• Added src/cya/_version.py (generated, gitignored).
• Updated src/cya/__init__.py to import __version__ from the generated file (with fallback).
• Added _version.py to .gitignore.
• Dev-head installs will now produce versions like 0.2.0.devN+g<hash>.
• Releases will be clean (once we tag).

Acceptance criteria met:

• Versioning is now dynamic and informative for dev-head installs.
• Clean path for future release versions.

T03 — Make reliable installation from development head possible

id: CYA-WP-0004-T03
status: done
priority: high
state_hub_task_id: "14e085dd-847a-4678-a1e4-abe5e3c369aa"
started: "2026-05-27 ralph iter 3"
completed: "2026-05-27"

Done.

• Added [project.optional-dependencies] dev and test in pyproject.toml.
• Created a simple but effective Makefile with:
  • make dev-install (recommended one-command dev-head install)
  • make test, make dist, make version, make clean
• Heavily updated README.md "Installation" section with clear instructions for:
  • Local dev-head install via Makefile
  • Direct pip install "git+..." from GitHub
  • Future released packages
• Updated AGENTS.md Commands section to reference the new make dev-install flow.
• With setuptools_scm from T02, git-based installs now produce proper development versions.

Acceptance criteria met:

• Primary user (and contributors) now have a simple, documented one-command path to install the absolute latest code from the development head.
• The installed version will clearly show it is a development version.

T04 — Enable clean building of distribution packages

id: CYA-WP-0004-T04
status: done
priority: high
state_hub_task_id: "d49a3362-865f-4397-b127-372a2aa2c4a2"
started: "2026-05-27 ralph iter 4"
completed: "2026-05-27"

Done.

• Created MANIFEST.in for proper sdist inclusion.
• Improved pyproject.toml (include-package-data, license-files under setuptools, package-data).
• python -m build successfully produces clean sdist + wheel.
• Verified in isolated venv: the wheel installs cleanly and cya --version works (shows proper dev version from setuptools_scm).

Acceptance criteria met:

• Clean, usable distribution packages can now be built.
• They install and run correctly in fresh environments.

T05 — Create a lightweight release process

id: CYA-WP-0004-T05
status: done
priority: medium
state_hub_task_id: "c97acc58-14d7-47b9-9ab3-936ab1eb92df"
started: "2026-05-27 ralph iter 5"
completed: "2026-05-27"

Done.

• Created docs/release-process.md — a clear, step-by-step, low-risk release checklist covering version decision → tests → build → tagging.
• Enhanced the Makefile with two very useful release targets:
  • make release-prep (runs clean + test + dist in one go)
  • make check-dist (smoke-tests the built wheel in a fresh venv)
• The process is fully reproducible and documented.

Acceptance criteria met:

• A maintainer now has a written checklist + Makefile helpers that make cutting a release feel safe and boring.
• The process produces ready-to-upload artifacts.

T06 — Update documentation for both installation methods

id: CYA-WP-0004-T06
status: todo
priority: high
state_hub_task_id: "5a4dcdf8-7b0f-45cb-8eb1-46b0d60f8420"

• Update README.md with clear sections for:
  • Development / bleeding-edge install (from git)
  • Installing a released version (when available)
• Update AGENTS.md "Commands" section.
• Add any necessary notes in the new workplan or a dedicated packaging guide.

Acceptance criteria:

• Both installation methods are clearly documented and discoverable by someone reading the README.

T07 — Register packaging as a first-class concern

id: CYA-WP-0004-T07
status: todo
priority: medium
state_hub_task_id: "f4ea08ab-219e-4e7f-86b9-a05e27b8a72c"

• Add basic packaging verification to the development workflow (e.g., make check-dist or a CI step).
• Document known limitations and future improvements (e.g., PyPI publishing, automated releases, signed packages).
• Register this area as an extension point / debt item in State Hub via the workplan.

Acceptance criteria:

• Packaging is no longer an afterthought — it has documented ownership and a path forward.

Dependencies & Cross-Repo Coordination

• No hard external dependencies on other tracked repositories for the core work.
• Future PyPI publication may involve coordination with whatever hosting or automation is chosen later.
• State Hub will be used to track the workplan and any packaging-related decisions or debt.

Activation & Ralph Execution

Status: active — activated for ralph-workplan loop execution (HEUREKA promise, max 20 iterations). This workplan addresses the practical gap where only editable development installs were supported, by enabling reliable installation from the development head and creating a repeatable process for versioning and building distribution packages.

---

Status note: This workplan closes an important practical gap. It makes cya usable from the latest code for the primary user and creates the foundation for proper releases.