feat: deprecate runserver in favor of start

It will be removed in a future release.
Developers are encouraged to use `tutor dev start` instead,
which is more flexible and provides a consistent interface
with `tutor local start`.

As part of this deprecation, we enable the `tty` and
`stdin_open` options on development docker-compose
services. This will allow developers to use `start`
for breakpoint debugging, which was previously only
availble via `runserver`. Several parallel PRs have
been merged in order to make the same change in the
development services of the official plugins.

Although `start` does not support the `--volume` option,
it supports a more-powerful `--mount` option. So, where
developers previously used:

    tutor dev runserver --volume ...

to bind-mount host directories, they should now use:

    tutor dev start --mount ...

Resolves openedx-unsupported/wg-developer-experience#61

CHANGELOG.md

@@ -4,6 +4,8 @@ Note: Breaking changes between versions are indicated by "💥".
 
 ## Unreleased
 
+- [Deprecation] Mark `tutor dev runserver` as deprecated in favor of `tutor dev start`. Since `start` now supports bind-mounting and breakpoint debugging, `runserver` is redundant and will be removed in a future release.
+- [Improvement] Allow breakpoint debugging when attached to a service via `tutor dev start SERVICE`.
 - [Security] Apply rate limiting security fix (see [commit](https://github.com/overhangio/edx-platform/commit/b5723e416e628cac4fa84392ca13e1b72817674f)).
 - [Feature] Introduce the ``-m/--mount`` option in ``local`` and ``dev`` commands to auto-magically bind-mount folders from the host.
 - [Feature] Add `tutor dev quickstart` command, which is similar to `tutor local quickstart`, except that it uses dev containers instead of local production ones and includes some other small differences for the convience of Open edX developers. This should remove some friction from the Open edX development setup process, which previously required that users provision using local producation containers (`tutor local quickstart`) but then stop them and switch to dev containers (`tutor local stop && tutor dev start -d`).

docs/dev.rst

@@ -112,7 +112,7 @@ It may sometimes be convenient to mount container directories on the host, for i
 Bind-mount volumes with ``--mount``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The `quickstart`, ``run``, ``runserver``, ``init`` and ``start`` subcommands of ``tutor dev`` and ``tutor local`` support the ``-m/--mount`` option (see :option:`tutor dev start -m`) which can take two different forms. The first is explicit::
+The ``quickstart``, ``run``, ``init`` and ``start`` subcommands of ``tutor dev`` and ``tutor local`` support the ``-m/--mount`` option (see :option:`tutor dev start -m`) which can take two different forms. The first is explicit::
 
     tutor dev start --mount=lms:/path/to/edx-platform:/openedx/edx-platform lms
 
@@ -150,14 +150,12 @@ Tutor makes it easy to create a bind-mount from an existing container. First, co
 
 This command recursively copies the contents of the ``/opendedx/venv`` directory to ``$(tutor config printroot)/volumes/venv``. The code of any Python dependency can then be edited -- for instance, you can then add a ``import ipdb; ipdb.set_trace()`` statement for step-by-step debugging, or implement a custom feature.
 
-Then, bind-mount the directory back in the container with the ``--volume`` option::
+Then, bind-mount the directory back in the container with the ``--mount`` option::
 
-		tutor dev runserver --volume=/openedx/venv lms
-
-Notice how the ``--volume=/openedx/venv`` option differs from `Docker syntax <https://docs.docker.com/storage/volumes/#choose-the--v-or---mount-flag>`__? Tutor recognizes this syntax and automatically converts this option to ``--volume=/path/to/tutor/root/volumes/venv:/openedx/venv``, which is recognized by Docker.
+		tutor dev start --mount=lms:$(tutor config printroot)/volumes/venv:/openedx/venv lms
 
 .. note::
-    The ``bindmount`` command and the ``--volume=/...`` option syntax are available both for the ``tutor local`` and ``tutor dev`` commands.
+    The ``bindmount`` command and the ``--mount=...`` option syntax are available both for the ``tutor local`` and ``tutor dev`` commands.
 
 Manual bind-mount to any directory
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -171,7 +169,7 @@ The above solution may not work for you if you already have an existing director
 Override docker-compose volumes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The above solutions require that you explicitly pass the ``-m/--mount`` options to every ``run``, ``runserver``, ``start`` or ``init`` command, which may be inconvenient. To address these issues, you can create a ``docker-compose.override.yml`` file that will specify custom volumes to be used with all ``dev`` commands::
+The above solutions require that you explicitly pass the ``-m/--mount`` options to every ``run``, ``start`` or ``init`` command, which may be inconvenient. To address these issues, you can create a ``docker-compose.override.yml`` file that will specify custom volumes to be used with all ``dev`` commands::
 
     vim "$(tutor config printroot)/env/dev/docker-compose.override.yml"
 
@@ -229,7 +227,9 @@ Then, you should run the following commands::
 
 After running all these commands, your edx-platform repository will be ready for local development. To debug a local edx-platform repository, you can then add a ``import ipdb; ipdb.set_trace()`` breakpoint anywhere in your code and run::
 
-    tutor dev runserver --mount=/path/to/edx-platform lms
+    tutor dev start --mount=/path/to/edx-platform lms
+
+If LMS isn't running, this will start it in your terminal. If an LMS container is already running background, this command will stop it, recreate it, and attach your terminal to it. Later, to detach your terminal without stopping the container, just hit ``Ctrl+z``.
 
 XBlock and edx-platform plugin development
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -250,7 +250,7 @@ You will have to re-build the openedx Docker image once::
 
     tutor images build openedx
 
-You should then run the development server as usual, with ``runserver``. Every change made to the ``mypackage`` folder will be picked up and the development server will be automatically reloaded.
+You should then run the development server as usual, with ``start``. Every change made to the ``mypackage`` folder will be picked up and the development server will be automatically reloaded.
 
 Running edx-platform unit tests
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/tutorials/nightly.rst

@@ -22,10 +22,9 @@ In addition to installing Tutor Nightly itself, this will install automatically
 
 Once Tutor Nightly is installed, you can run the usual ``tutor`` commands::
 
-    tutor local quickstart
-    tutor local stop
-    tutor dev runserver lms
-    # ...
+    tutor dev quickstart
+    tutor dev run lms bash
+    # ... and so on
 
 Upgrading to the latest version of Open edX
 -------------------------------------------

docs/tutorials/plugin.rst

@@ -260,6 +260,22 @@ Run this initialisation task with::
     ++++++ done!
     All services initialised.
 
+Tailoring services for development
+----------------------------------
+
+When you add services via :patch:`local-docker-compose-services`, those services will be available both in local production mode (``tutor local start``) and local development mode (``tutor dev start``). Sometimes, you may wish to further customize a service in ways that would not be suitable for production, but could be helpful for developers. To add in such customizations, implement the :patch:`local-docker-compose-dev-services` patch. For example, we can enable breakpoint debugging on the "myservice" development container by enabling the ``stdin_open`` and ``tty`` options::
+
+    hooks.Filters.ENV_PATCHES.add_item(
+        (
+            "local-docker-compose-dev-services",
+            """
+    myservice:
+        stdin_open: true
+        tty: true
+    """,
+        )
+    )
+
 Final result
 ------------
 
@@ -311,6 +327,16 @@ Eventually, our plugin is composed of the following files, all stored within the
     """,
         )
     )
+    hooks.Filters.ENV_PATCHES.add_item(
+        (
+            "local-docker-compose-dev-services",
+            """
+    myservice-job:
+        stdin_open: true
+        tty: true
+    """,
+        )
+    )
 
     # Modify configuration
     hooks.Filters.CONFIG_DEFAULTS.add_item(

docs/tutorials/theming.rst

@@ -44,7 +44,7 @@ With Tutor, it's pretty easy to develop your own themes. Start by placing your f
 
 Then, run a local webserver::
 
-    tutor dev runserver lms
+    tutor dev start lms
 
 The LMS can then be accessed at http://local.overhang.io:8000. You will then have to :ref:`enable that theme <settheme>`::
 

tutor/commands/dev.py

@@ -98,7 +98,7 @@ def quickstart(context: click.Context, non_interactive: bool, pullimages: bool)
 
 
 @click.command(
-    help="Run a development server",
+    help="DEPRECATED: Use 'tutor dev start ...' instead!",
     context_settings={"ignore_unknown_options": True},
 )
 @compose.mount_option
@@ -111,6 +111,11 @@ def runserver(
     options: t.List[str],
     service: str,
 ) -> None:
+    depr_warning = "'runserver' is deprecated and will be removed in a future release. Use 'start' instead."
+    for option in options:
+        if option.startswith("-v") or option.startswith("--volume"):
+            depr_warning += " Bind-mounts can be specified using '-m/--mount'."
+    fmt.echo_alert(depr_warning)
     config = tutor_config.load(context.obj.root)
     if service in ["lms", "cms"]:
         port = 8000 if service == "lms" else 8001

tutor/templates/dev/docker-compose.yml

@@ -8,6 +8,8 @@ x-openedx-service:
     target: development
     args:
       APP_USER_ID: "{{ HOST_USER_ID }}"
+  stdin_open: true
+  tty: true
   volumes:
     # Settings & config
     - ../apps/openedx/settings/lms:/openedx/edx-platform/lms/envs/tutor:ro