From 9b2cf21c2a89aacdf47b7272a41ccee6ad441c73 Mon Sep 17 00:00:00 2001 From: imfozilbek Date: Mon, 22 Dec 2025 00:44:55 +0500 Subject: [PATCH] docs: add CHANGELOG and TODO templates, update rules --- CHANGELOG.package.md | 34 ++++++++++++++++++ CLAUDE.md | 86 ++++++++++++++++++++++++++++---------------- README.md | 7 ++-- TODO.package.md | 39 ++++++++++++++++++++ 4 files changed, 133 insertions(+), 33 deletions(-) create mode 100644 CHANGELOG.package.md create mode 100644 TODO.package.md diff --git a/CHANGELOG.package.md b/CHANGELOG.package.md new file mode 100644 index 0000000..eba05f3 --- /dev/null +++ b/CHANGELOG.package.md @@ -0,0 +1,34 @@ +# Changelog + +All notable changes to this package will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/), +and this project adheres to [Semantic Versioning](https://semver.org/). + +## [Unreleased] + +### Added +- Initial setup + +--- + +## [0.1.0] - YYYY-MM-DD + +### Added +- Feature 1 +- Feature 2 + +### Changed +- Change 1 + +### Fixed +- Bug fix 1 + +--- + +## Template Usage + +1. Replace `YYYY-MM-DD` with actual date +2. Update sections for each release +3. Move [Unreleased] items to new version on release +4. Remove this section diff --git a/CLAUDE.md b/CLAUDE.md index 1f0c12f..58657c9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -289,44 +289,68 @@ git push origin main --tags **⛔ MUST read `./ROADMAP.md` first** to understand current status. -## ROADMAP.md Rules (MANDATORY) +## Package Documentation (MANDATORY) -**⛔ Every monorepo MUST have ROADMAP.md files:** +**⛔ Every package/app MUST have these files:** -| Location | Purpose | -|----------|---------| -| `/ROADMAP.md` | Master roadmap: phases, architecture, status table | -| `/packages/*/ROADMAP.md` | Package roadmap: detailed milestones, tasks | -| `/apps/*/ROADMAP.md` | App roadmap: features, UI/UX tasks | +| File | Purpose | +|------|---------| +| `ROADMAP.md` | Milestones, tasks with checkboxes | +| `CHANGELOG.md` | Version history, what changed | +| `TODO.md` | Technical debt, known issues | + +**Root level:** + +| File | Purpose | +|------|---------| +| `/ROADMAP.md` | Master: phases, architecture, status table | +| `/CHANGELOG.md` | Optional: root-level changes only | + +## ROADMAP.md Rules + +| Rule | Requirement | +|------|-------------| +| Structure | Phases → Milestones → Tasks with `[x]`/`[ ]` | +| Versioning | Independent semver per package (v0.1.0) | +| Dependencies | Show "Depends on: package vX.X.X" | +| Status | ✅ Completed, 🔄 In Progress, ⏳ Planned | + +## CHANGELOG.md Rules + +**Format:** [Keep a Changelog](https://keepachangelog.com/) -**Root ROADMAP.md:** ```markdown -## Current Status -| Package | Version | Next Milestone | -|---------|---------|----------------| -| @project/core | v0.2.0 ✅ | v0.3.0 - Feature | -``` - -**Package ROADMAP.md:** -```markdown -## v0.3.0 - Feature Name -| Task | Status | -|------|--------| -| Entity: Name | [x] | -| Use case | [ ] | -``` - -**Status indicators:** -``` -✅ Completed | 🔄 In Progress | ⏳ Planned +## [0.2.0] - 2025-01-15 +### Added +- New feature X +### Fixed +- Bug in Y +### Changed +- Refactored Z ``` **⛔ RULES:** -- Root ROADMAP = bird's eye view (phases, dependencies) -- Package ROADMAP = detailed tasks (checkboxes) -- Update BEFORE starting new milestone -- Mark tasks `[x]` immediately when done -- Never skip dependency order +- Update BEFORE release (not after) +- Group by: Added, Changed, Fixed, Removed +- Link to issues/PRs when relevant + +## TODO.md Rules (Technical Debt) + +**Format:** +```markdown +## High Priority +- [ ] Fix memory leak in X (#123) +- [x] ~~Refactor auth module~~ (done in v0.2.0) + +## Low Priority +- [ ] Add caching to Y +``` + +**⛔ RULES:** +- Add items when you notice shortcuts/hacks +- Mark `[x]` when resolved +- Reference in commits: `fix(api): resolve issue (TODO #3)` +- Review before each release **Dependency order (always):** ``` diff --git a/README.md b/README.md index 5d9aadf..dba8565 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,9 @@ Standard templates for Claude Code configuration across all projects. |------|-------------| | `CLAUDE.md` | Claude Code configuration with all mandatory rules | | `ROADMAP.md` | Root roadmap: phases, architecture, status table | -| `ROADMAP.package.md` | Package roadmap: detailed milestones per package | +| `ROADMAP.package.md` | Package roadmap: detailed milestones | +| `CHANGELOG.package.md` | Package changelog: version history | +| `TODO.package.md` | Package TODO: technical debt tracker | ## Usage @@ -17,7 +19,8 @@ Standard templates for Claude Code configuration across all projects. - `ROADMAP.md` → `/ROADMAP.md` 2. Copy to each package/app: - `ROADMAP.package.md` → `/packages/*/ROADMAP.md` - - `ROADMAP.package.md` → `/apps/*/ROADMAP.md` + - `CHANGELOG.package.md` → `/packages/*/CHANGELOG.md` + - `TODO.package.md` → `/packages/*/TODO.md` 3. Replace placeholders: - `PROJECT_NAME` → your project name - `@project/*` → your package prefix (e.g., `@myapp/*`) diff --git a/TODO.package.md b/TODO.package.md new file mode 100644 index 0000000..81da687 --- /dev/null +++ b/TODO.package.md @@ -0,0 +1,39 @@ +# TODO - Technical Debt + +Track known issues, shortcuts, and improvements needed. + +## High Priority + +> Critical issues that should be fixed soon. + +- [ ] Example: Fix memory leak in X component + +## Medium Priority + +> Important but not urgent. + +- [ ] Example: Add proper error handling to Y +- [ ] Example: Refactor Z for better performance + +## Low Priority + +> Nice to have, can wait. + +- [ ] Example: Add more unit tests +- [ ] Example: Improve documentation + +## Completed + +> Resolved items (keep for history). + +- [x] ~~Example task~~ (resolved in v0.1.0) + +--- + +## Template Usage + +1. Add items when you notice issues during development +2. Mark `[x]` and move to Completed when resolved +3. Reference in commits: `fix(pkg): resolve issue (TODO #3)` +4. Review before each release +5. Remove this section