Maintaining the docs and examples

Documentation and executable examples target the 2.0 SQL mget API.

Checks before merging

Pull-request CI follows the changed files. Extension changes run source tests, sanitizers, Docker integration and PostgreSQL compilation. Documentation changes run the Pages checks; executable-example changes also run PostgreSQL 14–18 smoke tests. Package inputs retain their separate archive validation. Manual workflow dispatch remains available. The examples matrix is not repeated on a push to master; direct pushes that bypass PR checks need a manual examples run.

The examples execute shell blocks from QUICKSTART.md and SQL/configuration from INSTALL_EXISTING.md on fresh databases, including a non-default port. The default workload benchmark, common SQL/RESP launcher smoke and Node unit tests run once, on PostgreSQL 16; other versions run the functional examples. Throughput is never a pass/fail threshold. Benchmark records and browser screenshots/traces are retained for 14 days as demo-benchmark-pg16 and browser artifacts.

Quick local checks:

make verify-static source-test source-sanitize
npm --prefix examples/node-postgres ci --ignore-scripts
node --test examples/node-postgres/queries.test.mjs

Run the documented database examples locally (Docker and Node.js 20+):

docker compose -f examples/compose.yaml up --build --wait
python3 tests/install_docs_smoke.py
python3 tests/quickstart_docs_smoke.py
docker compose -f examples/compose.yaml down

For PostgreSQL 14, 15, 17 or 18, export PGLC_DEMO_PG before starting Compose. Use --skip-benchmark on the quickstart check when only testing functionality. Always run compose down after a failed check too; the demo data is disposable.

After building the site with GitHub Pages' Jekyll builder, check the output:

python3 scripts/check_site.py _site
python3 -m venv /tmp/pglc-browser-tests
/tmp/pglc-browser-tests/bin/pip install -r tests/browser/requirements.txt
/tmp/pglc-browser-tests/bin/python -m playwright install --with-deps chromium webkit
/tmp/pglc-browser-tests/bin/python tests/browser/site_smoke.py _site

The browser suite covers all pages with Chromium and WebKit at 1440, 390 and 320 pixels, plus a mobile case without JavaScript. It checks metadata, HTTP and console errors, overflow, navigation, table of contents, FAQ and clipboard.

Publishing

Pages builds once, validates that output, then publishes the same artifact on upstream master. Pull requests never deploy. The workflow checks the published homepage’s HTTP response; it does not repeat the browser suite. Forks can validate pull requests but do not publish a preview automatically.

Enable Settings → Pages → Source: GitHub Actions before deploying. If deployment fails after validation, rerun the failed job while its Pages artifact exists. After its 14-day retention period, rerun the workflow.

Publishing a result

Keep the extension revision separate from the benchmark harness revision. Record the environment, exact commands, all repetitions, cache counters, and client-side processing. Do not average p99 values or reuse measurements from a different API. Publish the raw results alongside any table on the site.

Search indexing

The project site is https://profundium.github.io/pg_local_cache/. Its sitemap is generated from the public pages; adding a document does not require a second URL list. Set last_modified_at only after a substantive content edit. Do not replace it with the build date.

Search Console and Bing verification tokens go in google_site_verification and bing_site_verification in _config.yml. Empty values emit no tags. Sitemap: https://profundium.github.io/pg_local_cache/sitemap.xml.

Crawlers use the host-level https://profundium.github.io/robots.txt, managed in the organization site repository.

The public site uses Google Analytics (G-MHQBYKWZ7W); browser tests stub its loader so local/CI visits are not recorded. The extension has no telemetry.