wordmove-ng 6.0.0 → 6.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f483b0f5d6fbc250704d0f32134a73eef315ab0cc2b31d8313a1e6553ad1aaa
-  data.tar.gz: dfd3302b3678fac11044ea5a51405b57c4aab7369171f9d04d6b1e932476bd8a
+  metadata.gz: f35d0da6f7b15e8f492351b76ea90e096fe73b5c94cf55d9e8f10a0e93eb3802
+  data.tar.gz: cebf5ecc1de41bf581c5b07cdf4446e87ead5b73c891393b60cfa7a6d702c14c
 SHA512:
-  metadata.gz: fdc7e665dbbe4e97cd9d58310cad0c23ca0cde8870da5470390aa4ac0e02285fa78be59676658b60a93490e86b7addc807cb9007821bd94787b2bbf843a4b9e8
-  data.tar.gz: e33568402ef5f6638f8fe0748d29aeedd724af84f84ea9395dd7c7b9f2d89cbc051437c5ea3cf2afe317a248cc21dee1fabfb3cc43f8d236e5506a5c74359f6c
+  metadata.gz: dcb6cddeb0d95335204a1a40b2f429573ec114d0cffc7375e16af0eec4d2201df92c9c8f2040e809c610933853a1e71cf116ff3b3525a22f25d6b4da26366ac5
+  data.tar.gz: 35b2e3a3b29fb0e2ca9d6c128781cc0ca2feaa758b8efa49eeb71402c0ff2e683cb3bfcbbb8bf5d54d0d172ffd524a09579c7794b6da5a3da8638dc725c0bd8e

data/.github/workflows/pages.yml

@@ -0,0 +1,52 @@
+# Builds the docs/ site with Jekyll + just-the-docs and deploys it to GitHub
+# Pages. Requires the repository's Pages source to be set to "GitHub Actions".
+
+name: Docs
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+          working-directory: docs
+      - uses: actions/configure-pages@v5
+        id: pages
+      - name: Build
+        working-directory: docs
+        env:
+          JEKYLL_ENV: production
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment

data/.github/workflows/release.yml

