feat(updating)!: apply pre-update migrations on fresh project from current template version

BREAKING CHANGE: Pre-update migrations are now run on the fresh project
generated from the current template version. In most cases, this should
only improve update quality by reducing merge conflicts, but it is
possible that this change will break template updates in rare cases.
Thus, this change is marked as breaking out of an abundance of caution.

Author: sisp

copier/_main.py

@@ -368,11 +368,15 @@ def _answers_to_remember(self) -> Mapping[str, Any]:
         )
         return answers
 
-    def _execute_tasks(self, tasks: Sequence[Task]) -> None:
+    def _execute_tasks(
+        self, tasks: Sequence[Task], *, directory: Path | None = None
+    ) -> None:
         """Run the given tasks.
 
         Arguments:
             tasks: The list of tasks to run.
+            directory: The working directory to run the tasks in. Defaults to the
+                subproject's path.
         """
         operation = _operation.get()
         for i, task in enumerate(tasks):
@@ -404,7 +408,7 @@ def _execute_tasks(self, tasks: Sequence[Task]) -> None:
             working_directory = (
                 # We can't use _render_path here, as that function has special handling
                 # for files in the template
-                self.subproject.local_abspath
+                (directory or self.subproject.local_abspath)
                 / Path(self._render_string(str(task.working_directory), extra_context))
             ).absolute()
 
@@ -1410,11 +1414,13 @@ def _apply_update(self) -> None:  # noqa: C901
             ) as old_worker:
                 old_worker.run_copy()
 
-            # Run pre-migration tasks.
             with Phase.use(Phase.MIGRATE):
-                self._execute_tasks(
-                    self.template.migration_tasks("before", self.subproject.template)  # type: ignore[arg-type]
+                pre_migration_tasks = self.template.migration_tasks(
+                    "before",
+                    self.subproject.template,  # type: ignore[arg-type]
                 )
+                # Run pre-migration tasks on the current project.
+                self._execute_tasks(pre_migration_tasks)
 
             # Clear last answers cache to load possible answers migration if the
             # `skip_answered` flag is not set.
@@ -1488,6 +1494,10 @@ def _apply_update(self) -> None:  # noqa: C901
                     if self.match_skip(path) and path in old_copy_files:
                         path.unlink()
 
+                # Run pre-migration tasks on old copy.
+                self._execute_tasks(
+                    pre_migration_tasks, directory=old_copy / subproject_subdir
+                )
                 # Stage all files including Git-ignored ones.
                 git("add", "-f", ".")
                 # Make a commit to run Git hooks if applicable.

docs/updating.md

@@ -133,7 +133,7 @@ project_updated("updated project")
 project_full("fully updated<br>and migrated project")
 
 update["3-way merge"]
-regen_current["generate and run tasks"]
+regen_current["generate and run tasks<br>& apply pre-migrations"]
 regen_latest["generate and run tasks"]
 
 %% edges ----------------------------------------------------------
@@ -161,7 +161,8 @@ class regen_current,regen_latest,update blackborder;
 As you can see here, `copier` does several things:
 
 - Regenerate the project fresh from the **current** template version, using the
-    project's existing answers – this becomes the merge-base.
+    project's existing answers (with pre-migrations applied afterwards) – this becomes
+    the merge-base.
 - Regenerate the project fresh from the **latest** template version, using the same
     answers (with pre-migrations applied to the project beforehand).
 - Build a synthetic Git commit graph from these three states: the current-version

tests/test_migrations.py

@@ -4,6 +4,7 @@
 from typing import Any
 
 import pytest
+from inline_snapshot import snapshot
 from plumbum import local
 
 from copier import run_copy, run_update
@@ -513,6 +514,84 @@ def test_migration_env_variables(
         assert (f"{variable}={value}" in env) == with_version
 
 
+def test_pre_migration_runs_on_old_copy(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    src, dst = map(tmp_path_factory.mktemp, ("src", "dst"))
+
+    build_file_tree(
+        {
+            src / "copier.yml": "_subdirectory: template/",
+            src / "template" / "{{ _copier_conf.answers_file }}.jinja": (
+                "{{ _copier_answers|to_yaml }}"
+            ),
+            src / "template" / "pyproject.toml.jinja": (
+                """\
+                [tool.poetry.group.dev.dependencies]
+                pytest = "*"
+                """
+            ),
+        }
+    )
+    git_save(src, tag="v1")
+
+    build_file_tree(
+        {
+            src / "copier.yml": (
+                """\
+                _subdirectory: template/
+
+                _migrations:
+                -   version: v2
+                    when: "{{ _stage == 'before' }}"
+                    command: "{{ _copier_python }} {{ _copier_conf.src_path / 'migrate_pep735.py' }}"
+                """
+            ),
+            src / "template" / "pyproject.toml.jinja": (
+                """\
+                [dependency-groups]
+                dev = ["pytest"]
+                """
+            ),
+            src / "migrate_pep735.py": (
+                """\
+                from pathlib import Path
+                import tomlkit
+
+                pyproject = Path("pyproject.toml")
+                doc = tomlkit.parse(pyproject.read_bytes())
+                print(pyproject.read_bytes())
+
+                deps = sorted(doc["tool"]["poetry"]["group"]["dev"]["dependencies"])
+                del doc["tool"]["poetry"]["group"]["dev"]
+
+                dep_groups = tomlkit.table()
+                dep_groups.add("dev", deps)
+                doc.add("dependency-groups", dep_groups)
+
+                pyproject.write_text(tomlkit.dumps(doc).lstrip())
+                """
+            ),
+        }
+    )
+    git_save(src, tag="v2")
+
+    run_copy(str(src), dst, vcs_ref="v1")
+
+    git_save(dst, "init")
+    pyproject = dst / "pyproject.toml"
+    pyproject.write_text(pyproject.read_text() + 'mypy = "*"\n')
+    git_save(dst, "add mypy in poetry group")
+
+    run_update(dst, overwrite=True, unsafe=True)
+    assert pyproject.read_text() == snapshot(
+        """\
+[dependency-groups]
+dev = ["mypy", "pytest"]
+"""
+    )
+
+
 @pytest.mark.parametrize("with_version", [True, False])
 def test_migration_jinja_variables(
     tmp_path_factory: pytest.TempPathFactory, with_version: bool