Danijel Martinek
b96cce5d74
Closes the user's ask: versioning + a changelog generated on merging
to main, building on the just-mandated Conventional Commits substrate
(CLAUDE.md Key Conventions).
Architecture: ADR-021. Cookbook: docs/guides/releasing.md.
Initial state — six tracked packages at v0.1.0:
- . -> template-vertical (tag: template-v...)
- packages/auth -> @repo/auth (tag: auth-v...)
- packages/blog -> @repo/blog (tag: blog-v...)
- packages/media -> @repo/media (tag: media-v...)
- packages/marketing-pages -> @repo/marketing-pages (tag: marketing-pages-v...)
- packages/navigation -> @repo/navigation (tag: navigation-v...)
Core packages, tooling, and apps are NOT independently versioned
(ADR-021 rationale: core bumps cascade; apps aren't consumables;
surfacing them would create noise without information).
Configuration:
- release-please-config.json - 6 tracked packages, hybrid scope,
pre-1.0 conservative bump policy
(feat: -> patch, feat!: -> minor),
conventional-commit type mapping
- .release-please-manifest.json - baseline 0.1.0 for all 6 packages
- .github/workflows/release-please.yml - googleapis/release-please-
action@v4 on push to main,
concurrency-gated, write
permissions for the rolling PR
Workflow: on every push to main, release-please scans commits since
the last release tag PER PACKAGE (using commit-path, not the
conventional-commit scope), updates a single rolling release PR with
version bumps + per-package CHANGELOG entries. Merging that PR cuts
per-package tags + GitHub releases.
CHANGELOG files seeded at v0.1.0 baseline:
- CHANGELOG.md (root)
- packages/<feature>/CHANGELOG.md (5 features)
Subsequent versions are appended by release-please from commit
history. Do not edit manually.
Visibility surfaces updated (every agent entry point):
- CLAUDE.md Read First + new "Versioning is hybrid" Key Conventions
bullet (with bump policy summary)
- AGENTS.md preamble - new "Releases:" callout alongside Commits
- docs/glossary.md - new Releasing section with 8 terms (Conventional
Commits, release-please, Hybrid versioning, Tag prefix, Rolling
release PR, Bump targeting, Pre-1.0 bump policy, Release-As trailer,
CHANGELOG.md)
- docs/README.md - guides tree updated with releasing.md
- .claude/hooks/session-start.sh - one-line release reminder
- .claude/hooks/prompt-context.sh - new keyword group for
release/version/bump/semver/tag prompts
Package.json version bumps:
- root: name "template" -> "template-vertical", version "0.1.0"
- packages/auth, blog, media, marketing-pages, navigation: "0.0.0" -> "0.1.0"
Root rename rationale: release-please tags use the package-name + the
component prefix; "template-vertical" matches the repo identity (and
the user's question preview).
First release-please PR after this lands will sweep all subsequent
post-baseline commits into 0.1.1 / 0.2.0 bumps as appropriate.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
88 lines
5.6 KiB
Markdown
88 lines
5.6 KiB
Markdown
# docs/
|
|
|
|
Documentation hub for the `template-vertical` monorepo. **Start here if you landed at `docs/` directly.**
|
|
|
|
For the project entry point, see [`../CLAUDE.md`](../CLAUDE.md) (humans + agents) and [`../AGENTS.md`](../AGENTS.md) (package map + boundary rules).
|
|
|
|
---
|
|
|
|
## Resolving terminology
|
|
|
|
[`glossary.md`](./glossary.md) — **canonical vocabulary** for every cross-cutting term used in this repo (feature, use case, manifest, conformance, slice, coverage band, dispatch, etc.). When in doubt about what a term means _here_, check the glossary first.
|
|
|
|
---
|
|
|
|
## How the documentation is organised
|
|
|
|
```
|
|
docs/
|
|
├── glossary.md # canonical vocabulary
|
|
├── architecture/ # design + invariants (rarely changes)
|
|
│ ├── overview.md # high-level architecture summary
|
|
│ ├── vertical-feature-spec.md # canonical feature design spec
|
|
│ ├── dependency-flow.md # workspace + import-graph reference
|
|
│ ├── template-tiers.md # must-have vs optional core packages
|
|
│ ├── agent-first-workflow-and-conformance.md # workflow + 5-gate design
|
|
│ ├── data-flow-explainer.html # interactive (single-file)
|
|
│ ├── di-explainer.html # interactive (single-file)
|
|
│ ├── feature-conformance-explainer.html # interactive (single-file)
|
|
│ └── audit-and-compliance-explainer.html # interactive (single-file)
|
|
├── decisions/ # ADRs (durable design decisions)
|
|
│ └── adr-001..adr-020.md # 20 ADRs, numbered in order accepted
|
|
├── guides/ # day-to-day how-to docs
|
|
│ ├── runbook.md # ← first time? read this end-to-end
|
|
│ ├── conformance-quickref.md
|
|
│ ├── coverage.md # 4-layer coverage cookbook (ADR-020)
|
|
│ ├── releasing.md # release-please workflow + CHANGELOG cookbook (ADR-021)
|
|
│ ├── tdd-workflow.md
|
|
│ ├── testing-strategy.md
|
|
│ ├── adding-a-feature.md # manual path
|
|
│ ├── scaffolding-a-feature.md # generator path (preferred)
|
|
│ ├── scaffolding-core-package.md
|
|
│ ├── scaffolding-core-ui-component.md
|
|
│ ├── events-and-jobs.md # requires `gen core-package events`
|
|
│ ├── realtime.md # requires `gen core-package realtime`
|
|
│ ├── audit-and-compliance.md # requires `gen core-package audit`
|
|
│ ├── frontend-work-shape.md
|
|
│ └── infrastructure-work-shape.md
|
|
└── work/ # local task system (PRD → Epic → Story → Task)
|
|
├── README.md # work-folder layout + PRD lifecycle
|
|
├── _state.json # derived index (orchestrator-managed)
|
|
├── prds/<date>-<slug>.prd.md # PRDs
|
|
└── <epic-slug>/... # one folder per epic
|
|
```
|
|
|
|
## Document types
|
|
|
|
| Type | Where | Purpose | Lifetime |
|
|
| ----------------------- | ------------------------ | ------------------------------------------------ | ---------------------------------------- |
|
|
| **Glossary** | `glossary.md` | One sentence per term; flagged ambiguities | Long-lived |
|
|
| **Architecture** | `architecture/` | Design invariants, system shape | Long-lived |
|
|
| **ADR** | `decisions/adr-NNN-*.md` | Single decision: context → choice → consequences | Long-lived |
|
|
| **Guide** | `guides/` | How-to, reference, troubleshooting | Updated as features evolve |
|
|
| **PRD** | `work/prds/*.prd.md` | Implementation seed for one epic | `draft → in-review → approved → shipped` |
|
|
| **Epic / Story / Task** | `work/<epic>/...` | Workflow artifacts | Created → in-progress → done |
|
|
|
|
## When to put what where
|
|
|
|
- **A new architectural decision** (events, audit, instrumentation choices, etc.) → ADR. Number is `001 + max(existing)`.
|
|
- **A new how-to** (cookbook, troubleshooting, "how do I do X") → guide.
|
|
- **A new vocabulary term** that's cross-cutting → glossary, alphabetically grouped.
|
|
- **A new initiative** (multi-task feature work) → PRD seed. The decomposer refuses to run on `draft` — flip to `approved` after human review. `pnpm work prd-ship <id>` auto-flips to `shipped` on epic completion.
|
|
- **A new interactive diagram** → drop a single-file HTML at `architecture/<name>-explainer.html`; cross-link from the other explainers + from `architecture/overview.md`'s Interactive explainers section.
|
|
|
|
## See also
|
|
|
|
- [`../CLAUDE.md`](../CLAUDE.md) — entry point for agents
|
|
- [`../AGENTS.md`](../AGENTS.md) — package map + boundary rules + agent-driven development overview
|
|
- [`../README.md`](../README.md) — project-level README
|
|
|
|
## Conventions
|
|
|
|
- **Markdown over HTML** unless the doc is genuinely interactive (the 4 architecture HTMLs).
|
|
- **Reference ADRs by ID** (`ADR-NNN`) rather than path so renames don't break links.
|
|
- **Cross-reference paths sparingly** — they rot. Prefer naming the doc (e.g. "see the coverage guide").
|
|
- **Don't duplicate** — if two docs describe the same thing, consolidate or pick a single source of truth and link from the other.
|
|
- **Date PRDs + ADRs** in the file name (`YYYY-MM-DD` prefix for PRDs) and in their frontmatter.
|
|
- **Each ADR cites at least one related ADR** when extending or building on prior decisions.
|