Push Flow Convention

Push Flow Convention

Every repository MUST enforce the same pre-commit, pre-push, and versioning flow. No push lands without hooks, lint-staged, and a version bump.

Required Setup

1. Lefthook (pre-commit + pre-push)

Always use Lefthook for git hooks. Never use husky.

Install once per repo:

pnpm add -D lefthook lint-staged
pnpm exec lefthook install

Create lefthook.yml in project root:

pre-commit:
  commands:
    lint-staged:
      run: pnpm exec lint-staged

pre-push:
  commands:
    lint-staged:
      run: pnpm exec lint-staged --diff="origin/{push_remote_branch}...HEAD"
    bump:
      run: pnpm run bump

2. lint-staged

Declared in package.json. Runs ONLY on staged files so commits stay fast.

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,yml,yaml}": [
      "prettier --write"
    ]
  }
}

3. Version bump script

package.json MUST expose a bump script used by pre-push:

{
  "scripts": {
    "bump": "node scripts/bump-version.mjs"
  }
}

The script inspects the diff between the current branch and its upstream, applies the semver rule below, and writes the new version back to package.json. Commit the bump before pushing (amend the previous commit or create a chore: adjust package.json version (bump) commit — see commit-convention).

Semver Rules (applied on every push)

The bump is based on the changes in the commits being pushed:

Rules in order of precedence:

1. If ANY commit being pushed is a feat(...) → major bump.
2. Otherwise, count files changed (git diff --name-only origin/<branch>...HEAD | wc -l):
   • fewer than 5 → patch
   • 5 or more → minor

The feat rule always wins — a new feature is always a major bump regardless of file count.

Non-negotiables

1. NEVER push without pre-commit and pre-push hooks installed.
2. NEVER bypass hooks with --no-verify — if a hook fails, fix the root cause.
3. NEVER push without a version bump. Every push = new version.
4. The bump commit MUST use the chore: adjust package.json version (bump) message (see commit-convention).
5. lint-staged MUST run on every commit. A green lint-staged is a prerequisite for the commit to be created.
6. If pnpm is not the package manager, substitute with npm or yarn but keep the same flow.

Quick verification checklist

Before declaring the push flow set up, confirm:

• lefthook.yml exists with pre-commit and pre-push hooks
• pnpm exec lefthook install has been run (hooks registered in .git/hooks/)
• package.json has a lint-staged block
• package.json has a bump script
• A dry-run commit triggers lint-staged
• A dry-run push triggers the version bump