fix: Move to long-form Github URLs (#260)

See
epics-containers/services-template-helm#21 (comment)
and the ADR in this PR for explanation.

Author: callumforrester

.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.

README.md

@@ -48,7 +48,7 @@ You will need to `pip install copier` inside an activated `venv` from python3.11
 ```
 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.

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).

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"

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: