Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jun 16, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .github/workflows/tox_verify.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 7 additions & 1 deletion .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
65 changes: 33 additions & 32 deletions docs/CHANGELOG.md

Large diffs are not rendered by default.

17 changes: 11 additions & 6 deletions docs/getting_started/code_standards.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand Down Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion docs/getting_started/code_standards_details.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
46 changes: 46 additions & 0 deletions src/cli/tox_helpers.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
5 changes: 5 additions & 0 deletions tox.ini
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading