mirror of https://github.com/vacp2p/roadmap.git synced 2026-01-07 21:03:55 -05:00

Files

fbarbu15 845d6b8dcd Chore/roadmap validator (#318 )

## Summary

- Introduce a standalone Python roadmap validator with a CLI entry
point, modular validation pipeline, and GitHub Actions wiring so roadmap
content can be linted locally and in CI.
- Provide reusable validation primitives for path resolution,
front-matter parsing, identity checks, task parsing, catalog
enforcement, and template adherence.
- Document usage, configuration, and workflow behaviour to make the
validator approachable for contributors.

## Validator Details

- **Core tooling**
- Added the `tools/roadmap_validator/` package with `validate.py` (CLI),
`validator.py` (orchestration), and helper modules (`tasks.py`,
`identity.py`, `paths.py`, `constants.py`, `issues.py`).
- CLI supports directory/file targets, skips default filenames, emits
GitHub annotations, and integrates optional substring filtering
- README explains features, environment variables, and development
guidance.
- **Catalog and template enforcement**
- `catalog.py` verifies each allowed content unit has `index.md` and
`preview.md`, confirms roadmap entries appear under the proper
quarter/area, and flags stale or missing links.
- `templates.py` enforces template basics: front matter completeness,
`## Description` ordering/content, template placeholder cleanup, and
task section detection.
- **Task validation**
- `tasks.py` checks required metadata (`owner`, `status`, `start-date`,
`end-date`), date formats, populated descriptions/deliverables, TODO
markers, tangible deliverable heuristics, and `fully-qualified-name`
prefixes.
- **Workflow integration**
- `.github/workflows/roadmap-validator.yml` runs the validator on pushes
and manual dispatch, installs dependencies, scopes validation to changed
Markdown, and surfaces findings via GitHub annotations.

## Existing Roadmap Updates

- Normalised 2025q4 commitments across Web, DST, QA, SC, and other units
by filling in missing descriptions, deliverables, schedule notes,
recurring task statuses, and maintenance tasks.
- Added tasks where absent, removed remaining template placeholders,
aligned fully qualified names, and ensured roadmap files conform to the
new validator checks.

## Testing

```bash
python tools/roadmap_validator/validate.py *2025q4*
```

CI: `Roadmap Validator` workflow runs automatically on pushes/dispatch.

---------

Co-authored-by: kaiserd <1684595+kaiserd@users.noreply.github.com>

2025-10-28 15:41:11 +02:00

2.2 KiB

Raw Permalink Blame History

Roadmap Validator

Command line utility for verifying that roadmap Markdown files follow our actionability standards. The validator is used locally and in CI to guard the structure, metadata, and content quality of roadmap commitments.

Features

Enforces template basics (## Description content, no leftover placeholders).
Enforces required front matter keys (title, tags, description).
Infers roadmap identity from file paths and validates tags plus the inline identifier.
Ensures each ## Task List contains at least one well-formed ### task.
Checks task metadata (owner, status, start-date, end-date) and section completeness.
Flags TODO markers, vague descriptions without tangible deliverables, and malformed dates.
Restricts validation to specific content/ subdirectories (dst, qa, nim, p2p, rfc, sc, sec, web).
Confirms each unit catalog (e.g. content/dst/) includes index.md, preview.md, keeps entries in sync with validated roadmap files, and that each entry points to an existing Markdown file.

Installation

Python 3.10+ is required. The only runtime dependency is pyyaml, installed automatically in CI. For local runs:

pip install --disable-pip-version-check --no-cache-dir pyyaml

Usage

python tools/roadmap_validator/validate.py [targets...]
python tools/roadmap_validator/validate.py *2025q4*
python tools/roadmap_validator/validate.py qa/waku dst rfc/nomos

Targets

Provide files or directories; defaults to content/.
Wildcard-style tokens like *2025q4* filter to files whose contents include the substring.
Non-Markdown inputs are ignored; missing paths emit warnings.

GitHub Actions

.github/workflows/roadmap-validator.yml runs the validator on pushes to main and chore/roadmap-validator, checking changed Markdown files under allowed content directories. Findings emit annotations and are summarized in the job output.

Development Notes

Validation logic lives under tools/roadmap_validator/.
Catalog-specific checks are implemented in catalog.py.
Template enforcement lives in templates.py.
Add unit tests or new checks in tasks.py, identity.py, or validator.py.
Keep CLI changes backwards compatible, as the workflow depends on them.

2.2 KiB Raw Permalink Blame History