docs(15.9): the search screen is now the bundled static theme

[marevol]

Why

Since codelibs/fess#3460 the search screen (/, /search, /advance, /help, /profile, /cache, /chat and the error pages) is always a static theme: when theme.default is unset, the bundled bootstrap theme is used. A 15.8 installation that never chose a theme has no theme.default, so an upgrade switches it silently, and no setting brings the JSP search screen back. The 15.9 documentation did not say so, and several pages still described the JSP screen:

• install/upgrade.rst did not mention the switch. It also did not say that errors are now rendered at the requested URL with the real status instead of a 302 to /error/*, or that with login.required=true the page now returns 200 and /api/v2/* answers 401.
• Step 3 of the ZIP upgrade copied app/themes/. from the old installation. That directory also holds the bundled bootstrap theme, so following the step replaced the 15.9 search screen with the 15.8 version of the theme (1.0.5 over 1.3.0).
• The note on the removed page design editor pointed to dev/theme-development.rst, whose CSS and logo section sits under "JAR theme (legacy)" and said the search screen is built from JSPs.
• config/security-virtual-host.rst told users to edit the per-virtual-host JSPs. They are still generated, but the search screen no longer uses them.
• admin/theme-guide.rst said there are two ways to install a theme and left out the install form on the Theme page itself (feat(theme): fetch and install static themes from a maven repository fess#3462).

What changes

All seven languages (ja, en, de, es, fr, ko, zh-cn), 15.9 only.

• install/upgrade.rst: new section "The Search Screen Is Now a Static Theme":

  • the switch itself;
  • where JSP, CSS and image customizations go now (a copy of the bundled theme, or a published theme);
  • a "What Clients See" table of the status changes for /go/, /thumbnail/, /sso/metadata, /sso/logout, /api/v1/*, unknown URLs, uncaught exceptions and /error/*;
  • the login.required behaviour.

  Step 3 now copies only the user's own theme directories, warns against copying bootstrap, and points to bin/fess-setup install theme for published themes.

• dev/theme-development.rst: the overview now says the search screen is always a static theme. New section "Customizing the Bundled Theme":

  • copy bootstrap and rename it in theme.yml;
  • replace the four themes/bootstrap/ references in index.html. Without this step, the copy keeps loading the bundled CSS, logos and script, so edits do not show;
  • which files hold the colours, logos and texts;
  • how to package the copy and select it.

  Also: spaFallback is marked as no longer read, /advance is added to the served paths, and the section describes the Content-Security-Policy on the entry HTML. The JAR theme section now says that since 15.9 it affects only the login screen.

• admin/theme-guide.rst:

  • three install methods, including "Installing from the Repository" (the Available Themes list and Install by Name);
  • clearing the default returns to bootstrap;
  • the bundled theme cannot be deleted or replaced;
  • the theme.repositories property.

• config/security-virtual-host.rst, config/multitenancy.rst (and the English-only config/virtual-host.rst): a per-host look is a static theme whose name is the virtual host name in lowercase. The generated JSPs are used only by the login screen.

• install/run.rst, install/install-docker.rst: the first-run pages say the search screen is the bundled static theme, and how to change it.

The customization steps describe index.html as it is on main today: a copy must reference its own theme directory, so step 3 rewrites the four paths. codelibs/fess#3470 (not merged) would make that step unnecessary; if it lands, step 3 is the only part to update.

Verification

• Every claim was checked against the codelibs/fess source on main:
  • ThemeRegistry.resolveActiveTheme: virtual host, then theme.default, then bootstrap. Nothing is logged when theme.default is unset.
  • StaticThemeFilter: the served paths. spaFallback is not read.
  • ErrorPageServlet and web.xml: errors are rendered in place, with Accept-based text/plain bodies.
  • GoAction, ThumbnailAction, SsoAction: the 400 and 404 responses.
  • LoginRequirement: which /api/v2/ endpoints need a login.
  • StaticThemeInstaller: bootstrap is refused on upload and delete.
  • ThemeArtifactHelper and admin_theme.jsp: installing from the repository, with a checksum check.
  • VirtualHostHelper: only the login actions still resolve per-host JSPs.
  • The bundled index.html: four themes/bootstrap/ references. i18n.js and help.js load relative to assets/app.js.
• The behaviour was reproduced on a 15.9 build:
  • after a 15.8 installation is upgraded, / serves the static theme;
  • copying app/themes/. from 15.8 puts the 15.8 bootstrap over the 15.9 one;
  • a copy of bootstrap shows its own CSS, logo and footer only after its index.html paths are changed;
  • a theme named after a virtual host is served for that host;
  • the status codes in the table.
• All seven 15.9 trees were built with Sphinx:
  • the warning list is identical to main;
  • the new cross-references (theme-customize-bundled, upgrade-159-static-theme, Installing from the Repository) resolve;
  • the rendered text of each changed page has no unparsed inline markup;
  • the CJK heading rules are generated from display width.