Upgrade on OINK

Upgrade to Oink 0.4.0

Mon, 01 Jan 0001 00:00:00 +0000

Oink 0.4.0 is the consolidated Scenario Components release. Reading & Release, Landing, and Book were originally designed as 0.4, 0.5, and 0.6 tracks but ship together under the single public v0.4.0 tag. Do not pin the historical design numbers.

Ordinary Docsy-compatible content, existing homepage data, and the module path remain compatible. Most work is reviewing new default shell behavior and replacing two removed ICP-specific footer parameters.

1. Pin the immutable release

Create an upgrade branch and update the Hugo Module:

Upgrade the Oink Hugo Module

Mon, 01 Jan 0001 00:00:00 +0000

Pin a version

Production sites should import a release tag or immutable commit, never an unversioned branch. From the site root, update Oink to a specific ref:

BASH

hugo mod get github.com/pgsty/oink@TARGET_VERSION
hugo mod tidy

Replace TARGET_VERSION with the immutable tag named by the release note, for example v0.4.1. Do not use an unqualified module path or @latest as a production upgrade policy.

Migrate an existing Docsy site

Mon, 01 Jan 0001 00:00:00 +0000

OINK is intended to replace copied common shells, runtimes, and shortcodes without forcing a bulk rewrite of ordinary content. A safe migration removes overrides by dependency, keeps product-specific behavior in the site, and validates a temporary copy before changing production.

Migration principles

Pin the target implementation; do not migrate production to an unversioned branch.
Inventory overrides before deleting them.
Remove common theme copies, not the site’s business logic.
Preserve content URLs, front matter, and shortcode behavior where the OINK API is compatible.
Make unsafe or online exceptions explicit and temporary.
Test build output, browser behavior, and hosted behavior as separate layers.

Pin the target

Pin a published tag in go.mod or use the complete versioned archive. During pre-release evaluation, a Hugo Module site can use an ignored Go workspace to resolve a local checkout without editing the committed module version:

Upgrade and migrate

Mon, 01 Jan 0001 00:00:00 +0000

In this chapter

Upgrade to 0.4.0: Scenario Components migration and behavior review
Upgrade OINK: version-to-version steps and breaking changes
Migrate from Docsy: move an existing Docsy site to OINK

Principles

Production sites pin a release tag rather than following main.
Read the target version’s breaking changes before upgrading.
Upgrade on a branch, verify fully, then merge.
A green local build is not permission to publish: preview deployment and hosted smoke tests are separate gates.