Add changelog and update documentation rules
Add a top-level changelog.md and update documentation guidance to require and describe its use. .cursor/rules/documentation-rules.mdc: expanded description and added sections for “Changelog vs Dev Log” and “Changelog Format” with Keep a Changelog guidance and an example. .cursor/rules/project-overview.mdc: reference changelog.md and clarify that docs/dev-log.md is for milestones, testing, and discoveries. changelog.md: new file with an [Unreleased] section and an initial 0.0.1 stub (notes that docs/changelog.md was moved).
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
---
|
||||
description: Documentation and development log update rules
|
||||
description: Documentation, changelog, and development log update rules
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
@@ -8,12 +8,66 @@ alwaysApply: true
|
||||
After every meaningful code change, update the relevant documentation. Do not let code and documentation drift apart.
|
||||
|
||||
Always consider whether these files need updates:
|
||||
- `changelog.md`
|
||||
- `docs/dev-log.md`
|
||||
- `docs/protocol.md`
|
||||
- `docs/architecture.md`
|
||||
- `docs/setup.md`
|
||||
- `docs/testing.md`
|
||||
|
||||
## Changelog vs Dev Log
|
||||
|
||||
Use both files, but for different purposes:
|
||||
|
||||
| File | Purpose | When to update |
|
||||
|------|---------|----------------|
|
||||
| `changelog.md` | Complete record of every change | After **every** code edit, addition, removal, fix, or documentation update |
|
||||
| `docs/dev-log.md` | Milestones, testing, discoveries, next steps | After feature milestones or meaningful development sessions |
|
||||
|
||||
**Changelog** — log every change under `[Unreleased]` using [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories. Include what was added, changed, deprecated, removed, fixed, or security-related. Mention affected files or areas when helpful. Do **not** include testing results, test plans, verification notes, known issues, or next steps.
|
||||
|
||||
**Dev log** — keep the existing milestone format for broader feature work, technical discoveries, and testing.
|
||||
|
||||
## Changelog Format
|
||||
|
||||
Follow [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/).
|
||||
|
||||
- Keep an `## [Unreleased]` section at the top for all in-progress changes.
|
||||
- When cutting a release, move `[Unreleased]` entries into a new `## [X.Y.Z] - YYYY-MM-DD` section (ISO 8601 date), then clear `[Unreleased]`.
|
||||
- Newest versions come first, directly under the file preamble.
|
||||
- Omit empty change-type sections.
|
||||
- One bullet per change; keep entries concise and factual.
|
||||
|
||||
Use these change types (only when applicable):
|
||||
|
||||
| Type | Use for |
|
||||
|------|---------|
|
||||
| `Added` | New features, files, fields, or capabilities |
|
||||
| `Changed` | Changes to existing functionality |
|
||||
| `Deprecated` | Soon-to-be removed features |
|
||||
| `Removed` | Removed features or files |
|
||||
| `Fixed` | Bug fixes |
|
||||
| `Security` | Vulnerability fixes |
|
||||
|
||||
Example:
|
||||
|
||||
```md
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
- New packet field `exampleField` in transform sync.
|
||||
|
||||
### Fixed
|
||||
- Guard null actor pointer before proxy movement update.
|
||||
|
||||
## [0.1.0] - 2026-06-23
|
||||
|
||||
### Added
|
||||
- Initial world-state sync MVP.
|
||||
```
|
||||
|
||||
## Dev Log Format
|
||||
|
||||
At minimum, after every milestone or feature change, update `docs/dev-log.md` with:
|
||||
- Date
|
||||
- Summary of what changed
|
||||
|
||||
@@ -18,7 +18,8 @@ Important project areas:
|
||||
- `server/server.py`: Python relay server.
|
||||
- `server/fake_client.py`: fake testing client for protocol and relay checks.
|
||||
- `docs/`: architecture, setup, protocol, testing, and milestone documentation.
|
||||
- `docs/dev-log.md`: running project history and development log.
|
||||
- `changelog.md`: dated record of every code and documentation change (no testing notes).
|
||||
- `docs/dev-log.md`: milestone history, testing results, discoveries, and next steps.
|
||||
|
||||
Cursor workflow:
|
||||
- Read relevant files before editing.
|
||||
|
||||
Reference in New Issue
Block a user