Skip to content

Commit 9bdc1fe

Browse files
G-RathG-Rath
authored
Merge branch 'main' into justin808/add-precommit-hook
2 parents 5a903b7 + 8dc8cf8 commit 9bdc1fe

File tree

5 files changed

+377
-3
lines changed

5 files changed

+377
-3
lines changed

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

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

‎.github/workflows/claude-code-review.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,5 +53,7 @@ jobs:
5353
5454
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
5555
# or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
56-
claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
57-
56+
claude_args:
57+
'--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh
58+
issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr
59+
view:*),Bash(gh pr list:*)"'

‎.github/workflows/claude.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,4 +47,3 @@ jobs:
4747
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
4848
# or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
4949
# claude_args: '--allowed-tools Bash(gh pr:*)'
50-

‎.github/workflows/title.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
name: PR Title
2+
on:
3+
pull_request:
4+
types:
5+
- opened
6+
- edited
7+
- reopened
8+
concurrency:
9+
# Pushing new changes to a branch will cancel any in-progress CI runs
10+
group: ${{ github.workflow }}-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
# Restrict jobs in this workflow to have no permissions by default; permissions
14+
# should be granted per job as needed using a dedicated `permissions` block
15+
permissions: {}
16+
17+
jobs:
18+
check:
19+
runs-on: ubuntu-latest
20+
permissions:
21+
pull-requests: read
22+
steps:
23+
- uses: amannn/[email protected]
24+
env:
25+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎CLAUDE.md‎

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

0 commit comments

Comments
 (0)