slachiewicz opened a new issue, #1645: URL: https://github.com/apache/maven-site/issues/1645
`maven-doxia-site` is a separate repository, a separate Jenkins job and a separate svn publication tree, for 21 pages that live at `/doxia/` on maven.apache.org. Folding it into `maven-site` removes one repo, one job and one svnwcsub mount, and no URL has to change. This issue is the plan and the tracking point. It is not a decision — three things at the bottom need dev@ input first. ## How the site is published today Both repos have the same shape: a single-module site build, a Jenkins job on the `svn-websites` agent running `mvn site-deploy`, `maven-site-plugin` with `skipDeploy`, and `maven-scm-publish-plugin` doing the svn commit. `maven-site` publishes to `maven/website/content/`, `maven-doxia-site` to `maven/doxia/website/content/`. The webserver working copy at `/www/maven.apache.org/content` is assembled by `svnwcsub` from four checkouts, as documented in [`developers/website/index.md`](https://maven.apache.org/developers/website/index.html): | path | svn source | |---|---| | `/` | `maven/website/content/` | | `/components` | `maven/website/components/` | | `/doxia` | `maven/doxia/website/content/` | | `/doxia/components` | `maven/doxia/website/components/` | Released component documentation is never in git — release managers `svnmucc` it into the `components/` trees, and the site build recreates symlinks into them from the `components.links` files via `maven-antrun-plugin`. That task already globs `**/components.links`, so it picks up nested ones without a change. That `/doxia` mount is what makes this a two-party change: a `maven-site` PR **and** an INFRA ticket, in that order. ## Content move ``` maven-doxia-site/content/markdown/** -> maven-site/content/markdown/doxia/** maven-doxia-site/content/resources/** -> maven-site/content/resources/doxia/** ``` Directory structure is preserved verbatim, so every relative link inside the Doxia pages (`../macros/index.html`, `../doxia/doxia-modules/...`, `../doxia-archives/...`) keeps resolving, and root-absolute links (`/xsd/...`, `/plugin-developers/...`) are unaffected. `components.links` targets are relative, so the symlinks still land on `/doxia/components/...`. `pom.xml`, `Jenkinsfile`, `.asf.yaml`, `README.md`, `LICENSE` and `NOTICE` are not moved. Two lines in `maven-site/pom.xml`: - `<doxiaVersion>2.1.0</doxiaVersion>` — `index.md.vm` and `developers/modules.md.vm` use it, and render broken without it. - `content/resources/doxia/images/architecture.odg` in the rat excludes. `**/.htaccess`, `**/*.links` and `**/*.svg` are already covered. ## What breaks, and the fix for each Four things, found by comparing the two builds. **1. The site descriptor is singular.** A site build has exactly one `site.xml`. Doxia's own `bannerRight` logo, its `Doxia` breadcrumb and its five menus (About / Modules / Documentation / Developer Docs / reports) go away; the pages get the main Maven navigation. There is no per-directory descriptor, so the only option is folding the Doxia menus into `maven-site/content/site.xml` the way `/plugins/` and `/shared/` are handled. This is the one user-visible regression. **2. Five MPIR pages stop being generated:** `/doxia/team.html`, `/doxia/mailing-lists.html`, `/doxia/ci-management.html`, `/doxia/issue-management.html`, `/doxia/project-info.html`. Add `Redirect Permanent` for each to the relocated `/doxia/.htaccess`. All five root equivalents currently return 200, so they are valid targets — though for `issue-management.html` and `project-info.html`, which describe Maven as a whole rather than Doxia, pointing at `/doxia/` may serve readers better. `/doxia/scm.html` is *not* affected: Doxia has a hand-written `scm.md` that already wins over the MPIR report, so it survives the move unchanged. **3. Skin assets under `/doxia/images/` and `/doxia/css/` move to the site root.** The skin writes its icons, fonts, `js/`, `img/` and CSS into each *site root*; after the move that root is `/`, not `/doxia/`. Two consumers: - `references/index.md` uses `../images/icon_*_sml.gif` about twelve times — switch to `/images/icon_*_sml.gif`. Root `/images/` already has all of them, so this can land as its own commit before the move. - `/doxia/.htaccess` serves the archived release sites with `^/doxia/.*-archives/images/(.*)$ -> /doxia/images/$1` and `^/doxia/.*-archives/css/(.*)$ -> /doxia/css/$1`. Retarget both to `/images/$1` and `/css/$1`. Root `/css/` is a superset of what `/doxia/css/` holds today. **4. `site.css`.** Doxia's 40-line stylesheet turns out to be a strict subset of maven-site's 67-line one — identical `externalLink`, `body ul` and `#downloadbox` rules, and maven-site adds `.bordered` and `.grey`. So the pages pick up `/css/site.css` with no visual change and the Doxia copy can be dropped along with the redirect retarget above. Nothing else moves: the root `.htaccess` already applies to `/doxia/` today, the Doxia rules are all `^/doxia/`-anchored so they work from any directory, and `doap_Doxia.rdf` keeps its URL, so no comdev change is needed. ## Cut-over order This sequence never leaves the site broken: 1. Merge the `maven-site` PR. Jenkins deploys and creates `doxia/` inside `maven/website/content/`. Nothing user-visible happens — the `/doxia` mount still shadows it. 2. INFRA removes the `/doxia` mount from `svnwcsub.conf` and **keeps** `/doxia/components`. Component releases keep deploying to `maven/doxia/website/components/` exactly as before. 3. Verify `/doxia` now serves the maven-site build. 4. Only then decommission. Rollback at any point before step 4 is re-adding the mount. One thing to settle with INFRA before step 1: today `/doxia/components` nests inside `/doxia`, which is itself a working copy, and `/components` nests inside an *unversioned* path of the root working copy. After the change `/doxia/components` would nest inside a `doxia/` directory that *is* versioned in the outer working copy. That is the one thing that could force a different layout. <details> <summary>Draft INFRA ticket, to file at step 2</summary> **Summary:** Remove the `/doxia` svnwcsub mount for maven.apache.org The Apache Maven project has consolidated the Doxia website source into `apache/maven-site`. `/doxia/**` is now generated by the maven-site build and committed to `https://svn.apache.org/repos/asf/maven/website/content/doxia/`. Please remove this entry from `svnwcsub.conf` in `infrastructure-puppet` (`modules/svnwcsub/files/svnwcsub.conf`): - `/www/maven.apache.org/content/doxia` <- `https://svn.apache.org/repos/asf/maven/doxia/website/content/` Please **keep** this one — released Doxia component documentation is still published there by release managers and is not part of the git-managed site: - `/www/maven.apache.org/content/doxia/components` <- `https://svn.apache.org/repos/asf/maven/doxia/website/components/` Question before you apply it: `/doxia/components` will then be nested inside a `doxia/` directory that is versioned in the outer `/www/maven.apache.org/content` working copy, rather than inside a working copy of its own. The existing `/components` mount nests inside an unversioned path, which is not quite the same case. If svnwcsub cannot handle that, let us know and we will restructure on our side instead. Follow-up in the same or a separate ticket: archive `apache/maven-doxia-site` read-only. </details> ## Decommission, after step 3 verifies - [ ] disable the `Maven/maven-box/maven-doxia-site` Jenkins job - [ ] archive `apache/maven-doxia-site` - [ ] freeze or remove `maven/doxia/website/content/` in svn - [ ] `developers/website/index.md` — the four-mount table and the two `maven-doxia-site` `components.links` links - [ ] `developers/website/deploy-maven-website.md` — its "How Doxia website publication works" section is already obsolete CMS-era text - [ ] check `deploy-component-reference-documentation.md` and `component-reference-documentation-helper.md` for Doxia wording - [ ] fold anything missing from Doxia's `.asf.yaml` (labels, autolinks) into maven-site's ## Verification Build both and diff: ``` diff -r maven-doxia-site/target/site maven-site/target/site/doxia ``` The diff is noisy by design, because everything the skin and the reports write into a *site root* stops being written into `/doxia/`. Expected, and nothing else: - the five MPIR pages, plus `avatars/` from the team report - `css/apache-maven-fluido-*.min.css`, `css/print.css`, `css/site.css` - `fonts/`, `img/`, `js/` - `images/` reduced to Doxia's own files - navigation, banner and breadcrumb differences from (1) All of those are served from the site root instead, which is what the retargeted redirects point at. Anything outside this list is a bug. ## Can the git history come along? Yes. `maven-doxia-site` is 217 commits, 2012-12-10 to today — small and clean enough to graft: ``` git clone https://github.com/apache/maven-doxia-site.git doxia-history cd doxia-history git filter-repo \ --path content/markdown/ \ --path content/resources/ \ --path-rename content/markdown/:content/markdown/doxia/ \ --path-rename content/resources/:content/resources/doxia/ cd ../maven-site git remote add doxia ../doxia-history git fetch doxia git merge --allow-unrelated-histories doxia/master ``` The two `--path` filters keep only the directories that move, which also drops `content/site.xml` — it would otherwise collide with maven-site's own descriptor, and its content is folded in by hand anyway. `git blame` and `git log --follow` then work across the boundary. Two caveats. The git repo only goes back to the 2012 CMS migration; everything before that is in svn at `maven/doxia/site/trunk` and stays there either way. And maven-site's `.asf.yaml` sets `merge: false` with a required `Verify and build Maven Site` check, so a merge commit cannot land through the PR button as configured — it needs the merge button enabled temporarily, or a direct push to gitbox. The cheaper alternative is a plain copy plus archiving `maven-doxia-site` read-only, leaving the history browsable at a stable GitHub URL. Worth deciding up front: retrofitting the graft after a plain copy is considerably messier. ## Needs a decision 1. Fold the Doxia menus into the main `site.xml`, or accept plain main-site navigation? 2. Graft the history, or plain copy and archive? 3. Confirm with INFRA that the nested `/doxia/components` mount stays valid. *This issue was created with AI assistance.* -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
