github2gerrit 1.0.8__tar.gz → 1.0.9__tar.gz

{github2gerrit-1.0.8 → github2gerrit-1.0.9}/.pre-commit-config.yaml

@@ -59,7 +59,7 @@ repos:
         types: [yaml]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: a27a2e47c7751b639d2b5badf0ef6ff11fee893f  # frozen: v0.15.4
+    rev: b969e2851312ca2b24bbec879ba4954341d1bd12  # frozen: v0.15.5
     hooks:
       - id: ruff
         files: ^(src|scripts|tests)/.+\.py$
@@ -96,7 +96,7 @@ repos:
       - id: shellcheck
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: 76b3d32d3f4b965e1d6425253c59407420ae2c43  # frozen: v0.47.0
+    rev: e72a3ca1632f0b11a07d171449fe447a7ff6795e  # frozen: v0.48.0
     hooks:
       - id: markdownlint
         args: ["--fix", "--config", ".markdownlint.yaml"]
@@ -116,7 +116,7 @@ repos:
 
   # Check for misspellings in documentation files
   - repo: https://github.com/codespell-project/codespell
-    rev: 63c8f8312b7559622c0d82815639671ae42132ac # frozen: v2.4.1
+    rev: 2ccb47ff45ad361a21071a7eedda4c37e6ae8c5a  # frozen: v2.4.2
     hooks:
       - id: codespell
 

