[DISCUSS] Folding the Doxia site into maven-site
Sylwester Lachiewicz <[email protected]>
| Newsgroups | gmane.comp.jakarta.turbine.maven.devel |
|---|---|
| Message-ID | <CAJG7DX1AAfBqe2+EnLmaMYzvo0_YT0r-x+YSKgVAvB6z2Wjyzg@mail.gmail.com> |
Hi everyone,
I would like to propose folding the maven-doxia-site repository into
maven-site so the entire site is built from a single source tree.
Currently, maven-doxia-site is a separate repository, Jenkins job, and SVN
publication tree for the 21 pages located at /doxia/ on
https://maven.apache.org/
This move will not change any /doxia/ URLs. The full plan is outlined in
https://github.com/apache/maven-site/issues/1645, and the content move is
complete and passing tests in https://github.com/apache/maven-site/pull/1646.
The infrastructure changes are tracked under INFRA-28277, which is
deliberately on hold until the PR is merged and deployed.
Before merging, I would like to get your opinions on two specific points:
1. Navigation
A site build has exactly one site.xml, meaning the Doxia pages cannot
keep their own banner, breadcrumb, and menus. Instead, they will adopt the
main Maven navigation. This is the only user-visible change.
The current PR nests the Doxia menus inside the Documentation menu,
next to Maven Tools. Alternatively, we could leave the Doxia pages with
plain main-site navigation and remove their specific menus entirely.
2. Git history
The maven-doxia-site repository has 217 commits dating back to December
2012. We can either:
a) Graft the history onto maven-site using git-filter-repo and a merge
with --allow-unrelated-histories so git blame and git log --follow continue
to work. This requires temporarily enabling the merge button or a direct
push to GitBox due to our .asf.yaml restrictions.
b) Do a plain copy, as the PR currently does, and archive
maven-doxia-site as read-only.
Deciding this upfront is ideal, as retrofitting the history later is much
more complex. Note that either option only covers the Git era; anything
prior to the 2012 CMS migration will remain in SVN.
For context, building both trees and diffing them shows that only the
necessary root-level items change. Additionally, resolving local links in
the built Doxia pages actually fixes 14 broken links that currently point
to the main site.
If there are no objections, I plan to merge the PR in a week and update
INFRA-28277 once the deployment is complete.
Thanks,
Sylwester