Skip to content

Template updates

This established server first adopted development tooling from justpen-mcp-dev-template at d9848a0927c238fd1b11189930a292ff60efef16. Its current development baseline is v0.6.0, commit 0629c93504af314acbf522209a130973444d06d3.

Reviewed adoption and history

The v0.4.0 adoption renders a separate reference with the real project identity, then applies reviewed development changes to the existing application. The Copier record comes from that reference; it does not claim that this server was originally created by Copier. No first-run bootstrap or recopy runs over the application.

Keep .copier-answers.yml committed and let Copier maintain its source, revision and answers. The recorded initial_version = 0.0.0 describes the generated comparison baseline, not this application's version. Run make version to read the server version; template updates preserve the application version.

The explicit changelog_start_rev at standalone commit 3f302105a980ac7a7ae00935907aadc87a2cfcf6 remains authoritative after enrollment. Preserve the real Git history and historical tags; do not use the first Copier record as a replacement application-history boundary.

Update on a feature branch

Begin with a clean, committed checkout. Fetch an exact upstream commit without importing template release tags into the application's tag namespace:

git switch -c chore/update-template
git fetch --no-tags https://github.com/justpenkit/justpen-mcp-dev-template.git main:refs/remotes/template/main
template_commit=$(git rev-parse refs/remotes/template/main)
uvx --from 'copier>=9.18.2,<10' copier update --vcs-ref="$template_commit" --defaults
git diff

Codex uses codex/update-template. The update uses the source URL in the genuine Copier record and the exact fetched commit. Use a full clone, fetch before each update, and never merge the template branch or copy its release tags into this application.

--defaults reuses the recorded answers. Keep the reference's initial-version answer so Copier can compare generated baselines while preserving application version changes. Omit --defaults to review answers; use --vcs-ref=:current: when changing answers without upgrading the template. Always select a revision.

Review application customizations

Copier compares the old reference, new reference and application changes. Changes to the same lines can conflict. Inspect every diff and all Git conflict entries; resolve them while preserving:

  • The justpen_integration_mcp runtime, Gmail tool registration, Google configuration and status: "ok" / status: "error" response contract.
  • python -m justpen_integration_mcp; no template demo CLI or py.typed claim.
  • Application dependencies, proprietary licensing, current version and the explicit standalone changelog boundary. Do not copy generic package metadata or an MIT application license from the reference.
  • Product docs, API module directives, navigation, assets and local docs ownership.
  • The application make build target and mocked Google API behavior in tests.
  • Shared permissions, strict lint/type/coverage rules and the unit/integration split.

Use make uv-lock for required dependency resolution, then make setup to refresh changed tooling and installed hooks. Use make test-one TEST=... for the relevant scenario while developing an integration test or its harness. Commit/push hooks provide routine unit and strict-docs gates; do not repeat a passing gate manually. CI checks the supported Python versions and real tool, hook, release and docs integrations without Google credentials.

Review the final diff through a PR and use a regular merge commit. A template update does not itself bump this application's version. Do not use copier recopy as a shortcut, run bootstrap, or import generator tests and setup/cleanup machinery.

Protected metadata

Before an agent applies direct pyproject.toml or uv.lock changes through Copier, preview the same exact revision and answers in a disposable checkout. Present the concrete diff and obtain its required approval before applying it to the working project. Ordinary dependency resolution uses the make uv-* targets.

The guard reverts a copier update run by an agent that changes protected files, because copier is not an approved route. Run copier update from a terminal after approving the preview, or approve the result with make guard-accept-changes. See the agent guide for the guard and its limits. Follow the policy even when an indirect tool can write the file.

CI job names

Template updates can rename CI jobs. One check job replaced the quality job and the check (py3.x) matrix legs. If your repository requires status checks by name, update those rules to check (and integration) after merging the update, or pull requests will wait for checks that no longer run.

See Copier's update documentation for the merge model and recovery options.