[Bug]: Docs: Inconsistent prioritization of Docker vs. Native commands in contributing.rst #5387
Description
Description
The docs/dev/docker.rst documentation does an excellent job establishing Docker as the recommended,
zero-host-dependency environment for local development.
The Problem
However, when a new contributor moves from the Docker setup guide to the standard workflow guide
(docs/dev/contributing.rst), the documentation reverts to prioritizing native bash commands, while
Docker equivalents are hidden inside inline comments.
For example, under the "For normal, non-urgent features..." section, the guide leads with:
./update_deps.sh # if using Docker: docker compose up --build; no need to bother if deps haven't changed
./manage.py update # if using Docker: docker compose exec web python esp/manage.py updateThis creates a disjointed onboarding experience. A new contributor who just spun up the Docker
environment will naturally copy the first executable command they see, resulting in
Command not found or dependency errors — because they are trying to run native scripts on a host
machine that was promised to need "no Python or PostgreSQL" installed.
Proposed Solution
Since Docker is now the primary recommended development environment, contributing.rst should be
refactored to prioritize the Docker workflow as the top-level executable code snippets.
Native bash instructions (like ./manage.py update) should either be:
- Moved to inline comments, or
- Placed under a designated "Without Docker" sub-header, similar to how the
Testing section
of the document is currently formatted.
Example Refactor
Before:
./update_deps.sh # if using Docker: docker compose up --build
./manage.py update # if using Docker: docker compose exec web python esp/manage.py updateAfter:
# With Docker (recommended):
docker compose up --build
docker compose exec web python esp/manage.py update
# Without Docker:
# ./update_deps.sh
# ./manage.py update