Move Guides Publishing to grails.apache.org/guides

[jamesfredley]

Guide Publishing is split between https://github.com/apache/grails-static-website/ and https://github.com/grails-guides/grails-guides-template/. It should likely be consolidated and published to https://grails.apache.org/guides eliminating the need for a separate subdomain guides.grails.org.

https://github.com/apache/grails-static-website/blob/master/.github/workflows/publish.yml#L44-L53 - the grails-static-website has been disabled for now.

Individual guides are published to https://github.com/grails-guides/grails-guides-template/tree/gh-pages using another process, which makes moving this to grails.apache.org non-trivial.

[jamesfredley]

Publishing to legacy location restored on 613ce1e, https://guides.grails.org/ with the updated Apache site requirements.

[jamesfredley]

Grails Guides: Publishing Architecture and Migration Plan

This document describes how Grails guide publishing works today, what's wrong with
it, and the plan to consolidate everything into apache/grails-static-website.

---

Table of Contents

Part 1 -- Current System

• Numbers at a Glance
• Current Architecture Overview
• Complete Repo Inventory
  • Repos with both initial/ and complete/ (79)
  • Repos with complete/ only (14)
  • Repos with neither (1)
  • Repos not published in guides.json (10)
  • Known data issues
• Grails Version Analysis
  • Branch distribution across repos
  • Published versions in guides.json
  • What "multi-version" really means today
  • Unpublished branch analysis
• How Publishing Works Today
  • Step 1: Scaffold the guide
  • Step 2: Create the GitHub repo
  • Step 3: Set up CI manually
  • Step 4: CI runs and the guide gets published
  • Step 5: The guide appears on guides.grails.org
• Current CI/CD Flow Diagram
• Current Component Reference
• Current Pain Points

Part 2 -- Migration Plan

• Consolidation Plan
  • Phase 1: Move guide metadata here
  • Phase 2: Move common doc snippets and theme resources here
  • Phase 3: Move guide-build.gradle here
  • Phase 4: Move ALL guide AsciiDoc source here
  • Phase 5: Simplify deployment
  • Phase 6: Strip doc-publishing from guide repos
  • Phase 7: Wind down grails-guides-template
  • URL Redirect Plan
• Migration Checklist

Part 3 -- New System (After Migration)

• How Publishing Will Work After Migration
  • Adding a new guide (doc-only)
  • Adding a new guide with sample projects
  • Updating an existing guide
  • Adding a new Grails version to an existing guide
  • How versioning simplifies with migration
• Comparison: Before vs After
• Key Files Reference

---

Part 1 -- Current System

Numbers at a Glance

Metric	Count
Repos in grails-guides org (excluding template)	94
Repos published in guides.json	84
Total guides.json entries (including multi-version)	125
Single-version guides in guides.json	44
Multi-version guides in guides.json	40
Repos in org but NOT in guides.json (unpublished)	10
Repos with both initial/ and complete/ dirs	79
Repos with complete/ only (no initial/)	14
Repos with neither initial/ nor complete/	1
Repos with a grails6 branch	3
Repos with a grails5 branch	37
Repos with a grails-4 or grails4 branch	27
Repos with a grails3 branch	40

---

Current Architecture Overview

Guide publishing spans three layers:

1. 94 individual guide repos in the grails-guides GitHub org (e.g.
   grails-guides/creating-your-first-grails-app) -- each is a standalone Grails
   project containing AsciiDoc source, an initial/ starter project, and a
   complete/ solution.

2. grails-guides/grails-guides-template (infrastructure + deployment repo) --
   provides the shared build plugin (gradle/guide-build.gradle), guide scaffolding
   script (create-guide.sh), CI/CD scripts (githubactions/), common AsciiDoc
   snippets (src/main/docs/), and theme resources (src/main/resources/).
   Its gh-pages branch stores the built HTML for every guide, the central
   guides.json registry, and the guides index site served at
   https://guides.grails.org.

3. apache/grails-static-website (this repo) -- generates the guides index site
   (listing, search, tag/category pages) by fetching guides.json at build time.
   The output is pushed back to grails-guides/grails-guides-template gh-pages.

Note: Many CI scripts and individual guide build.gradle files still reference
the old URL grails/grails-guides. This was the former location of
grails-guides/grails-guides-template before it was moved to the grails-guides
GitHub org. GitHub redirects mask this, but the references are stale.

The grails-guides GitHub Org

The grails-guides GitHub org contains 95 repositories:

• grails-guides-template -- the infrastructure repo described above.
• 94 individual guide repositories -- each named after the guide topic.

Every individual guide repo in the org:

• Has its own GitHub Actions CI workflow (manually set up -- not generated by the
  scaffolding script)
• May maintain version branches (master, grails3, grails4, grails5, grails6)
• Applies guide-build.gradle remotely from grails-guides-template at Gradle build time
• Downloads and executes CI scripts from grails-guides-template at CI runtime via curl
• Pushes built HTML and metadata to grails-guides-template gh-pages

---

Complete Repo Inventory

Repos with both initial/ and complete/ directories (79)

These repos contain runnable sample Grails applications. After migration, these
repos will remain in the grails-guides org as sample project repos (with
doc-publishing stripped out). AsciiDoc source moves to grails-static-website.

Repo	Published	Repo branches
adding-commit-info	Yes (master, grails3)	fix-commits-upgrade, gradle4, grails3, grails-3.2.8, grails-4, master
angular2-combined	Yes	grail-4, master
building-a-react-app	Yes (master)	master
building-a-vue-app	Yes (master)	master, rewrite
building-an-android-client-powered-by-a-grails-backend	Yes (master)	master
building-an-ios-objectc-client-powered-by-a-grails-backend	Yes (master)	grails5, grails-4, master
building-an-ios-swift-client-powered-by-a-grails-backend	Yes (master)	grails5, grails-4, master, upgrade
command-objects-and-forms	Yes (master, grails3)	grails3, grails-4, master, tests, upgrade
creating-your-first-grails-app	Yes (master, grails3)	grails3, grails4, master, upgrade
database-per-tenant	Yes (master)	grails5, ilopmar-patch-1, master
discriminator-per-tenant	Yes (master)	grails5, master
gorm-event-listeners	Yes (master, grails3)	fix_typos, grails3, grails-4, many-to-many, master, without-tags
gorm-graphql-with-react-and-apollo	Yes (master)	master, + many dependabot branches
gorm-ratpack	Yes (master, grails3)	grails3, master
grails_api_ai	No	master
grails_i18n	Yes (master, grails3)	grails3, master
grails_url_mappings	Yes (master)	grails5, master
grails-android-security	No	master, upgrade
grails-as-docker-container	Yes (master, grails3)	grails3, grails5, grails-4, guide, master
grails-async-promises	Yes (master, grails3)	grails3, master
grails-basicauth	Yes (master, grails3)	grails3, master
grails-code-coverage	Yes (master, grails3)	grails3, master
grails-codenarc	Yes (master)	master
grails-configuration-properties-micronaut	Yes (grails4, grails6)	basics-g5-changes, grails4, grails5, grails6, master
grails-controller-testing	Yes (master, grails3)	grails_three_three, grails3, master
grails-custom-security-tenant-resolver	Yes (master, grails3)	current-user-with-spring-security-service, grails3, master
grails-database-migration	Yes (grails4, grails3, grails6)	grails3, grails5, grails6, master
grails-deploy-aws-elastic-beanstalk	No	master
grails-deploy-heroku	No	master
grails-deploy-pws	No	grails5, grails-4, master
grails-docker-external-services	Yes (master)	grails5, master
grails-dynamic-multiple-datasources	Yes (master, grails3)	grails3, grails5, master
grails-elasticsearch	Yes	master
grails-email	Yes (master, grails3)	grails3, grails5, master
grails-events	Yes (master, grails3)	grails3, master
grails-geb-multiple-browsers	Yes (master, grails3)	grails3, master
grails-google-cloud	Yes (master)	grails5, grails-4, grails-gr8-demos, master
grails-google-home	Yes (master)	alvarosanchez-patch-1, grails5, grails-4, master
grails-gorm-data-services	Yes (master, grails3)	grails3, grails-4, master
grails-ios-objectivec-security	No	master, upgrade
grails-javamelody	Yes	grails5, master
grails-logicaldelete	Yes (master, grails3)	grails3, grails5, master
grails-micronaut-http	Yes (grails5)	bean-inject-error, grails5, grails6, master
grails-mock-basics	Yes (master, grails3)	grails3, master
grails-mock-http-server	Yes (master, grails3)	grails3, grails5, master
grails-mock-logging-slf4j-test	Yes (master, grails3)	grails3, grails5, grails-4-datastore-rest-client, grails-4, master
grails-multi-datasource	Yes (master, grails3)	error, grails3, grails5, master
grails-multi-project-build	Yes (master)	grails5, grails-4, master, upgrade_guide
grails-oauth-facebook	No	master
grails-oauth-google	Yes (master)	grails5, master, suggestions
grails-oauth-twitter	Yes (master)	grails5, master
grails-on-circleci-basics	Yes (master)	grails5, grails-4, master
grails-on-github-actions	Yes (master)	grails5, master
grails-on-travis-basics	Yes (master, grails3)	grails3, grails5, master
grails-rabbitmq	Yes	grails5, grails-4, master
grails-restapi-angularjs	Yes (master)	grails5, grails-4, master
grails-scheduled	Yes (grails3, master)	grails3, grails5, grails-4, master, suggestions
grails-schwartz	Yes	grails5, master
grails-soap	Yes (master, grails3)	grails3, master
grails-spring-security-core-plugin-custom-authentication	Yes (master, grails3)	grails3, grails5, master
grails-taglib-wyswyg-trix	Yes (master, grails3)	grails3, grails-4, master
grails-test-domain-class-constraints	Yes (master, grails3)	errorCodes, grails_three_three, grails3, grails-4, master, unique-constraint
grails-test-security	Yes (master, grails3)	grails3, master
grails-tvmlapp	Yes (master, grails3)	grails3, grails5, master
grails-upload-file	Yes (master, grails3)	grails3, grails5, grails-4, master
grails-vs-nodejs	Yes (master)	master
grails-vue-combined	Yes (master)	grails-4, master
grails-yourkit-profiling	Yes (master)	grails5, master
neo4j-movies	Yes	master, upgrade
querying-gorm-dynamic-finders	Yes (master, grails3)	grails3, master
react-combined	Yes	grails-4, master, review
react-router-spring-security	No	master
react-spring-security	Yes (master)	master, upgrade
rest-hibernate	Yes (master, grails3)	grails3, grails-4, master
rest-mongodb	Yes (master)	master, upgrade
server-sent-events	Yes (master, grails3)	grails3, grails5, grails-4, master
using-hal-with-json-views	Yes (master, grails3)	grails3, master, upgrade
vaadin-grails	Yes	3.3.0.RC1, grails-4, master, upgrade
web-app-step-by-step	No	compilestatic, link-to-grails-download, master, sdkman-link, sett, sett-rev