{github2gerrit-1.0.8 → github2gerrit-1.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github2gerrit
-Version: 1.0.8
+Version: 1.0.9
 Summary: Submit a GitHub pull request to a Gerrit repository.
 Project-URL: Homepage, https://github.com/lfreleng-actions/github2gerrit-action
 Project-URL: Repository, https://github.com/lfreleng-actions/github2gerrit-action
@@ -39,7 +39,6 @@ Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
 Requires-Dist: pytest>=9.0.2; extra == 'dev'
 Requires-Dist: responses>=0.25.8; extra == 'dev'
 Requires-Dist: ruff>=0.6.3; extra == 'dev'
-Requires-Dist: types-click>=7.1.8; extra == 'dev'
 Requires-Dist: types-requests>=2.31.0; extra == 'dev'
 Requires-Dist: types-urllib3>=1.26.25.14; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -1637,7 +1636,9 @@ requiring manual configuration per PR or user.
   - `src/github2gerrit/gitutils.py` (subprocess and git helpers)
 - Linting and type checking
   - Ruff and MyPy use settings in `pyproject.toml`.
-  - Run from pre‑commit hooks and CI.
+  - Run from [prek](https://github.com/j178/prek) hooks and CI.
+  - prek is a faster, Rust-based drop-in replacement for pre-commit
+    that reads the existing `.pre-commit-config.yaml` unchanged.
 - Tests
   - Pytest with coverage targets around 80%.
   - Add unit and integration tests for each feature.
@@ -1647,6 +1648,10 @@ requiring manual configuration per PR or user.
 - Install `uv` and run:
   - `uv pip install --system .`
   - `uv run github2gerrit --help`
+- Install prek hooks:
+  - `uv tool install prek && prek install -f`
+- Run all checks (including tests) manually:
+  - `prek run --all-files`
 - Run tests:
   - `uv run pytest -q`
 - Lint and type check:

{github2gerrit-1.0.8 → github2gerrit-1.0.9}/README.md

@@ -1591,7 +1591,9 @@ requiring manual configuration per PR or user.
   - `src/github2gerrit/gitutils.py` (subprocess and git helpers)
 - Linting and type checking
   - Ruff and MyPy use settings in `pyproject.toml`.
-  - Run from pre‑commit hooks and CI.
+  - Run from [prek](https://github.com/j178/prek) hooks and CI.
+  - prek is a faster, Rust-based drop-in replacement for pre-commit
+    that reads the existing `.pre-commit-config.yaml` unchanged.
 - Tests
   - Pytest with coverage targets around 80%.
   - Add unit and integration tests for each feature.
@@ -1601,6 +1603,10 @@ requiring manual configuration per PR or user.
 - Install `uv` and run:
   - `uv pip install --system .`
   - `uv run github2gerrit --help`
+- Install prek hooks:
+  - `uv tool install prek && prek install -f`
+- Run all checks (including tests) manually:
+  - `prek run --all-files`
 - Run tests:
   - `uv run pytest -q`
 - Lint and type check:

{github2gerrit-1.0.8 → github2gerrit-1.0.9}/action.yaml

@@ -129,6 +129,14 @@ inputs:
       (format: [{"key": "username", "value": "ISSUE-ID"}])
     required: false
     default: "[]"
+  COMMIT_RULES_JSON:
+    description: >-
+      JSON object defining commit message rules with per-project and
+      per-actor overrides. Supports arbitrary label-value pairs placed
+      in the commit body or trailer block.
+      (see: docs/COMMIT_RULES.md)
+    required: false
+    default: ""
   AUTOMATION_ONLY:
     description: "Only accept pull requests from known automation tools"
     required: false
@@ -168,7 +176,7 @@ runs:
 
     - name: "Setup uv"
       # yamllint disable-line rule:line-length
-      uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098  # v7.3.1
+      uses: astral-sh/setup-uv@e06108dd0aef18192324c70427afc47652e63a82  # v7.5.0
       with:
         enable-cache: false
 
@@ -294,6 +302,7 @@ runs:
         ALLOW_DUPLICATES: ${{ inputs.ALLOW_DUPLICATES }}
         ISSUE_ID: ${{ inputs.ISSUE_ID }}
         ISSUE_ID_LOOKUP_JSON: ${{ inputs.ISSUE_ID_LOOKUP_JSON }}
+        COMMIT_RULES_JSON: ${{ inputs.COMMIT_RULES_JSON }}
         CI_TESTING: ${{ inputs.CI_TESTING }}
         CLOSE_MERGED_PRS: ${{ inputs.CLOSE_MERGED_PRS }}
         FORCE: ${{ inputs.FORCE }}

github2gerrit-1.0.9/docs/COMMIT_RULES.md

@@ -0,0 +1,255 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2025 The Linux Foundation -->
+
+# Commit Rules (`COMMIT_RULES_JSON`)
+
+The **commit rules** feature provides a flexible, JSON-driven mechanism for
+injecting arbitrary lines into commit messages submitted to Gerrit. It
+generalises the existing `ISSUE_ID` / `ISSUE_ID_LOOKUP_JSON` support to handle
+per-project requirements such as FD.io VPP's mandatory `Type:` field.
+
+## Quick Start
+
+Set the `COMMIT_RULES_JSON` GitHub Actions variable (organisation or
+repository level) to a JSON object describing the rules:
+
+```yaml
+# .github/workflows/g2g.yml
+jobs:
+  submit:
+    steps:
+      - uses: lfreleng-actions/github2gerrit-action@main
+        with:
+          COMMIT_RULES_JSON: ${{ vars.COMMIT_RULES_JSON }}
+          # ... other inputs ...
+```
+
+## JSON Schema
+
+The top-level object has three optional sections:
+
+| Section    | Type                          | Description                                    |
+|------------|-------------------------------|------------------------------------------------|
+| `defaults` | `array` of rule objects       | Baseline rules applied to every commit.        |
+| `projects` | `object` (project → rules[])  | Per-Gerrit-project overrides.                  |
+| `actors`   | `object` (actor → rules[])    | Per-GitHub-actor overrides (e.g. bots).        |
+
+### Rule Object
+
+Each rule object describes a single line to insert into the commit message:
+
+| Field       | Type     | Required | Default        | Description                                                                |
+|-------------|----------|----------|----------------|----------------------------------------------------------------------------|
+| `key`       | `string` | Yes      | —              | The label name (e.g. `Type`, `Issue-ID`, `Ticket`).                        |
+| `value`     | `string` | Yes      | —              | The value to insert.                                                       |
+| `location`  | `string` | No       | `"trailer"`    | Where to place the line — `"trailer"` or `"body"`.                         |
+| `separator` | `string` | No       | `"blank_line"` | Separation style when `location` is `"body"` — `"blank_line"` or `"none"`. |
+
+### Locations
+
+- **`trailer`** — places the line in the Git trailer block at the end of
+  the commit message, alongside `Change-Id`, `Signed-off-by`, etc.
+- **`body`** — places the line in the commit body, before the trailer
+  block. Fields like VPP's `Type:` need this location because Gerrit
+  server-side hooks expect them in the body rather than the trailer section.
+
+### Separators (body location only)
+
+- **`blank_line`** (default) — inserts a blank line before the new
+  content, matching the conventional VPP commit style.
+- **`none`** — appends the line directly after the existing body text
+  without extra blank lines.
+
+## Resolution Precedence
+
+The engine resolves rules in this order when building the commit message
+(last writer wins for a given `key`):
+
+1. **`defaults`** — baseline rules for all projects and actors.
+2. **`projects[<gerrit_project>]`** — overrides defaults for the matching
+   Gerrit project (from `.gitreview` or `GERRIT_PROJECT`).
+3. **`actors[<github_actor>]`** — overrides everything for the matching
+   GitHub actor (from `GITHUB_ACTOR`).
+
+The existing `ISSUE_ID` input always takes priority over any `Issue-ID`
+rule from commit rules. Both mechanisms can coexist safely.
+
+## Examples
+
+### FD.io (VPP + CSIT on the same Gerrit server)
+
+VPP requires a `Type:` field in the commit body; CSIT does not.
+Both projects need `Issue-ID` in the trailer block.
+
+```json
+{
+  "defaults": [
+    {
+      "key": "Issue-ID",
+      "value": "CIMAN-33",
+      "location": "trailer"
+    }
+  ],
+  "projects": {
+    "vpp": [
+      {
+        "key": "Type",
+        "value": "ci",
+        "location": "body",
+        "separator": "blank_line"
+      },
+      {
+        "key": "Issue-ID",
+        "value": "CIMAN-33",
+        "location": "trailer"
+      }
+    ],
+    "hicn": [
+      {
+        "key": "Type",
+        "value": "ci",
+        "location": "body",
+        "separator": "blank_line"
+      }
+    ]
+  },
+  "actors": {
+    "dependabot[bot]": [
+      {
+        "key": "Type",
+        "value": "ci",
+        "location": "body"
+      },
+      {
+        "key": "Issue-ID",
+        "value": "CIMAN-33",
+        "location": "trailer"
+      }
+    ],
+    "renovate[bot]": [
+      {
+        "key": "Issue-ID",
+        "value": "CIMAN-44",
+        "location": "trailer"
+      }
+    ]
+  }
+}
+```
+
+**Result for VPP + dependabot:**
+
+```text
+gha: update actions/checkout from v3 to v4
+
+Type: ci
+
+Issue-ID: CIMAN-33
+Change-Id: I1234567890abcdef...
+Signed-off-by: dependabot[bot] <support@github.com>
+```
+
+**Result for CSIT + human user:**
+
+```text
+fix: correct test assertion
+
+Issue-ID: CIMAN-33
+Change-Id: I1234567890abcdef...
+Signed-off-by: Jane Doe <jane@example.com>
+```
+
+### ONAP (Issue-ID only)
+
+ONAP projects only need `Issue-ID` in the trailer:
+
+```json
+{
+  "actors": {
+    "dependabot[bot]": [
+      {
+        "key": "Issue-ID",
+        "value": "CIMAN-33"
+      }
+    ]
+  }
+}
+```
+
+### Extra body fields
+
+Some projects need more than one body field:
+
+```json
+{
+  "projects": {
+    "vpp": [
+      {
+        "key": "Type",
+        "value": "ci",
+        "location": "body",
+        "separator": "blank_line"
+      },
+      {
+        "key": "Ticket",
+        "value": "VPP-2088",
+        "location": "body",
+        "separator": "none"
+      }
+    ]
+  }
+}
+```
+
+**Result:**
+
+```text
+gha: update dependency versions
+
+Type: ci
+Ticket: VPP-2088
+
+Change-Id: I1234567890abcdef...
+Signed-off-by: bot <bot@example.com>
+```
+
+## CLI Usage
+
+You can also pass the commit rules JSON via the command line:
+
+```bash
+github2gerrit --commit-rules '{"defaults": [...]}' \
+  https://github.com/org/repo/pull/123
+```
+
+Or via the environment variable:
+
+```bash
+export COMMIT_RULES_JSON='{"defaults": [...]}'
+github2gerrit https://github.com/org/repo/pull/123
+```
+
+## Interaction with ISSUE_ID / ISSUE_ID_LOOKUP_JSON
+
+The existing `ISSUE_ID` and `ISSUE_ID_LOOKUP_JSON` inputs continue to
+work unchanged. When both mechanisms specify an `Issue-ID`:
+
+1. An explicit `ISSUE_ID` input (or a value resolved from
+   `ISSUE_ID_LOOKUP_JSON`) **always wins**.
+2. If `ISSUE_ID` is empty, the engine applies the `Issue-ID` rule from
+   `COMMIT_RULES_JSON` instead.
+
+This means you can safely enable `COMMIT_RULES_JSON` for an organisation
+without breaking workflows that already set `ISSUE_ID` directly.
+
+## Validation and Error Handling
+
+- Invalid JSON produces a warning but does **not** fail the workflow
+  (matching the existing `ISSUE_ID_LOOKUP_JSON` convention).
+- Individual rule entries with missing or invalid `key`/`value` fields
+  produce a warning and the engine skips them; valid entries in the same
+  document still apply.
+- Unknown `location` values default to `"trailer"` with a warning.
+- Unknown `separator` values default to `"blank_line"` with a warning.
+- Duplicate lines are automatically detected and skipped (both in body
+  and trailer locations).

{github2gerrit-1.0.8 → github2gerrit-1.0.9}/pyproject.toml

@@ -102,7 +102,6 @@ dev = [
   # Type checking helpers
   "pytest-mock>=3.15.1",
   "types-requests>=2.31.0",
-  "types-click>=7.1.8",
   "types-urllib3>=1.26.25.14",
 ]
 
@@ -230,7 +229,6 @@ directory = "coverage_html_report"
 minversion = "8.0"
 addopts = "-ra -q --cov=github2gerrit --cov-report=term-missing --cov-report=html"
 testpaths = ["tests"]
-asyncio_default_fixture_loop_scope = "function"
 markers = [
     "integration: marks tests as integration tests (deselect with '-m \"not integration\"')",
 ]

{github2gerrit-1.0.8 → github2gerrit-1.0.9}/src/github2gerrit/cli.py

@@ -22,6 +22,7 @@ from typing import cast
 from urllib.parse import urlparse
 
 import click
+import click.core
 import typer
 
 from . import models
@@ -674,6 +675,16 @@ def main(
             "for automatic lookup."
         ),
     ),
+    commit_rules_json: str = typer.Option(
+        "",
+        "--commit-rules",
+        envvar="COMMIT_RULES_JSON",
+        help=(
+            "JSON object defining commit message rules with per-project "
+            "and per-actor overrides. Supports arbitrary key-value lines "
+            "placed in the commit body or trailer block."
+        ),
+    ),
     log_reconcile_json: bool = typer.Option(
         True,
         "--log-reconcile-json/--no-log-reconcile-json",
@@ -845,8 +856,8 @@ def main(
         param_name: str, env_var: str, current: bool
     ) -> bool:
         """Return *current* if the CLI flag was explicit, else parse env."""
-        source = ctx.get_parameter_source(param_name)
-        if source == click.core.ParameterSource.COMMANDLINE:
+        source = ctx.get_parameter_source(param_name)  # pyright: ignore[reportAttributeAccessIssue]
+        if source == click.core.ParameterSource.COMMANDLINE:  # pyright: ignore[reportAttributeAccessIssue]
             return current
         env_val = os.getenv(env_var)
         if env_val is not None:
@@ -995,6 +1006,9 @@ def main(
 
     if resolved_issue_id:
         os.environ["ISSUE_ID"] = resolved_issue_id
+    # Always set COMMIT_RULES_JSON so passing an empty string via CLI
+    # clears any pre-existing env var rather than leaving stale rules.
+    os.environ["COMMIT_RULES_JSON"] = commit_rules_json or ""
     os.environ["ALLOW_DUPLICATES"] = "true" if allow_duplicates else "false"
     os.environ["CI_TESTING"] = "true" if ci_testing else "false"
     os.environ["CLOSE_MERGED_PRS"] = "true" if close_merged_prs else "false"
@@ -1173,6 +1187,7 @@ def _build_inputs_from_env() -> Inputs:
         gerrit_project=env_str("GERRIT_PROJECT"),
         issue_id=env_str("ISSUE_ID", ""),
         issue_id_lookup_json=env_str("ISSUE_ID_LOOKUP_JSON", ""),
+        commit_rules_json=env_str("COMMIT_RULES_JSON", ""),
         allow_duplicates=env_bool("ALLOW_DUPLICATES", True),
         ci_testing=env_bool("CI_TESTING", False),
         duplicates_filter=env_str("DUPLICATE_TYPES", "open"),
@@ -1620,8 +1635,9 @@ def _process_single(
                         progress_tracker=progress_tracker,
                     )
                     safe_console_print(
-                        "   To create a new change, trigger the 'opened' "
-                        "workflow action.",
+                        "   To create a new change, set CREATE_MISSING=true "
+                        "or add a '@github2gerrit create missing change' "
+                        "comment on the PR.",
                         style="yellow",
                         progress_tracker=progress_tracker,
                     )
@@ -1800,6 +1816,7 @@ def _load_effective_inputs() -> Inputs:
                     gerrit_project=data.gerrit_project,
                     issue_id=data.issue_id,
                     issue_id_lookup_json=data.issue_id_lookup_json,
+                    commit_rules_json=data.commit_rules_json,
                     allow_duplicates=data.allow_duplicates,
                     ci_testing=data.ci_testing,
                     duplicates_filter=data.duplicates_filter,