BUG-HUNT: [process] Global npm dependency for commit messages in Python project #2416

New issue

Open

opened 2026-04-03 17:39:48 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 17:39:48 +00:00

Owner

Background and Context

The CONTRIBUTING.md file (lines 173–174) instructs developers to globally install commitizen and cz-customizable via npm to format commit messages:

npm install -g commitizen@2.8.6 cz-customizable@4.0.0

This introduces a Node.js/npm dependency into the development workflow of a Python-centric project. The rest of the toolchain (nox, hatch, pyright, ruff, behave, robot) is entirely Python-based. Requiring a global npm installation is inconsistent with the project's tooling philosophy and creates friction for contributors who may not have Node.js installed.

Current Behavior

Contributors must install commitizen@2.8.6 and cz-customizable@4.0.0 globally via npm to use the interactive git cz commit helper. This:

Introduces a Node.js/npm dependency into a Python project
Relies on globally pinned versions that may conflict with other projects
Creates reproducibility issues (different contributors may have different global versions)
Adds friction to the onboarding process for Python developers unfamiliar with npm

Expected Behavior

All development dependencies should be managed within the project's primary Python toolchain. The commit message helper should be available via a nox session (e.g., nox -s commit) or as a pre-commit hook, without requiring any global npm installation. A Python-native alternative (e.g., commitizen from PyPI — cz-git or the commitizen Python package) should be used instead.

Acceptance Criteria

The npm-based commitizen global install instruction is removed from CONTRIBUTING.md
A Python-native commit message helper is integrated into the project's toolchain (e.g., via nox session or pre-commit hook)
Contributors can format commit messages using only Python/nox tooling (no Node.js required)
CONTRIBUTING.md is updated to reflect the new workflow
The new workflow is tested and verified to produce Conventional Changelog-compliant commit messages

Supporting Information

File: CONTRIBUTING.md, lines 173–174
Severity: Medium — affects every contributor's onboarding experience
Category: consistency
Reported by: ca-bug-hunter (Bug Hunting supervisor)

Metadata

Branch: fix/contributing-remove-npm-commitizen-dependency
Commit Message: fix(contributing): replace global npm commitizen with Python-native commit tooling
Milestone: v3.8.0
Parent Epic: #1678

Subtasks

Research Python-native commitizen alternatives (e.g., commitizen PyPI package, pre-commit hooks)
Add chosen tool as a dev dependency in pyproject.toml (managed by hatch/uv)
Create a nox session (e.g., nox -s commit) or pre-commit hook for interactive commit formatting
Remove the npm install -g commitizen cz-customizable instruction from CONTRIBUTING.md
Update CONTRIBUTING.md to document the new Python-native commit workflow
Verify the new workflow produces Conventional Changelog-compliant commit messages
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage >= 97%.

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: ca-new-issue-creator

## Background and Context The `CONTRIBUTING.md` file (lines 173–174) instructs developers to globally install `commitizen` and `cz-customizable` via `npm` to format commit messages: ```bash npm install -g commitizen@2.8.6 cz-customizable@4.0.0 ``` This introduces a Node.js/npm dependency into the development workflow of a Python-centric project. The rest of the toolchain (`nox`, `hatch`, `pyright`, `ruff`, `behave`, `robot`) is entirely Python-based. Requiring a global npm installation is inconsistent with the project's tooling philosophy and creates friction for contributors who may not have Node.js installed. ## Current Behavior Contributors must install `commitizen@2.8.6` and `cz-customizable@4.0.0` globally via `npm` to use the interactive `git cz` commit helper. This: - Introduces a Node.js/npm dependency into a Python project - Relies on globally pinned versions that may conflict with other projects - Creates reproducibility issues (different contributors may have different global versions) - Adds friction to the onboarding process for Python developers unfamiliar with npm ## Expected Behavior All development dependencies should be managed within the project's primary Python toolchain. The commit message helper should be available via a `nox` session (e.g., `nox -s commit`) or as a `pre-commit` hook, without requiring any global npm installation. A Python-native alternative (e.g., `commitizen` from PyPI — `cz-git` or the `commitizen` Python package) should be used instead. ## Acceptance Criteria - [ ] The npm-based `commitizen` global install instruction is removed from `CONTRIBUTING.md` - [ ] A Python-native commit message helper is integrated into the project's toolchain (e.g., via `nox` session or `pre-commit` hook) - [ ] Contributors can format commit messages using only Python/nox tooling (no Node.js required) - [ ] `CONTRIBUTING.md` is updated to reflect the new workflow - [ ] The new workflow is tested and verified to produce Conventional Changelog-compliant commit messages ## Supporting Information - **File**: `CONTRIBUTING.md`, lines 173–174 - **Severity**: Medium — affects every contributor's onboarding experience - **Category**: consistency - **Reported by**: ca-bug-hunter (Bug Hunting supervisor) ## Metadata - **Branch**: `fix/contributing-remove-npm-commitizen-dependency` - **Commit Message**: `fix(contributing): replace global npm commitizen with Python-native commit tooling` - **Milestone**: v3.8.0 - **Parent Epic**: #1678 ## Subtasks - [ ] Research Python-native commitizen alternatives (e.g., `commitizen` PyPI package, `pre-commit` hooks) - [ ] Add chosen tool as a dev dependency in `pyproject.toml` (managed by `hatch`/`uv`) - [ ] Create a `nox` session (e.g., `nox -s commit`) or `pre-commit` hook for interactive commit formatting - [ ] Remove the `npm install -g commitizen cz-customizable` instruction from `CONTRIBUTING.md` - [ ] Update `CONTRIBUTING.md` to document the new Python-native commit workflow - [ ] Verify the new workflow produces Conventional Changelog-compliant commit messages - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator

freemo added this to the v3.8.0 milestone

2026-04-03 17:39:59 +00:00

freemo referenced this issue

2026-04-03 17:40:35 +00:00

[CA-GROOMER] Backlog Groomer — Session State (groomer-1) #2386

freemo added a new dependency

2026-04-03 17:41:05 +00:00

#1678 Epic: CI Execution Time Optimization — Timeouts, Concurrency, and Coverage Artifact Sharing

freemo commented

2026-04-03 18:24:33 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — A global npm dependency in a Python project is a toolchain inconsistency, not a functional bug.
Milestone: v3.8.0
MoSCoW: Could Have — This is a developer experience improvement. The npm dependency works and is documented. Replacing it with a Python-native solution is desirable but not urgent.
Parent Epic: Needs assignment — this is a tooling/infrastructure issue. Will link to Epic #362 (Security & Safety Hardening) as the closest match for build process improvements.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — A global npm dependency in a Python project is a toolchain inconsistency, not a functional bug. - **Milestone**: v3.8.0 - **MoSCoW**: Could Have — This is a developer experience improvement. The npm dependency works and is documented. Replacing it with a Python-native solution is desirable but not urgent. - **Parent Epic**: Needs assignment — this is a tooling/infrastructure issue. Will link to Epic #362 (Security & Safety Hardening) as the closest match for build process improvements. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added the

MoSCoW

Could have

label

2026-04-03 18:25:30 +00:00

freemo removed the

MoSCoW

Could have

label

2026-04-05 03:59:42 +00:00