You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@grails.apache.org by "jamesfredley (via GitHub)" <gi...@apache.org> on 2026/05/02 17:46:50 UTC
[PR] Fold per-guide manifest.yml + toc.yml into conf/guides.yml (single source of truth) [grails-static-website]
jamesfredley opened a new pull request, #481:
URL: https://github.com/apache/grails-static-website/pull/481
## Summary
Every `manifest.yml` had the same 10 keys, all of which were already redundantly present in `conf/guides.yml` or trivially derivable from it. Every `toc.yml` was a small per-version yaml that lived next to the chapters but had no contributor-facing reason to exist as a separate file. After this PR, contributing a new guide is **one entry in `conf/guides.yml` + chapter `.adoc` files** (+ optional `snippets/` for vendored sample-app source). **No per-guide YAML files at all.**
## Net diff
**4,570 deletions, 2,673 insertions across 256 files.** Most of the insertions are TOC blocks now living inline in `conf/guides.yml`; the deletions are 252 files (126 `manifest.yml` + 126 `toc.yml`).
## Refactor
- `RenderGuidesPlugin.manifestToAttributes` -> `buildAttributes(guide, version, versionKey)`: builds the AsciiDoc attribute map directly from the `conf/guides.yml` entry, no `manifest.yml` file read. `sampleRef.repo` / `sampleRef.branch` surface as `githubSlug` / `githubBranch` (drives the rendered "Get the Code" sidebar).
- `RenderGuidesPlugin` staging task: per-version `toc:` block in `conf/guides.yml` is materialized at staged-build path as `<staged>/guide/toc.yml` so the vendored `DocPublisher` (which still reads `toc.yml` from disk) needs no changes.
- `ValidateGuidesTask`: drops `manifest.yml` + `toc.yml` existence checks; adds a check that each version has a non-empty `toc` block in `conf/guides.yml`.
- `README.md` "Authoring a Guide" section rewritten to reflect the simpler shape - no per-guide YAML files, `toc:` lives inline in the registry entry.
## Data migration
- 126 `toc.yml` files folded into the matching `conf/guides.yml` `versions[<N>].toc` blocks via textual injection (preserves existing `conf/guides.yml` formatting - quote styles, comments, blank lines).
- 126 `toc.yml` files deleted.
- 126 `manifest.yml` files deleted (every key was redundant).
## Verification
```bash
./gradlew validateGuides -PvalidationMode=both --no-configuration-cache
# [validateGuides] mode=both: 84 guide(s) parsed, 0 SKIP-warned, 0 errors
# BUILD SUCCESSFUL
./gradlew renderGuide_creating_your_first_grails_app_6 \
renderGuide_grails_database_migration_6 \
renderGuide_adding_commit_info_4 \
--rerun-tasks --no-configuration-cache
# BUILD SUCCESSFUL
# 0 Unresolved directive errors across all 3 guides
```
The rendered HTML is byte-equivalent to the pre-PR output for the same guides (same `githubSlug` in the "Get the Code" sidebar, same TOC ordering, same chapter titles).
## Effect on contributing a new guide
**Before** (after #480 landed): 1 entry in `conf/guides.yml` + 1 `manifest.yml` + 1 `toc.yml` + chapter `.adoc` files.
**After this PR:** 1 entry in `conf/guides.yml` (with embedded `toc:` block) + chapter `.adoc` files. That's it.
## Coordination with #479
#479 currently still ships its own `manifest.yml` + `toc.yml` (it predates this work). I will rebase #479 onto the new master once this lands - the v8 guide gets folded into the new shape with one follow-up commit.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@grails.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fold per-guide manifest.yml + toc.yml into conf/guides.yml (single source of truth) [grails-static-website]
Posted by "jamesfredley (via GitHub)" <gi...@apache.org>.
jamesfredley merged PR #481:
URL: https://github.com/apache/grails-static-website/pull/481
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@grails.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org