@@ -97,4 +97,9 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           TAG: ${{ needs.release-please.outputs.tag_name || github.ref_name }}
-        run: gh release upload "$TAG" pkg/*.gem --clobber
+        # release-please creates the release itself; a hand-pushed tag has none yet.
+        run: |
+          if ! gh release view "$TAG" >/dev/null 2>&1; then
+            gh release create "$TAG" --title "$TAG" --notes "See CHANGELOG.md for details."
+          fi
+          gh release upload "$TAG" pkg/*.gem --clobber

data/.gitignore

@@ -19,3 +19,5 @@ test/tmp
 test/version_tmp
 tmp
 .vs/
+docs/_site
+docs/Gemfile.lock

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "6.0.0"
+  ".": "6.0.1"
 }

data/CHANGELOG.md

@@ -5,7 +5,14 @@ All notable changes to wordmove-ng are documented here. The project follows
 are listed at https://github.com/welaika/wordmove/releases; the kokiddp fork's changes
 between 5.2.2 and this project are summarised under 6.0.0.
 
-## 6.0.0 (unreleased)
+## [6.0.1](https://github.com/tekgnosis-net/wordmove-ng/compare/v6.0.0...v6.0.1) (2026-09-09)
+
+
+### Documentation
+
+* add the documentation site on GitHub Pages ([3b3e70a](https://github.com/tekgnosis-net/wordmove-ng/commit/3b3e70ae4ed548778634aa115cf0b64d53cfb727))
+
+## 6.0.0 (2026-09-09)
 
 First release as an independent project. Breaking changes are marked **breaking**.
 

data/CLAUDE.md

@@ -90,6 +90,13 @@ Key pieces:
   `global.collation_fallbacks`, `global.charset_fallbacks`. Add new toggles as movefile keys
   with an env override and document them in README + CHANGELOG in the same commit.
 
+## Docs site
+
+`docs/` is a Jekyll + just-the-docs site published to https://tekgnosis-net.github.io/wordmove-ng/
+by `.github/workflows/pages.yml` on pushes to `master` that touch `docs/`. Internal links use
+`{{ site.baseurl }}/<slug>/` (pretty permalinks). Preview: `cd docs && bundle exec jekyll serve`.
+Update the relevant page in the same commit as any user-facing behaviour change.
+
 ## Conventions worth knowing
 
 - **Commit messages are Conventional Commits** (`feat:`, `fix:`, `feat!:`/`BREAKING CHANGE:`,

data/README.md

@@ -12,7 +12,11 @@ by weLaika, continued through the [kokiddp fork](https://github.com/kokiddp/word
 The movefile format, commands and flags are unchanged. What changed is under the hood, and
 in a few places where the old behaviour was unsafe. See [Upgrading from wordmove 5.x](#upgrading-from-wordmove-5x).
 
-[![Tests](https://github.com/tekgnosis-net/wordmove-ng/actions/workflows/ruby.yml/badge.svg)](https://github.com/tekgnosis-net/wordmove-ng/actions/workflows/ruby.yml)
+**Full documentation: <https://tekgnosis-net.github.io/wordmove-ng/>**
+
+[![Tests](https://github.com/tekgnosis-net/wordmove-ng/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/tekgnosis-net/wordmove-ng/actions/workflows/ruby.yml?query=branch%3Amaster)
+[![Gem](https://img.shields.io/gem/v/wordmove-ng)](https://rubygems.org/gems/wordmove-ng)
+[![Docs](https://img.shields.io/badge/docs-tekgnosis--net.github.io%2Fwordmove--ng-blue)](https://tekgnosis-net.github.io/wordmove-ng/)
 
 ## Highlights
 
@@ -37,7 +41,7 @@ Ruby 3.0 or newer is required.
 gem install wordmove-ng
 ```
 
-Until the gem is on rubygems.org, or to run the latest master:
+To run the latest master instead of a release:
 
 ```bash
 gem install specific_install
@@ -242,12 +246,13 @@ production:
 File sync mirrors the source: files missing on the source are deleted on the destination.
 Put anything you need to keep in `exclude`, which is always relative to `wordpress_path`.
 
-The wiki has the full reference:
-[movefile.yml configurations explained](https://github.com/tekgnosis-net/wordmove-ng/wiki/movefile.yml-configurations-explained),
-[Usage and flags explained](https://github.com/tekgnosis-net/wordmove-ng/wiki/Usage-and-flags-explained),
-[Multiple environments explained](https://github.com/tekgnosis-net/wordmove-ng/wiki/Multiple-environments-explained),
-[Hooks](https://github.com/tekgnosis-net/wordmove-ng/wiki/Hooks).
-Where a wiki page still describes wordmove 5.x behaviour, this README wins.
+The documentation site has the full reference:
+[Configuration](https://tekgnosis-net.github.io/wordmove-ng/configuration/),
+[Usage and flags](https://tekgnosis-net.github.io/wordmove-ng/usage/),
+[Database sync](https://tekgnosis-net.github.io/wordmove-ng/database-sync/),
+[Hooks](https://tekgnosis-net.github.io/wordmove-ng/hooks/),
+[Multiple environments](https://tekgnosis-net.github.io/wordmove-ng/environments/),
+[Troubleshooting](https://tekgnosis-net.github.io/wordmove-ng/troubleshooting/).
 
 ## Logging
 
@@ -315,7 +320,9 @@ stored anywhere.
    the GitHub release.
 
 Pushing a `v*` tag by hand at the head of `master` triggers the same publish job; that is
-how 6.0.0 is cut.
+how 6.0.0 was cut. Merge the release PR only when there is something worth shipping:
+release-please keeps proposing a patch release for any Conventional Commit, including
+`ci:` and `docs:` ones.
 
 One-time setup for a new maintainer or a fork:
 

data/docs/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.4"
+gem "just-the-docs", "~> 0.12"

data/docs/README.md

@@ -0,0 +1,10 @@
+Documentation site, published to https://tekgnosis-net.github.io/wordmove-ng/ by
+`.github/workflows/pages.yml` on every push to `master`.
+
+Preview locally:
+
+```bash
+cd docs
+bundle install
+bundle exec jekyll serve   # http://127.0.0.1:4000/wordmove-ng/
+```

data/docs/_config.yml

@@ -0,0 +1,47 @@
+title: wordmove-ng
+description: Move WordPress sites between environments over SSH, database included.
+url: https://tekgnosis-net.github.io
+baseurl: /wordmove-ng
+repository: tekgnosis-net/wordmove-ng
+
+theme: just-the-docs
+permalink: pretty
+color_scheme: light
+logo: /assets/images/wordmove-ng.png
+favicon_ico: /assets/images/wordmove-ng.png
+search_enabled: true
+heading_anchors: true
+
+aux_links:
+  GitHub: https://github.com/tekgnosis-net/wordmove-ng
+  RubyGems: https://rubygems.org/gems/wordmove-ng
+aux_links_new_tab: true
+
+nav_external_links:
+  - title: Changelog
+    url: https://github.com/tekgnosis-net/wordmove-ng/blob/master/CHANGELOG.md
+
+footer_content: 'Copyright &copy; 2013-2019 weLaika Soc. Coop. (Wordmove), 2026 tekgnosis.net (wordmove-ng). Distributed under the <a href="https://github.com/tekgnosis-net/wordmove-ng/blob/master/LICENSE">MIT license</a>.'
+
+callouts:
+  note:
+    title: Note
+    color: blue
+  warning:
+    title: Warning
+    color: yellow
+  danger:
+    title: Danger
+    color: red
+
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - vendor/
+  - README.md
+
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default

data/docs/configuration.md

@@ -0,0 +1,345 @@
+---
+title: Configuration
+nav_order: 5
+---
+
+# Configuration
+{: .no_toc }
+
+`movefile.yml` describes your local install and every remote. It is a YAML file, evaluated as an ERB template first, so it can read environment variables.
+
+1. TOC
+{:toc}
+
+## File name and location
+
+wordmove-ng looks for `movefile.yml`, `movefile.yaml`, `movefile` or `Movefile` in the current directory and then in each parent up to the one containing `wp-config.php`. `-c other.yml` selects another file inside the project.
+
+{: .note }
+Indentation defines the structure. Two spaces per level, no tabs. `wordmove-ng doctor` validates the file against a schema and tells you what is wrong.
+
+## Complete example
+
+```yaml
+global:
+  maintenance_mode: false
+
+local:
+  vhost: http://site.test
+  wordpress_path: /home/john/sites/site
+  database:
+    name: site
+    user: root
+    password: root
+    host: 127.0.0.1
+    # port: 3306
+    # socket: /path/to/mysqld.sock
+
+staging:
+  vhost: https://staging.example.com
+  wordpress_path: /var/www/staging
+  database:
+    name: staging
+    user: staging
+    password: "<%= ENV['STAGING_DB_PASS'] %>"
+    host: localhost
+  ssh:
+    host: staging.example.com
+    user: deploy
+  exclude:
+    - ".git/"
+    - ".env"
+    - "node_modules/"
+    - "wp-config.php"
+    - "wp-content/*.sql.gz"
+
+production:
+  vhost: https://example.com
+  wordpress_path: /var/www/example
+  database:
+    name: example
+    user: example
+    password: "<%= ENV['PROD_DB_PASS'] %>"
+    host: localhost
+    # mysqldump_options: --max_allowed_packet=50MB
+    # mysql_options: --protocol=TCP
+  ssh:
+    host: example.com
+    user: deploy
+    # port: 22
+    # password: only with sshpass installed; prefer keys
+    # rsync_options: --verbose
+    # gateway:
+    #   host: bastion.example.com
+    #   user: jump
+  exclude:
+    - ".git/"
+    - ".env"
+    - "node_modules/"
+    - "wp-config.php"
+    - "wp-content/*.sql.gz"
+  forbid:
+    push:
+      db: true            # never push the database to production
+  hooks:
+    push:
+      after:
+        - command: wp cache flush
+          where: remote
+          raise: false
+```
+
+## First level keys
+
+`local` is mandatory and must keep that name. `global` is optional. Every other first level key is a remote environment, selected with `-e`. See [Multiple environments]({{ site.baseurl }}/environments/).
+
+## `global`
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `maintenance_mode` | `false` | Wrap the target's database import and adaptation in `wp maintenance-mode activate`/`deactivate`. `WORDMOVE_MAINTENANCE_MODE=1` in the environment forces it on for one run. |
+| `collation_fallbacks` | built-in table | Collations rewritten before import, e.g. `utf8mb3_uca1400_ai_ci: utf8mb4_unicode_ci`. Setting the key replaces the default table. |
+| `charset_fallbacks` | `utf8mb3: utf8mb4` | Charsets rewritten before import. |
+| `sql_adapter` | ignored | Accepted with a warning for 5.x movefiles. |
+
+## `local` and each remote
+
+### `vhost`
+{: .no_toc }
+
+> mandatory
+
+The URL you use to reach the site, including any subdirectory WordPress is installed in. It should match `wp option get home`. Omit the trailing slash. `init` pre-fills it from `wp-config.php` or `wp option get home`.
+
+### `wordpress_path`
+{: .no_toc }
+
+> mandatory
+
+The absolute path of the installation. Spaces and other shell characters are handled; no manual escaping. On a remote it is the path **on that host**.
+
+{: .warning }
+Avoid values where one environment's `vhost` or `wordpress_path` is a prefix of another's (`https://site.test` and `https://site.test.example.com`): the search-replace of the shorter value would also rewrite the longer one. The doctor reports this.
+
+### `database`
+{: .no_toc }
+
+> mandatory keys: `name`, `user`, `password`, `host`
+
+| Key | Meaning |
+| --- | --- |
+| `name`, `user`, `password`, `host` | as in `wp-config.php`. For a remote, as seen **from the remote host**: wordmove-ng connects over SSH first and runs `mysqldump`/`mysql`/`wp` there. |
+| `port` | optional; `init` splits `DB_HOST` values like `localhost:3307`. |
+| `socket` | optional unix socket; `init` splits `DB_HOST` values like `localhost:/path/mysqld.sock`. |
+| `mysqldump_options` | passed verbatim to `mysqldump`/`mariadb-dump`, e.g. `--max_allowed_packet=50MB --ignore-table=db.wp_bigtable`. |
+| `mysql_options` | passed verbatim to `mysql`/`mariadb` on import, e.g. `--protocol=TCP`. |
+
+`mariadb`/`mariadb-dump` are preferred when installed, falling back to `mysql`/`mysqldump`. Imports run with `--binary-mode` (unless `mysql_options` already sets it), `SET FOREIGN_KEY_CHECKS=0` and a trailing `COMMIT;`; a MariaDB sandbox header is stripped.
+
+### `paths`
+{: .no_toc }
+
+> optional
+
+Customise WordPress internal paths when they are not the defaults, relative to `wordpress_path`. Configure it on every environment whose layout differs.
+
+```yaml
+paths:
+  wp_content: app
+  wp_config: config/wp-config.php
+  uploads: app/uploads
+  plugins: app/plugins
+  mu_plugins: app/mu-plugins
+  themes: app/themes
+  languages: app/languages
+```
+
+## Remote-only keys
+
+### `ssh`
+{: .no_toc }
+
+> mandatory key: `host`
+
+```yaml
+ssh:
+  host: host
+  user: user
+  port: 22                    # optional
+  password: secret            # optional; needs sshpass, prefer keys
+  rsync_options: "--verbose"  # optional, appended to rsync
+  gateway:                    # optional jump host, becomes `ssh -J`
+    host: bastion
+    user: jump
+    port: 22
+```
+
+Every operation uses the **system `ssh` client**: rsync for directories, `ssh` for remote commands and hooks, `scp` for dump files. Whatever works for `ssh` on your command line works here: ssh-agent, `~/.ssh/config`, `ProxyJump`, hardware keys, modern key types. Only `host` is mandatory because the rest can live in `~/.ssh/config`:
+
+```
+Host client_x_staging
+  Hostname 79.99.8.94
+  User welaika
+  Port 1337
+  ProxyJump bastion
+```
+
+```yaml
+staging:
+  ssh:
+    host: client_x_staging
+```
+
+- Without `password`, connections run with `BatchMode=yes`: a failing key authentication is an error naming the failed command, never a prompt.
+- `password` is passed through `sshpass -p` to `ssh`, `scp` and `rsync`. It requires `sshpass` locally and exposes the password in the process list.
+- `rsync_options` are appended to the defaults `-rlpt --compress --omit-dir-times --delete`. See [rsync options for CI]({{ site.baseurl }}/usage/#rsync-options-in-a-continuous-delivery-context).
+- `gateway` becomes `ssh -J [user@]host[:port]`. A `gateway.password` cannot be honoured and is ignored; the doctor warns.
+- Remote commands always run through `sh -c`, so the remote login shell can be bash, zsh, fish or csh. Programs only need to be in the `$PATH` of a non interactive login.
+
+### `exclude`
+{: .no_toc }
+
+> optional
+
+Patterns ignored during `push` and `pull`, which also means matching files are **not deleted** on the destination when missing at the source. Each entry becomes an rsync `--exclude`, relative to `wordpress_path`, so all rsync pattern syntax applies; see [working on specific plugins]({{ site.baseurl }}/usage/#work-only-on-specific-plugins-or-themes).
+
+```yaml
+exclude:
+  - ".git/"
+  - ".gitignore"
+  - ".env"
+  - "node_modules/"
+  - "tmp/*"
+  - "movefile.yml"
+  - "wp-config.php"
+  - "wp-content/*.sql.gz"
+```
+
+### `hooks`
+{: .no_toc }
+
+> optional
+
+Commands run before or after a push or pull, locally or on the remote. See [Hooks]({{ site.baseurl }}/hooks/).
+
+### `forbid`
+{: .no_toc }
+
+> optional
+
+Blocks actions by configuration; forbidden tasks ignore command line flags and are skipped with a warning. Values must be booleans.
+
+```yaml
+forbid:
+  push:
+    db: true
+    uploads: false
+    plugins: false
+    themes: false
+    languages: false
+    mu_plugins: false
+  pull:
+    db: false
+```
+
+### Removed: `ftp`
+{: .no_toc }
+
+FTP, FTPS and SFTP transports were removed in 6.0. A remote with an `ftp` block fails validation with a clear message. See [Upgrading]({{ site.baseurl }}/upgrading/#4-ftp-and-sftp-are-gone).
+
+## Environment variables and `.env`
+
+Because the movefile is an ERB template, secrets can come from the environment:
+
+```yaml
+production:
+  database:
+    user: "<%= ENV['PROD_DB_USER'] %>"
+    password: "<%= ENV['PROD_DB_PASS'] %>"
+```
+
+Set them in the shell (`export PROD_DB_PASS="…"`) or in a `.env` file next to the movefile:
+
+```bash
+PROD_DB_USER="username"
+PROD_DB_PASS="password"
+```
+
+`.env.<environment>` (for example `.env.production`) is loaded when that environment is selected with `-e`. Add `.env*` to `exclude` and to `.gitignore`.
+
+System variables work too: `wordpress_path: "<%= ENV['HOME'] %>/sites/example"`.
+
+## YAML and ERB tips
+
+### Anchors to avoid repetition
+{: .no_toc }
+
+```yaml
+global:
+  default: &default
+    vhost: "http://example.com"
+    wordpress_path: "/var/www/site"
+    database: &db
+      host: localhost
+      user: username
+      password: password
+      name: database
+    ssh: &ssh
+      host: server
+      user: foo
+
+staging:
+  <<: *default
+  vhost: http://staging.example.com
+  database:
+    <<: *db
+    name: db_staging
+  ssh:
+    <<: *ssh
+    user: foobar
+
+production:
+  <<: *default
+  vhost: https://www.example.com
+  database:
+    <<: *db
+    name: db_production
+```
+
+The `default` anchor lives under `global` because every other first level key is treated as an environment.
+
+### Variables inside the template
+{: .no_toc }
+
+```yaml
+production:
+  <% prod_wp_path = "/home/site/public" %>
+  vhost: "https://example.com"
+  wordpress_path: <%= prod_wp_path %>
+  hooks:
+    pull:
+      after:
+        - command: 'cd <%= prod_wp_path %> && wp core version'
+          where: remote
+```
+
+### Conditional sections
+{: .no_toc }
+
+```yaml
+  hooks:
+    pull:
+      after:
+        <% if ENV.fetch('NOTIFY', nil) %>
+        - command: 'bash ./scripts/notify.sh'
+          where: local
+        <% end %>
+        - command: 'wp cache flush'
+          where: remote
+```
+
+`ENV.fetch('NOTIFY', nil)` returns the variable or `nil`; you can also compare against values (`<% if ENV.fetch('TARGET', '') == 'blue' %>`).
+
+## Schema validation
+
+`wordmove-ng doctor` validates every section against the schemas in [`lib/wordmove/assets`](https://github.com/tekgnosis-net/wordmove-ng/tree/master/lib/wordmove/assets), reports unknown or mistyped keys, rejects `ftp` blocks and flags prefix collisions between search terms.

data/docs/contributing.md

@@ -0,0 +1,53 @@
+---
+title: Contributing and releasing
+nav_order: 11
+---
+
+# Contributing and releasing
+{: .no_toc }
+
+1. TOC
+{:toc}
+
+## Reporting a bug
+
+Run `wordmove-ng doctor` first and include its output. Then open an issue with the command you ran, the relevant part of `movefile.yml` with secrets removed, the full error output, and your OS, Ruby (`ruby --version`) and wordmove-ng (`wordmove-ng --version`) versions. Only the latest release is supported; bugs in the legacy `wordmove` 5.x gem belong to its own tracker.
+
+## Development
+
+```bash
+git clone https://github.com/tekgnosis-net/wordmove-ng.git
+cd wordmove-ng
+bundle install
+bundle exec rake                                 # specs + rubocop, what CI runs
+bundle exec rspec spec/deployer/ssh_db_spec.rb   # one file
+bin/wordmove-ng --help                           # run from the checkout, from any directory
+```
+
+CI runs the suite and rubocop on Ruby 3.0 through 4.0. Code must run on all of them. New rubocop offences are fixed rather than added to `.rubocop_todo.yml`, which only grandfathers the pre-6.0 backlog.
+
+Repository layout, request flow and conventions are described in [`CLAUDE.md`](https://github.com/tekgnosis-net/wordmove-ng/blob/master/CLAUDE.md).
+
+## Commit messages
+
+Write [Conventional Commits](https://www.conventionalcommits.org): `fix: …` (patch), `feat: …` (minor), `feat!: …` or a `BREAKING CHANGE:` footer (major), and `docs:`, `chore:`, `ci:`, `test:`, `refactor:` for everything that does not ship a change. The version number and `CHANGELOG.md` are generated from them; never edit `lib/wordmove/version.rb` or the changelog by hand.
+
+## Releasing
+
+Releases are automated by [release-please](https://github.com/googleapis/release-please) and published to [rubygems.org](https://rubygems.org/gems/wordmove-ng) with [trusted publishing](https://guides.rubygems.org/trusted-publishing/), so no API key is stored anywhere.
+
+1. Every push to `master` updates a "release PR" that bumps the version and the changelog from the commits since the last release. release-please proposes a patch release for any Conventional Commit, `ci:` and `docs:` included, so merge the PR only when there is something worth shipping.
+2. Merging it creates the `vX.Y.Z` tag and the GitHub release.
+3. The `publish` job in `.github/workflows/release.yml` re-runs the suite on the tagged commit, builds the gem, pushes it to rubygems.org and attaches the `.gem` file to the GitHub release.
+
+Pushing a `v*` tag by hand at the head of `master` triggers the same publish job.
+
+## This documentation
+
+The site is built from the `docs/` folder on `master` with Jekyll and the just-the-docs theme by `.github/workflows/pages.yml`. Preview locally with
+
+```bash
+cd docs && bundle install && bundle exec jekyll serve
+```
+
+Please keep it, and the README, updated when changing user-facing behaviour.