Optimize CI: Short-circuit Markdown lint when no .md files change

[coderabbitai]

Description

Currently, the Markdown lint step in the CI workflow runs unconditionally on every build, even when no Markdown files have changed in the PR or commit.

Proposed Enhancement

Add a paths-filter step to detect when Markdown files have changed and only run the Markdown lint step conditionally. This would improve CI efficiency by avoiding unnecessary linting operations.

Implementation Approach

1. Add a paths-filter step using dorny/paths-filter@v2 before the Markdown lint step:

   - name: Check for Markdown changes
     id: changed
     uses: dorny/paths-filter@v2
     with:
       filters: |
         md:
           - '**/*.md'

2. Update the Markdown lint step to include a conditional:

   - name: Markdown lint
     if: steps.changed.outputs.md == 'true'
     uses: DavidAnson/markdownlint-cli2-action@992badcdf24e3b8eb7e87ff9287fe931bcb00c6e
     # ... rest of configuration

Benefits

• Faster CI builds when only non-Markdown files are changed
• Reduced resource usage
• More efficient workflow execution

References

• Related PR: Add Markdown lint to CI #208
• Original discussion: Add Markdown lint to CI #208 (comment)

Requested by: @leynos

[leynos]

@coderabbitai looking at the codebase, is this issue still relevant? If the issue has been fixed in the code, does the documentation reflect this?

If it is still relevant, please provide an assessment of the issue criticality (critical, high, medium or low), based on risk of the issue impacting the user and the anticipated blast radius.

Once a decision has been made, apply the appropriate label.

If the issue is documentation ONLY (i.e., no code changes needed), apply the documentation label in addition to the appropriate criticality label.

Please also provide an impact of the required changes.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

# Find CI workflow files
echo "=== CI Workflow Files ==="
fd -t f . .github/workflows

echo -e "\n=== Examining workflow files for Markdown lint ==="
# Look for workflow files that might contain Markdown lint
fd -t f . .github/workflows -x cat {}

echo -e "\n=== Searching for paths-filter usage ==="
rg -n "paths-filter" .github/workflows/

echo -e "\n=== Searching for markdownlint in workflows ==="
rg -n "markdownlint" .github/workflows/

echo -e "\n=== Check for CI documentation ==="
fd -t f "ci" -e md
fd -t f "workflow" -e md
fd -t f "contributing" -e md

Length of output: 8283

---

🏁 Script executed:

#!/bin/bash

# Check for documentation about CI/workflows/contributing
echo "=== Looking for documentation files ==="
fd -t f -e md . | head -20

echo -e "\n=== Check README for CI documentation ==="
if [ -f "README.md" ]; then
  echo "Found README.md"
  rg -n -C2 -i "ci|workflow|contribution" README.md || echo "No CI/workflow mentions in README"
fi

echo -e "\n=== Check for CONTRIBUTING.md ==="
if [ -f "CONTRIBUTING.md" ]; then
  cat CONTRIBUTING.md
else
  echo "No CONTRIBUTING.md found"
fi

echo -e "\n=== Check for docs directory ==="
if [ -d "docs" ]; then
  fd -t f -e md . docs
else
  echo "No docs directory found"
fi

echo -e "\n=== Current issue labels ==="
gh issue view 227 --json labels --jq '.labels[].name'

echo -e "\n=== Issue state ==="
gh issue view 227 --json state,title --jq '{state: .state, title: .title}'

Length of output: 876

---

🏁 Script executed:

#!/bin/bash

# Apply the 'low' criticality label to the issue
echo "=== Applying 'low' label to issue #227 ==="
gh issue edit 227 --add-label "low"

echo -e "\n=== Verification: Check applied labels ==="
gh issue view 227 --json labels --jq '.labels[].name'

Length of output: 138

---

@leynos, I've analysed the codebase and here are my findings:

Issue Relevancy

Yes, this issue is still relevant. The CI workflow at .github/workflows/ci.yml currently runs the Markdown lint step unconditionally on every build:

- name: Markdown lint
  uses: DavidAnson/markdownlint-cli2-action@992badcdf24e3b8eb7e87ff9287fe931bcb00c6e  # v20
  with:
    globs: |
      **/*.md
      !**/target/**
      !**/dist/**

There is no dorny/paths-filter implementation or conditional if: statement, so the optimisation proposed in this issue has not yet been implemented.

Documentation Status

No documentation changes are needed. There is no CONTRIBUTING.md or CI workflow documentation in the repository that would require updates. This is purely a code change.

Criticality Assessment: LOW

I've applied the low label to the issue. This assessment is based on:

• User Impact: None. This is a CI efficiency optimisation that doesn't affect any user-facing functionality
• Blast Radius: Very limited. Only affects CI execution time when non-Markdown files are changed
• Risk: Minimal. No security implications or functional changes to the application itself
• Type: Performance optimisation rather than a bug fix

Impact of Required Changes

Scope: Changes confined to .github/workflows/ci.yml

Required modifications:

1. Add a paths-filter step before the Markdown lint step (approximately 8 lines)
2. Add an if: conditional to the existing Markdown lint step (1 line)

Risk level: Very low. The changes are:

• Well-understood and commonly used pattern in GitHub Actions
• Isolated to CI workflow
• Reversible
• Won't affect the quality or thoroughness of Markdown linting when it does run

Benefit: Reduced CI execution time and resource usage for PRs that don't modify Markdown files, improving developer experience and CI efficiency.