feat(tooling,ci): add changelog formatting checks (#1691)

Co-authored-by: danceratopz <[email protected]>

Author: richardgreg

.github/workflows/tox_verify.yaml

@@ -53,6 +53,22 @@ jobs:
         env:
           GITHUB_STEP_SUMMARY: ${{ env.GITHUB_STEP_SUMMARY }}
 
+  changelog:
+    name: Validate changelog entries
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout ethereum/execution-spec-tests
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - name: Install uv ${{ vars.UV_VERSION }} and python ${{ vars.DEFAULT_PYTHON_VERSION }}
+        uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          version: ${{ vars.UV_VERSION }}
+          python-version: ${{ vars.DEFAULT_PYTHON_VERSION }}
+      - name: Run changelog validation via tox
+        run: uvx --with=tox-uv tox -e changelog
+
   markdownlint:
     name: Lint markdown files with markdownlint
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -9,7 +9,13 @@ repos:
         pass_filenames: false
       - id: tox-docs
         name: tox-docs
-        entry: uvx --with=tox-uv tox --parallel -e spellcheck,markdownlint,mkdocs
+        entry: uvx --with=tox-uv tox --parallel -e spellcheck,markdownlint
         language: system
         files: \.md$
         pass_filenames: false
+      - id: tox-changelog
+        name: tox-changelog
+        entry: uvx --with=tox-uv tox -e changelog
+        language: system
+        files: ^docs/CHANGELOG\.md$
+        pass_filenames: false

docs/CHANGELOG.md

@@ -16,6 +16,17 @@ Code pushed to @ethereum/execution-spec-tests must fulfill the following checks
 | HTML doc build         | `uvx --with=tox-uv tox -e mkdocs`               | Documentation generated without warnings.                                                                   |
 | Spellcheck             | `uvx --with=tox-uv tox -e spellcheck`           | Code and documentation spell-check using codespell. |
 | Markdown lint          | `uvx --with=tox-uv tox -e markdownlint`         | Markdown lint (requires [additional dependency](code_standards_details.md#additional-dependencies)).        |
+| Changelog validation   | `uvx --with=tox-uv tox -e changelog`            | Validates changelog entries format and structure in `docs/CHANGELOG.md`.                                    |
+
+!!! important "Avoid CI surprises - Use pre-commit hooks!"
+    **We strongly encourage all contributors to install and use pre-commit hooks!** This will run fast checks (lint, typecheck, spellcheck) automatically before each commit, helping you catch issues early and avoid frustrating CI failures after pushing your changes.
+
+    Install with one simple command:
+    ```console
+    uvx pre-commit install
+    ```
+    
+    This saves you time by catching formatting issues, type errors, and spelling mistakes before they reach CI.
 
 !!! tip "Running checks easily"
 
@@ -43,12 +54,6 @@ Code pushed to @ethereum/execution-spec-tests must fulfill the following checks
     uvx --with=tox-uv tox -e lint,typecheck
     ```
 
-    Use [pre-commit hooks](./code_standards_details.md#pre-commit-hooks) that perform the fastest checks:
-
-    ```
-    uvx pre-commit install
-    ```
-
 !!! tip "Lint & code formatting: Using `ruff` and VS Code to help autoformat and fix module imports"
 
     On the command-line, solve fixable issues with:

docs/getting_started/code_standards.md

@@ -47,7 +47,7 @@ uvx --with=tox-uv tox -e lint,typecheck,spellcheck,pytest
 #### For Documentation Changes (`./docs/`)
 
 ```console
-uvx --with=tox-uv tox -e spellcheck,markdownlint,mkdocs
+uvx --with=tox-uv tox -e spellcheck,markdownlint,mkdocs,changelog
 ```
 
 !!! note "Tox Virtual Environment"

docs/getting_started/code_standards_details.md

@@ -7,9 +7,11 @@
 """
 
 import os
+import re
 import shutil
 import subprocess
 import sys
+from pathlib import Path
 
 import click
 from pyspelling import __main__ as pyspelling_main  # type: ignore
@@ -186,3 +188,47 @@ def codespell():
         sys.exit(1)
 
     sys.exit(0)
+    sys.exit(pyspelling_main.main())
+
+
+@click.command()
+def validate_changelog():
+    """
+    Validate changelog formatting to ensure bullet points end with proper punctuation.
+
+    Checks that all bullet points (including nested ones) end with either:
+    - A period (.) for regular entries
+    - A colon (:) for section headers that introduce lists
+    """
+    changelog_path = Path("docs/CHANGELOG.md")
+
+    if not changelog_path.exists():
+        click.echo(f"❌ Changelog file not found: {changelog_path}")
+        sys.exit(1)
+
+    try:
+        with open(changelog_path, "r", encoding="utf-8") as f:
+            content = f.read()
+    except Exception as e:
+        click.echo(f"❌ Error reading changelog: {e}.")
+        sys.exit(1)
+
+    # Find bullet points that don't end with period or colon
+    invalid_lines = []
+    for line_num, line in enumerate(content.splitlines(), 1):
+        if re.match(r"^\s*-\s+", line) and re.search(r"[^\.:]$", line.rstrip()):
+            invalid_lines.append((line_num, line.strip()))
+
+    if invalid_lines:
+        click.echo(f"❌ Found bullet points in {changelog_path} without proper punctuation:")
+        click.echo()
+        for line_num, line in invalid_lines:
+            click.echo(f"Line {line_num}: {line}")
+        click.echo()
+        click.echo("💡 All bullet points should end with:")
+        click.echo("  - A period (.) for regular entries.")
+        click.echo("  - A colon (:) for paragraphs that introduce lists.")
+        sys.exit(1)
+    else:
+        click.echo("✅ All bullet points have proper punctuation!")
+        sys.exit(0)

src/cli/tox_helpers.py

@@ -43,6 +43,11 @@ description = Lint markdown files (markdownlint)
 extras = docs
 commands = python -c "import src.cli.tox_helpers; src.cli.tox_helpers.markdownlint()"
 
+[testenv:changelog]
+description = Validate changelog entries (changelog)
+extras = docs
+commands = python -c "import src.cli.tox_helpers; src.cli.tox_helpers.validate_changelog()"
+
 [testenv:mkdocs]
 description = Build documentation in strict mode (mkdocs)
 extras = docs,lint