Repos with complete/ only -- no initial/ (14)

These repos have a completed sample project but no starter project. The 7
quickcast repos are video-companion code (no interactive tutorial flow). After
migration, repos with meaningful sample code remain in the org; doc-only repos
(quickcasts) can be archived entirely.

Repo	Published	Repo branches	Notes
gorm-without-grails	Yes (master)	grails3, master	Standalone GORM demo
grails-configuration-properties	Yes (master, grails3)	grails3, master
grails-elasticbeanstalk	Yes (master)	grails5, grails-4, master
grails-file-download-excel	Yes (master, grails3)	grails3, grails5, master
grails-micronaut-kafka	Yes (master)*	master	*Typo in guides.json: listed as grails-micronaut-kakfa
grails-quickcast-logging	Yes	master	Quickcast (video companion)
grails-quickcasts-angularjs-scaffolding-with-grails-3	Yes	master	Quickcast
grails-quickcasts-developing-grails-3-applications-with-intellij-idea	Yes	master	Quickcast
grails-quickcasts-interceptors	Yes	master	Quickcast
grails-quickcasts-json-views	Yes	master	Quickcast
grails-quickcasts-multi-project-builds	Yes	master	Quickcast
grails-quickcasts-retrieving-config-values	Yes	master	Quickcast
using-the-react-profile	Yes (master)	master
using-the-vue-profile	Yes (master, grails3)	dependabot branch, grails3, master

Repos with neither initial/ nor complete/ (1)

Repo	Published	Repo branches	Notes
grails-acl	No	master	Doc-only, never published

Repos in org but NOT published in guides.json (10)

These repos exist in the grails-guides org but have no corresponding entry in
guides.json, meaning they do not appear on https://guides.grails.org. Their
CI may never have successfully run updateGuidesJson, or they may be incomplete.

Repo	initial/	complete/	Branches
grails_api_ai	yes	yes	master
grails-acl	no	no	master
grails-android-security	yes	yes	master, upgrade
grails-deploy-aws-elastic-beanstalk	yes	yes	master
grails-deploy-heroku	yes	yes	master
grails-deploy-pws	yes	yes	grails5, grails-4, master
grails-ios-objectivec-security	yes	yes	master, upgrade
grails-oauth-facebook	yes	yes	master
react-router-spring-security	yes	yes	master
web-app-step-by-step	yes	yes	compilestatic, link-to-grails-download, master, sdkman-link, sett, sett-rev

Known data issues

• Typo in guides.json: grails-micronaut-kakfa should be grails-micronaut-kafka
• Category case inconsistency: guides.json has both "Grails + DevOps" (6 guides)
  and "Grails + Devops" (1 guide) -- should be unified
• Branch value issue: grails-on-travis-basics has a guides.json entry with
  githubBranch set to "master,grails3" (comma inside the value) instead of being
  two separate entries
• Underscored repo names: grails_api_ai, grails_i18n, grails_url_mappings
  use underscores instead of hyphens (inconsistent with all other repo names)

---

Grails Version Analysis

Branch distribution across repos

Repos use version branches to maintain guides for different Grails versions. The
branch naming is inconsistent -- some use grails4, others use grails-4:

Branch	Repos	Notes
master	93	Present in almost every repo; maps to Grails 4 in guides.json
grails3	40	Grails 3.x version
grails-4	25	Grails 4.x version (hyphenated variant)
grails4	2	Grails 4.x version (non-hyphenated variant)
grails5	37	Grails 5.x version
grails6	3	Grails 6.x version

Only 3 repos have been updated to Grails 6: grails-configuration-properties-micronaut,
grails-database-migration, and grails-micronaut-http.

Published versions in guides.json

The guides.json branch-to-major-version mapping (in GuidesFetcher.groovy):

BRANCH_TO_MAJOR = [grails3: 3, grails4: 4, master: 4, grails5: 5, grails6: 6]

This means master = Grails 4 in the published guides. The mapping does NOT
include grails-4 (hyphenated), so repos with a grails-4 branch but no
grails4 branch are effectively not publishing a separate Grails 4 version --
their master branch serves as the Grails 4 version.

Of the 40 multi-version guides in guides.json:

• 37 have exactly master + grails3 (Grails 4 + Grails 3)
• 1 has grails4 + grails6 (grails-configuration-properties-micronaut)
• 1 has grails4 + grails3 + grails6 (grails-database-migration)
• 1 has a data issue (grails-on-travis-basics -- comma-separated in one entry)

What "multi-version" really means today

In practice, almost all multi-version guides are just Grails 3 vs Grails 4 (master).
Despite 37 repos having a grails5 branch and 25 having a grails-4 branch, these
branches have NOT been published to guides.json because:

1. The githubactions-build.sh template curls build-guide from
   grails-guides-template master branch
2. The master branch version of build-guide only handles master and grails3
   branches for publishing
3. The 6.0.x branch version handles grails3-grails6 but is not used by any
   guide repo's CI

This means the grails5 branches in 37 repos and grails-4 branches in 25 repos
exist in Git but their built docs were never published.

Unpublished branch analysis

The grails5 and grails-4 branches were never published to guides.json (see
above), but many contain distinct content that should be considered for publishing
during migration. The table below shows each branch's relationship to master.

grails5 branches (37 repos):

Status	Count	Meaning
Ahead of master	35	Branch has unique commits not in master -- distinct content
Behind master	2	Branch is a subset of master -- no unique content

