From 2a846a2e32010896932b55ca6fcde81ac73227b1 Mon Sep 17 00:00:00 2001 From: Callum Forrester Date: Wed, 7 May 2025 07:39:22 +0100 Subject: [PATCH 1/2] Replace short-form URLS Replace short-form URLS with long-form URLS in documentation. Copier supports URLs of the style gh:org/repo, but other supporting tools, such as renovate, may not. We have chosen to use the well-known standard. --- .github/workflows/_example.yml | 2 +- README.md | 2 +- docs/tutorials/adopt-existing.md | 4 ++-- docs/tutorials/create-new.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/_example.yml b/.github/workflows/_example.yml index 349c0a61..ea14af9e 100644 --- a/.github/workflows/_example.yml +++ b/.github/workflows/_example.yml @@ -20,7 +20,7 @@ jobs: - name: Rewrite copier answers run: | - sed -i 's|_src_path: .|_src_path: gh:DiamondLightSource/python-copier-template|' example/.copier-answers.yml + sed -i 's|_src_path: .|_src_path: https://github.com/DiamondLightSource/python-copier-template.git|' example/.copier-answers.yml - name: Publish example # We pin to the SHA, not the tag, for security reasons. diff --git a/README.md b/README.md index 87b6dcf7..fcf5d7eb 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ You will need to `pip install copier` inside an activated `venv` from python3.10 ``` mkdir /path/to/my-project # The --trust argument is required to run setup tasks such as initializing a git repository -copier copy --trust gh:DiamondLightSource/python-copier-template /path/to/my-project +copier copy --trust https://github.com/DiamondLightSource/python-copier-template.git /path/to/my-project ``` You can also use it via `pipx run copier` if you have that installed. diff --git a/docs/tutorials/adopt-existing.md b/docs/tutorials/adopt-existing.md index 0f3c9185..1832869b 100644 --- a/docs/tutorials/adopt-existing.md +++ b/docs/tutorials/adopt-existing.md @@ -18,7 +18,7 @@ Copier will *overwrite* files with the template files. Please check the changes If you have a [python3-pip-skeleton](https://github.com/DiamondLightSource/python3-pip-skeleton) based project then it is best to adopt the `1.0.0` release of this template, then `copier update` to get to the latest. This is because `copier update` will try and merge file changes across renames done between releases, while `copier copy` cannot. This looks like: ```shell -copier copy gh:DiamondLightSource/python-copier-template --trust --vcs-ref=1.0.0 /path/to/existing-project +copier copy https://github.com/DiamondLightSource/python-copier-template.git --trust --vcs-ref=1.0.0 /path/to/existing-project git diff # Examine the changes, put back anything you want to keep git commit -m "Adopt python-copier-template 1.0.0" @@ -33,7 +33,7 @@ git commit -m "Update to python-copier-template x.x.x" If you have a project with a different structure then it is best to go straight to the latest release: ```shell -copier copy --trust gh:DiamondLightSource/python-copier-template /path/to/existing-project +copier copy --trust https://github.com/DiamondLightSource/python-copier-template.git /path/to/existing-project git diff # Examine the changes, put back anything you want to keep git commit -m "Adopt python-copier-template x.x.x" diff --git a/docs/tutorials/create-new.md b/docs/tutorials/create-new.md index 31c62bb4..ed5c49da 100644 --- a/docs/tutorials/create-new.md +++ b/docs/tutorials/create-new.md @@ -4,7 +4,7 @@ Once you have followed the [](./installation) tutorial, you can use `copier` to ``` $ mkdir /path/to/my-project -$ copier copy --trust gh:DiamondLightSource/python-copier-template /path/to/my-project +$ copier copy --trust https://github.com/DiamondLightSource/python-copier-template.git /path/to/my-project ``` This will: From aa9f768946c6c4c58ca4b71d5b486453e723dbc4 Mon Sep 17 00:00:00 2001 From: Callum Forrester Date: Wed, 7 May 2025 07:49:58 +0100 Subject: [PATCH 2/2] Add an ADR about changing URLS Add an ADR justifying the change to long-form URLs --- .../decisions/0021-long-form-urls.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 docs/explanations/decisions/0021-long-form-urls.md diff --git a/docs/explanations/decisions/0021-long-form-urls.md b/docs/explanations/decisions/0021-long-form-urls.md new file mode 100644 index 00000000..0c9cd33b --- /dev/null +++ b/docs/explanations/decisions/0021-long-form-urls.md @@ -0,0 +1,19 @@ +# 21. Use long-form URLs in documentation + +Date: 2025-05-07 + +## Status + +Accepted + +## Context + +Copier supports shortcut URLs (see [docs](https://copier.readthedocs.io/en/stable/generating)) of the form `gh:namespace/project`. This was convenient for making our documentation look neater and more digestible to new users, however it is just a convention. When trying to integrate other tools with copier we find that they do not necessarily support the convention. See [this discussion](https://github.com/renovatebot/renovate/discussions/35577) for example. + +## Decision + +Remove shortcut URLs from this repository and replace them with standard URLs. + +## Consequences + +Downstream projects following the documentation will be created with standard URLs and will be supported by renovate and other tools. The alternative solution is to open PRs to these tools so they too support the shortcuts. It was decided that it was quicker, easier and probably more architecturally correct to use long-form URLs since they are already a well-known and widely adopted standard. See [this discussion](https://github.com/epics-containers/services-template-helm/issues/21#issuecomment-2855125741).