markdownlint-cli icon indicating copy to clipboard operation
markdownlint-cli copied to clipboard

Add pre-commit hooks for maintaining version match

Open dncrews opened this issue 1 month ago • 1 comments

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.json before 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.yaml with version sync hook
  • Added .github/scripts/sync-version-on-commit.mjs to handle version synchronization
  • Added .github/workflows/pre-commit.yml to run hooks in CI
  • Updated README.md with contributor setup instructions

How It Works

When any version-related file is modified:

  1. Pre-commit hook reads version from package.json (source of truth)
  2. Updates all other files to match
  3. If files were modified, commit fails with instructions to review and stage changes
  4. 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).

dncrews avatar Nov 21 '25 20:11 dncrews

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

DavidAnson avatar Nov 21 '25 21:11 DavidAnson