Skip to content

Commit 764e935

Browse files
justin808claude
justin808
and
claude
authored
Add changelog guidelines to CLAUDE.md (#33)
Following shakacode/react_on_rails#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 <noreply@anthropic.com>
1 parent d32d6fa commit 764e935

File tree

2 files changed

+304
-0
lines changed

2 files changed

+304
-0
lines changed

‎.claude/commands/update-changelog.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
# Update Changelog
2+
3+
You are helping to add an entry to the CHANGELOG.md file for the PackageJson project.
4+
5+
## Critical Requirements
6+
7+
1. **User-visible changes only**: Only add changelog entries for user-visible changes:
8+
9+
- New features
10+
- Bug fixes
11+
- Breaking changes
12+
- Deprecations
13+
- Performance improvements
14+
- Security fixes
15+
- Changes to public APIs or configuration options
16+
17+
2. **Do NOT add entries for**:
18+
- Linting fixes
19+
- Code formatting
20+
- Internal refactoring
21+
- Test updates
22+
- Documentation fixes (unless they fix incorrect docs about behavior)
23+
- CI/CD changes
24+
25+
## Formatting Requirements
26+
27+
### Entry Format
28+
29+
Each changelog entry MUST follow this exact format:
30+
31+
```markdown
32+
- **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.
33+
```
34+
35+
**Important formatting rules**:
36+
37+
- Start with a dash and space: `- `
38+
- Use **bold** for the main description
39+
- End the bold description with a period before the link
40+
- Always link to the PR: `[PR 1818](https://github.com/shakacode/package_json/pull/1818)` - **NO hash symbol**
41+
- Always link to the author: `by [username](https://github.com/username)`
42+
- End with a period after the author link
43+
- Additional details can be added after the main entry, using proper indentation for multi-line entries
44+
45+
### Breaking Changes Format
46+
47+
For breaking changes, use this format:
48+
49+
```markdown
50+
- **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).
51+
52+
**Migration Guide:**
53+
54+
1. Step one
55+
2. Step two
56+
```
57+
58+
### Category Organization
59+
60+
Entries should be organized under these section headings. The project uses both standard and custom headings:
61+
62+
**Standard headings** (from keepachangelog.com) - use these for most changes:
63+
64+
- `#### Added` - New features
65+
- `#### Changed` - Changes to existing functionality
66+
- `#### Deprecated` - Deprecation notices
67+
- `#### Removed` - Removed features
68+
- `#### Fixed` - Bug fixes
69+
- `#### Security` - Security-related changes
70+
- `#### Improved` - Improvements to existing features
71+
72+
**Custom headings** (project-specific) - use sparingly when standard headings don't fit:
73+
74+
- `#### Breaking Changes` - Breaking changes with migration guides
75+
- `#### Performance` - Performance improvements
76+
77+
**Prefer standard headings.** Only use custom headings when the change needs more specific categorization.
78+
79+
**Only include section headings that have entries.**
80+
81+
### Version Management
82+
83+
After adding entries, use the rake task to manage version headers:
84+
85+
```bash
86+
bundle exec rake update_changelog
87+
```
88+
89+
This will:
90+
91+
- Add headers for the new version
92+
- Update version diff links at the bottom of the file
93+
94+
## Process
95+
96+
### For Regular Changelog Updates
97+
98+
1. **Determine the correct version tag to compare against**:
99+
100+
- First, check the tag dates: `git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10`
101+
- Find the latest version tag and its date
102+
- Compare main branch date to the tag date
103+
- If the tag is NEWER than main, it means main needs to be updated to include the tag's commits
104+
- **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
105+
106+
2. **Check commits and version boundaries**:
107+
108+
- Run `git log --oneline LAST_TAG..main` to see commits since the last release
109+
- Also check `git log --oneline main..LAST_TAG` to see if the tag is ahead of main
110+
- If the tag is ahead, entries in "Unreleased" section may actually belong to that tagged version
111+
- Identify which commits contain user-visible changes
112+
- Extract PR numbers and author information from commit messages
113+
- **Never ask the user for PR details** - get them from the git history
114+
115+
3. **Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits.
116+
117+
4. **Read the current CHANGELOG.md** to understand the existing structure and formatting.
118+
119+
5. **Determine where entries should go**:
120+
121+
- If the latest version tag is NEWER than main branch, move entries from "Unreleased" to that version section
122+
- If main is ahead of the latest tag, add new entries to "Unreleased"
123+
- Always verify the version date in CHANGELOG.md matches the actual tag date
124+
125+
6. **Add or move entries** to the appropriate section under appropriate category headings.
126+
127+
- **CRITICAL**: When moving entries from "Unreleased" to a version section, merge them with existing entries under the same category heading
128+
- **NEVER create duplicate section headings** (e.g., don't create two "### Fixed" sections)
129+
- If the version section already has a category heading (e.g., "### Fixed"), add the moved entries to that existing section
130+
- Maintain the category order as defined above
131+
132+
7. **Verify formatting**:
133+
134+
- Bold description with period
135+
- Proper PR link (NO hash symbol)
136+
- Proper author link
137+
- Consistent with existing entries
138+
- File ends with a newline character
139+
140+
8. **Run linting** after making changes:
141+
142+
```bash
143+
bundle exec rubocop
144+
yarn run prettier
145+
```
146+
147+
9. **Show the user** the added or moved entries and explain what was done.
148+
149+
### For Beta to Non-Beta Version Release
150+
151+
When releasing from beta to a stable version (e.g., v1.1.0-beta.3 → v1.1.0):
152+
153+
1. **Remove all beta version labels** from the changelog:
154+
155+
- Change `### [v1.1.0-beta.1]`, `### [v1.1.0-beta.2]`, etc. to a single `### [v1.1.0]` section
156+
- Combine all beta entries into the stable release section
157+
158+
2. **Consolidate duplicate entries**:
159+
160+
- If bug fixes or changes were made to features introduced in earlier betas, keep only the final state
161+
- Remove redundant changelog entries for fixes to beta features
162+
- Keep the most recent/accurate description of each change
163+
164+
3. **Update version diff links** using `bundle exec rake update_changelog`
165+
166+
### For New Beta Version Release
167+
168+
When creating a new beta version, ask the user which approach to take:
169+
170+
**Option 1: Process changes since last beta**
171+
172+
- Only add entries for commits since the previous beta version
173+
- Maintains detailed history of what changed in each beta
174+
175+
**Option 2: Collapse all prior betas into current beta**
176+
177+
- Combine all beta changelog entries into the new beta version
178+
- Removes previous beta version sections
179+
- Cleaner changelog with less version noise
180+
181+
After the user chooses, proceed with that approach.
182+
183+
## Examples
184+
185+
Run this command to see real formatting examples from the codebase:
186+
187+
```bash
188+
grep -A 3 "^#### " CHANGELOG.md | head -30
189+
```
190+
191+
### Good Entry Example
192+
193+
```markdown
194+
- **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).
195+
```
196+
197+
### Entry with Sub-bullets Example
198+
199+
```markdown
200+
- **Multi-part feature**: Added new configuration options for enhanced functionality:
201+
- `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)
202+
- `another_option`: Description of another option. [PR 124](https://github.com/shakacode/package_json/pull/124) by [username](https://github.com/username)
203+
```
204+
205+
### Breaking Change Example
206+
207+
```markdown
208+
- **Method Removal**: Several deprecated methods have been removed. If you're using any of the following methods, you'll need to migrate:
209+
- `old_method_one()`
210+
- `old_method_two()`
211+
212+
**Migration Guide:**
213+
214+
To migrate:
215+
216+
1. Replace `old_method_one()` with `new_method()`
217+
2. Update configuration to use new format
218+
```
219+
220+
## Additional Notes
221+
222+
- Keep descriptions concise but informative
223+
- Focus on the "what" and "why", not the "how"
224+
- Use past tense for the description
225+
- Be consistent with existing formatting in the changelog
226+
- Always ensure the file ends with a trailing newline
227+
- See CHANGELOG.md for additional contributor guidelines

‎CLAUDE.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## ⚠️ CRITICAL REQUIREMENTS
6+
7+
**BEFORE EVERY COMMIT/PUSH:**
8+
9+
1. **ALWAYS run `bundle exec rubocop` and fix ALL violations**
10+
2. **ALWAYS ensure files end with a newline character**
11+
3. **NEVER push without running full lint check first**
12+
13+
These requirements are non-negotiable. CI will fail if not followed.
14+
15+
## Development Commands
16+
17+
### Essential Commands
18+
19+
- **Install dependencies**: `bundle install`
20+
- **Run tests**: `rake spec` or `bundle exec rspec`
21+
- **Linting** (MANDATORY BEFORE EVERY COMMIT):
22+
- **REQUIRED**: `bundle exec rubocop` - Must pass with zero offenses
23+
- Auto-fix RuboCop violations: `bundle exec rubocop -a`
24+
- **⚠️ MANDATORY BEFORE GIT PUSH**: `bundle exec rubocop` and fix ALL violations + ensure trailing newlines
25+
- **Default task** (runs tests and rubocop): `rake`
26+
27+
## Changelog
28+
29+
- **Update CHANGELOG.md for user-visible changes only** (features, bug fixes, breaking changes, deprecations, performance improvements)
30+
- **Do NOT add entries for**: linting, formatting, refactoring, tests, or documentation fixes
31+
- **Format**: `[PR 123](https://github.com/shakacode/package_json/pull/123) by [username](https://github.com/username)` (no hash in PR number)
32+
- **Use `/update-changelog` command** for guided changelog updates with automatic formatting
33+
- **Version management**: Run `bundle exec rake update_changelog` after releases to update version headers (if task exists)
34+
- **Examples**: Run `grep -A 3 "^#### " CHANGELOG.md | head -30` to see real formatting examples
35+
36+
## ⚠️ FORMATTING RULES
37+
38+
**RuboCop is the SOLE authority for formatting Ruby files. NEVER manually format code.**
39+
40+
### Standard Workflow
41+
1. Make code changes
42+
2. Run `bundle exec rubocop -a` to auto-fix violations
43+
3. Commit changes
44+
45+
### Debugging Formatting Issues
46+
- Check for violations: `bundle exec rubocop`
47+
- Fix violations: `bundle exec rubocop -a`
48+
- If CI fails on formatting, always run automated fixes, never manual fixes
49+
50+
## Project Architecture
51+
52+
### Core Components
53+
54+
This is a Ruby gem that provides a Ruby interface for managing `package.json` files and JavaScript package managers.
55+
56+
#### Ruby Side (`lib/package_json/`)
57+
58+
- **`lib/package_json.rb`**: Main entry point and core PackageJson class
59+
- **`lib/package_json/manager.rb`**: Base class for package manager abstraction
60+
- **`lib/package_json/managers/`**: Specific implementations for npm, yarn, pnpm, bun, etc.
61+
62+
### Build System
63+
64+
- **Ruby**: Standard gemspec-based build (see `package_json.gemspec`)
65+
- **Testing**: RSpec for Ruby tests
66+
- **Linting**: RuboCop for Ruby
67+
68+
## Important Notes
69+
70+
- This gem provides a "middle-level" abstraction over JavaScript package managers
71+
- Supports npm, yarn (classic and berry), pnpm, and bun
72+
- Does not capture or intercept package manager output by default
73+
- Uses `Kernel.system` under the hood for package manager operations
74+
75+
## Contributing
76+
77+
Bug reports and pull requests are welcome on GitHub at https://github.com/shakacode/package_json.

0 commit comments

Comments
 (0)