Update external docs

Author: garrett

external/bots/README.md

@@ -32,8 +32,8 @@ For managing these images:
 
  - `image-download`: Download selected or all test images
  - `image-create`: Create test machine images from scratch (usually through
-   virt-install or downloading a cloud image), with common build and test
-   dependencies for Cockpit projects preinstalled
+   downloading a cloud image), with common build and test dependencies for
+   Cockpit projects preinstalled
  - `image-upload`: Upload a locally built test image to the official image servers
 
 For running and debugging the images:

external/source/HACKING.md

@@ -63,29 +63,27 @@ To re-create your development container from the latest image, run:
 ## Working on Cockpit's session pages
 
 Most contributors want to work on the web (HTML, JavaScript, CSS) parts of Cockpit.
+
+### Install Cockpit
+
 First, install Cockpit on your local machine as described in:
 
 <https://cockpit-project.org/running.html>
 
+### Build session pages
+
 Next, run this command from your top level Cockpit checkout directory, and make
 sure to run it as the same user that you'll use to log into Cockpit below.
 
     mkdir -p ~/.local/share/
     ln -s $(pwd)/dist ~/.local/share/cockpit
 
-This will cause cockpit to read JavaScript, HTML, and CSS files directly from the
+This will cause Cockpit to read JavaScript, HTML, and CSS files directly from the
 locally built package output directory instead of using the system-installed Cockpit
 files.
 
-Now you can log into Cockpit on your local Linux machine at the following
-address. Use the same user and password that you used to log into your Linux
-desktop.
-
-<http://localhost:9090>
-
-After every change to the source files, bundles need to be rebuilt. The
-recommended and fastest way is to do that is using the "watch" mode (`-w` or
-`--watch`) on the page that you are working on. For example, if you want to
+The recommended way to build bundles is to use the "watch" mode
+(`-w` or`--watch`) on the page you are working on. For example, if you want to
 work on anything in [pkg/systemd](https://github.com/cockpit-project/cockpit/tree/main/pkg/systemd/), run:
 
     ./build.js -w systemd
@@ -97,8 +95,16 @@ pkg/lib/), you can also build all pages:
 
     ./build.js -w
 
-Reload cockpit in your browser after page is built. Press `Ctrl`-`C` to
-stop watch mode once you are done with changing the code.
+Now you can log into Cockpit on your local Linux machine at the following
+address, using the same username and password as your desktop login:
+
+<http://localhost:9090>
+
+Watch mode automatically rebuilds when source files are modified. Once it
+finishes building, refresh your browser to see the changes in Cockpit.
+Press `Ctrl-C` to stop watch mode when you are done changing the code.
+
+### Testing
 
 You often need to test code changes in a VM. You can set the `$RSYNC` env
 variable to copy the built page into the given SSH target's
@@ -109,6 +115,8 @@ one of these commands:
     RSYNC=c ./build.js -w kdump
     RSYNC=c ./build.js -w
 
+### Returning to system packages
+
 To make Cockpit use system packages again, instead of your checkout directory,
 remove the symlink with the following command and log back into Cockpit:
 
@@ -152,10 +160,26 @@ which will output a URL to connect to with a browser, such as
 <http://localhost:8765/qunit/base1/test-dbus.html>. Adjust the path for different
 tests and inspect the results there.
 
-You can also run individual tests by specifying the `TESTS` environment
-variable:
+QUnit tests are run as part of a pytest test called `test_browser`.  You can
+run individual tests via `pytest -k`, like so:
+
+    pytest -k test-fsinfo.html
+
+You can see JavaScript code coverage information for QUnit tests.  For a
+summary table:
+
+    pytest -k test_browser --js-cov
+
+And for detailed output on uncovered sections in a specific file, something
+like:
+
+    pytest -k test-fsinfo.html --js-cov-files='*/fsinfo.ts'
+
+Coverage information is gathered into the pytest tmpdir, regardless of which
+coverage-related commandline flags are given, so it's also possible to drill
+down after the fact — without re-running tests — using something like:
 
-    make check TESTS=qunit/base1/test-chan.html
+    test/common/js_coverage.py -m '*/fsinfo.ts' /tmp/pytest-of-*/pytest-current/js-coverage/*
 
 There are also static code and syntax checks which you should run often:
 
@@ -199,7 +223,7 @@ The Python bridge can be used interactively on a local machine:
 To make it easy to test out channels without having to write out messages
 manually, `cockpit.misc.print` can be used:
 
-    PYTHONPATH=src python3 -m cockpit.misc.print open fslist1 path=/etc watch=False | PYTHONPATH=src python3 -m cockpit.bridge
+    PYTHONPATH=src python3 -m cockpit.misc.print open fsinfo path=/etc 'attrs=["type", "entries"]' | PYTHONPATH=src python3 -m cockpit.bridge
 
 These shell aliases might be useful when experimenting with the protocol:
 

external/source/test/README.md

@@ -172,21 +172,15 @@ You can set these environment variables to configure the test suite:
                   "centos-10"
                   "debian-stable"
                   "debian-testing"
-                  "fedora-39"
                   "fedora-40"
                   "fedora-coreos"
                   "rhel-9-4"
-                  "rhel4edge",
                   "ubuntu-2204"
                   "ubuntu-stable"
-               "fedora-39" is the default (TEST_OS_DEFAULT in bots/lib/constants.py)
+               "fedora-40" is the default (TEST_OS_DEFAULT in bots/lib/constants.py)
 
     TEST_JOBS  How many tests to run in parallel.  The default is 1.
 
-    TEST_CDP_PORT  Attach to an actually running browser that is compatible with
-                   the Chrome Debug Protocol, on the given port. Don't use this
-                   with parallel tests.
-
     TEST_BROWSER  What browser should be used for testing. Currently supported values:
                      "chromium"
                      "firefox"

external/wiki/Proxying-Cockpit-over-Apache-with-LetsEncrypt.md

@@ -101,6 +101,26 @@ Change this file so it looks like the following.
 </IfModule>
 ```
 
+With Apache 2.4.47 or later, this could also be written as:
+
+```apacheconf
+<IfModule mod_ssl.c>
+<VirtualHost *:443>
+  ServerName cockpit.your-domain.com
+  SSLCertificateFile /etc/letsencrypt/live/cockpit.your-domain.com/fullchain.pem
+  SSLCertificateKeyFile /etc/letsencrypt/live/cockpit.your-domain.com/privkey.pem
+  Include /etc/letsencrypt/options-ssl-apache.conf
+
+  ProxyPreserveHost On
+  ProxyRequests Off
+
+  # Proxy to your local cockpit instance
+  ProxyPass / http://127.0.0.1:9090/ upgrade=websocket
+  ProxyPassReverse / http://127.0.0.1:9090/
+</VirtualHost>
+</IfModule>
+```
+
 Save and close the file. Then restart Apache web server.
 
 `sudo systemctl restart apache2`