andrew
87a264da80
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).
109 lines
3.1 KiB
Plaintext
109 lines
3.1 KiB
Plaintext
---
|
|
description: Documentation, changelog, and development log update rules
|
|
alwaysApply: true
|
|
---
|
|
|
|
# Documentation Rules
|
|
|
|
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
|
|
- Files modified
|
|
- What was tested
|
|
- What worked
|
|
- Any known issues
|
|
- Suggested next steps
|
|
|
|
Use this dev-log format:
|
|
|
|
```md
|
|
## YYYY-MM-DD - Feature or Milestone Name
|
|
|
|
### Summary
|
|
Briefly explain what changed.
|
|
|
|
### Files Changed
|
|
- `path/to/file`
|
|
- `path/to/file`
|
|
|
|
### Details
|
|
- Important technical detail
|
|
- Important technical detail
|
|
|
|
### Testing
|
|
- What was tested
|
|
- What the expected result was
|
|
- What actually happened
|
|
|
|
### Known Issues
|
|
- Issue or `None currently known`
|
|
|
|
### Next Steps
|
|
- Suggested next task
|
|
```
|
|
|
|
If the protocol changes, update `docs/protocol.md`. If the architecture changes, update `docs/architecture.md`. If setup changes, update `docs/setup.md`. If testing workflow changes, update `docs/testing.md`.
|