Repo	Ahead	Behind	Status	Commit summary	File-level changes
building-an-ios-objectc-client-powered-by-a-grails-backend	1	0	ahead	grails5 upgrade	19 files. Notable: AnnouncementService.groovy modified (5 lines), AnnouncementControllerSpec.groovy modified (85 lines)
building-an-ios-swift-client-powered-by-a-grails-backend	1	0	ahead	grails5 upgrade	20 files. Notable: AnnouncementService.groovy modified (4 lines), AnnouncementControllerSpec.groovy modified (85 lines)
database-per-tenant	1	0	ahead	grails5 upgrade	20 files. Notable: codenarc rules.groovy, testrules.groovy, codenarc.gradle removed
discriminator-per-tenant	1	0	ahead	grails5 upgrade	19 files. Notable: tenantSelection.adoc modified (2 lines)
grails_url_mappings	0	1	behind	(no unique content)	--
grails-as-docker-container	1	0	ahead	"grails4 upgrade" (may be mislabeled)	18 files: build infra only
grails-configuration-properties-micronaut	4	0	ahead	grails 5 upgrade + CI updates	14 files. Notable: gradle.yml workflow modified, githubactions-build.sh modified
grails-database-migration	1	0	ahead	grails5 upgrade	18 files: build infra only
grails-deploy-pws	1	0	ahead	grails5 upgrade	20 files. Notable: deployWithGradle.adoc modified (2 lines)
grails-docker-external-services	1	0	ahead	grails 5 upgrade	18 files: build infra only
grails-dynamic-multiple-datasources	1	0	ahead	grails5 upgrade	2 files: 2 build.gradle only
grails-elasticbeanstalk	1	0	ahead	"grails5 - problem with management endpoint" (may be incomplete)	11 files: build infra only
grails-email	1	0	ahead	grails 5 upgrade	18 files: build infra only
grails-file-download-excel	1	0	ahead	"grails5 update - geb issue" (Geb problem noted)	11 files: build infra only
grails-google-cloud	1	0	ahead	grails5 upgrade	19 files. Notable: UploadBookFeaturedImageService.groovy modified (5 lines)
grails-google-home	1	0	ahead	grails 5 upgrade	16 files: build infra only
grails-javamelody	1	0	ahead	grails5 upgrade	22 files. Notable: 2 GebConfig.groovy removed, gettingStarted.adoc modified (2 lines)
grails-logicaldelete	1	0	ahead	"grails5 upgrade - geb issue" (Geb problem noted)	18 files: build infra only
grails-micronaut-http	4	0	ahead	CI/config updates	3 files: gradle.yml, githubactions-build.sh, gradle.properties only
grails-mock-http-server	1	0	ahead	grails5	19 files. Notable: OpenweathermapServiceSpec.groovy modified (2 lines)
grails-mock-logging-slf4j-test	1	0	ahead	grails5 changes	18 files: build infra only
grails-multi-datasource	1	0	ahead	grails 5 upgrade	19 files. Notable: MultipleDataSourceSpec.groovy modified (16 lines)
grails-multi-project-build	1	0	ahead	grails5 upgrade	11 files: build infra only
grails-oauth-google	1	0	ahead	grails5 upgrade	20 files. Notable: howto.adoc modified (4 lines)
grails-oauth-twitter	2	0	ahead	grails 5 upgrade (2 commits)	22 files. Notable: GebConfig.groovy removed, howto.adoc modified (4 lines)
grails-on-circleci-basics	1	0	ahead	grails5 upgrade	18 files: build infra only
grails-on-github-actions	1	0	ahead	grails5 upgrade	17 files: build infra only
grails-on-travis-basics	1	0	ahead	grails5 upgrade	20 files. Notable: DefaultHomePageSpec.groovy modified (3 lines), integrationTest.adoc modified (2 lines)
grails-rabbitmq	2	0	ahead	grails5 upgrade (2 commits)	35 files. Notable: BookPageViewDataServiceSpec.groovy modified (2 lines), buildingAnalytics.adoc modified (4 lines)
grails-restapi-angularjs	1	0	ahead	grails5 upgrade	19 files: build infra only
grails-scheduled	1	0	ahead	grails 5 upgrade	18 files: build infra only
grails-schwartz	1	0	ahead	grails5 upgrade	21 files. Notable: 2 GebConfig.groovy removed
grails-spring-security-core-plugin-custom-authentication	1	0	ahead	grails5 upgrade	18 files: build infra only
grails-tvmlapp	1	0	ahead	grails5 upgrade	18 files. Notable: QuickcastSpec.groovy modified (3 lines)
grails-upload-file	1	0	ahead	grails5 upgrade	19 files. Notable: codenarc rules.groovy removed
grails-yourkit-profiling	2	0	ahead	grails5 upgrade (2 commits)	18 files: build infra only
server-sent-events	0	1	behind	(no unique content)	--

Summary: 616 files across 35 repos. "Build infra" = gradle wrapper, build.gradle, gradle.properties, application.yml, settings.gradle. Only 15 of 35 repos have any changes beyond build infra. The Grails 5 migration is almost entirely a build/infrastructure upgrade -- only 10 source/test files were touched across all repos.

grails-4 branches (25 repos):

Status	Count	Meaning
Diverged from master	15	Both branch and master have unique commits -- distinct content
Behind master	10	Branch is a subset of master -- no unique content

