pg.ddx.io GitHub: postgresql-interfaces/psqlodbc (issues + PRs as email threads)
help / color / mirror / Atom feed[postgresql-interfaces/psqlodbc] PR #236: Document how to release the website
3+ messages / 1 participants
[nested] [flat]
* [postgresql-interfaces/psqlodbc] PR #236: Document how to release the website
@ 2026-11-04 18:31 "davecramer (@davecramer)" <noreply+davecramer@github.com>
0 siblings, 0 replies; 3+ messages in thread
From: davecramer (@davecramer) @ 2026-11-04 18:31 UTC (permalink / raw)
To: postgresql-interfaces/psqlodbc <noreply+postgresql-interfaces-psqlodbc@github.com>
Adds `website/RELEASING.md`, which explains how to publish https://odbc.postgresql.org/. Merging to `main` doesn't publish the site.
It covers:
- The release steps: merge to `main`, point `www-release` at the commit, run the `Deploy Website` workflow, then check `deploy-info.json` on the live site.
- When to release: after website changes, and after each driver release, because the changelog page is built from `Changelog.md`.
- What a deploy does, step by step.
- How to roll back.
- Who owns the infrastructure, and what to send PostgreSQL infrastructure if the deploy fails with `Not authorized to perform sts:AssumeRoleWithWebIdentity`.
The steps used to be in the comment at the top of `docs-deploy.yml`. That comment now points to the new file and keeps only the list of repository variables, so the process is described in one place. `website/README.md` links to the new file too.
actionlint passes on `docs-deploy.yml`.
Assisted-By: Claude
inline patch 1: .github/workflows/docs-deploy.yml, website/README.md, website/RELEASING.md (+67/-13 lines) download inline-1.patch
diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml
index 0b397134..0165b419 100644
--- a/.github/workflows/docs-deploy.yml
+++ b/.github/workflows/docs-deploy.yml
@@ -1,18 +1,8 @@
name: Deploy Website
-# Builds the website with docs.yml and deploys it to https://odbc.postgresql.org/.
-# The deploy runs only from the www-release branch. After a release, update
-# www-release to the commit to deploy and start the deploy on it:
-#
-# gh workflow run docs-deploy.yml -R postgresql-interfaces/psqlodbc --ref www-release
-#
-# The deploy uploads the site to the root of the S3 bucket, then deletes the
-# files in the bucket that are no longer in the site, then uploads
-# /deploy-info.json with metadata about the deployment, and then invalidates
-# the CloudFront cache. Each deploy replaces the previous one and no earlier
-# version is kept. To roll back, set www-release back to an earlier commit and
-# start the deploy again. A run on any other branch fails with an error before
-# it builds the site.
+# Builds the website with docs.yml and deploys it to https://odbc.postgresql.org/,
+# only from the www-release branch. website/RELEASING.md describes how to
+# release, roll back, and what each step below does.
#
# The workflow reads these repository variables:
#
diff --git a/website/README.md b/website/README.md
index 277d65e3..f8510e5a 100644
--- a/website/README.md
+++ b/website/README.md
@@ -19,3 +19,7 @@ hugo --minify # builds the site into public/
- The images and `.reg` files come from `docs/`, which the Windows installer and the source tarball also ship.
Pages that moved keep their old addresses through `aliases` in their front matter, so a link such as `/docs/config.html` redirects to `/docs/configuration/`.
+
+## Releasing
+
+Merging to `main` does not publish the site. [RELEASING.md](RELEASING.md) describes how to release it to https://odbc.postgresql.org/.
diff --git a/website/RELEASING.md b/website/RELEASING.md
new file mode 100644
index 00000000..c958974d
--- /dev/null
+++ b/website/RELEASING.md
@@ -0,0 +1,60 @@
+# Releasing the website
+
+https://odbc.postgresql.org/ is served by CloudFront from an S3 bucket. The `Deploy Website` workflow (`.github/workflows/docs-deploy.yml`) builds the site in `website/` and uploads it. It deploys only from the `www-release` branch, so a change merged to `main` is not published until someone releases it.
+
+Release the website after merging changes under `website/`, and after each driver release, because the changelog page is built from `Changelog.md`.
+
+## Steps
+
+1. **Merge the changes to `main`.** On a pull request, the `docs` workflow builds the site and lints the two workflows. It runs when the pull request changes `website/`, `Changelog.md` or `docs/`.
+
+2. **Point `www-release` at the commit to publish,** normally the tip of `main`:
+
+ ```sh
+ git fetch origin
+ git push origin origin/main:refs/heads/www-release
+ ```
+
+ The push fails if `www-release` has commits that `main` doesn't. That only happens after a rollback, described below; use `--force` then.
+
+3. **Start the deploy and wait for it:**
+
+ ```sh
+ gh workflow run docs-deploy.yml -R postgresql-interfaces/psqlodbc --ref www-release
+ gh run watch -R postgresql-interfaces/psqlodbc \
+ "$(gh run list -R postgresql-interfaces/psqlodbc --workflow docs-deploy.yml --branch www-release --limit 1 --json databaseId --jq '.[0].databaseId')"
+ ```
+
+4. **Check the live site.** https://odbc.postgresql.org/deploy-info.json shows the commit, the driver version from `configure.ac`, the time and the run ID of the deploy that is live:
+
+ ```sh
+ curl -s https://odbc.postgresql.org/deploy-info.json
+ ```
+
+ CloudFront's cache is cleared at the end of each deploy, so the new pages show straight away.
+
+## What a deploy does
+
+1. Checks that the run is on `www-release`. A run on any other branch fails before it builds anything.
+2. Builds the site with the Hugo version that `.github/workflows/docs.yml` pins.
+3. Uploads the site to the root of the bucket.
+4. Deletes the files in the bucket that are no longer in the site, after the upload, so that a page that moved stays available while the new files upload.
+5. Uploads `/deploy-info.json`.
+6. Invalidates the CloudFront cache.
+
+Each deploy replaces the previous one, and the bucket keeps no earlier version.
+
+## Rolling back
+
+Point `www-release` at an earlier commit and deploy again:
+
+```sh
+git push --force origin <commit>:refs/heads/www-release
+gh workflow run docs-deploy.yml -R postgresql-interfaces/psqlodbc --ref www-release
+```
+
+## Infrastructure
+
+PostgreSQL infrastructure owns the AWS account that hosts the site, and the `postgresql.org` DNS. The workflow signs in to AWS through GitHub OIDC, with no stored keys. It reads the role, region, bucket and distribution from repository variables, listed at the top of `.github/workflows/docs-deploy.yml`.
+
+If the deploy fails at "Configure AWS credentials" with `Not authorized to perform sts:AssumeRoleWithWebIdentity`, the role's trust policy does not accept the token. The token's subject is `repo:postgresql-interfaces/psqlodbc:ref:refs/heads/www-release` and its audience is `sts.amazonaws.com`. Ask PostgreSQL infrastructure to check the trust policy.
^ permalink raw [nested|flat] 3+ messages in thread
* Re: [postgresql-interfaces/psqlodbc] PR #236: Document how to release the website
@ 2026-11-04 18:40 "davecramer (@davecramer)" <noreply+davecramer@github.com>
1 sibling, 0 replies; 3+ messages in thread
From: davecramer (@davecramer) @ 2026-11-04 18:40 UTC (permalink / raw)
To: postgresql-interfaces/psqlodbc <noreply+postgresql-interfaces-psqlodbc@github.com>
@davecramer closed this.
^ permalink raw [nested|flat] 3+ messages in thread
* Re: [postgresql-interfaces/psqlodbc] PR #236: Document how to release the website
@ 2026-11-04 18:40 "davecramer (@davecramer)" <noreply+davecramer@github.com>
1 sibling, 0 replies; 3+ messages in thread
From: davecramer (@davecramer) @ 2026-11-04 18:40 UTC (permalink / raw)
To: postgresql-interfaces/psqlodbc <noreply+postgresql-interfaces-psqlodbc@github.com>
@davecramer merged this (commit e2227027ce36).
^ permalink raw [nested|flat] 3+ messages in thread
end of thread, other threads:[~2026-11-04 18:40 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-11-04 18:31 [postgresql-interfaces/psqlodbc] PR #236: Document how to release the website "davecramer (@davecramer)" <noreply+davecramer@github.com>
2026-11-04 18:40 ` "davecramer (@davecramer)" <noreply+davecramer@github.com>
2026-11-04 18:40 ` "davecramer (@davecramer)" <noreply+davecramer@github.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox