tomevault-io Changelog
Update CHANGELOG.md with user-facing changes from the current branch.
Workflow
1. Get the diff
Get the full diff of the current branch against main:
git diff main...HEAD
2. Identify user-facing changes
Analyze the diff and identify changes that affect the user. Ignore internal refactors, code style changes, and developer-only changes (test infrastructure, CI config, etc.) unless they have user-facing impact.
Also skip minor polish changes that users wouldn't notice or care about (e.g. small spacing tweaks, cosmetic adjustments, moving elements slightly). Only include changes that meaningfully affect the user's experience or workflow.
Categorize each change:
- New - new features
- Improved - changes in existing functionality
- Deprecated - soon-to-be removed features
- Removed - removed features
- Fixed - bug fixes
- Security - vulnerability fixes
If there are no user-facing changes, inform the user and stop.
3. Write entries
Each entry should:
- Be written for humans. Describe what changed AND why the user should care. Lead with a concise statement of what changed, then explain the benefit. For example: "Cheatsheet dialog replaced with a help panel that stays open while you work, so you can reference shortcuts without interrupting what you're doing." Not: "Cheatsheet dialog replaced with a help panel."
- Focus on outcomes and impact, not implementation details. Skip sub-features and internal specifics (e.g. don't mention specific icons added, individual links moved, or UI patterns used).
- Use plain language, not technical jargon.
- One bullet per feature. A bullet can have multiple sentences if needed, but don't split a single feature into multiple bullets.
- Use "New" only for entirely new capabilities. If the feature already exists in any form, it's "Improved".
- Within each category, order entries by user impact (most impactful first).
- Avoid em dashes. Use periods or commas instead.
- Vary sentence structure when it reads naturally, but don't sacrifice clarity for variety. "Now" is fine when it signals a change clearly.
4. Update CHANGELOG.md
Use the current ISO week (YYYY-Www, e.g. 2026-W06) as the section heading. To get the current week, run date +%G-W%V. More recent weeks go at the top (below the # Changelog title).
Only include category subheadings (New, Improved, etc.) that have entries.
If this week's heading already exists: merge intelligently — add new bullets under existing category subheadings, create new subheadings as needed, skip duplicate entries.
If this week's heading does not exist: create a new ## YYYY-Www section at the top (below the title).
Format:
# Changelog
## 2026-W06
### New
- You can now export notes as PDF from the share menu, so you can share or print them with formatting intact.
### Fixed
- Fixed a bug where tags with special characters weren't searchable.
## 2026-W03
### Improved
- The sidebar now remembers your scroll position between sessions, so you don't lose your place when navigating away.
5. Commit
After editing CHANGELOG.md, commit with message "Update changelog".
Source: lumen-notes/lumen — distributed by TomeVault.