Support migrating and updating existing projects (frequenz-floss#69)

- Fix outdated documentation
- Overwrite existing files when renaming
- Fix typo in README
- Copy the replay file into the repo
- Add instructions to migrate and update existing projects

Author: llucax

README.md

@@ -13,7 +13,7 @@ If offers:
 
 [Cookiecutter]: https://cookiecutter.readthedocs.io/en/stable
 
-## Start a new projects
+## Start a new project
 
 To start a new project you should first [install
 Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/installation.html).
@@ -55,3 +55,73 @@ python3 -m venv .venv
 pip install .[dev-noxfile]
 nox
 ```
+
+## Migrating an existing project
+
+The easiest way to migrate an existing project is to just generate a new one
+basing all the inputs in the current project metadata and then overwritting the
+existing files.
+
+It is recommended to commit all changes before doing this, so you can then use
+`git` to look at the changes.
+
+If you generate the new repo in a temporary directory, you can easily overwrite
+the files in your existing project by using `rsync` or similar tools:
+
+```sh
+cd /tmp
+cookiecutter gh:frequenz-floss/frequenz-repo-config-python --directory=cookiecutter
+rsync -r new-project/ /path/to/existing/project
+cd /path/to/existing/project
+git diff
+# Fix all the `TODO`s and cleanup the generated files
+git commit -a
+```
+
+!!! warning
+
+    The trailing slash in `new-project/` and the lack of it in
+    `/path/to/existing/project` are meaningful to `rsync`.
+
+## Update an existing project
+
+To update an existing project you can use the [Cookiecutter *replay
+file*](https://cookiecutter.readthedocs.io/en/stable/advanced/replay.html) that
+was saved during the project generation.  The file is saved in
+`.cookiecutter-replay.json`.  Using this file you can re-run Cookiecutter
+without having to enter all the inputs again.
+
+!!! warning
+
+    Don't forget to commit all changes in your repository before doing this!
+    Files will be overwritten!
+
+```sh
+git commit -a  # commit all changes
+cd ..
+cookiecutter gh:frequenz-floss/frequenz-repo-config-python \
+    --directory=cookiecutter \
+    --force \
+    --replay \
+    --replay-file project-directory/.cookiecutter-replay.json
+```
+
+This will create a new commit with all the changes to the overwritten files.
+Bear in mind that all the `TODO`s will come back, so there will be quite a bit
+of cleanup to do.  You can easily check what was changed using `git show`, and
+you can use `git commit --amend` to amend the previous commit with the template
+updates, or create a new commit with the fixes.  You can also use `git citool`
+or `git gui` to easily add, remove or even discard (revert) changes in the
+templates update commit.
+
+!!! note
+
+    The `project-directory` is the directory of your previously generated
+    project. If you renamed it, then the files will be generated in a new
+    directory with the original name.  You can update the target directory in
+    the replay file.
+
+!!! note
+
+    Please remember to keep your replay file up to date if you change any
+    metadata in the project.

cookiecutter/hooks/post_gen_project.py

@@ -92,6 +92,8 @@ def finish_setup() -> None:
     """
     was_repo_initialized = initialize_git_repo()
 
+    copy_replay_file()
+
     remove_unneeded_files()
 
     match cookiecutter.type:
@@ -110,6 +112,22 @@ def finish_setup() -> None:
     commit_git_changes(first_commit=was_repo_initialized)
 
 
+def copy_replay_file() -> None:
+    """Copy the replay file to the project root."""
+    src = _pathlib.Path("~/.cookiecutter_replay/cookiecutter.json").expanduser()
+    dst = _pathlib.Path(".cookiecutter-replay.json")
+    if not src.exists():
+        print(f"WARNING: No replay file found in {src}. Skipping...")
+
+    try:
+        _shutil.copyfile(src, dst)
+    except (OSError, IOError) as error:
+        print(
+            f"WARNING: Error copying the replay file {src} -> {dst} ({error}). "
+            "Skipping..."
+        )
+
+
 def initialize_git_submodules() -> bool:
     """Initialize git submodules.
 
@@ -357,12 +375,13 @@ def finish_api_setup() -> None:
 
     * Rename `src` to `py`
     * Rename `tests` to `pytests`
-    * Create `submodules` folder
-    * Create `.gitmodules` file
-    * Initialize submodules
     """
-    _pathlib.Path("src").rename("py")
-    _pathlib.Path("tests").rename("pytests")
+    # We can't do a simple rename because the target directory might not be empty if
+    # overwriting an existing project.
+    _shutil.copytree("src", "py", dirs_exist_ok=True)
+    _shutil.rmtree("src")
+    _shutil.copytree("tests", "pytests", dirs_exist_ok=True)
+    _shutil.rmtree("tests")
 
 
 def finish_app_setup() -> None: