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,7 @@ Note: Breaking changes between versions are indicated by "💥".
 
 ## Unreleased
 
+- [Deprecation] Mark `tutor dev runserver` as deprecated, to 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`. Where developers previously used `tutor dev runserver --volume ...` to bind-mount host directories, they should now use `tutor dev start --mount ...`.
 - [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`).
 - 💥[Improvement] Make it possible to run `tutor k8s exec <command with multiple arguments>` (#636). As a consequence, it is no longer possible to run quoted commands: `tutor k8s exec "<some command>"`. Instead, you should remove the quotes: `tutor k8s exec <some command>`.

docs/dev.rst

@@ -97,7 +97,7 @@ The ``openedx-dev`` Docker image is based on the same ``openedx`` image used by
 
 If you are using a custom ``openedx`` image, then you will need to rebuild ``openedx-dev`` every time you modify ``openedx``. To so, run::
 
-    tutor dev dc build lms
+    tutor dev dc build lmsru
 
 
 .. _bind_mounts:
@@ -112,7 +112,7 @@ It may sometimes be convenient to mount container directories on the host, for i
 Bind-mount volumes with ``--mount``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``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 ``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
 
@@ -171,7 +171,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"
 
@@ -207,7 +207,7 @@ Setting up a development environment for edx-platform
 
 Following the instructions :ref:`above <bind_mounts>` on how to bind-mount directories from the host above, you may mount your own `edx-platform <https://github.com/openedx/edx-platform/>`__ fork in your containers by running::
 
-    tutor dev runserver --mount=/path/to/edx-platform lms
+    tutor dev start -d --mount=/path/to/edx-platform lms
 
 But to achieve that, you will have to make sure that your fork works with Tutor.
 
@@ -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 -d 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 'start -d' instead",
     context_settings={"ignore_unknown_options": True},
 )
 @compose.mount_option

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