From 15ae31ba11940e9bf48620f118fca618774b981c Mon Sep 17 00:00:00 2001 From: Callum Forrester Date: Mon, 7 Apr 2025 12:57:27 +0100 Subject: [PATCH] Drop support for developing in a local venv in favour of devcontainers --- .../decisions/0020-support-devcontainers.md | 21 +++++++++++++++++++ docs/how-to/dev-install.md | 19 ++--------------- 2 files changed, 23 insertions(+), 17 deletions(-) create mode 100644 docs/explanations/decisions/0020-support-devcontainers.md diff --git a/docs/explanations/decisions/0020-support-devcontainers.md b/docs/explanations/decisions/0020-support-devcontainers.md new file mode 100644 index 00000000..8cf22953 --- /dev/null +++ b/docs/explanations/decisions/0020-support-devcontainers.md @@ -0,0 +1,21 @@ +# 20. Support devcontainers as the opinionated way to contribute + +Date: 2025-04-07 + +## Status + +Accepted + +## Context + +The Python copier template is growing more opinionated over time. It includes a `.devcontainer` and `.vscode` directory committed to version control, providing out-of-box configuration for contributors to set up development environments. In general we have preferred contributors to use the devcontainer rather than a local [venv](https://docs.python.org/3/library/venv.html), as it means development takes place in a consistent environment and it is much easier to support contributors and diagnose their problems by locally reproducing their environments. We can also vend a consistent, tested set of recommended vscode plugins. + +## Decision + +[Devcontainers](https://code.visualstudio.com/docs/devcontainers/containers) are the opinionated way to contribute to projects based on this template. The template will be developed, maintained and tested on the assumption that a contributor is using a devcontainer. + +## Consequences + +The Python copier template development environment is no longer guaranteed to work outside of a devcontainer. Support is not guaranteed for contributors not using a devcontainer, in the first instance requests for such support should be answered with gentle encouragement to adopt them. + +This does not mean non-devcontainer environments are forbidden or designed out, but it does mean the individual contributor is responsible for maintaining such environments, making them work and dealing with any breaking changes themselves. The devcontainer environment is provided for contributors who want something that works out-of-box and is supported, so they can get started quickly. diff --git a/docs/how-to/dev-install.md b/docs/how-to/dev-install.md index ea191829..3d7328b2 100644 --- a/docs/how-to/dev-install.md +++ b/docs/how-to/dev-install.md @@ -8,20 +8,7 @@ First clone the repository locally using [Git](https://git-scm.com/downloads). T ## Install dependencies -You can choose to either develop on the host machine using a `venv` (which requires python 3.10 or later) or to run in a container under [VSCode](https://code.visualstudio.com/) - - -::::{tab-set} - -:::{tab-item} Local virtualenv -``` -python3 -m venv venv -source venv/bin/activate -pip install -e '.[dev]' -``` -::: - -:::{tab-item} VSCode devcontainer +It is recommended that developers use a [vscode devcontainer](https://code.visualstudio.com/docs/devcontainers/containers). This repository contains configuration to set up a containerized development environment that suits its own needs. Ensure you have the [vscode devcontainer extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) installed. @@ -32,10 +19,8 @@ code . ``` Click on 'Reopen in Container' when prompted on startup or, if vscode is already running, open the command menu with CTRL+SHIFT+P, search for and run 'Reopen in Container'. -Open a new terminal -::: -:::: +Open a new terminal ## Build and test