Release process

Oink treats implementation, validation, publication, and deployment as different states. A green local build is useful evidence, but it is not a public tag, a downloadable module, or a deployed documentation update.

Release states

Report the exact state and evidence; do not call a local build a release.

Versioning

Theme releases use root tags such as vX.Y.Z in github.com/pgsty/oink. The theme is now the repository’s root module, so nested theme/vX.Y.Z tags are no longer used.

The project site’s version parameter identifies a published site variant and is not automatically a Git ref. Installation instructions and go.mod must use the actual resolvable theme tag.

Validate the theme repository

From a clean pgsty/oink checkout:

1. inspect the source diff and attribution changes;
2. verify every VENDOR.json file and SHA-256 entry;
3. confirm the repository has no generated public/, resource cache, node_modules/, or embedded example site;
4. build a minimal consumer through the Hugo Module path with the minimum and current supported Hugo Extended versions;
5. inspect the module zip and confirm layouts, assets, translations, static files, licenses, and notices are present.

The module zip test matters because Go excludes special directory names such as vendor from published modules. Oink stores bundled dependencies under assets/third_party/ so they survive module distribution.

Validate the project site

Clone pgsty/oink and pgsty/oink.pgsty.com as siblings, then connect them with an ignored workspace:

cd oink.pgsty.com
go work init .
go work edit -replace=github.com/pgsty/oink=../oink
export HUGO_MODULE_WORKSPACE=go.work
npm install
npm test

Inspect representative English and Chinese pages, mobile navigation, both color modes, local search, print output, diagrams, API documentation, and 404 pages. This validates the candidate against the site; it does not publish either repository.

Tag and publish the theme

After review, create one immutable signed root tag in the theme repository:

git tag -s vX.Y.Z -m "Oink vX.Y.Z"
git push origin main vX.Y.Z

Pushing and creating a GitHub release require explicit authorization. After the tag is public, verify it from a clean environment:

hugo mod get github.com/pgsty/[email protected]
hugo mod graph

If an offline archive is attached to the release, publish and independently verify its SHA-256 checksum. Keep LICENSE, NOTICE, and VENDOR.json in the archive.

Update the project site

Once the theme tag resolves publicly, update the independent site repository:

hugo mod get github.com/pgsty/[email protected]
hugo mod tidy
npm test

Commit go.mod, go.sum, version parameters, changelog, and upgrade guidance together. Deploy previews first, then advance the production publishing branch only after review.

Post-release verification

After publication:

1. fetch the tag from a clean clone and inspect its signature;
2. resolve the module through the public Go proxy;
3. build a minimal new site with the documented commands;
4. open the production documentation and verify module instructions, canonical links, languages, search, and assets;
5. verify any released archive and checksum;
6. record the final tag, module version, hosted URLs, and artifact hashes.

Hotfix and rollback

A hotfix follows the same evidence chain with a smaller scope. Never move or replace a published tag. Roll back a site deployment to a known artifact, then publish a new patch version of the theme when necessary.

Definition of done

A release is complete only when the approved tag exists, the public module resolves, required checks pass, the project site pins the tag, and hosted smoke tests succeed. Anything less should be reported by its actual state.