swpm-keepachangelog

name	swpm-keepachangelog
id	swpm-keepachangelog
version	1.0.0
tags	["swpm","changelog","keepachangelog","documentation"]
description	Keep a Changelog 1.1.0 standards for SWPM. Defines format, sections, and conventions for CHANGELOG.md entries. Activates when user modifies CHANGELOG.md.

SWPM Keep a Changelog Standards

Use this skill when modifying CHANGELOG.md or when questions arise about changelog format, sections, or entry conventions.

When to Use

• User is editing CHANGELOG.md - activates to ensure entries follow Keep a Changelog 1.1.0
• Developer asks "How should I format this changelog entry?"
• Questions about what section to use (Added, Changed, Fixed, etc.)
• Updating version entries with proper date format
• Do not use for version number decisions (use swpm-semver for SemVer)

Keep a Changelog 1.1.0 Rules

Required Format

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- New feature description

### Changed

- Change description

## [2.6.0] - 2023-12-26

### Changed

- Revert the `--location=global` flag translation on npm

### Fixed

- Fix description here

Version Line Format

✅ Correct:

## [2.6.0] - 2023-12-26
## [2.7.0-alpha] - 2023-12-26

❌ Incorrect:

## 2.6.0 - 2023/12/26    // Slashes, no brackets
## v2.6.0 - 2023-12-26    // Don't use 'v' prefix in heading

Date Format

• ISO 8601: YYYY-MM-DD (hyphens, not slashes)
• ✅ 2023-12-26
• ❌ 2023/12/26
• ❌ 26-12-2023

Required Sections

Each version should have relevant sections:

• Added - for new features
• Changed - for changes in existing functionality
• Deprecated - for soon-to-be removed features
• Removed - for now removed features
• Fixed - for any bug fixes
• Security - in case of vulnerabilities

Optional Sections

• Unreleased - section at top for upcoming changes
• Updated - ❌ NOT standard, don't use (use Changed instead)

SWPM Changelog Conventions

Current Issues to Fix

The current CHANGELOG.md has these problems:

1. Date format: Uses 2023/12/26 (slashes) → Should be 2023-12-26 (hyphens)
2. Non-standard section: Uses ### Updated → Should use ### Changed
3. Missing sections: No ### Security in recent versions
4. Header: References Keep a Changelog 1.0.0 → Should reference 1.1.0

Version Ordering

• Most recent version at the top
• ## [Unreleased] section at the very top
• Older versions below in reverse chronological order

Entry Format

### Fixed

- volta version detection when not installed
- if volta was not installed don't take in care the volta pin version on `package.json`

• Use - (dash) for bullet points
• Use backticks for code references: `package.json`, `--global`
• Sentence case: capitalize first letter, no period at end
• Be descriptive but concise

Example Entries

✅ Correct - Added

### Added

- `bun` command and flags included in new version
- Repository helpers unit test

✅ Correct - Changed

### Changed

- TypeScript strict configuration
- Bump package versions

✅ Correct - Fixed

### Fixed

- `global` flag position on `yarn` and `yarn@berry`
- Get repository URL when using SSH URI

❌ Incorrect

### Updated // Not a standard section

- Bump package versions

### Fixed

- Fixed global flag (double "fixed")
- global flag (no code backticks)
- Bump package versions. (period at end)

Version Comparison Links

At the bottom of the file, include comparison links:

[unreleased]: https://github.com/deinsoftware/swpm/compare/v2.6.0...HEAD
[2.6.0]: https://github.com/deinsoftware/swpm/compare/v2.5.2...v2.6.0
[2.5.2]: https://github.com/deinsoftware/swpm/compare/v2.5.1...v2.5.2

Release Checklist

Before releasing a new version:

1. Move entries from ## [Unreleased] to new version section
2. Add version line: ## [X.Y.Z] - YYYY-MM-DD
3. Add appropriate sections (### Added, ### Changed, etc.)
4. Add comparison link at bottom of file
5. Commit with message like Release vX.Y.Z

Example Questions

Q: "How should I document a new command in the changelog?" A: Use ### Added section:

### Added

- `clean` command to remove unused dependencies

Q: "What section should I use for bug fixes?" A: Use ### Fixed section:

### Fixed

- Fix `global` flag position on yarn

Q: "Can I use ### Updated section?" A: No, use ### Changed instead. Updated is not a standard Keep a Changelog section.

Q: "What date format should I use?" A: ISO 8601 format with hyphens: 2023-12-26 (not slashes 2023/12/26)

Q: "Where should the new version go in the file?" A: At the top, after ## [Unreleased], most recent first.

Observations

Before helping with changelog edits:

• Check current CHANGELOG.md format
• Verify date format uses hyphens not slashes
• Ensure sections are standard (Added, Changed, Deprecated, Removed, Fixed, Security)
• Check if ## [Unreleased] section exists at top
• Verify version comparison links at bottom of file
• Reference: https://keepachangelog.com/en/1.1.0/

Reference

Full Keep a Changelog specification: https://keepachangelog.com/en/1.1.0/