Merge pull request #444 from NLeSC/416-instructions-update-existing

README: Update usage instructions

Author: sjvrijn

.github/PULL_REQUEST_TEMPLATE.md

@@ -18,7 +18,7 @@ Create a `python-template-test` repo on GitHub (will be overwritten if existing)
 ```
 # Create a temporary directory by running the following command. Keep the XXXXXX in the directory name. 
 cd $(mktemp -d --tmpdir py-tmpl-XXXXXX)
-# Use --vcs-ref <pr-branch> to point to the branch to you want to test
+# Use --vcs-ref <pr-branch> to point to the branch you want to test
 copier copy --vcs-ref <pr-branch> https://github.com/<pr-user>/python-template .
 # Fill with python-template-test info
 # Create a local git repo to push to GitHub to trigger CI actions

ADD_TO_EXISTING_PACKAGE.md

@@ -42,20 +42,38 @@ Use this [Copier](https://copier.readthedocs.io) template to generate an empty P
 
 ## How to use
 
-### Step 1/3: Install `copier`
+There are multiple scenarios to use this template:
 
+- [Scenario 1](#scenario-1-create-a-new-package): Generating a new package using template
+- [Scenario 2](#scenario-2-apply-to-pre-existing-code): Applying the template to some pre-existing code
+- [Scenario 3](#scenario-3-updating-a-template-made-package): Updating a package made with the template
+
+In all three scenarios, you will need to install Copier first, which we
+recommend doing with [`pipx`](https://github.com/pypa/pipx):
 ```shell
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
 pipx install copier
 ```
 
-### Step 2/3: Generate the files and directory structure
+> [!NOTE]
+> Note that it is also possible to install Copier with regular `pip`, but that
+> Copier will then be installed in your common environment and may cause
+> conflicts with its dependencies, while `pipx` will install Copier in a
+> separate and dedicated environment.
+
+### Scenario 1: Create a new package
+
 
-Run `copier` with the template:
+#### Step 1/2: Create the files and directory structure
+
+Run `copier copy` with the template:
 
 ```shell
 # Notes:
-#   1. See table below for explanation of each question
-#   2. The files will be generated in a new directory
+#   1. Make sure that `path/to/destination` is an empty directory
+#   2. See table below for explanation of each question
+#   3. The files will be generated in the specified destination directory
 copier copy https://github.com/nlesc/python-template.git path/to/destination
 ```
 
@@ -74,9 +92,9 @@ copier copy https://github.com/nlesc/python-template.git path/to/destination
 | code_of_conduct_email     | [email protected] | Email address of the person who should be contacted in case of violations of the Code of Conduct. |
 
 Once the project files have been generated, follow the steps outlined in
-[template/next_steps.md](template/next_steps.md).
+[next_steps.md](template/next_steps.md).
 
-### Step 3/3: Read about what was just generated
+#### Step 2/2: Read about what was just generated
 
 Good job! You have now generated the skeleton for your package:
 
@@ -135,7 +153,53 @@ Good job! You have now generated the skeleton for your package:
 ```
 
 For an explanation of what's there, read on in the [project_setup.md](template/project_setup.md) file.
-There are also instructions on how to [apply the template to an existing Python package](ADD_TO_EXISTING_PACKAGE.md).
+
+### Scenario 2: Apply to pre-existing code
+
+To apply the template to pre-existing code, you can use the same `copier copy`
+command as when creating a new package, except that you point to the folder
+containing your existing code rather than a new one:
+
+```shell
+copier copy https://github.com/nlesc/python-template.git path/to/existing/code
+```
+
+This works because if `path/to/destination` already exists, Copier will
+update what is already there by either adding new files or updating
+existing files. Copier will ask to overwrite any files that resulted in
+conflicts. Especially if your files are already under version control, it is
+recommended to answer 'yes' for all files, you will still be able to review
+the changes suggested by the template.
+
+### Scenario 3. Updating a template-made package
+
+Copier provides the functionality for re-applying the template to a previously
+created project using the `copier update` command. This has two effects:
+
+1. Your project will be updated according to the latest version of the template
+2. You can change any of your previous answers to apply these changes
+   throughout your entire project.
+
+> [!CAUTION]
+> Do not manually update answers in `.copier-answers.yml`,
+> as it will result in unexpected behavior.
+
+```shell
+cd path/to/project
+copier update
+```
+
+If you don't want to change any of your answers, but only want to update your
+project according to the latest template updates, you can provide the
+`--skip-answered` option. This tells Copier to reuse all of your previous
+answers, and simply bring in all updates from the template into
+your current project, such as updating which Python versions are supported.
+You will still be asked to answer any new questions that have been added to
+the template since you last applied it.
+
+```shell
+copier update --skip-answered
+```
 
 ## Examples