Skip to main content

Updating Spec-Up-T (custom-update)

Introduction​

Use this page when the repo already runs Spec-Up-T and you want a newer spec-up-t package (scripts, boilerplate files, recommended dependencies). That includes normal version upgrades such as 1.x → 2.1.0.

If the repo still runs classic Spec-Up and has not been converted yet, use Migrating from Spec-Up instead. Migration is a one-time conversion with spec-up-migrate; this page is for upgrades after that.

New projects are a separate path. npx create-spec-up-t installs whatever spec-up-t version the starter pack pins. See Starter Pack Architecture.

Steps

From 1.x:

npx spec-up-t@latest custom-update

After 2.1.0:

npm run custom-update

The command prints a plan and asks before it writes. --yes applies the plan without asking. --dry-run prints the plan only.

Commit the changes.

From 1.x, or from the old node -e script, to 2.1.0​

You do not have to install 2.0.0 first.

The GitHubUi “Custom Update” button does not jump 1.x → 2.1.0. npm update will not cross a major.

As of 2.1.0, this script no longer runs the update:

node -e "require('spec-up-t/src/install-from-boilerplate/custom-update.js')"

It exits with an error and prints the repair command. In the root of your spec repo, run:

npx spec-up-t@latest custom-update

@latest matters. Unqualified npx spec-up-t uses the local install, which is the old code.

That one command is the path from 1.x to 2.1.0, including repos that skipped 2.0.0. Commit the rewritten package.json and any other files the update changed.

This two-step sequence worked on 2.0.0 and does not work on 2.1.0 while package.json still has the node -e script:

npm install spec-up-t@2.1.0
npm run custom-update

The second command fails and does not rewrite package.json. Use npx spec-up-t@latest custom-update instead.

After a successful 2.1.0 update​

npm run custom-update

The script is then:

spec-up-t custom-update

That uses the local install, so later updates stay on the version you installed. GitHubUi and the Actions “Custom update” option still run npm run custom-update.

Repos that already completed the 2.0.0 update have:

node ./node_modules/spec-up-t/src/install-from-boilerplate/custom-update.js

That path still runs the update. The next successful run rewrites it to spec-up-t custom-update.

Escape hatch​

Always the package from npm, not the local install:

npx spec-up-t@latest custom-update

Upgrading to 2.2.0​

From 2.2.0, custom-update prints a plan and does not write unless you confirm on a terminal or pass --yes. GitHub Actions has no prompt.

The GitHubUi Custom Update button runs whatever menu.yml is already in the repo. Until the custom-update case is:

npm run custom-update -- --yes

the button prints the plan and the job fails. Nothing is written.

Do one of these once, then commit:

npx spec-up-t@latest custom-update --yes

or edit .github/workflows/menu.yml so that case is the line above.

From 2.4.0, --yes does not replace a menu.yml that differs from the boilerplate. To pick up the line above in an older menu, run this locally and commit:

npx spec-up-t@latest custom-update --yes --force-workflows

After that commit, the button applies the plan. It still does not pass --force-workflows.

Preview and apply​

custom-update prints a plan before it writes. The plan lists script changes, file changes, dependency changes, .gitignore patterns to add, npm install, and per-spec snapshot copies or tracked build-dir renames.

On your machine it then asks Apply this plan? [y/N].

npx spec-up-t@latest custom-update --dry-run
npx spec-up-t@latest custom-update --yes
npm run custom-update -- --yes

--dry-run prints the plan and leaves the repo as it is. --yes applies the plan without asking. The boilerplate menu.yml passes --yes. See Upgrading to 2.2.0 when the button still runs the old line.

Workflow files​

These boilerplate workflows are copied when the file is missing:

  • .github/workflows/menu.yml (this file keeps the custom-update choice)
  • .github/workflows/render-and-deploy.yml
  • .github/workflows/zenodo-update.yml

If one of those files already exists and differs from the boilerplate, custom-update leaves it and the plan says keep. Repo-specific edits, such as an npm ci install step or a comment about an API token, are not overwritten.

Replace them only when you mean to:

npx spec-up-t@latest custom-update --force-workflows

Run that locally and commit the workflow diff. The GitHubUi Custom Update button does not pass --force-workflows. GITHUB_TOKEN cannot push changes under .github/workflows/, so that button cannot land a workflow edit.

Known stale files are still removed, including .github/workflows/set-gh-pages.yml. Any other file under .github/workflows stays.

When to run it​

For a Trust over IP specification, the working group decides when to take a Spec-Up-T release. The command applies an update; it does not schedule one. See When to run custom-update.

What custom-update does not do​

  • It does not create a git commit. menu.yml or you commit the result.
  • It does not read dependency versions from the starter-pack repository. Those versions are shipped inside spec-up-t.
  • It does not delete extra GitHub Actions workflows. It does not overwrite the known boilerplate workflows listed above when they differ, unless you pass --force-workflows.
  • GitHubUi does not need a code change. It still dispatches menu.yml. That workflow passes --yes.