In the parent commit, we started supporting to load the client-side
search via the `/search?search=<term>` URL into the interactive search
box served from the Rails app version of the page.
The trick to make this work was to exploit the fact that `/search` will
resolve to a full HTML page in the Hugo/Pagefind version, including the
client-side search code, which finds the search box, interprets its
contents, and peforms the desired functionality.
However, this still shows a quite ugly "full page" inside the search
results <div>.
Even worse: While the user typed less than three characters, this would
show the warning (intended for users who turned off Javascript) that
the search functionality is now client-side and requires Javascript.
Of course, this all only matters as long as the cached versions of the
Rails app site are served while transitioning to the Hugo/Pagefind
version of the site.
For the transition from a Rails app to a static website, let's detect
the situation that we're running "in mixed mode" and replace the full
search page with a small placeholder that is less annoying to the eye.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
We are in the process of moving over https://git-scm.com/ from a Rails
app to a Hugo/Pagefind-based site that is hosted on GitHub Pages.
Our first attempt on September 20th, 2024, revealed that there are
challenges with cached pages, both browser cache and Cloudflare cache
adding their own quirks. The most obvious problem was that _some_ cached
URL contents seem to be lagging behind from the Rails app while new ones
from the static Hugo site are added.
To help with this, I added code in the parent commit to let the the Hugo
site keep offering the `.css` and `.js` files of the Rails app. That
way, a previously-cached version of, say, https://git-scm.com/docs/git
would still find the referenced style sheets and Javascript files.
For the same reason, this here commit prepares the `/search` page to be
able to deal with being called when `window.location` points to
`/assets/application-<some-hex>.js`, which is the case when the
Hugo/Pagefind version of `/search?term=<needle>` is called from a Rails
version of the interactive search box.
According to the `Cache-control:` header sent back by the Rails app, the
`max-age` is set to 14,400 seconds, i.e. 4 hours, therefore the
transition window should be relatively manageable.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Currently, Git's home page is still a Rails app. When we tried to
transition away from it to the new Hugo/Pagefind-backed site, we noticed
a couple of problems, where some pages would look quite odd.
The reason turned out to be both Cloudflare and browser caching, where
force-reloading some pages would still retrieve the original versions of
the pages, but the `.css` and `.js` files referenced by those original
versions were gone.
And it is not just because the Hugo site puts those files in different
locations: Rails automatically amends the file name of style sheets and
Javascript libraries with a hash so that stale caches would not play a
role when new versions of those files become available (historically,
browsers are quite challenged when it comes to force-reloading pages
where also their referenced `.css`/`.js` files need to be
force-reloaded).
We can help with that! Simply by "putting back" those `.css`/`.js` files
into the place where the Rails version of the pages expects them.
Luckily, those files haven't changed very much, the most recent one was
the September update to disallow font ligatures in code blocks, and the
second-most recent was the August update to add the `/` keyboard
shortcut to get to the search box. Here are the `Last-modified:` headers
of those files when fetching them from https://git-scm.com/:
application*.css: Tue, 10 Sep 2024 17:26:19 GMT
application*.js: Mon, 19 Aug 2024 07:40:42 GMT
modernize*.js: Tue, 15 Dec 2020 06:13:03 GMT
So those files are very unlikely to change a lot, especially now, during
the transition.
By adding them to the Hugo/Pagefind site, even partial caches should not
break the site when switching DNS over to GitHub Pages.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Now that we are really close to switching over https://git-scm.com/ from
the Rails app to the Hugo/Pagefind-generated static site, it is time to
stop assuming that it is the former.
Indeed, I have just changed the `deploy` workflow to ensure that the
site works as expected when being deployed as `http://git-scm.com/`.
So let's just change the `playwright` workflow to have another input
that specifies whether the person triggering that workflow expects the
URL to resolve to a Rails app variant of the site or not, and stop
trying to determine that automatically.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
The `isRailsApp` variable tells whether the URL in question refers to
the original Rails App variant of https://git-scm.com/ or to the new
Hugo/Pagefind-based site. The variable is set to true if the URL is
https://git-scm.com/.
However, today we tried for the first time to switch
https://git-scm.com/ to the new site. Therefore, that condition would
have been wrong (even as luck had it, the URL in use was a http one, not
an https one, i.e. the insecure variant, and therefore `isRailsApp` was
correctly set to `false`, but that was just happenstance).
Let's make sure that the value of the `isRailsApp` is correct by looking
for the tell-tale `<meta name="generator" content="Hugo <version>">` tag
that is generated by Hugo but not by the Rails app.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Whenever an operation fails, it is nice to see what the current browser
windows looked like. It really helps to diagnose failures better.
The actual code is inspired by the comments at
https://stackoverflow.com/questions/78020451/how-to-take-screenshot-on-failure
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
This marks the switch-over from a Rails app to a Hugo/Pagefind-based
website that is served via GitHub Pages.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
This topic brings in some UI testing, to build confidence not only in
the migration of the website, but also to be able to prevent (or at
least swiftly detect) regressions.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Whenever deploying the site, it is a good idea to run the tests
afterwards.
An alternative would be to run the tests before deploying, but there are
challenges that would make this cumbersome:
- For deployments, we run Hugo with a specific base URL, which could let
the UI tests redirect to the site that we want to deploy to, and
therefore fail to verify the locally-built site.
- Even if an outside change (such as a change from the ProGit book
repository) would break those tests, we would still want to deploy the
site. This is better than falling behind just because no volunteer
finds time to fix the issues.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
As all building blocks are now in place to run the Playwright tests
in-place, we can run them as part of every Pull Request, to catch
regressions before they enter the official site.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Some book sections' titles end in a question mark. In URLs, question
marks are interpreted as the separator between the path part and the
query string. This matters because the book sections' titles are used to
construct their URLs.
We want to follow Postel's Law and accept even URLs with non-URI-encoded
question marks, gracefully redirecting to the correct URL. Add code to
the Playwright-based tests to that extent.
While at it, also verify that the redirection uses proper URI-encoding
for non-ASCII characters; This requires a minor improvement of the
intentionally very simplistic `serve-public.js` script.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
To make it easier to run the tests locally (or in the near future, in
every PullRequest), let's add a minimal node.js script that serves the
static webpages in as similar a manner to GitHub Pages as is needed for
the tests to validate the site.
This server will be started automatically when running with the
environment variable PLAYWRIGHT_TEST_URL set to http://localhost:5000/.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
The UI tests are most beneficial when they are run regularly ;-)
For starters, this allows running them in a GitHub workflow that is
triggered manually, offering the user to specify which site to test.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
A bug in one of the translated manual pages was reported via
https://discord.com/channels/1042895022950994071/1043101606549401661/1248660690676224124
where the command `git remote rename` was translated to `git remote
renom`.
While it _is_ true that the French translation of the noun "rename" is
"renom", in this instance the translation is incorrect because it is a
Git command, and Git will complain about an unknown subcommand when
thusly invoked.
It's a bit tricky to find the source of these contents of git-scm.com:
https://github.com/jnavila/git-html-l10n/blob/master/fr/git-remote.txt,
Or at least it _should_ be, but strangely enough that source does not
have the typo and it has not changed for the last 7 months.
The actual _actual_ source of these git-scm.com contents is
https://github.com/jnavila/git-manpages-l10n/blob/master/po/documentation.fr.po,
from which `git-html-l10n` is auto-generated, but even there, the text
correctly reads `git remote rename`.
Digging a bit deeper, this was fixed in
https://github.com/jnavila/git-manpages-l10n/commit/b435bfd (Translated
using Weblate (French), 2022-04-16) and that fix trickled into
https://github.com/jnavila/git-html-l10n/commit/506285b (update
2022-04-22, 2022-04-22) a week later. But apparently almost 2.5 years
later, the fix did not make it to the Git home page. Most likely the
problem is a glitch somewhere in the cache/database of the Rails app.
Document this particular problem as fixed in the Hugo/Pagefind version
of Git's home page, and as broken on the Rails app version, by
specifically checking for this in the Playwright tests.
Reported-by: emmanuel Hesry <ehesry@gmail.com>
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Currently, the Git home page is implemented as a Rails app. For various
reasons, this app behaves a bit different than the upcoming
Hugo/Pagefind-based home page.
Let's document the differences via the UI tests.
Let's also make it easy to test against various sites, via the
environment variable `PLAYWRIGHT_TEST_URL`. When set, it is used instead
of https://git-scm.com/. This enables swift and painless validation of
the Hugo/Pagefind site, as it is now easy to augment the Playwright
tests to test something on the original Rails app and then to verify
without much hassle that the Hugo/Pagefind site behaves the same.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
The Git home page displays some platform-dependent behavior. With this
commit, we test that by pretending to run on the three major operating
systems: Windows, macOS and Linux. Specifically, we verify that:
- the correct download is suggested, based on the current browser
- a subset of the GUIs are shown based on the platform indicated by the
current browser
Pretending to be running on a given platform is a bit tricky because the
`navigator.userAgent`/`navigator.platform` attributes are used by the
Git home page (via `session.min.js`) to determine what operating system
the user is running.
These can be easily overridden on most browser, using the
`Object.defineProperty()` method.
However, in my tests, Chromium on Linux (and only on that operating
system) simply ignored those calls and still reported that it is running
on Linux.
To work around this, we need to use the Chrome DevTools Protocol, via
the `BrowserContext.newCDPSession()` method; For more details see
https://playwright.dev/docs/api/class-browsercontext#browser-context-new-cdp-session
Obviously, this can _only_ be used with Chromium/Chrome and won't work
on, say, Firefox or Safari. That is the reason for the somewhat ugly
`pretendPlatform()` function we need to use here.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Playwright (https://playwright.dev/) is a quite complete framework to
perform UI tests on websites.
We use this framework here to verify that:
- the search works
- switching between languages works
- following links from a translated manual page fall back to English if
the linked-to manual page has no translation
- navigating between book sections colorizes the correct links in the
drop-down
A new feature of the Hugo/Pagefind-based site is that the search
facility is language-aware. For this reason, we also verify that:
- search results are language-dependent
These tests can be run by first installing the `@playwright/test`
dependency, via `npm install`, and then invoking `npx playwright test`.
Helped-extensively-by: Max Schmitt <max@schmitt.mx>
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
ttaylorr
Johannes Schindelin
dscho