Add pre-commit hooks for maintaining version match
Pre-commit Hook for Version Synchronization
Summary
Adds automated version synchronization using pre-commit hooks to ensure version consistency across all project files.
Problem
The project maintains version references in multiple files (package.json, markdownlint.js, README.md, .pre-commit-hooks.yaml). When updating versions, it's easy to miss updating one or more files, leading to inconsistencies.
See https://github.com/dncrews/markdownlint-cli/pull/2 for a demonstration where tests pass (because package.json and markdownlint.js match) but the pre-commit hook correctly fails because README.md and .pre-commit-hooks.yaml weren't updated.
Solution
-
Pre-commit hook: Automatically syncs all version references to match
package.jsonbefore each commit - CI enforcement: GitHub Actions workflow runs pre-commit checks on all PRs
- Developer documentation: Added Contributing section to README with setup instructions for all platforms
Changes
- Added
.pre-commit-config.yamlwith version sync hook - Added
.github/scripts/sync-version-on-commit.mjsto handle version synchronization - Added
.github/workflows/pre-commit.ymlto run hooks in CI - Updated
README.mdwith contributor setup instructions
How It Works
When any version-related file is modified:
- Pre-commit hook reads version from
package.json(source of truth) - Updates all other files to match
- If files were modified, commit fails with instructions to review and stage changes
- Developer reviews changes, stages them, and retries commit
Benefits
- Eliminates manual version sync across files
- Catches version mismatches before they reach remote (as shown in the demo PR)
- Works locally and in CI for comprehensive coverage
- Clear setup instructions for new contributors
- Fixes #578
Next Steps
For maintainers: To make this check mandatory, add pre-commit as a required status check in the branch protection rules for master (Settings → Branches → Branch protection rules).
I'll leave this PR open for comment, but my initial thoughts are captured here and explain why I'm not merging this right now: https://github.com/igorshubovych/markdownlint-cli/issues/578#issuecomment-3564725106