Repo	Ahead	Behind	Status	Commit summary	File-level changes
adding-commit-info	0	16	behind	(no unique content)	--
building-an-ios-objectc-client-powered-by-a-grails-backend	2	1	diverged	Gradle 5 upgrade, Grails 4 upgrade with client HTTP change	12 files. Notable: AnnouncementService.groovy modified (2 lines), AnnouncementControllerSpec.groovy modified (82 lines)
building-an-ios-swift-client-powered-by-a-grails-backend	3	1	diverged	Gradle 5 upgrade, Grails 4 upgrade with HTTP client change, add view plugin	10 files. Notable: AnnouncementService.groovy modified (2 lines), AnnouncementControllerSpec.groovy modified (82 lines)
command-objects-and-forms	0	32	behind	(no unique content)	--
gorm-event-listeners	0	23	behind	(no unique content)	--
grails-as-docker-container	0	15	behind	(no unique content)	--
grails-deploy-pws	2	1	diverged	Gradle wrapper upgrade (2 commits)	9 files: build infra only
grails-elasticbeanstalk	3	1	diverged	Gradle 5, Grails 4 (Spring Boot 2 health actuator change), actuator path fix	10 files. Notable: HealthSpec.groovy modified (2 lines), deploy.adoc modified (2 lines), writingTheApp.adoc modified (88 lines)
grails-google-cloud	3	1	diverged	Gradle upgrade, Grails 4 (pathingJar needed), test correction	11 files. Notable: UploadBookFeaturedImageService.groovy modified (5 lines), BookSpec.groovy modified (8 lines)
grails-google-home	3	2	diverged	Gradle 4 upgrade, Grails 4 upgrade, remove codenarc	10 files. Notable: codenarc rules.groovy removed, codenarc.gradle removed
grails-gorm-data-services	2	22	diverged	Upgrade to Grails 4 (2 commits)	11 files. Notable: BootStrap.groovy modified (1 line), 2 .gradle cache files removed
grails-mock-logging-slf4j-test	0	14	behind	(no unique content)	--
grails-multi-project-build	0	28	behind	(no unique content)	--
grails-on-circleci-basics	0	23	behind	(no unique content)	--
grails-rabbitmq	2	1	diverged	Gradle 5 upgrade, Grails 4 upgrade	16 files: build infra only (4 subprojects)
grails-restapi-angularjs	2	1	diverged	Gradle 5 upgrade, Grails 4 upgrade	9 files: build infra only
grails-scheduled	0	4	behind	(no unique content)	--
grails-taglib-wyswyg-trix	0	27	behind	(no unique content)	--
grails-test-domain-class-constraints	26	42	diverged	Grails 3.3.8 -> 4.0 SNAPSHOT: Gradle 5, GORM 7, Hibernate 5.3.7, asset-pipeline, codenarc, remove Geb/mavenLocal, add openjdk11, update views	83 files. Notable: .travis.yml modified, codenarc rules.groovy modified, HotelSpec.groovy modified, GebConfig.groovy added, 44 scaffold assets refreshed (images, JS, CSS, GSP views for Grails 4 templates)
grails-upload-file	9	24	diverged	Gradle wrapper, asset-pipeline, Hibernate core, Grails/GORM versions, replace addResources, codenarc	20 files. Notable: HotelController.groovy, PointOfInterestController.groovy, RestaurantController.groovy modified (2 lines each)
grails-vue-combined	9	1	diverged	Grails 4 server upgrade, views compile fix (#208), Grails 4 RC1 + Vue profile 2	121 files. Full webpack to Vue CLI migration: ~25 webpack/eslint/nightwatch/jest configs removed, Vue CLI configs added, yarn.lock added, client assets updated (bootstrap.css 13K lines, grails.css, Welcome.vue), server Application.groovy and logback.groovy modified, config.adoc modified
react-combined	7	3	diverged	Gradle 5, Grails 4 upgrade, views compile fix, fix issue #3	13 files. Notable: project restructured (gradle.properties moved to server/), writingTheApp.adoc modified (3 lines)
rest-hibernate	20	37	diverged	Gradle 5, Grails 4.0 SNAPSHOT, GORM 7, remove Geb/mavenLocal, GORM Data Service, @CompileStatic, codenarc, add func tests	27 files. Notable: ProductController.groovy modified (8 lines), BootStrap.groovy modified (3 lines), ProductService.groovy added (9 lines), HomeSpec.groovy added (37 lines), ProductFunctionalSpec.groovy added (157 lines), ProductControllerSpec.groovy modified (15 lines), codenarc configs modified
server-sent-events	0	18	behind	(no unique content)	--
vaadin-grails	2	1	diverged	Gradle 5 + Grails upgrade, guide text changes	16 files. Notable: UrlMappings.groovy modified, DemoGrailsUI.groovy modified, README.md modified, gettingStarted.adoc, profile.adoc, toc.yml modified

Summary: 377 files across 15 diverged repos. More diverse than Grails 5 due to the Grails 3-to-4 scope. Outliers: grails-vue-combined (121 files, webpack to Vue CLI migration), grails-test-domain-class-constraints (83 files, scaffold assets), rest-hibernate (27 files, new service + functional tests). The 10 "behind" branches are subsets of master with no unique work.

grails4 branches (2 repos):

Repo	Ahead	Behind	Status
creating-your-first-grails-app	0	30	behind (no unique content)
grails-configuration-properties-micronaut	0	0	identical to master

Neither grails4 branch has unique content.

---

How Publishing Works Today

This is the end-to-end lifecycle of a guide in the current system, from creation
to appearing on https://guides.grails.org:

Step 1: Scaffold the guide

An author clones grails-guides-template and runs create-guide.sh:

./create-guide.sh my-new-guide

This script:

1. Runs grails create-app my-new-guide to generate a Grails app
2. Renames the app directory to initial/
3. Copies initial/ to complete/
4. Writes settings.gradle with include 'complete', 'initial'
5. Copies template files from src/main/project/ into the guide root

The template files copied are:

• build.gradle -- applies guide-build.gradle remotely
• gradle.properties -- metadata stub with TODO placeholders
• githubactions-build.sh -- CI entrypoint (curls scripts at runtime)
• src/main/docs/guide/ -- AsciiDoc skeleton (toc.yml, gettingStarted.adoc, etc.)

What is NOT created by the script:

• .github/workflows/ -- the GitHub Actions workflow YAML must be created manually
• No CI configuration is auto-generated

Step 2: Create the GitHub repo

The author manually:

1. Creates a new repository in the grails-guides org on GitHub
2. The repo name must match the guide directory name
3. Pushes the scaffolded project

Step 3: Set up CI manually

The author must manually:

1. Create .github/workflows/gradle.yml (or similar) -- there is no template for this
2. Configure repository secrets: GH_TOKEN, GIT_NAME, GIT_EMAIL

A typical workflow looks like this (from creating-your-first-grails-app):

name: Java CI with Gradle
on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Set up JDK 11
      uses: actions/setup-java@v2
      with:
        java-version: '11'
        distribution: 'adopt'
        cache: gradle
    - name: Run script
      run: ./githubactions-build.sh
      env:
        GH_TOKEN: ${{ secrets.GH_TOKEN }}
        GIT_NAME: ${{ secrets.GIT_NAME }}
        GIT_EMAIL: ${{ secrets.GIT_EMAIL }}

Note: many of these workflows are outdated (actions/checkout@v2, JDK 11, adopt
distribution). The grails-guides-template README still references Travis CI as
the CI system, with instructions for travis encrypt -- GitHub Actions was
retrofitted without updating the docs.

Step 4: CI runs and the guide gets published

On push, the workflow runs ./githubactions-build.sh. This is where it gets wild:

4a. githubactions-build.sh (in the guide repo)

This script does not contain any build logic. It downloads and executes scripts
from grails-guides-template at runtime via curl:

#!/bin/bash
set -e
export EXIT_STATUS=0

# Download the build script from grails-guides-template master branch at runtime
curl -O https://raw.githubusercontent.com/grails/grails-guides/master/githubactions/build-guide
chmod 777 build-guide
./build-guide || EXIT_STATUS=$?

if [[ $EXIT_STATUS -ne 0 ]]; then
    echo "build-guide failed"
    exit $EXIT_STATUS
fi

# Download the republish script from grails-guides-template master branch at runtime
curl -O https://raw.githubusercontent.com/grails/grails-guides/master/githubactions/republish-guides-website.sh
chmod 777 republish-guides-website.sh
./republish-guides-website.sh || EXIT_STATUS=$?

exit $EXIT_STATUS

Every single guide repo has an identical copy of this file. All 94 of them curl
the same two scripts from grails-guides-template master branch (using the old
grails/grails-guides URL).

4b. build-guide (curled from grails-guides-template)

This is the actual build logic. It:

1. Runs ./gradlew -Dgeb.env=chromeHeadless check (tests)
2. Runs ./gradlew publishGuide (AsciiDoc -> HTML)
3. Only for specific branches (master, grails3, grails4, grails5, grails6):
   • Clones grails-guides-template gh-pages branch
   • Runs ./gradlew updateGuidesJson -- this is how a guide gets added to
     guides.json (the central registry). The task reads gradle.properties and
     upserts the guide's metadata into the JSON file.
   • Copies built HTML to the appropriate directory on gh-pages:
     • master branch -> <guide-name>/ (root, no version prefix)
     • grails3 branch -> grails3/<guide-name>/
     • grails4 branch -> grails4/<guide-name>/
     • etc.
   • Commits and pushes to gh-pages

Branch discrepancy: The master branch of grails-guides-template has a
build-guide that only handles master and grails3. The 6.0.x branch version
handles grails3, grails4, grails5, grails6 (not master). Since the
githubactions-build.sh template curls from master, guides using that template
only get the older behavior.

4c. republish-guides-website.sh (curled from grails-guides-template)

After the guide is built, this script regenerates the entire guides index site:

1. Clones grails/grails-static-website (this repo, using old URL) master branch
2. Runs ./gradlew buildGuide -- which fetches guides.json from gh-pages and
   generates index/tag/category HTML pages
3. Clones grails-guides-template gh-pages again
4. Copies build/dist/* (the generated index pages) into gh-pages
5. Commits and pushes

This means every single guide CI build triggers a full rebuild of the entire guides
index site. And the same rebuild also runs every 2 hours via the cron job in
grails-static-website's publish.yml.

Step 5: The guide appears on guides.grails.org

Once the gh-pages push completes, the guide is live:

• Guide HTML: https://guides.grails.org/<guide-name>/guide/index.html
• Versioned: https://guides.grails.org/grails{N}/<guide-name>/guide/index.html
• Listed on the index: https://guides.grails.org/index.html
• Searchable by tags and categories

The guide was added to guides.json by updateGuidesJson (step 4b) and the index
was regenerated by republish-guides-website.sh (step 4c), so it shows up in the
listing immediately.

---

Current CI/CD Flow Diagram

Guide Author pushes to grails-guides/<guide-name>
        |
        v
.github/workflows/gradle.yml  (manually created, per-repo)
        |
        v
githubactions-build.sh  (identical in every repo)
        |
        |-- curl build-guide from grails-guides-template master (old URL)
        |-- curl republish-guides-website.sh from grails-guides-template master (old URL)
        |
        v
build-guide  (downloaded at runtime)
        |
        |-- ./gradlew check                    (run tests)
        |-- ./gradlew publishGuide             (AsciiDoc -> HTML via grails-docs)
        |       |
        |       |-- build.gradle: apply from   (curls guide-build.gradle from
        |       |   grails-guides-template master or 6.0.x, old URL)
        |       |
        |       |-- guide-build.gradle:
        |       |     prepareResources          (downloads grails-guides-template
        |       |                                as ZIP to get theme resources)
        |       |     publishGuide              (uses org.grails:grails-docs:6.0.0-RC1)
        |       |
        |       v
        |   build/docs/guide/index.html
        |
        |-- git clone grails-guides-template gh-pages (old URL)
        |-- ./gradlew updateGuidesJson          (upserts into guides.json)
        |-- cp build/docs -> gh-pages/grails{N}/<guide-name>/
        |-- git push gh-pages
        |
        v
republish-guides-website.sh  (downloaded at runtime)
        |
        |-- git clone grails-static-website (this repo, old URL)
        |-- ./gradlew buildGuide
        |       |
        |       |-- GuidesFetcher: HTTP GET guides.json from gh-pages
        |       |-- GuidesTask: generates index.html, categories/*.html, tags/*.html
        |       v
        |   build/dist/
        |
        |-- git clone grails-guides-template gh-pages (old URL)
        |-- cp build/dist/* -> gh-pages/
        |-- git push gh-pages
        |
        v
https://guides.grails.org  (GitHub Pages from grails-guides-template gh-pages)

Additionally, grails-static-website's own publish.yml runs the same
./gradlew buildGuide + push to grails-guides-template gh-pages independently:

• On every push to master
• On a cron schedule every 2 hours
• On manual workflow_dispatch

---

Current Component Reference

grails-guides-template structure (source branches: master, 6.0.x)

grails-guides-template/
├── create-guide.sh                  # Scaffolds new guide projects
├── build.gradle                     # Downloads navbar assets from grails-navbar repo
├── gradle/
│   └── guide-build.gradle           # Shared build plugin applied by all guides
├── githubactions/
│   ├── build-guide                  # CI: test + build + publish guide HTML
│   └── republish-guides-website.sh  # CI: regenerate guides index site
├── src/main/
│   ├── docs/
│   │   ├── common-completesolution.adoc
│   │   ├── common-gradle.adoc
│   │   ├── common-howto.adoc
│   │   ├── common-installingGrails.adoc
│   │   ├── common-requirements.adoc
│   │   └── ... (~45 common-*.adoc snippets)
│   ├── project/                     # Template copied into new guides
│   │   ├── build.gradle
│   │   ├── gradle.properties
│   │   ├── githubactions-build.sh
│   │   └── src/main/docs/guide/
│   │       ├── toc.yml
│   │       ├── gettingStarted.adoc
│   │       ├── howto.adoc
│   │       ├── requirements.adoc
│   │       ├── runningTheApp.adoc
│   │       └── writingTheApp.adoc
│   └── resources/                   # Theme assets
│       ├── css/                     # guide.css, screen.css, navbar.css, etc.
│       ├── fonts/                   # Archia family + FontAwesome
│       └── img/                     # Grails logo, category icons
└── README.md                        # Still references Travis CI

grails-guides-template gh-pages branch (deployment)

gh-pages/
├── guides.json                      # Central metadata registry (125 entries, 84 unique guides)
├── index.html                       # Guides listing (generated by static-website)
├── categories/*.html                # Per-category pages
├── tags/*.html                      # Per-tag pages
├── sitemap.xml
├── stylesheets/                     # Site CSS
├── javascripts/                     # Site JS
├── images/                          # Site images
├── creating-your-first-grails-app/  # Guide HTML (master branch builds)
│   └── guide/index.html
├── grails3/                         # Grails 3 versioned guides
│   └── <guide-name>/guide/index.html
├── grails4/                         # Grails 4 versioned guides
├── grails5/                         # Grails 5 versioned guides
└── grails6/                         # Grails 6 versioned guides

Individual guide repo structure (e.g. creating-your-first-grails-app)

creating-your-first-grails-app/
├── .github/workflows/
│   └── gradle.yml                   # Manually created, NOT from template
├── githubactions-build.sh           # Curls build-guide + republish at runtime
├── build.gradle                     # apply from: guide-build.gradle (remote, old URL)
├── gradle.properties                # Guide metadata
├── settings.gradle                  # include 'complete', 'initial'
├── initial/                         # Starter Grails app
├── complete/                        # Completed solution
├── src/main/
│   ├── docs/guide/
│   │   ├── toc.yml
│   │   └── *.adoc                   # Guide content
│   └── resources/img/               # Guide-specific images
├── gradle/wrapper/                  # Gradle wrapper
├── gradlew / gradlew.bat
└── README.md

Guide build.gradle

Every guide's build.gradle remotely applies the shared build script. Some reference
master, some 6.0.x:

plugins {
    id 'org.asciidoctor.convert' version '1.5.3'
}
asciidoctorj {
    version = '1.5.4'
}
// NOTE: old URL; actual repo is grails-guides/grails-guides-template
apply from:"https://raw.githubusercontent.com/grails/grails-guides/master/gradle/guide-build.gradle"

Guide gradle.properties

title=Creating your first Grails Application
subtitle=Learn how to create your first Grails app
authors=Zachary Klein
copyright=Copies of this document may be made for your own use and for...
githubSlug=grails-guides/creating-your-first-grails-app
githubBranch=master
category=Grails Apprentice
tags=mysql,gsp,grails4
publicationDate=23 Jan 2017

Property	Description	Required
title	Display title	Yes
subtitle	Short description	Yes
authors	Comma-separated authors	Yes
githubSlug	Repo identifier (grails-guides/...)	Yes
githubBranch	Git branch	Yes
tags	Comma-separated tags	Yes
category	Must match a predefined category	Yes
publicationDate	Format: dd MMM yyyy	Yes

Shared build plugin: guide-build.gradle

Applied remotely by every guide. Key tasks:

• prepareResources -- downloads grails-guides-template (branch 6.0.x) as
  a ZIP from GitHub and extracts theme resources (CSS, fonts, images) and common
  AsciiDoc snippets. This is a network fetch on every build.
• copyLocalGuideImgResources -- copies guide-specific images from
  src/main/resources/img/ into the extracted build tree.
• publishGuide -- runs grails.doc.gradle.PublishGuide (from
  org.grails:grails-docs:6.0.0-RC1) to convert AsciiDoc to HTML.
  Output: build/docs/guide/single.html renamed to build/docs/guide/index.html.
  Also creates a redirect build/docs/index.html.
• updateGuidesJson -- reads gh-pages/guides.json, upserts the current guide's
  metadata from gradle.properties, writes the updated JSON back. This is how a
  guide registers itself in the central metadata file.

Validation at task graph resolution time enforces that all required properties are
set and not TODO.

Guides index generation (this repo: grails-static-website)

The buildGuides Gradle task (registered in GrailsWebsitePlugin) orchestrates:

buildGuides
├── genGuides  (GuidesTask)    -- fetches guides.json, generates HTML pages
├── copyAssets (AssetsTask)     -- copies CSS/JS/images
└── genSitemap (SitemapTask)   -- generates sitemap.xml

GuidesFetcher (buildSrc/.../model/guides/GuidesFetcher.groovy):

• Fetches guides.json from
  https://raw.githubusercontent.com/grails-guides/grails-guides-template/gh-pages/guides.json
• Parses each entry into a GuideDto
• Groups by githubSlug; creates SingleGuide (one branch) or
  GrailsVersionedGuide (multiple branches like grails3/4/5/6)
• Branch-to-version mapping: grails3->3, grails4->4, master->4, grails5->5, grails6->6
• Filters out future-dated guides, sorts newest-first

GuidesTask (buildSrc/.../tasks/GuidesTask.groovy):

• Calls GuidesFetcher.fetchGuides() and TagUtils.populateTags(guides)
• Generates build/temp/guides.html (main listing)
• Generates build/temp/tags/<tag>.html for each tag
• Generates build/temp/categories/<category>.html for each category
• Renders all through the site template into build/dist/

GuidesPage (buildSrc/.../model/guides/GuidesPage.groovy):

• Renders HTML using Groovy MarkupBuilder
• 14 predefined categories with SVG icons
• Links to https://guides.grails.org/<name>/guide/index.html (single)
• Links to https://guides.grails.org/grails{N}/<slug>/guide/index.html (versioned)
• Features: latest guides list (8 most recent), tag cloud, search box, category grouping

Main site publishing (publish.yml workflow)

The GitHub Actions workflow runs on push to master, every 2 hours via cron, and on
manual dispatch:

# Step 1: Build and publish the main grails.apache.org site
GRADLE_TASK: build
GITHUB_SLUG: apache/grails-website
GH_BRANCH: asf-site-production

# Step 2: Build and publish the guides.grails.org index site
GRADLE_TASK: buildGuide
GITHUB_SLUG: grails-guides/grails-guides-template
GH_BRANCH: gh-pages

Both steps use publish.sh, which runs the Gradle task, clones the target repo's
deploy branch, copies build/dist/ into it, and pushes.

---

Current Pain Points

1. Runtime curl of CI scripts -- every guide CI run downloads build-guide
   and republish-guides-website.sh from GitHub at runtime. The CI logic is not
   committed to the guide repos; it's fetched live. This is fragile (GitHub outage
   = broken CI) and opaque (the actual CI behavior is invisible in the guide repo).

2. Remote apply from for Gradle builds -- every guide's build.gradle fetches
   guide-build.gradle from GitHub at Gradle configuration time. Combined with
   prepareResources downloading a ZIP of grails-guides-template, a single guide
   build makes 3+ HTTP requests to GitHub before any real work begins.

3. Cascading index rebuilds -- every single guide CI build runs
   republish-guides-website.sh, which clones this entire repo, runs
   ./gradlew buildGuide, and pushes the result. If 5 guides push in the same hour,
   the index gets rebuilt 5 times -- plus once more from the cron job. These can also
   race and cause push conflicts on gh-pages.

4. Stale old-URL references everywhere -- the githubactions-build.sh in all 94
   guide repos curls from grails/grails-guides (old URL). The build-guide and
   republish-guides-website.sh scripts clone grails/grails-guides (old URL) and
   grails/grails-static-website (old URL). Guide build.gradle files apply from
   grails/grails-guides (old URL). GitHub redirects mask this but add fragility.

5. master vs 6.0.x branch discrepancy in build-guide -- the master
   branch version of build-guide only handles master and grails3 branches.
   The 6.0.x branch version handles grails3-grails6 (not master). Since
   the curled template references master, guides using the default template only
   publish for master and grails3. This is why only 3 guides have published
   Grails 6 content despite 3 repos having a grails6 branch, and why 37 repos
   with grails5 branches have never published Grails 5 content.

6. No workflow template in scaffolding -- create-guide.sh copies
   build.gradle, gradle.properties, githubactions-build.sh, and docs, but does
   NOT create .github/workflows/. The GitHub Actions workflow must be created and
   configured manually for each guide, leading to inconsistency across 94 repos.

7. Outdated README -- the grails-guides-template README documents Travis CI
   as the CI system (with travis encrypt instructions). GitHub Actions was
   retrofitted without updating the documentation.

8. Outdated guide workflows -- many guide repos use actions/checkout@v2,
   actions/setup-java@v2, JDK 11, and adopt distribution. These are years out
   of date.

9. Overloaded gh-pages branch -- grails-guides-template gh-pages stores
   built guide HTML (pushed by 94 individual guide CIs), guides.json (mutated by
   updateGuidesJson from each guide CI), AND the index site (pushed by both
   republish-guides-website.sh and grails-static-website's cron). Multiple
   independent CI pipelines write to the same branch concurrently.

10. guides.json as the integration point -- metadata is serialized to JSON in
    one repo, fetched via HTTP in another. Changes to the schema require coordinating
    across repos.

11. Stale grails-docs dependency -- the PublishGuide task comes from
    org.grails:grails-docs:6.0.0-RC1, a Grails-specific doc toolchain. Modern
    AsciiDoctor Gradle plugins are more capable and actively maintained.

12. 94 repos to maintain -- the grails-guides org has 94 individual guide repos
    plus the template. Most target older Grails versions (only 3 have Grails 6
    branches). Maintaining permissions, branch policies, and secrets across all of
    them is significant overhead.

13. 10 unpublished repos -- 10 repos exist in the org but never made it into
    guides.json, so they are invisible on the guides site. Their status is unclear.

14. Inconsistent branch naming -- 25 repos use grails-4 (hyphenated) while 2
    use grails4 (unhyphenated). The GuidesFetcher branch mapping only recognizes
    grails4, meaning the 25 repos with grails-4 branches are not properly mapped.

---

Part 2 -- Migration Plan

Consolidation Plan

Goal

Move all guide AsciiDoc source and publishing infrastructure into
grails-static-website so that:

• All guide AsciiDoc source lives in this repo
• Guide metadata is defined in a single YAML file (conf/guides.yml)
• Built guide HTML and the index site are deployed together
• One CI pipeline handles everything
• No runtime curl of scripts, no remote apply from, no cascading rebuilds
• The grails-guides GitHub org retains only repos with initial/+complete/
  sample applications (79 repos), serving purely as runnable code companions

Phase 1: Move guide metadata here

What: Create conf/guides.yml in this repo containing all guide metadata
currently in guides.json. Stop fetching from GitHub at build time.

Changes:

• Add conf/guides.yml with all 84 published guide entries (title, authors, tags,
  category, publication date, Grails versions)
• Fix the grails-micronaut-kakfa typo to grails-micronaut-kafka
• Unify "Grails + DevOps" / "Grails + Devops" category case
• Add entries for the 10 currently unpublished repos (or explicitly exclude them)
• Add a guides property to GrailsWebsiteExtension pointing to it
• Modify GuidesFetcher to read from a local YAML file instead of a remote JSON URL
• Update GuidesTask to accept the local file as an @InputFile

Benefits: No more network dependency during builds. Metadata changes are
version-controlled with the site. Adding/updating a guide is a simple YAML edit + PR.

Impact on grails-guides org: None yet. Individual guide repos continue to
function as before; their CI just becomes the non-authoritative source for metadata.

Phase 2: Move common doc snippets and theme resources here

What: Bring src/main/docs/common-*.adoc (~45 files) and src/main/resources/
(CSS, fonts, images) from grails-guides-template into this repo.

Changes:

• Copy grails-guides-template/src/main/docs/common-*.adoc to guides/common/
• Copy grails-guides-template/src/main/resources/ to guides/resources/
• Update guide-build.gradle (or its replacement) to reference local paths
• Individual guide repos can still exist but would reference resources from this repo

Benefits: Theme and common content are versioned with the site. No ZIP download
at build time (prepareResources task eliminated).

Impact on grails-guides-template: Its source branches (master, 6.0.x) become
redundant for src/main/docs/ and src/main/resources/. Only gh-pages is still
needed until Phase 5.

Phase 3: Move guide-build.gradle here

What: Bring the shared Gradle build plugin into buildSrc/ alongside the existing
site build logic.

Changes:

• Port guide-build.gradle tasks (publishGuide, updateGuidesJson) into
  buildSrc/ as proper Gradle task classes (like GuidesTask already is)
• Replace the org.grails:grails-docs PublishGuide dependency with the standard
  org.asciidoctor.jvm.convert Gradle plugin
• Individual guide repos would apply from this repo (or use a published plugin)

Benefits: Build logic is testable, type-safe Groovy/Java classes. Modern
AsciiDoctor tooling. Single place to update build conventions.

Impact on grails-guides-template: gradle/guide-build.gradle,
create-guide.sh, and githubactions/ become dead code. The repo's source branches
are now fully superseded.

Impact on individual guide repos: Their build.gradle must be updated to point
the apply from URL at this repo (or use a published Gradle plugin). This can be
done incrementally per guide.

Phase 4: Move ALL guide AsciiDoc source here

What: Move the AsciiDoc source from every guide repo into this repo. This is
mandatory for all 84 published guides and optionally for the 10 unpublished ones.

Changes:

• Create guides/<guide-name>/ directories containing guide/toc.yml and .adoc files
• Add a Gradle task to build all local guides in one pass
• The buildGuides task builds all guide HTML from local AsciiDoc source
• conf/guides.yml references the local path for each guide

Per-guide migration procedure:

1. Copy AsciiDoc: Copy src/main/docs/guide/ from the guide repo into
   guides/<guide-name>/ in this repo
2. Copy guide-specific images: Copy src/main/resources/img/ into
   guides/<guide-name>/images/
3. Update conf/guides.yml: Ensure the guide entry has source: local
4. Remove doc-publishing from the guide repo: Delete src/main/docs/,
   githubactions-build.sh, the doc-related parts of build.gradle, and
   gradle.properties metadata fields used only for doc publishing
5. Update the guide repo CI: If the repo has initial/+complete/ sample
   projects, keep a simplified workflow that only builds/tests the sample apps
   (no more publishGuide, updateGuidesJson, or republish-guides-website.sh).
   If the repo has no sample projects, archive it entirely.

What happens to each repo category:

Category	Count	Action
Has both initial/ and complete/	79	AsciiDoc moves here. Repo keeps sample projects with simplified CI.
Has complete/ only (non-quickcast)	7	AsciiDoc moves here. Strip doc-publishing, archive the repo.
Has complete/ only (quickcast)	7	AsciiDoc moves here. Strip doc-publishing, archive the repo.
Has neither dir	1	grails-acl -- doc-only, never published. Archive the repo.
Unpublished (in org, not in guides.json)	10	Evaluate each: migrate AsciiDoc if the guide has value; archive if abandoned.

Proposed structure:

grails-static-website/
├── conf/
│   └── guides.yml                 <-- all guide metadata (84+ entries)
├── guides/
│   ├── common/                    <-- shared AsciiDoc snippets (from grails-guides-template)
│   ├── resources/                 <-- theme CSS, fonts, images (from grails-guides-template)
│   ├── creating-your-first-grails-app/
│   │   ├── toc.yml
│   │   ├── images/                <-- guide-specific images
│   │   └── guide/*.adoc
│   ├── grails-mock-basics/
│   │   ├── toc.yml
│   │   └── guide/*.adoc
│   └── ... (84+ guide directories)
├── buildSrc/
│   └── .../guides/
│       ├── GuidesFetcher.groovy      <-- reads conf/guides.yml
│       ├── GuidesTask.groovy         <-- generates index site
│       ├── GuideBuildTask.groovy     <-- NEW: builds individual guide HTML
│       └── ...
└── .github/workflows/
    └── publish.yml                <-- single workflow for site + guides

Phase 5: Simplify deployment

What: Deploy everything (main site + guide HTML + guide index) as part of
grails.apache.org. All guides will be served at https://grails.apache.org/guides/.

Changes:

• Build output produces one unified build/dist/ tree:

  build/dist/
  ├── index.html                  <-- grails.apache.org homepage
  ├── guides/
  │   ├── index.html              <-- grails.apache.org/guides/ listing
  │   ├── categories/*.html
  │   ├── tags/*.html
  │   └── <guide-name>/
  │       └── guide/index.html    <-- individual guide HTML
  └── ...
  

• A single publish.yml step pushes to apache/grails-website asf-site-production
• Remove the second publish.sh step that pushes to grails-guides-template gh-pages
• Eliminate republish-guides-website.sh -- no more cascading rebuilds
• Update GUIDES_URL in GuidesPage.groovy from https://guides.grails.org to
  https://grails.apache.org/guides

New URL structure:

• https://grails.apache.org/guides/ -- guides listing (index)
• https://grails.apache.org/guides/<guide-name>/guide/index.html -- individual guide
• https://grails.apache.org/guides/tags/<tag>.html -- guides by tag
• https://grails.apache.org/guides/categories/<category>.html -- guides by category

Benefits: One deploy, one repo, one domain. No cross-repo push
choreography. No concurrent writes to gh-pages. Drastically simpler CI/CD.

Phase 6: Strip doc-publishing from guide repos

What: After AsciiDoc source has been migrated (Phase 4), strip the doc-publishing
machinery from every guide repo in the grails-guides org.

Per-repo procedure for repos keeping initial/+complete/ (79 repos):

1. Delete src/main/docs/ (AsciiDoc source -- now in grails-static-website)
2. Delete githubactions-build.sh (no longer needed)
3. Simplify build.gradle:
   • Remove the apply from: that fetches guide-build.gradle
   • Remove the asciidoctor plugin
   • Keep only what's needed to build/test initial/ and complete/ subprojects
4. Remove doc-publishing metadata from gradle.properties (title, subtitle, authors,
   githubSlug, githubBranch, category, tags, publicationDate)
5. Update .github/workflows/gradle.yml:
   • Remove the ./githubactions-build.sh step
   • Replace with ./gradlew check to just run tests on the sample apps
   • Update to modern actions versions (checkout@v4, setup-java@v4, JDK 17+)
   • Remove GH_TOKEN / GIT_NAME / GIT_EMAIL secrets (no longer pushing to gh-pages)
6. Add a README.md note: "Guide content is published from
   apache/grails-static-website.
   This repo contains only the sample applications."

For repos with complete/ only (14 repos):

Same stripping procedure as above, then archive the repo. These repos have no
initial/ project, so they do not serve as interactive tutorial companions.
The complete/ code is preserved in the archived repo for reference.

For repos with neither dir (1 repo: grails-acl):

Archive the repo. It was never published and has no sample code.

Phase 7: Wind down grails-guides-template

What: After consolidation is complete, clean up grails-guides-template.

Impact on grails-guides/grails-guides-template:

• Source branches (master, 6.0.x) are fully superseded after Phases 2-3 --
  all build logic, common docs, and theme resources now live in grails-static-website
• gh-pages branch continues to serve guides.grails.org via GitHub Pages, but
  all HTML files are replaced with meta-refresh redirects to grails.apache.org/guides/
  (see URL Redirect Plan below)
• Action: Replace all HTML on gh-pages with redirect stubs. Archive the repo's
  source branches. The gh-pages branch stays live to serve redirects indefinitely.

Impact on the grails-guides org after all phases:

What remains	Count	Purpose
Repos with initial/+complete/ sample apps	79	Runnable code companions for guides (no doc-publishing)
Repos archived (complete/-only, doc-only, obsolete)	15	Read-only reference (14 complete-only + 1 no-code)
grails-guides-template	1	Source branches archived; gh-pages stays live for redirects

URL Redirect Plan

Current guide URLs follow the pattern:

https://guides.grails.org/<guide-name>/guide/index.html          (single version)
https://guides.grails.org/grails{N}/<guide-name>/guide/index.html (versioned)

After consolidation, guides will be served from grails.apache.org/guides/. To
preserve existing links, the grails-guides-template gh-pages branch (which
serves guides.grails.org via GitHub Pages) will be updated with meta-refresh
redirects pointing to the new grails.apache.org URLs.

Redirect implementation: Replace all HTML files on gh-pages with redirect
stubs using <meta http-equiv="refresh">:

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="refresh" content="0; url=https://grails.apache.org/guides/<guide-name>/guide/index.html">
  <link rel="canonical" href="https://grails.apache.org/guides/<guide-name>/guide/index.html">
</head>
<body>
  <p>This page has moved to
    <a href="https://grails.apache.org/guides/<guide-name>/guide/index.html">
      grails.apache.org/guides/<guide-name>/guide/index.html
    </a>.
  </p>
</body>
</html>

This covers:

• https://guides.grails.org/<guide-name>/guide/index.html ->
  https://grails.apache.org/guides/<guide-name>/guide/index.html
• https://guides.grails.org/grails{N}/<guide-name>/guide/index.html ->
  https://grails.apache.org/guides/grails{N}/<guide-name>/guide/index.html
• https://guides.grails.org/index.html ->
  https://grails.apache.org/guides/index.html
• https://guides.grails.org/tags/*.html ->
  https://grails.apache.org/guides/tags/*.html
• https://guides.grails.org/categories/*.html ->
  https://grails.apache.org/guides/categories/*.html

The gh-pages branch stays live (not archived) to serve redirects indefinitely.
The grails-guides-template repo itself can still be archived since the gh-pages
branch is independent of the source branches.

---

Migration Checklist

Phase 1 -- Metadata

• Create conf/guides.yml from current guides.json (84 published + 10 unpublished to evaluate)
• Fix typo: grails-micronaut-kakfa -> grails-micronaut-kafka
• Unify category: "Grails + DevOps" / "Grails + Devops"
• Fix data issue: grails-on-travis-basics branch value "master,grails3"
• Update GuidesFetcher to read local YAML
• Verify index site renders identically

Phase 2 -- Common docs and resources

• Copy ~45 common-*.adoc snippets to guides/common/
• Copy theme resources (CSS, fonts, images) to guides/resources/

Phase 3 -- Build plugin

• Port guide-build.gradle tasks into buildSrc/
• Replace grails-docs with standard asciidoctor-gradle-plugin
• Add GuideBuildTask for building individual guide HTML

Phase 4 -- Guide AsciiDoc source (all 84 published guides)

• Migrate AsciiDoc from all 79 repos with initial/+complete/
• Migrate AsciiDoc from all 14 repos with complete/-only
• Migrate AsciiDoc from grails-acl (if worth preserving)
• Evaluate and migrate the 10 unpublished repos
• Verify all guides build and render correctly from local source

Phase 5 -- Deployment

• Update publish.yml to produce unified output under build/dist/guides/
• Remove second publish.sh step for grails-guides-template
• Update GUIDES_URL in GuidesPage.groovy to https://grails.apache.org/guides
• Verify all guide URLs work at grails.apache.org/guides/

Phase 6 -- Strip doc-publishing from guide repos

• Strip doc-publishing from 79 repos with initial/+complete/
• Simplify CI workflows in all retained repos
• Archive repos with no meaningful sample code
• Remove GH_TOKEN / GIT_NAME / GIT_EMAIL secrets from all repos

Phase 7 -- Wind down template

• Replace all HTML files on grails-guides-template gh-pages with meta-refresh redirects to grails.apache.org/guides/
• Verify all guides.grails.org URLs redirect correctly
• Archive grails-guides-template source branches (master, 6.0.x)
• Keep gh-pages branch live for redirects
• Add deprecation notice to grails-guides org description

---

Part 3 -- New System (After Migration)

How Publishing Will Work After Migration

After consolidation, adding or updating a guide is straightforward. There are no
repos to create, no CI to configure, no secrets to set up, no scripts to curl.

Adding a new guide (doc-only, no sample project)

This is the simplest case -- a guide that is pure documentation with no runnable
initial/+complete/ sample apps.

1. Create the guide directory:

   guides/my-new-grails8-feature/
   ├── toc.yml
   └── guide/
       ├── intro.adoc
       ├── writingTheApp.adoc
       └── summary.adoc
   

2. Write toc.yml (table of contents):

   title: My New Grails 8 Feature
   authors:
     - Your Name
   ---
   introduction: intro.adoc
   writingTheApp:
     title: Writing the Application
     guide: writingTheApp.adoc
   summary: summary.adoc

3. Write .adoc files using AsciiDoc syntax. Use include:: to pull in
   shared snippets from guides/common/ (e.g. common-requirements.adoc).

4. Add an entry in conf/guides.yml:

   - name: my-new-grails8-feature
     title: "My New Grails 8 Feature"
     subtitle: "Learn how to use the new feature in Grails 8"
     authors: "Your Name"
     category: "Grails Apprentice"
     tags: [grails8, new-feature]
     publicationDate: "15 Feb 2026"
     grailsVersions: [8]

5. Build and preview locally:

   ./gradlew buildGuides
   # Open build/dist/guides/my-new-grails8-feature/guide/index.html

6. Submit a PR to apache/grails-static-website. Once merged, the guide is
   automatically built and deployed by publish.yml.

That's it. One PR, one repo, automatic deployment.

Adding a new guide with sample projects

For guides that include runnable initial/+complete/ Grails applications:

1. Create the guide content in this repo (same as above -- steps 1-4).

2. Add sampleProjectRepo to the guide's conf/guides.yml entry:

   - name: my-new-grails8-guide
     title: "My New Grails 8 Guide"
     subtitle: "A hands-on guide to building with Grails 8"
     authors: "Your Name"
     category: "Grails Apprentice"
     tags: [grails8]
     publicationDate: "15 Feb 2026"
     grailsVersions: [8]
     sampleProjectRepo: "grails-guides/my-new-grails8-guide"

3. Create the sample project repo in the grails-guides org:

   grails-guides/my-new-grails8-guide/
   ├── initial/          <-- starter Grails app
   ├── complete/         <-- finished solution
   ├── settings.gradle   <-- include 'complete', 'initial'
   ├── build.gradle      <-- just builds/tests the sample apps (no doc publishing)
   └── .github/workflows/
       └── build.yml     <-- runs ./gradlew check only
   

   The sample project repo is simple -- no githubactions-build.sh, no
   apply from: remote scripts, no doc-publishing metadata, no secrets needed
   for pushing to gh-pages. It just builds and tests the sample apps.

4. Submit two PRs:

   • PR to apache/grails-static-website with the guide content + YAML entry
   • Create the sample project repo with initial/+complete/

Updating an existing guide

1. Edit the AsciiDoc in guides/<guide-name>/guide/*.adoc.
2. Update conf/guides.yml if metadata changed (e.g. adding a new Grails version).
3. Submit a PR. That's it.

If the guide has a sample project repo in grails-guides, update the sample code
there in a separate PR.

Adding a new Grails version to an existing guide

1. Update conf/guides.yml to add the version:

   grailsVersions: [6, 7, 8]  # was [6, 7]

2. Update AsciiDoc if there are version-specific instructions (use AsciiDoc
   conditionals or separate sections as needed).

3. Update the sample project repo (if one exists) -- either update the existing
   initial/+complete/ to the new Grails version, or add versioned directories
   (e.g. complete-grails8/) if multiple versions need distinct sample code.

4. Submit a PR.

How versioning simplifies with migration

In the current system, multi-version guides require maintaining separate Git branches
per Grails version, each with its own CI pipeline writing to gh-pages. After
consolidation:

1. No more multi-branch complexity: Guide version metadata lives in
   conf/guides.yml with a simple grailsVersions: [4, 5, 6] list. The AsciiDoc
   source is a single copy with version-conditional content if needed.

2. Publish previously unpublished versions: The 35 grails5 branches with
   distinct content and the 15 grails-4 branches with distinct content can now
   be published by adding their AsciiDoc and sample code during migration. These
   were never published only because the CI scripts didn't handle them.

3. Explicit version support: Instead of inferring version from branch names
   with inconsistent patterns (grails4 vs grails-4), each guide declares
   supported versions explicitly in conf/guides.yml.

4. Single-pass build: One Gradle build generates all guide HTML for all versions,
   instead of each version branch triggering separate CI pipelines that race to
   write to gh-pages.

5. Easy to add Grails 7/8 guides: Adding a new guide version is a YAML edit,
   not a branch + CI + secrets setup.

---

Comparison: Before vs After

	Current system	After migration
Create a new guide	Run create-guide.sh, create GitHub repo, manually create workflow YAML, configure 3 secrets, push	Create guides/<name>/ dir + conf/guides.yml entry, submit PR
Where guide content lives	Scattered across 94 repos	Single guides/ directory in this repo
How it gets published	Push to guide repo -> CI curls scripts -> builds AsciiDoc -> pushes to gh-pages -> curls another script -> rebuilds index -> pushes again	Push to this repo -> CI builds everything -> deploys
CI configuration	Per-repo workflow YAML + 3 secrets + runtime curl of scripts	Single publish.yml in this repo
Preview changes	Must push to trigger CI; no local preview	./gradlew buildGuides locally
Add a Grails version	Create a branch, hope the CI handles it (it probably won't due to build-guide branch discrepancy)	Edit one line in conf/guides.yml
Time to publish	Minutes (CI cascade across repos)	Seconds (single build + deploy)
Guide URL	guides.grails.org/<name>/guide/index.html	grails.apache.org/guides/<name>/guide/index.html
Repos to maintain	94 guide repos + 1 template repo	1 repo (this one) + sample project repos

---

Key Files Reference

grails-static-website (this repo)

File	Purpose
buildSrc/.../GrailsWebsitePlugin.groovy	Registers all tasks including genGuides and buildGuides
buildSrc/.../tasks/GuidesTask.groovy	Generates guide index, tag, and category HTML pages
buildSrc/.../model/guides/GuidesFetcher.groovy	Fetches and parses guides.json from GitHub
buildSrc/.../model/guides/GuidesPage.groovy	Renders guide listing HTML (categories, tags, search)
buildSrc/.../model/guides/Guide.groovy	Guide interface (category, name, title, tags, etc.)
buildSrc/.../model/guides/SingleGuide.groovy	Guide with one Grails version
buildSrc/.../model/guides/GrailsVersionedGuide.groovy	Guide spanning multiple Grails versions
.github/workflows/publish.yml	CI: builds main site + guides index, pushes to deploy branches
publish.sh	Runs Gradle build, clones deploy repo, copies output, pushes

grails-guides/grails-guides-template (infrastructure + deployment repo)

File	Branch	Purpose
gradle/guide-build.gradle	master, 6.0.x	Shared build script applied by all guide repos
create-guide.sh	master, 6.0.x	Scaffolds a new guide project
src/main/docs/common-*.adoc	master, 6.0.x	~45 reusable AsciiDoc snippets included by guides
src/main/resources/	master, 6.0.x	CSS, fonts, images for guide HTML theme
src/main/project/	master, 6.0.x	Template files copied into new guides (build.gradle, gradle.properties, githubactions-build.sh, docs skeleton)
githubactions/build-guide	master	CI script: test + build + publish a single guide + update guides.json. master version handles master+grails3 only
githubactions/build-guide	6.0.x	CI script: same but handles grails3-grails6 (not master)
githubactions/republish-guides-website.sh	master, 6.0.x	CI script: clone static-website, rebuild index, push to gh-pages
gh-pages branch	--	Deployment: built guide HTML, guides.json (125 entries), and index site
README.md	master, 6.0.x	Still references Travis CI as the CI system

Individual guide repos (grails-guides org, 94 repos)

File	Purpose
.github/workflows/gradle.yml	GitHub Actions workflow -- manually created, NOT from template. Often outdated (actions@v2, JDK 11).
githubactions-build.sh	CI entrypoint. Identical in every repo. Curls build-guide and republish-guides-website.sh from grails-guides-template master at runtime.
build.gradle	Applies guide-build.gradle remotely via apply from: URL (old grails/grails-guides URL). Some point to master, some to 6.0.x.
gradle.properties	Guide metadata (title, authors, tags, category, publicationDate, githubSlug, githubBranch)
settings.gradle	Includes complete and initial subprojects
src/main/docs/guide/toc.yml	Table of contents for the guide
src/main/docs/guide/*.adoc	AsciiDoc source files
src/main/resources/img/	Guide-specific images
initial/	Starter Grails app for the reader to begin with (79 repos)
complete/	Finished Grails app -- the solution (93 repos)