From 344ca0f9b816ef2324ab84d5a26ce8ce82615786 Mon Sep 17 00:00:00 2001 From: Sander van Rijn Date: Mon, 19 Aug 2024 14:38:10 +0200 Subject: [PATCH 01/10] fix typo --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 0145f12d..e70f32de 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.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 to point to the branch to you want to test +# Use --vcs-ref to point to the branch you want to test copier copy --vcs-ref https://github.com//python-template . # Fill with python-template-test info # Create a local git repo to push to GitHub to trigger CI actions From b805491170a31bcc6bfcf64a4872ae45eb8844b7 Mon Sep 17 00:00:00 2001 From: Sander van Rijn Date: Mon, 19 Aug 2024 17:28:29 +0200 Subject: [PATCH 02/10] remove ADD_TO_EXISTING_PACKAGE file --- ADD_TO_EXISTING_PACKAGE.md | 29 ----------------------------- 1 file changed, 29 deletions(-) delete mode 100644 ADD_TO_EXISTING_PACKAGE.md diff --git a/ADD_TO_EXISTING_PACKAGE.md b/ADD_TO_EXISTING_PACKAGE.md deleted file mode 100644 index 9edfca2b..00000000 --- a/ADD_TO_EXISTING_PACKAGE.md +++ /dev/null @@ -1,29 +0,0 @@ -# Add your existing code to directory generated by the NLeSC Python template - -The following steps requires that your existing code is in a GitHub repository. - -1. Follow the [instructions to create a new package](https://github.com/NLeSC/python-template#how-to-use) with the Python template, while answering the questions like you would for the existing package. - -2. Create a Git structure for the new directory: (replace `` with directory name you used during coopier questionnaire) -```shell -$ cd -$ git init -$ git add --all -$ git commit -m "Added code generated by copier" -$ git branch -M main -``` - -3. Import the existing repository from GitHub (Replace `` with your GitHub organization name , `` with your GitHub repository name and `` with your default branch for example `main` or `master`): -```shell -$ git remote add -f existing_code https://github.com// -$ git fetch existing_code -$ git merge existing_code/ --allow-unrelated-histories -``` - -4. The previous step will likely result in several merge conflicts. Solve the conflicts by editing the files. -5. Once all conflicts have been resolved then add all the files to GitHub: -```shell -$ git add --all -$ git commit -m "Merged existing code with code generated by copier" -$ git push -``` From 79cea70a640bd3175766277b624080bb618eb9a7 Mon Sep 17 00:00:00 2001 From: Sander van Rijn Date: Mon, 19 Aug 2024 17:29:40 +0200 Subject: [PATCH 03/10] update usage instruction to explain 3 ways to use copier --- README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 57 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ec98a601..01e51892 100644 --- a/README.md +++ b/README.md @@ -42,20 +42,29 @@ Use this [Copier](https://copier.readthedocs.io) template to generate an empty P ## How to use -### Step 1/3: Install `copier` +There are multiple ways to use this template: +1. Creating a new package based on the template +2. Applying the template's best practices to some pre-existing code +3. Updating a package made with the template based on the latest template updates + +In all three cases, you will need to install copier first: ```shell pipx install copier ``` -### Step 2/3: Generate the files and directory structure +### Option 1: Create a new package + + +#### Step 1/2: Generate the files and directory structure Run `copier` 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 ``` @@ -76,7 +85,7 @@ copier copy https://github.com/nlesc/python-template.git path/to/destination Once the project files have been generated, follow the steps outlined in [template/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 +144,49 @@ 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). + +### Option 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. + +### Option 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. + +```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 From 6e09142857e3623b71ea2a22b8110ab0bd583da8 Mon Sep 17 00:00:00 2001 From: Sander van Rijn Date: Tue, 20 Aug 2024 11:16:30 +0200 Subject: [PATCH 04/10] Update README.md Co-authored-by: fdiblen <144492+fdiblen@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 01e51892..5752f684 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ Use this [Copier](https://copier.readthedocs.io) template to generate an empty P There are multiple ways to use this template: 1. Creating a new package based on the template -2. Applying the template's best practices to some pre-existing code +2. Applying the template to some pre-existing code 3. Updating a package made with the template based on the latest template updates In all three cases, you will need to install copier first: From 5f369e7e9308e01b7bfef86aaa6a2c1a2b12be61 Mon Sep 17 00:00:00 2001 From: Sander van Rijn Date: Tue, 20 Aug 2024 11:16:52 +0200 Subject: [PATCH 05/10] Update README.md Co-authored-by: Olga Lyashevska --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5752f684..ae8366c5 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Use this [Copier](https://copier.readthedocs.io) template to generate an empty P ## How to use -There are multiple ways to use this template: +There are multiple scenarios to use this template: 1. Creating a new package based on the template 2. Applying the template to some pre-existing code From fc07bfe35eb258dc37e747a13bb0a5e11147c87c Mon Sep 17 00:00:00 2001 From: Sander van Rijn Date: Tue, 20 Aug 2024 11:21:27 +0200 Subject: [PATCH 06/10] Update README.md Co-authored-by: Olga Lyashevska --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ae8366c5..740838f2 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ There are multiple scenarios to use this template: 1. Creating a new package based on the template 2. Applying the template to some pre-existing code -3. Updating a package made with the template based on the latest template updates +3. Updating a package made with the template In all three cases, you will need to install copier first: ```shell From 5aa33ded8c61da1990315eee833d2a7ecc9c0244 Mon Sep 17 00:00:00 2001 From: Sander van Rijn Date: Tue, 20 Aug 2024 11:21:51 +0200 Subject: [PATCH 07/10] Update README.md Co-authored-by: Olga Lyashevska --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 740838f2..9221dbf7 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ Use this [Copier](https://copier.readthedocs.io) template to generate an empty P There are multiple scenarios to use this template: -1. Creating a new package based on the template +1. Generating a new package using template 2. Applying the template to some pre-existing code 3. Updating a package made with the template From 227f82beeb1f83cc4a45937f92d1d0e9b69d2ab0 Mon Sep 17 00:00:00 2001 From: Sander van Rijn Date: Tue, 20 Aug 2024 11:32:11 +0200 Subject: [PATCH 08/10] rename options/cases to scenarios --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 9221dbf7..e0fba446 100644 --- a/README.md +++ b/README.md @@ -44,19 +44,19 @@ Use this [Copier](https://copier.readthedocs.io) template to generate an empty P There are multiple scenarios to use this template: -1. Generating a new package using template -2. Applying the template to some pre-existing code -3. Updating a package made with the 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 cases, you will need to install copier first: +In all three scenarios, you will need to install copier first: ```shell pipx install copier ``` -### Option 1: Create a new package +### Scenario 1: Create a new package -#### Step 1/2: Generate the files and directory structure +#### Step 1/2: Create the files and directory structure Run `copier` with the template: @@ -83,7 +83,7 @@ copier copy https://github.com/nlesc/python-template.git path/to/destination | code_of_conduct_email | yourname@esciencecenter.nl | 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 2/2: Read about what was just generated @@ -145,7 +145,7 @@ 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. -### Option 2: Apply to pre-existing code +### 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 @@ -162,7 +162,7 @@ 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. -### Option 3. Updating a template-made package +### 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: From 4debab7de1f2942f4b4dbb5bebbfa51ab1a1fba4 Mon Sep 17 00:00:00 2001 From: Sander van Rijn Date: Tue, 20 Aug 2024 11:50:26 +0200 Subject: [PATCH 09/10] Add pipx install instructions + explanation --- README.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e0fba446..afc8a257 100644 --- a/README.md +++ b/README.md @@ -48,17 +48,26 @@ There are multiple scenarios to use this 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: +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 ``` +> [!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 #### Step 1/2: Create the files and directory structure -Run `copier` with the template: +Run `copier copy` with the template: ```shell # Notes: @@ -155,7 +164,7 @@ containing your existing code rather than a new one: copier copy https://github.com/nlesc/python-template.git path/to/existing/code ``` -This works because if `path/to/destination` already exists, `copier` will +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 @@ -171,6 +180,10 @@ created project using the `copier update` command. This has two effects: 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 @@ -178,7 +191,7 @@ 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 +`--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 From 399a7a11d336bd48a1326580517b5aeb6d9db590 Mon Sep 17 00:00:00 2001 From: Sander van Rijn Date: Tue, 20 Aug 2024 12:03:54 +0200 Subject: [PATCH 10/10] scenarios as list --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index afc8a257..d7951f13 100644 --- a/README.md +++ b/README.md @@ -44,9 +44,9 @@ Use this [Copier](https://copier.readthedocs.io) template to generate an empty P 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 +- [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):