nextcloud / nextcloud/academy

CI: check the manifest and content files agree

Open
#37 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
2
Forks
1
Avg merge
1d 2h
Merged PRs (30d)
7

Description

Add a check that content/course-manifest.json and the markdown files agree.

Why

The manifest declares 87 modules; 17 files exist. That gap is intentional (#16), but nothing distinguishes "intentionally unwritten" from "the file is named wrong and the page 404s". lib/content.ts resolves a module to content/<track>/<level>/<index>.md and returns null when the file is missing, so a mismatch is a silently broken page.

This will matter more with every module written, not less.

Scope

A small node script, run in CI, asserting:

  • every content file has a corresponding manifest entry (a file nothing points at is dead weight)
  • every manifest entry either has a content file or is explicitly marked as unwritten

The second half implies a convention for "planned but unwritten" — a flag in the manifest, or an allowlist. Deciding that is part of this issue.

Done when

A renamed or misplaced content file fails CI instead of producing a blank page.

Part of #38.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading content/course-manifest.json and lib/content.ts to confirm how manifest entries map to content///.md, then inspect how CI runs Node scripts. Define the convention for planned-but-unwritten modules and make the CI check fail for orphaned files or manifest entries that are neither present nor explicitly unwritten.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
ci-cd, content, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.