feat!: Add renovate (#311)

Need to add some release notes on renovate to the release

An example PR it makes: bluesky/ophyd-async#1109

Author: DominicOram

.github/dependabot.yml

@@ -36,16 +36,14 @@ You can see the template in action in the [example project](https://github.com/D
 
 ## Create a new project from the commandline
 
-You will need to `pip install copier` inside an activated `venv` from python3.11 or later, then you can create a new module via:
+We recommend that you invoke copier via `uvx`, which will download, install, and run it in its own isolated `venv`. At Diamond you can `module load uv` to get `uvx` on your path, then:
 
 ```
 git init --initial-branch=main /path/to/my-project
 # $_ resolves to /path/to/my-project
-copier copy https://github.com/DiamondLightSource/python-copier-template.git $_
+uvx copier copy https://github.com/DiamondLightSource/python-copier-template.git $_
 ```
 
-You can also use it via `uvx copier` if you have `uv` installed.
-
 <!-- README only content. Anything below this line won't be included in index.md -->
 
 See https://DiamondLightSource.github.io/python-copier-template for more detailed documentation.

README.md

@@ -6,6 +6,7 @@ Practical step-by-step guides for the more experienced user.
 :maxdepth: 1
 :glob:
 
+how-to/setup-repo
 how-to/dev-install
 how-to/*
 ```

docs/how-to.md

@@ -37,3 +37,12 @@ If you want to watch additional directories for changes you can pass these as ar
 ```
 $ tox -e docs-autobuild -- --watch tests
 ```
+
+(building-docs-in-ci)=
+## Building docs in CI
+
+After a successful run of CI
+
+Settings > Pages
+
+![Setup GitHub Pages](../images/gh-pages-setup.png)

docs/how-to/build-docs.md

@@ -3,6 +3,20 @@
 
 Code coverage is reported to the command line and to a `cov.xml` file by the command `tox -e tests`. The file is uploaded to the Codecov service in CI.
 
-## Adding a Codecov Token
+(installing-codecov-github-app)=
+## Installing Codecov GitHub app
 
-If the repo is not hosted in DiamondLightSource, then you need to visit `https://app.codecov.io/account/gh/<org_name>/org-upload-token` to generate a token for your org, and store it as a secret named `CODECOV_TOKEN` in `https://github.com/organizations/<org_name>/settings/secrets/actions`
+If your repo is hosted in the DiamondLightSource org, then the codecov GitHub app is already installed and a global token stored so you don't need to do anything.
+
+If your repo is in an org where the codecov GitHub app is not installed, then follow these steps to install it on the org:
+
+- Visit https://github.com/apps/codecov
+- Click `Configure`
+- Select the org your repo is hosted in
+- Select `All repositories` and click `Install`
+
+![Install Codecov](../images/gh-install-codecov.png)
+
+Now you need to visit `https://app.codecov.io/account/gh/<org_name>/org-upload-token` to generate a token for your org, and store it as a secret named `CODECOV_TOKEN` in `https://github.com/organizations/<org_name>/settings/secrets/actions`
+
+Next time you create a pull request or merge to main, the code coverage will be uploaded, and the badge on the repository updated.

docs/how-to/coverage.md

@@ -28,6 +28,7 @@ To update all dependencies to their latest versions run:
 ```
 uv sync --upgrade
 ```
+This command will be run by [renovate](./renovate) once a week in CI.
 
 ```{seealso}
 [The uv docs on locking and syncing](https://docs.astral.sh/uv/concepts/projects/sync)

docs/how-to/lock-requirements.md

@@ -14,7 +14,7 @@ You will need the following information:
 
 ## If publishing to the DiamondLightSource PyPI organisation
 
-If you are publishing to the DiamondLightSource PyPI organisation then use the above information and follow the [Developer Portal Guide on PyPI publishing](https://dev-portal.diamond.ac.uk/guide/python/how-tos/pypi/).
+If you are publishing to the DiamondLightSource PyPI organisation then use the above information and follow the [Developer Portal Guide on PyPI publishing](https://dev-guide.diamond.ac.uk/python/how-tos/pypi/).
 
 ## If publishing the PyPI project to another organisation
 

docs/how-to/pypi.md

@@ -0,0 +1,39 @@
+# Use renovate to keep dependencies up to date
+
+[Renovate](https://github.com/apps/renovate) is a tool for automating dependency updates. It is used to:
+- Automatically update the [uv lock file](./lock-requirements.md) and automerge if tests pass
+- Update any dependencies in the Dockerfile
+- Update the versions of any GitHub actions not manager by the python-copier-template
+
+## Install the Renovate GitHub app
+
+The renovate app will:
+- Create weekly PRs to update the lockfile to the latest versions, automerging if tests pass
+- Create PRs for other dependencies whenever they are released, but not automerge
+
+If your repo is hosted in the DiamondLightSource org, then the Renovate GitHub app is already installed so you don't need to do anything.
+
+If your repo is in an org where the Renovate GitHub app is not installed, then follow these steps to install it on the org:
+
+- Visit https://github.com/apps/renovate
+- Click `Configure`
+- Select the org your repo is hosted in
+- Select `All repositories` and click `Install`
+- Select `Renovate Only` as the product
+- Select `Scan only` as the mode
+- Click `Finish`
+- Click `Settings`
+- Select the `Dependencies` tab
+- Uncheck `Silent mode`, uncheck `Create onboarding PRs`, and click `Save`
+- Visit https://github.com/apps/renovate-approve
+- Click `Configure`
+- Select the org your repo is hosted in
+- Select `All repositories` and click `Install`
+
+![Install Renovate](../images/gh-install-renovate.png)
+
+Renovate will now run periodically to check for updates.
+ 
+## Pin the dependency dashboard issue
+
+Renovate will create a dependency dashboard when it first runs, this is the way you interact with the bot, requesting it to re-run. It is recommended that you pin this issue to your repo so you can find it easily. Select `Pin issue` in the right hand bar of the issue to do this.

docs/how-to/renovate.md

@@ -0,0 +1,35 @@
+# Setup the repository with recommended settings
+
+When the repository has been created, it will require some settings to be changed for all the features of the python-copier-template to work. These are listed below.
+
+## Discussions
+
+The contributing guide for the template recommends that new users start a discussion for questions. You can enable this feature by navigating to your repository page and:
+
+- Visiting `Settings` > `General`
+- Scrolling down to `Features`
+- Enabling it as shown
+
+![Setup GitHub Features](../images/gh-features-setup.png)
+
+## Branch protection
+
+GitHub will prompt you that your `main` branch is not protected. It is recommended that a [branch protection rule](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule) is setup for `main` to require pull requests.
+
+If the repository is in the `DiamondLightSource` org, then follow [the dev guide](https://dev-guide.diamond.ac.uk/version-control/how-tos/github-setup-prs/) to see the recommended settings.
+
+## Code Coverage
+
+To ensure that code coverage is correctly uploaded to codecov.io follow [](#installing-codecov-github-app)
+
+## Renovate
+
+To ensure that your dependencies are kept up to date follow [](./renovate.md)
+
+## GitHub pages
+
+If you configured the project to have sphinx docs then follow [](#building-docs-in-ci)
+
+## PyPI uploading
+
+If you configured the project to upload built wheels to PyPI then follow [](./pypi.md)