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	done	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: done
priority: high
state_hub_task_id: "5a4dcdf8-7b0f-45cb-8eb1-46b0d60f8420"
started: "2026-05-27 ralph iter 6 (final docs)"
completed: "2026-05-27"

Done.

• Significantly polished the Installation section in README.md to clearly distinguish:
  • Development / bleeding-edge installs (via make dev-install or direct git+)
  • Future path for released versions
• Added references to docs/release-process.md
• Updated AGENTS.md "Commands" section with packaging-related Makefile targets and the current workplan reference.

Acceptance criteria met:

• Both installation methods are now clearly documented and easy to discover in the README.

T07 — Register packaging as a first-class concern

id: CYA-WP-0004-T07
status: done
priority: medium
state_hub_task_id: "f4ea08ab-219e-4e7f-86b9-a05e27b8a72c"
started: "2026-05-27 ralph iter 7 (final)"
completed: "2026-05-27"

Done.

• make check-dist already exists and is promoted as the packaging verification step.
• Added a clear "Debt & Future Work (Registered)" section in the workplan itself, explicitly listing PyPI publishing, automated releases, package signing, CI gates, and multi-Python testing as tracked items in State Hub.
• Packaging is now treated as a first-class, owned concern with documented ownership and a clear path forward.

Acceptance criteria met:

• Packaging is no longer an afterthought — it has documented ownership, verification tooling, and registered future work in State Hub.

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.

Debt & Future Work (Registered)

This workplan explicitly registers the following as first-class technical debt / extension points:

• PyPI publishing workflow
• Automated releases via CI on tags
• Package signing
• Adding make check-dist (or equivalent) as a required CI gate
• Multi-Python version testing for distribution packages

These are now tracked in State Hub via this workplan.

Completion

Status: done — all tasks completed via ralph loop.

This workplan successfully delivered reliable dev-head installation, dynamic versioning, clean distribution package building, a lightweight release process, and clear documentation for both use cases.

Packaging is now a first-class, owned concern in the project with a documented path forward.

---

Status note: CYA-WP-0004 is complete. The project has moved from "only editable install" to having a full, practical story for both bleeding-edge development installs and future proper releases.