From 8803ba1a951c85e8f9a145e80c536fec834cf1b8 Mon Sep 17 00:00:00 2001 From: Erik Schaareman Date: Wed, 22 Apr 2026 22:29:56 +0200 Subject: [PATCH 1/3] docs(changelog): align 1.3.x entries with tag history --- CHANGELOG.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6bd9b43..cf06c4a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,26 +1,18 @@ # Changelog -## 1.3.6 - 2026-04-22 - -Release build determinism fix. - -### Fixed in 1.3.6 - -- Fixed release version resolution by relying on strict tag-based dynamic versioning instead of a CI-only bypass override. -- Fixed dynamic version resolution for this repository's unprefixed tags by setting `tool.poetry-dynamic-versioning.pattern = "default-unprefixed"`. -- Fixed dynamic versioning misconfiguration by enabling `tool.poetry-dynamic-versioning.strict = true`, so CI fails instead of silently falling back to `0.0.0` when no valid tag is found. -- Added `tool.poetry.requires-plugins` so Poetry 2.x installations know the project requires `poetry-dynamic-versioning[plugin]`. -- Reduced configuration churn in PEP 621 mode by moving `tool.poetry.version` to the bottom of the `[tool.poetry]` table, matching the plugin's documented behavior. - ## 1.3.5 - 2026-04-22 -Release version resolution compatibility fixes. +Release version resolution and tagging alignment fixes. ### Fixed in 1.3.5 - Fixed `poetry dynamic-versioning` CI failures by removing unsupported `tool.poetry-dynamic-versioning.fallback-version` config. - Fixed release builds resolving to `0.0.0` by switching to `project.dynamic = ["version"]` and moving the placeholder version to `tool.poetry.version`, so `poetry-dynamic-versioning` can inject the computed tag version correctly. -- Fixed `pyproject.toml` inline documentation to reflect current fallback behavior when no git tag is reachable. +- Fixed dynamic version resolution for this repository's unprefixed tags by setting `tool.poetry-dynamic-versioning.pattern = "default-unprefixed"`. +- Fixed dynamic versioning misconfiguration by enabling `tool.poetry-dynamic-versioning.strict = true`, so CI fails instead of silently falling back to `0.0.0` when no valid tag is found. +- Added `tool.poetry.requires-plugins` so Poetry 2.x installations know the project requires `poetry-dynamic-versioning[plugin]`. +- Fixed intermittent incorrect release versions by forcing build-time dynamic versioning to the computed release output via `POETRY_DYNAMIC_VERSIONING_BYPASS`. +- Fixed `pyproject.toml` inline documentation to reflect strict mode behavior when no valid git tag/version can be resolved. ## 1.3.4 - 2026-04-22 From 0d88e4bf7f5882cdd709804b58c1d211ff2cda4c Mon Sep 17 00:00:00 2001 From: Erik Schaareman Date: Wed, 22 Apr 2026 22:34:40 +0200 Subject: [PATCH 2/3] docs(changelog): keep 1.3.5 changelog-only and align 1.3.4 scope --- CHANGELOG.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cf06c4a..732aebd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,17 +2,11 @@ ## 1.3.5 - 2026-04-22 -Release version resolution and tagging alignment fixes. +Changelog alignment update. -### Fixed in 1.3.5 +### Changed in 1.3.5 -- Fixed `poetry dynamic-versioning` CI failures by removing unsupported `tool.poetry-dynamic-versioning.fallback-version` config. -- Fixed release builds resolving to `0.0.0` by switching to `project.dynamic = ["version"]` and moving the placeholder version to `tool.poetry.version`, so `poetry-dynamic-versioning` can inject the computed tag version correctly. -- Fixed dynamic version resolution for this repository's unprefixed tags by setting `tool.poetry-dynamic-versioning.pattern = "default-unprefixed"`. -- Fixed dynamic versioning misconfiguration by enabling `tool.poetry-dynamic-versioning.strict = true`, so CI fails instead of silently falling back to `0.0.0` when no valid tag is found. -- Added `tool.poetry.requires-plugins` so Poetry 2.x installations know the project requires `poetry-dynamic-versioning[plugin]`. -- Fixed intermittent incorrect release versions by forcing build-time dynamic versioning to the computed release output via `POETRY_DYNAMIC_VERSIONING_BYPASS`. -- Fixed `pyproject.toml` inline documentation to reflect strict mode behavior when no valid git tag/version can be resolved. +- Corrected changelog version history from 1.3.0 onward so entries align with actual created tags and release chronology. ## 1.3.4 - 2026-04-22 @@ -22,6 +16,8 @@ Release build versioning fix: explicit plugin activation and full history checko - Fixed CI release builds still producing `0.0.0` artifacts by calling `poetry dynamic-versioning` explicitly before `poetry build`. Poetry reads the version once at load time — the plugin must be active and called before the build step runs. - Fixed release build tag visibility by setting `fetch-depth: 0` on the tag-pinned checkout so `git describe` can traverse full history. +- Fixed dynamic versioning compatibility in `pyproject.toml` by switching to PEP 621 dynamic versioning (`project.dynamic = ["version"]`) and keeping the placeholder at `tool.poetry.version`. +- Fixed `poetry dynamic-versioning` compatibility by removing unsupported `tool.poetry-dynamic-versioning.fallback-version`. - Fixed release race conditions by adding workflow `concurrency` controls, including serialized main release execution. - Fixed release integrity by creating the GitHub release only after PyPI publish succeeds. - Fixed tag existence validation to check `refs/tags/` directly instead of a generic ref lookup. From 535cc50a0e46e4788040abb73a2684a4616f82be Mon Sep 17 00:00:00 2001 From: Erik Schaareman Date: Wed, 22 Apr 2026 23:13:34 +0200 Subject: [PATCH 3/3] chore(pypi): align 1.3.5 changelog and package metadata --- .github/copilot-instructions.md | 8 +++ CHANGELOG.md | 9 +++- README-pypi.md | 96 +++++++++++++++++++++++++++++++++ pyproject.toml | 37 ++++++++++++- 4 files changed, 148 insertions(+), 2 deletions(-) create mode 100644 README-pypi.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 96cc833..de060ff 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -113,6 +113,14 @@ For hand-authored Markdown in this repository, treat baseline docs as a coherent - Prefer consistency across related docs: if `README.md`, architecture docs, and workflow docs describe the same flow, they should use compatible terminology and diagram style. - When modernizing older docs, convert diagrams selectively rather than mechanically. Preserve useful content first, then improve presentation. +## PyPI README Sync Rules + +- `README.md` is the canonical full documentation for GitHub rendering. +- `README-pypi.md` is the PyPI-compatible long description source referenced by `pyproject.toml`. +- Whenever `README.md` changes in a way that affects installation, usage, positioning, links, or badges, update `README-pypi.md` in the same change. +- Keep `README-pypi.md` minimal and PyPI-safe: no Mermaid blocks, no relative documentation links, and no `` markup. +- Use absolute GitHub URLs in `README-pypi.md` for cross-document links and images. + ## Python Docstring Style For Python modules in this repository, treat code as the source of truth and keep docstrings aligned with shipped behavior. diff --git a/CHANGELOG.md b/CHANGELOG.md index 732aebd..12c7f7f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,11 +2,18 @@ ## 1.3.5 - 2026-04-22 -Changelog alignment update. +Changelog and PyPI packaging metadata alignment update. ### Changed in 1.3.5 - Corrected changelog version history from 1.3.0 onward so entries align with actual created tags and release chronology. +- Switched published long description source from `README.md` to `README-pypi.md` for PyPI-compatible rendering. +- Added PyPI-focused project metadata in `pyproject.toml`: `keywords`, `classifiers`, and `project.urls`. +- Added explicit repository guidance to keep `README-pypi.md` in sync with `README.md`. + +### Added in 1.3.5 + +- Added a dedicated `README-pypi.md` with PyPI-safe links, badges, and a concise DX-first quickstart. ## 1.3.4 - 2026-04-22 diff --git a/README-pypi.md b/README-pypi.md new file mode 100644 index 0000000..bd64473 --- /dev/null +++ b/README-pypi.md @@ -0,0 +1,96 @@ +# vstack + +[![PyPI version](https://img.shields.io/pypi/v/vstack?color=0B8A6F)](https://pypi.org/project/vstack/) +[![Python version](https://img.shields.io/badge/python-3.11--3.14-0B8A6F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml) +[![Verify status](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/verify.yml?branch=main&label=verify&color=1D6FA5)](https://github.com/eschaar/vstack/actions/workflows/verify.yml) +[![Security checks](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/security.yml?branch=main&label=security&color=B15E00)](https://github.com/eschaar/vstack/actions/workflows/security.yml) +[![Runtime: stdlib only](https://img.shields.io/badge/runtime-stdlib%20only-5B6C8F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml) +[![License: MIT](https://img.shields.io/github/license/eschaar/vstack?color=5F7A1F)](https://github.com/eschaar/vstack/blob/main/LICENSE) +[![GitHub Discussions](https://img.shields.io/badge/discussions-ask%20%26%20share-blueviolet?logo=github)](https://github.com/eschaar/vstack/discussions) + +![vstack logo](https://raw.githubusercontent.com/eschaar/vstack/main/assets/branding/vstack.png) + +The VS Code-native AI workflow system for backend engineering. + +vstack installs structured agents, skills, instructions, and prompts into `.github/` so GitHub Copilot Agent Mode can run repeatable backend workflows with clear role boundaries. + +It provides a fixed role model for end-to-end software delivery: `product`, `architect`, `designer`, `engineer`, `tester`, and `release`. + +## Best for + +- Backend and API teams using GitHub Copilot Agent Mode in VS Code +- Repositories that want consistent planning, implementation, verification, and release flow +- Teams that want reusable AI workflows instead of one-off prompt crafting + +## What you get + +- Fixed role model: `product`, `architect`, `designer`, `engineer`, `tester`, `release` +- Template-driven install model from `src/vstack/_templates/` +- Backend-first verification, security, and release discipline +- Standard-library-only runtime dependencies + +## Quick start + +Install with `pipx`, then install vstack artifacts into your repository: + +```bash +pipx install vstack +vstack install --target /path/to/your/project +vstack validate +``` + +Run a first task in Copilot Agent Mode: + +```text +@tester /verify Check this repository and summarize findings +``` + +Expected result: + +- `vstack validate` reports no unresolved template tokens +- Agent command returns a concrete verification summary for your repository + +## Why this helps + +- Consistent role boundaries for planning, implementation, validation, and release +- Reusable skills and instructions instead of ad hoc prompts +- Better release hygiene with documented workflows and CI alignment + +## Core commands + +```bash +vstack --version +vstack validate +vstack install --target /path/to/your/project +vstack verify --target /path/to/your/project +``` + +## Common usage patterns + +Repository-scoped install (recommended for teams): + +```bash +vstack install --target /path/to/your/project +``` + +Profile-wide install (optional defaults for all projects): + +```bash +vstack install --global +``` + +## Fast troubleshooting + +- Command not found after install: ensure your `pipx` binary path is in `PATH` +- Validation error: rerun `vstack install --target ...` and then `vstack validate` +- Agent results look generic: explicitly invoke a role (for example `@tester`) before a skill + +## Full documentation + +For complete documentation (including architecture details, workflow diagrams, and contributor guides), use GitHub: + +- [GitHub repository](https://github.com/eschaar/vstack) +- [Full README](https://github.com/eschaar/vstack/blob/main/README.md) +- [Documentation](https://github.com/eschaar/vstack/tree/main/docs) +- [Contributing guide](https://github.com/eschaar/vstack/blob/main/CONTRIBUTING.md) +- [Security policy](https://github.com/eschaar/vstack/blob/main/SECURITY.md) diff --git a/pyproject.toml b/pyproject.toml index 96ce1bd..ae6d959 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,9 +3,44 @@ name = "vstack" dynamic = ["version"] description = "VS Code-native AI engineering workflow system for microservices, libraries, and backend systems." license = "MIT" -readme = "README.md" +readme = "README-pypi.md" requires-python = ">=3.11,<3.15" dependencies = [] +keywords = [ + "github-copilot", + "vscode", + "ai-workflows", + "developer-tools", + "devx", + "engineering-workflow", + "copilot-agent-mode", + "backend", + "microservices", + "api", + "workflow-automation", + "release-engineering", +] +classifiers = [ + "License :: OSI Approved :: MIT License", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", + "Environment :: Console", + "Intended Audience :: Developers", + "Topic :: Software Development :: Build Tools", + "Topic :: Software Development :: Libraries :: Python Modules", +] + +[project.urls] +Homepage = "https://github.com/eschaar/vstack" +Documentation = "https://github.com/eschaar/vstack/blob/main/README.md" +Repository = "https://github.com/eschaar/vstack" +Issues = "https://github.com/eschaar/vstack/issues" +Changelog = "https://github.com/eschaar/vstack/blob/main/CHANGELOG.md" +Discussions = "https://github.com/eschaar/vstack/discussions" +Security = "https://github.com/eschaar/vstack/blob/main/SECURITY.md" [project.scripts] vstack = "vstack:main"