applying-template-updates

Applying template updates

docs/deployment/template-updates.md explains the update; this skill is the procedure. Work on the copier/update branch the workflow opened (or the branch where copier update --trust was run). Stop and ask, rather than guess, at three points: a conflict hunk inside a sentinel block, an upgrade note you cannot perform (a secret, a repository setting), and a seeded-file change you are not certain applies to this project. Report at the end: what you applied, what you skipped and why, and what is left for a human.

1. Read the pull request body

Extract from it: the previous and target template refs, the compare link, the UPGRADING.md sections for the jump, and the list of files with conflict markers. If the body has no upgrade notes, fetch UPGRADING.md at the target ref from the template repository — it is an index whose released ## vX.Y sections point at per-minor upgrading/vX.Y.md files — and fetch every per-minor file from the previous ref's minor through the target's, reading each one whole. Never grep or tail your way through them: each file is complete for its minor, and the index enumerates which files a jump needs.

2. Apply every upgrade note

Each section is an instruction to a person. Perform it on the branch: renames, rewritten seeded tests, .gitignore lines, uv lock. A note you cannot perform (a secret to add, a repository setting to change) is a stop point: list it for the human. Do not skip a note because the project looks unaffected; check, then say so in the report.

3. Resolve conflict markers

Find them with git grep -n '^<<<<<<< before updating$'. A hunk has four marker lines: <<<<<<< before updating (local side), ||||||| last update (common base), =======, >>>>>>> after updating (template side). Resolving means keeping one side and deleting all four markers and the base block. For each hunk:

• outside a DOMAIN-* / CONFIG-* / PROJECT-* sentinel block, keep the template side and move any local content it displaces into the nearest sentinel block, or note it as a change to propose to the template;
• inside a sentinel block, stop and ask: the local side is the project's, and a template change in the same place means the sentinel moved.