From b813a5b7bdc368a7bd4e7eba6638ece183933324 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Fri, 25 Jul 2025 17:05:35 +0200 Subject: [PATCH 1/4] docs: :memo: guide for updating or using in existing project --- docs/guide.qmd | 70 +++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 61 insertions(+), 9 deletions(-) diff --git a/docs/guide.qmd b/docs/guide.qmd index eb70e54..03a77c7 100644 --- a/docs/guide.qmd +++ b/docs/guide.qmd @@ -11,8 +11,8 @@ post-creation tasks. In order to use this template, you need to install a few programs: - [Python](https://www.python.org/): Required for installing and using - many of the tools in this template, and because the template - itself uses Python. + many of the tools in this template, and because the template itself + uses Python. - [Git](https://git-scm.com/): For version control and setting up Git to track the newly created data package. - [copier](https://copier.readthedocs.io/en/stable/#quick-start): A @@ -24,8 +24,8 @@ In order to use this template, you need to install a few programs: - [just](https://just.systems/man/en/): A build management tool that helps with running common build and check tasks. -You will need to install Python and Git yourself, but the other tools can -be installed using +You will need to install Python and Git yourself, but the other tools +can be installed using [`pipx`](https://pipxproject.github.io/pipx/)---which we strongly recommend---with the following command: @@ -33,7 +33,7 @@ recommend---with the following command: pipx install copier uv rust-just ``` -## Using this template +## Creating a new data package You can use this template to create a new Data Package with a standard set of files and folders, as well as all the features and configurations @@ -43,7 +43,7 @@ you want to create the new Data Package. Then run the following command: ``` bash # Copy into the current directory, which is the "." -uvx copier copy gh:seedcase-project/template-data-package . +uvx copier copy --trust gh:seedcase-project/template-data-package . ``` ::: callout-caution @@ -56,11 +56,64 @@ doing. Unfortunately, this template can't be used without the `--trust` option. ::: +## Using on an existing Data Package + +If you want to use this template on an existing Data Package, you can +use the `copy` command of `copier` as like above to apply the template +to the existing Data Package. This will add all the template's files and +configurations to the existing Data Package the new + +``` bash +uvx copier copy --trust gh:seedcase-project/template-data-package . +``` + +It will go through a series of prompts, as in the case of creating a new +Data Package, including asking if you want to overwrite existing files. +The Data Package does need to be tracked by Git and in a clean state (no +changes). + +## Updating from the template + +There are two ways to update an existing Data Package with the latest +changes from the template: `update` and `recopy`. + +Use `update` if you want to only apply any updates made to the template +itself. `update` will compare the version of the template you used when +you first copied the template with the current version of the template, +and then apply the changes that are different. This also means it won't +overwrite any changes you made to files in your current Data Package, +for example, if you deleted a file that was in the template, it won't be +copied back. + +Use `recopy` if you want to reapply the template from scratch, which +will overwrite any changes you made to the files that were copied from +the template. This is useful if you want to reset the Data Package to +the state of the template. For example, if you deleted a file but want +it back from the template or are simply curious to see if there are any +new changes that you might want to use. + +In both cases, the commands are very similar and also use many of the +same options as the `copy` command. If you want to use the same answers +as given when you first copied the template, you can use the +`--defaults` option. Then it will only prompt you for the questions that +have changed since the last time you copied the template. + +``` bash +uvx copier update --trust --defaults +# Or +uvx copier recopy --trust --defaults +``` + +As with the `copy` command, the Data Package needs to be tracked by Git +and must be in a clean state (no changes) for the `update` and `recopy` +commands to work. + ## Post-creation setup These steps are mainly for us in the Seedcase Project to set up the repository with the settings we use, but you can follow them if you want -to set up your Data Package in a similar way. +to set up your Data Package in a similar way. They are also included in +a message after you've copied the template. After copying the template, while in the directory of the new Data Package, run the following: @@ -82,8 +135,7 @@ Some configuration is needed after copying this template to a new repository, including configuration external to the repository. - The template file `.github/workflows/release-package.yml` requires - the - [auto-release-token](https://github.com/apps/auto-release-token) + the [auto-release-token](https://github.com/apps/auto-release-token) GitHub App to be installed, as well as a GitHub secret called `UPDATE_VERSION_TOKEN` and a variable called `UPDATE_VERSION_APP_ID` to be set up in the repository (or organization) settings. See this From 7808ee789e5d47cb4574016766610ef6c85b7100 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Mon, 28 Jul 2025 10:58:36 +0200 Subject: [PATCH 2/4] docs: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: martonvago <57952344+martonvago@users.noreply.github.com> Co-authored-by: Signe Kirk Brødbæk <40836345+signekb@users.noreply.github.com> --- docs/guide.qmd | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/guide.qmd b/docs/guide.qmd index 03a77c7..d4787d3 100644 --- a/docs/guide.qmd +++ b/docs/guide.qmd @@ -56,12 +56,12 @@ doing. Unfortunately, this template can't be used without the `--trust` option. ::: -## Using on an existing Data Package +## Applying the template to an existing Data Package If you want to use this template on an existing Data Package, you can -use the `copy` command of `copier` as like above to apply the template +use the `copy` command of `copier` just like above to apply the template to the existing Data Package. This will add all the template's files and -configurations to the existing Data Package the new +configurations to the existing Data Package. ``` bash uvx copier copy --trust gh:seedcase-project/template-data-package . @@ -69,16 +69,19 @@ uvx copier copy --trust gh:seedcase-project/template-data-package . It will go through a series of prompts, as in the case of creating a new Data Package, including asking if you want to overwrite existing files. -The Data Package does need to be tracked by Git and in a clean state (no + +::: callout-note +To use the `copy` command, the Data Package needs to be tracked by Git and in a clean state (no changes). +::: -## Updating from the template +## Applying the latest template changes There are two ways to update an existing Data Package with the latest changes from the template: `update` and `recopy`. -Use `update` if you want to only apply any updates made to the template -itself. `update` will compare the version of the template you used when +Use `update` to apply template updates to your project without overwriting +local changes. `update` will compare the version of the template you used when you first copied the template with the current version of the template, and then apply the changes that are different. This also means it won't overwrite any changes you made to files in your current Data Package, From 8279c1dc5ed1f73b02b52d91d27ec86c9067bea2 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Mon, 28 Jul 2025 11:04:43 +0200 Subject: [PATCH 3/4] docs: :pencil2: restructure sentence for better clarity --- docs/guide.qmd | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/guide.qmd b/docs/guide.qmd index d4787d3..24b9d17 100644 --- a/docs/guide.qmd +++ b/docs/guide.qmd @@ -10,9 +10,9 @@ post-creation tasks. In order to use this template, you need to install a few programs: -- [Python](https://www.python.org/): Required for installing and using - many of the tools in this template, and because the template itself - uses Python. +- [Python](https://www.python.org/): Required the template tool itself + (copier) and for installing and using many of the tools in this + template. - [Git](https://git-scm.com/): For version control and setting up Git to track the newly created data package. - [copier](https://copier.readthedocs.io/en/stable/#quick-start): A @@ -71,8 +71,8 @@ It will go through a series of prompts, as in the case of creating a new Data Package, including asking if you want to overwrite existing files. ::: callout-note -To use the `copy` command, the Data Package needs to be tracked by Git and in a clean state (no -changes). +To use the `copy` command, the Data Package needs to be tracked by Git +and in a clean state (no changes). ::: ## Applying the latest template changes @@ -80,13 +80,13 @@ changes). There are two ways to update an existing Data Package with the latest changes from the template: `update` and `recopy`. -Use `update` to apply template updates to your project without overwriting -local changes. `update` will compare the version of the template you used when -you first copied the template with the current version of the template, -and then apply the changes that are different. This also means it won't -overwrite any changes you made to files in your current Data Package, -for example, if you deleted a file that was in the template, it won't be -copied back. +Use `update` to apply template updates to your project without +overwriting local changes. `update` will compare the version of the +template you used when you first copied the template with the current +version of the template, and then apply the changes that are different. +This also means it won't overwrite any changes you made to files in your +current Data Package, for example, if you deleted a file that was in the +template, it won't be copied back. Use `recopy` if you want to reapply the template from scratch, which will overwrite any changes you made to the files that were copied from From 45e2317806fcb19e94d6e3bfc57405c5bdb9c665 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Mon, 28 Jul 2025 13:21:13 +0200 Subject: [PATCH 4/4] docs: :pencil2: forgot a word Co-authored-by: martonvago <57952344+martonvago@users.noreply.github.com> --- docs/guide.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide.qmd b/docs/guide.qmd index 24b9d17..919efd2 100644 --- a/docs/guide.qmd +++ b/docs/guide.qmd @@ -10,7 +10,7 @@ post-creation tasks. In order to use this template, you need to install a few programs: -- [Python](https://www.python.org/): Required the template tool itself +- [Python](https://www.python.org/): Required by the template tool itself (copier) and for installing and using many of the tools in this template. - [Git](https://git-scm.com/): For version control and setting up Git