Changelog Conventions for Jeffrey's Skills

Why changelogs matter

A changelog is the user-facing summary of what changed since the last version. It should answer:

• What is new that I should be excited about?
• What changed that might affect my workflow?
• What was fixed that was broken before?

Good changelogs build trust and reduce update anxiety.

Format specification

Use standard headings. Include only the sections that apply.

Added

New capabilities or content that did not exist before.

Changed

Modifications to existing behavior. Users may need to adjust.

Deprecated

Features that still work but will be removed in a future version.

Removed

Features that no longer exist. This is a breaking change.

Fixed

Bug fixes or corrections to existing behavior.

Security

Security-related updates. Include a CVE when applicable.

Example

### Added

- Support for TypeScript 6.0 syntax examples
- New troubleshooting section for common errors

### Fixed

- Corrected example that used a deprecated API
- Fixed typo in configuration path

### Changed

- Updated recommended Node.js version to 22.x

Writing guidelines

Do

• Start each bullet with a verb (Added, Fixed, Changed, Removed).
• Be specific and user-centric.
• Keep one change per bullet.
• Mention impact when relevant ("No restart required").

Do not

• Do not write "various improvements" or "misc fixes".
• Do not list internal refactors unless users are affected.
• Do not dump raw commit messages.
• Do not use excessive jargon.

Length guidelines

• Minimum: 10 characters
• Recommended: 50 to 500 characters for a typical update
• Maximum: 10,000 characters

If a changelog is long, consider splitting the release.

Initial release format

For v1, keep it simple:

Initial release of [Skill Name].

Features:

- [Key feature 1]
- [Key feature 2]
- [Key feature 3]

Common examples

Added

### Added

- Support for async/await patterns in all examples
- New section on error handling patterns

Fixed

### Fixed

- Example code now compiles on Rust 1.75+
- Corrected port in Docker config (was 8000, now 8080)

Changed

### Changed

- Default timeout increased from 30s to 60s
- Reorganized sections for clearer learning progression

Removed

### Removed

- Deprecated --legacy flag (use --compat instead)
- Python 2.7 examples (end of life)

FAQ

Q: Do I need every section every time? A: No. Include only what applies to that release.

Q: What if I only fixed a typo? A: That is still a valid changelog. Example: "Fixed typo in section 3.2".

Q: Can I use emoji? A: Prefer not to. Keep it professional and accessible.