Maintaining the docs and examples

Public documentation describes the 2.0 SQL mget contract. Keep historical benchmarks and migration narratives out of these pages.

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. Check the latest commit before merging.

The examples execute shell blocks from QUICKSTART.md and SQL/configuration from INSTALL_EXISTING.md on fresh databases, including a non-default port. The full default benchmark 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
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. Local checks cannot verify account permissions or GitHub’s deployment service.

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.

Keep each guide focused on a reader’s task: trying the extension, installing it, comparing read paths, testing transaction behavior, or calling the API. Use a descriptive title and answer the main question in the opening paragraphs. Link to the next relevant guide in context. Google’s guidance covers title links, snippets, and crawlable internal links. A Lighthouse SEO score checks basic technical signals; it does not establish index coverage, search demand, rankings, or traffic.

A property owner must verify that URL-prefix property in Google Search Console. Add the real HTML verification token to google_site_verification in _config.yml, deploy, then submit https://profundium.github.io/pg_local_cache/sitemap.xml. Inspect the home and guide URLs and review non-brand impressions and clicks. An empty token emits no tag. bing_site_verification works the same way for Bing Webmaster Tools. A PR cannot verify ownership or submit a sitemap from an unconnected account.

The project’s /pg_local_cache/robots.txt does not control the host. A crawler uses https://profundium.github.io/robots.txt; manage that in the organization site repository if needed. The absence of a robots file does not disallow crawling. See Google’s robots guidance and sitemap guidance.

Repository description and topics are settings, not files changed by merging a PR. A repository administrator can apply:

gh repo edit profundium/pg_local_cache \
  --description 'PostgreSQL extension for shared-memory primary-key row caching with explicit SQL mget and transaction-aware invalidation.' \
  --homepage https://profundium.github.io/pg_local_cache/ \
  --add-topic postgresql --add-topic postgresql-extension \
  --add-topic caching --add-topic cache-invalidation \
  --add-topic shared-memory --add-topic performance

There is no added visitor tracking or extension telemetry. Use Search Console and GitHub traffic to see discovery; use workload reports to establish actual trials. Downloads and copied commands are not confirmed installations.