Skip to content

Commit 3ba1ba4

Browse files
justin808claude
justin808
and
claude
authored
Add changelog guidelines to CLAUDE.md (#208)
Following the approach from React on Rails PR #1867, this adds comprehensive changelog documentation requirements to this project. Changes: - Added .claude/commands/update-changelog.md with detailed changelog guidelines - Created CLAUDE.md with project-specific guidance for Claude Code - Adapted content for cypress-on-rails project (removed RuboCop references since this project doesn't use it) - Included formatting requirements, entry structure, and version management guidance 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 d1662ca commit 3ba1ba4

File tree

2 files changed

+293
-0
lines changed

2 files changed

+293
-0
lines changed

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

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# Update Changelog
2+
3+
You are helping to add an entry to the CHANGELOG.md file for the Cypress on Rails 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/cypress-on-rails/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/cypress-on-rails/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/cypress-on-rails/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+
- `#### API Improvements` - API changes and improvements
76+
- `#### Developer Experience` - Developer workflow improvements
77+
- `#### Generator Improvements` - Generator-specific changes
78+
- `#### Performance` - Performance improvements
79+
80+
**Prefer standard headings.** Only use custom headings when the change needs more specific categorization.
81+
82+
**Only include section headings that have entries.**
83+
84+
### Version Management
85+
86+
After adding entries, use the rake task to manage version headers:
87+
88+
```bash
89+
bundle exec rake update_changelog
90+
```
91+
92+
This will:
93+
94+
- Add headers for the new version
95+
- Update version diff links at the bottom of the file
96+
97+
## Process
98+
99+
### For Regular Changelog Updates
100+
101+
1. **Determine the correct version tag to compare against**:
102+
103+
- First, check the tag dates: `git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10`
104+
- Find the latest version tag and its date
105+
- Compare main branch date to the tag date
106+
- If the tag is NEWER than main, it means main needs to be updated to include the tag's commits
107+
- **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
108+
109+
2. **Check commits and version boundaries**:
110+
111+
- Run `git log --oneline LAST_TAG..master` to see commits since the last release
112+
- Also check `git log --oneline master..LAST_TAG` to see if the tag is ahead of master
113+
- If the tag is ahead, entries in "Unreleased" section may actually belong to that tagged version
114+
- Identify which commits contain user-visible changes
115+
- Extract PR numbers and author information from commit messages
116+
- **Never ask the user for PR details** - get them from the git history
117+
118+
3. **Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits.
119+
120+
4. **Read the current CHANGELOG.md** to understand the existing structure and formatting.
121+
122+
5. **Determine where entries should go**:
123+
124+
- If the latest version tag is NEWER than master branch, move entries from "Unreleased" to that version section
125+
- If master is ahead of the latest tag, add new entries to "Unreleased"
126+
- Always verify the version date in CHANGELOG.md matches the actual tag date
127+
128+
6. **Add or move entries** to the appropriate section under appropriate category headings.
129+
130+
- **CRITICAL**: When moving entries from "Unreleased" to a version section, merge them with existing entries under the same category heading
131+
- **NEVER create duplicate section headings** (e.g., don't create two "### Fixed" sections)
132+
- If the version section already has a category heading (e.g., "### Fixed"), add the moved entries to that existing section
133+
- Maintain the category order as defined above
134+
135+
7. **Verify formatting**:
136+
137+
- Bold description with period
138+
- Proper PR link (NO hash symbol)
139+
- Proper author link
140+
- Consistent with existing entries
141+
- File ends with a newline character
142+
143+
8. **Show the user** the added or moved entries and explain what was done.
144+
145+
### For Beta to Non-Beta Version Release
146+
147+
When releasing from beta to a stable version (e.g., v2.1.0-beta.3 → v2.1.0):
148+
149+
1. **Remove all beta version labels** from the changelog:
150+
151+
- Change `### [v2.1.0-beta.1]`, `### [v2.1.0-beta.2]`, etc. to a single `### [v2.1.0]` section
152+
- Combine all beta entries into the stable release section
153+
154+
2. **Consolidate duplicate entries**:
155+
156+
- If bug fixes or changes were made to features introduced in earlier betas, keep only the final state
157+
- Remove redundant changelog entries for fixes to beta features
158+
- Keep the most recent/accurate description of each change
159+
160+
3. **Update version diff links** using `bundle exec rake update_changelog`
161+
162+
### For New Beta Version Release
163+
164+
When creating a new beta version, ask the user which approach to take:
165+
166+
**Option 1: Process changes since last beta**
167+
168+
- Only add entries for commits since the previous beta version
169+
- Maintains detailed history of what changed in each beta
170+
171+
**Option 2: Collapse all prior betas into current beta**
172+
173+
- Combine all beta changelog entries into the new beta version
174+
- Removes previous beta version sections
175+
- Cleaner changelog with less version noise
176+
177+
After the user chooses, proceed with that approach.
178+
179+
## Examples
180+
181+
Run this command to see real formatting examples from the codebase:
182+
183+
```bash
184+
grep -A 3 "^#### " CHANGELOG.md | head -30
185+
```
186+
187+
### Good Entry Example
188+
189+
```markdown
190+
- **Support for Playwright**: Added support for Playwright browser automation framework alongside Cypress. The gem now works with both Cypress and Playwright test suites. [PR 123](https://github.com/shakacode/cypress-on-rails/pull/123) by [username](https://github.com/username).
191+
```
192+
193+
### Entry with Sub-bullets Example
194+
195+
```markdown
196+
- **Enhanced Factory Bot Integration**: Improved factory bot integration with new configuration options:
197+
- `factory_bot_fixture_path`: Configurable directory for factory bot fixtures (default: "spec/fixtures")
198+
- `enable_factory_bot_cleanup`: Automatically clean up factory bot data after each test (default: true) [PR 456](https://github.com/shakacode/cypress-on-rails/pull/456) by [username](https://github.com/username)
199+
```
200+
201+
### Breaking Change Example
202+
203+
```markdown
204+
- **Ruby Version Requirement**: Minimum Ruby version increased from 2.5 to 2.7 to align with Rails 7 requirements. Ruby 2.5 and 2.6 are no longer supported.
205+
206+
**Migration Guide:**
207+
208+
To upgrade to this version:
209+
210+
1. Update your Ruby version to 2.7 or higher:
211+
rbenv install 2.7.0
212+
213+
2. Update your Gemfile to specify the minimum Ruby version:
214+
ruby '>= 2.7.0'
215+
```
216+
217+
## Additional Notes
218+
219+
- Keep descriptions concise but informative
220+
- Focus on the "what" and "why", not the "how"
221+
- Use past tense for the description
222+
- Be consistent with existing formatting in the changelog
223+
- Always ensure the file ends with a trailing newline
224+
- See CHANGELOG.md for additional formatting examples

‎CLAUDE.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
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 ensure files end with a newline character**
10+
2. **ALWAYS run tests before pushing**
11+
12+
These requirements are non-negotiable. CI will fail if not followed.
13+
14+
## Development Commands
15+
16+
### Essential Commands
17+
18+
- **Install dependencies**: `bundle`
19+
- **Run tests**:
20+
- Ruby tests: `bundle exec rspec`
21+
- All tests: `bundle exec rake` (default task runs tests)
22+
- **⚠️ MANDATORY BEFORE GIT PUSH**: Ensure tests pass + ensure trailing newlines
23+
24+
## Changelog
25+
26+
- **Update CHANGELOG.md for user-visible changes only** (features, bug fixes, breaking changes, deprecations, performance improvements)
27+
- **Do NOT add entries for**: linting, formatting, refactoring, tests, or documentation fixes
28+
- **Format**: `[PR 123](https://github.com/shakacode/cypress-on-rails/pull/123) by [username](https://github.com/username)` (no hash in PR number)
29+
- **Use `/update-changelog` command** for guided changelog updates with automatic formatting
30+
- **Version management**: Run `bundle exec rake update_changelog` after releases to update version headers (if rake task exists)
31+
- **Examples**: Run `grep -A 3 "^#### " CHANGELOG.md | head -30` to see real formatting examples
32+
33+
## Project Architecture
34+
35+
### Core Components
36+
37+
This is a Ruby gem that provides integration between Cypress/Playwright and Rails applications.
38+
39+
#### Ruby Side (`lib/cypress_on_rails/`)
40+
41+
- **`middleware.rb`**: Rack middleware for handling Cypress/Playwright commands
42+
- **`configuration.rb`**: Global configuration management
43+
- **Generators**: Located in `lib/generators/cypress_on_rails/`
44+
45+
#### Test Framework Support
46+
47+
- **Cypress**: JavaScript-based E2E testing framework
48+
- **Playwright**: Modern browser automation framework
49+
- Both frameworks share the same Ruby backend commands
50+
51+
### Build System
52+
53+
- **Ruby**: Standard gemspec-based build
54+
- **Testing**: RSpec for Ruby tests
55+
- **Linting**: RuboCop for Ruby
56+
57+
### Examples and Testing
58+
59+
- **Specs**: `spec/` - RSpec tests for the gem
60+
- **E2E Examples**: `specs_e2e/` - End-to-end test examples
61+
- **Rake tasks**: Defined in `rakelib/` for various development operations
62+
63+
## Important Notes
64+
65+
- Server-side commands are executed via Rack middleware
66+
- Commands can use factory_bot, database_cleaner, and other test helpers
67+
- VCR integration available for HTTP mocking
68+
- Supports both Cypress and Playwright frameworks
69+
- Configuration is done in `config/initializers/cypress_on_rails.rb`

0 commit comments

Comments
 (0)