From 7704168b0b1176ee9e9850ffcdf3a5cedc069aad Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 2 Nov 2025 16:13:39 -1000 Subject: [PATCH] Add changelog guidelines to CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Following https://github.com/shakacode/react_on_rails/pull/1867, this adds comprehensive changelog documentation requirements. Changes: - Added .claude/commands/update-changelog.md with detailed guidelines on when and how to update CHANGELOG.md - Created CLAUDE.md with essential development commands and changelog section - Guidelines focus on user-visible changes only (features, bug fixes, breaking changes, deprecations, performance improvements) - Standardized formatting with PR and author links, consistent with keepachangelog.com Impact: This ensures consistent, high-quality changelog maintenance across the project, making it easier for users to understand what changes affect them. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/commands/update-changelog.md | 227 +++++++++++++++++++++++++++ CLAUDE.md | 77 +++++++++ 2 files changed, 304 insertions(+) create mode 100644 .claude/commands/update-changelog.md create mode 100644 CLAUDE.md diff --git a/.claude/commands/update-changelog.md b/.claude/commands/update-changelog.md new file mode 100644 index 0000000..8420bd2 --- /dev/null +++ b/.claude/commands/update-changelog.md @@ -0,0 +1,227 @@ +# Update Changelog + +You are helping to add an entry to the CHANGELOG.md file for the PackageJson project. + +## Critical Requirements + +1. **User-visible changes only**: Only add changelog entries for user-visible changes: + + - New features + - Bug fixes + - Breaking changes + - Deprecations + - Performance improvements + - Security fixes + - Changes to public APIs or configuration options + +2. **Do NOT add entries for**: + - Linting fixes + - Code formatting + - Internal refactoring + - Test updates + - Documentation fixes (unless they fix incorrect docs about behavior) + - CI/CD changes + +## Formatting Requirements + +### Entry Format + +Each changelog entry MUST follow this exact format: + +```markdown +- **Bold description of change**. [PR 1818](https://github.com/shakacode/package_json/pull/1818) by [username](https://github.com/username). Optional additional context or details. +``` + +**Important formatting rules**: + +- Start with a dash and space: `- ` +- Use **bold** for the main description +- End the bold description with a period before the link +- Always link to the PR: `[PR 1818](https://github.com/shakacode/package_json/pull/1818)` - **NO hash symbol** +- Always link to the author: `by [username](https://github.com/username)` +- End with a period after the author link +- Additional details can be added after the main entry, using proper indentation for multi-line entries + +### Breaking Changes Format + +For breaking changes, use this format: + +```markdown +- **Feature Name**: Description of the breaking change. See migration guide below. [PR 1818](https://github.com/shakacode/package_json/pull/1818) by [username](https://github.com/username). + +**Migration Guide:** + +1. Step one +2. Step two +``` + +### Category Organization + +Entries should be organized under these section headings. The project uses both standard and custom headings: + +**Standard headings** (from keepachangelog.com) - use these for most changes: + +- `#### Added` - New features +- `#### Changed` - Changes to existing functionality +- `#### Deprecated` - Deprecation notices +- `#### Removed` - Removed features +- `#### Fixed` - Bug fixes +- `#### Security` - Security-related changes +- `#### Improved` - Improvements to existing features + +**Custom headings** (project-specific) - use sparingly when standard headings don't fit: + +- `#### Breaking Changes` - Breaking changes with migration guides +- `#### Performance` - Performance improvements + +**Prefer standard headings.** Only use custom headings when the change needs more specific categorization. + +**Only include section headings that have entries.** + +### Version Management + +After adding entries, use the rake task to manage version headers: + +```bash +bundle exec rake update_changelog +``` + +This will: + +- Add headers for the new version +- Update version diff links at the bottom of the file + +## Process + +### For Regular Changelog Updates + +1. **Determine the correct version tag to compare against**: + + - First, check the tag dates: `git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10` + - Find the latest version tag and its date + - Compare main branch date to the tag date + - If the tag is NEWER than main, it means main needs to be updated to include the tag's commits + - **CRITICAL**: Always use `git log TAG..BRANCH` to find commits that are in the tag but not in the branch, as the tag may be ahead + +2. **Check commits and version boundaries**: + + - Run `git log --oneline LAST_TAG..main` to see commits since the last release + - Also check `git log --oneline main..LAST_TAG` to see if the tag is ahead of main + - If the tag is ahead, entries in "Unreleased" section may actually belong to that tagged version + - Identify which commits contain user-visible changes + - Extract PR numbers and author information from commit messages + - **Never ask the user for PR details** - get them from the git history + +3. **Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits. + +4. **Read the current CHANGELOG.md** to understand the existing structure and formatting. + +5. **Determine where entries should go**: + + - If the latest version tag is NEWER than main branch, move entries from "Unreleased" to that version section + - If main is ahead of the latest tag, add new entries to "Unreleased" + - Always verify the version date in CHANGELOG.md matches the actual tag date + +6. **Add or move entries** to the appropriate section under appropriate category headings. + + - **CRITICAL**: When moving entries from "Unreleased" to a version section, merge them with existing entries under the same category heading + - **NEVER create duplicate section headings** (e.g., don't create two "### Fixed" sections) + - If the version section already has a category heading (e.g., "### Fixed"), add the moved entries to that existing section + - Maintain the category order as defined above + +7. **Verify formatting**: + + - Bold description with period + - Proper PR link (NO hash symbol) + - Proper author link + - Consistent with existing entries + - File ends with a newline character + +8. **Run linting** after making changes: + + ```bash + bundle exec rubocop + yarn run prettier + ``` + +9. **Show the user** the added or moved entries and explain what was done. + +### For Beta to Non-Beta Version Release + +When releasing from beta to a stable version (e.g., v1.1.0-beta.3 → v1.1.0): + +1. **Remove all beta version labels** from the changelog: + + - Change `### [v1.1.0-beta.1]`, `### [v1.1.0-beta.2]`, etc. to a single `### [v1.1.0]` section + - Combine all beta entries into the stable release section + +2. **Consolidate duplicate entries**: + + - If bug fixes or changes were made to features introduced in earlier betas, keep only the final state + - Remove redundant changelog entries for fixes to beta features + - Keep the most recent/accurate description of each change + +3. **Update version diff links** using `bundle exec rake update_changelog` + +### For New Beta Version Release + +When creating a new beta version, ask the user which approach to take: + +**Option 1: Process changes since last beta** + +- Only add entries for commits since the previous beta version +- Maintains detailed history of what changed in each beta + +**Option 2: Collapse all prior betas into current beta** + +- Combine all beta changelog entries into the new beta version +- Removes previous beta version sections +- Cleaner changelog with less version noise + +After the user chooses, proceed with that approach. + +## Examples + +Run this command to see real formatting examples from the codebase: + +```bash +grep -A 3 "^#### " CHANGELOG.md | head -30 +``` + +### Good Entry Example + +```markdown +- **New feature description**: Added helpful functionality that users will appreciate. [PR 123](https://github.com/shakacode/package_json/pull/123) by [username](https://github.com/username). +``` + +### Entry with Sub-bullets Example + +```markdown +- **Multi-part feature**: Added new configuration options for enhanced functionality: + - `option_name`: Description of the option and its purpose. [PR 123](https://github.com/shakacode/package_json/pull/123) by [username](https://github.com/username) + - `another_option`: Description of another option. [PR 124](https://github.com/shakacode/package_json/pull/124) by [username](https://github.com/username) +``` + +### Breaking Change Example + +```markdown +- **Method Removal**: Several deprecated methods have been removed. If you're using any of the following methods, you'll need to migrate: + - `old_method_one()` + - `old_method_two()` + +**Migration Guide:** + +To migrate: + +1. Replace `old_method_one()` with `new_method()` +2. Update configuration to use new format +``` + +## Additional Notes + +- Keep descriptions concise but informative +- Focus on the "what" and "why", not the "how" +- Use past tense for the description +- Be consistent with existing formatting in the changelog +- Always ensure the file ends with a trailing newline +- See CHANGELOG.md for additional contributor guidelines diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8b86b34 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,77 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## ⚠️ CRITICAL REQUIREMENTS + +**BEFORE EVERY COMMIT/PUSH:** + +1. **ALWAYS run `bundle exec rubocop` and fix ALL violations** +2. **ALWAYS ensure files end with a newline character** +3. **NEVER push without running full lint check first** + +These requirements are non-negotiable. CI will fail if not followed. + +## Development Commands + +### Essential Commands + +- **Install dependencies**: `bundle install` +- **Run tests**: `rake spec` or `bundle exec rspec` +- **Linting** (MANDATORY BEFORE EVERY COMMIT): + - **REQUIRED**: `bundle exec rubocop` - Must pass with zero offenses + - Auto-fix RuboCop violations: `bundle exec rubocop -a` +- **⚠️ MANDATORY BEFORE GIT PUSH**: `bundle exec rubocop` and fix ALL violations + ensure trailing newlines +- **Default task** (runs tests and rubocop): `rake` + +## Changelog + +- **Update CHANGELOG.md for user-visible changes only** (features, bug fixes, breaking changes, deprecations, performance improvements) +- **Do NOT add entries for**: linting, formatting, refactoring, tests, or documentation fixes +- **Format**: `[PR 123](https://github.com/shakacode/package_json/pull/123) by [username](https://github.com/username)` (no hash in PR number) +- **Use `/update-changelog` command** for guided changelog updates with automatic formatting +- **Version management**: Run `bundle exec rake update_changelog` after releases to update version headers (if task exists) +- **Examples**: Run `grep -A 3 "^#### " CHANGELOG.md | head -30` to see real formatting examples + +## ⚠️ FORMATTING RULES + +**RuboCop is the SOLE authority for formatting Ruby files. NEVER manually format code.** + +### Standard Workflow +1. Make code changes +2. Run `bundle exec rubocop -a` to auto-fix violations +3. Commit changes + +### Debugging Formatting Issues +- Check for violations: `bundle exec rubocop` +- Fix violations: `bundle exec rubocop -a` +- If CI fails on formatting, always run automated fixes, never manual fixes + +## Project Architecture + +### Core Components + +This is a Ruby gem that provides a Ruby interface for managing `package.json` files and JavaScript package managers. + +#### Ruby Side (`lib/package_json/`) + +- **`lib/package_json.rb`**: Main entry point and core PackageJson class +- **`lib/package_json/manager.rb`**: Base class for package manager abstraction +- **`lib/package_json/managers/`**: Specific implementations for npm, yarn, pnpm, bun, etc. + +### Build System + +- **Ruby**: Standard gemspec-based build (see `package_json.gemspec`) +- **Testing**: RSpec for Ruby tests +- **Linting**: RuboCop for Ruby + +## Important Notes + +- This gem provides a "middle-level" abstraction over JavaScript package managers +- Supports npm, yarn (classic and berry), pnpm, and bun +- Does not capture or intercept package manager output by default +- Uses `Kernel.system` under the hood for package manager operations + +## Contributing + +Bug reports and pull requests are welcome on GitHub at https://github.com/shakacode/package_json.