feat: dynamic app name and version suffix

Here, we make it possible to automatically append a suffix to the version and app
name (in the sense of appdirs). This guarantees that a tutor edge project will
not accidentally override another community release.

In addition, we take the opportunity to document the tutor versioning format.
(I've been meaning to do that for a long time)

docs/tutor.rst

@@ -68,11 +68,30 @@ You can then browse the documentation with::
 Releasing a new version
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-- Bump the ``__version__`` value in ``tutor/__about__.py``.
+- Bump the ``__version__`` value in ``tutor/__about__.py``. (see :ref:`versioning` below)
 - Replace "Unreleased" by the version name and date in CHANGELOG.md.
 - Create a commit with the version changelog.
 - Run ``make release``: this will push to the default repo/branch for the current branch.
 
+.. _versioning:
+
+Versioning
+----------
+
+The versioning format used in Tutor is the following::
+
+    RELEASE.MAJOR.MINOR(-BRANCH)
+
+When making a new Tutor release, increment the:
+
+- RELEASE version when a new Open edX release comes out. The new value should match the ordinal value of the first letter of the release name: Aspen 🡒 1, Birch 🡒 2, ... Zebra 🡒 26.
+- MAJOR version when making a backward-incompatible change (prefixed by "💥" in the changelog, as explained below).
+- MINOR version when making a backward-compatible change.
+
+An optional BRANCH suffix may be appended to the release name to indicate that extra changes were added on top of the latest release. For instance, "x.y.z-edge" corresponds to release x.y.z on top of which extra changes were added to make it compatible with the Open edX master branches (see the :ref:`tutorial on running Tutor Edge <edge>`).
+
+`Officially-supported plugins <https://overhang.io/tutor/plugins>`__ follow the same versioning pattern. As a third-party plugin developer, you are encouraged to use the same pattern to make it immediately clear to your end-users which Open edX versions are supported.
+
 .. _contributing:
 
 Contributing to Tutor

tutor/__about__.py

@@ -1 +1,23 @@
+import os
+
+# Increment this version number to trigger a new release. See
+# docs/tutor.html#versioning for information on the versioning scheme.
 __version__ = "12.1.4"
+
+# The version suffix will be appended to the actual version, separated by a
+# dash. Use this suffix to differentiate between the actual released version and
+# the versions from other branches. For instance: set the suffix to "edge" in
+# the edge branch.
+# The suffix is cleanly separated from the __version__ in this module to avoid
+# conflicts when merging branches.
+__version_suffix__ = ""
+
+# The app name will be used to define the name of the default tutor root and
+# plugin directory. To avoid conflicts between multiple locally-installed
+# versions, if it is defined the version suffix will also be appended to the app
+# name.
+__app__ = os.environ.get("TUTOR_APP", "tutor")
+
+if __version_suffix__:
+    __version__ += "-" + __version_suffix__
+    __app__ += "-" + __version_suffix__

tutor/commands/cli.py

@@ -11,7 +11,7 @@ from .images import images_command
 from .k8s import k8s
 from .local import local
 from .plugins import plugins_command, add_plugin_commands
-from ..__about__ import __version__
+from ..__about__ import __version__, __app__
 from .. import exceptions
 from .. import fmt
 from .. import utils
@@ -41,7 +41,7 @@ def main() -> None:
     "-r",
     "--root",
     envvar="TUTOR_ROOT",
-    default=appdirs.user_data_dir(appname="tutor"),
+    default=appdirs.user_data_dir(appname=__app__),
     show_default=True,
     type=click.Path(resolve_path=True),
     help="Root project directory (environment variable: TUTOR_ROOT)",

tutor/env.py

@@ -7,7 +7,7 @@ import jinja2
 import pkg_resources
 
 from . import exceptions, fmt, plugins, utils
-from .__about__ import __version__
+from .__about__ import __app__, __version__
 from .types import Config, ConfigValue
 
 TEMPLATES_ROOT = pkg_resources.resource_filename("tutor", "templates")
@@ -59,6 +59,7 @@ class Renderer:
         environment.globals["rsa_import_key"] = utils.rsa_import_key
         environment.filters["rsa_private_key"] = utils.rsa_private_key
         environment.filters["walk_templates"] = self.walk_templates
+        environment.globals["TUTOR_APP"] = __app__.replace("-", "_")
         environment.globals["TUTOR_VERSION"] = __version__
         self.environment = environment
 

tutor/plugins.py

@@ -8,6 +8,7 @@ import appdirs
 import click
 import pkg_resources
 
+from .__about__ import __app__
 from . import exceptions, fmt, serialize
 from .types import Config, get_typed
 
@@ -272,7 +273,7 @@ class DictPlugin(BasePlugin):
     ROOT_ENV_VAR_NAME = "TUTOR_PLUGINS_ROOT"
     ROOT = os.path.expanduser(
         os.environ.get(ROOT_ENV_VAR_NAME, "")
-    ) or appdirs.user_data_dir(appname="tutor-plugins")
+    ) or appdirs.user_data_dir(appname=__app__ + "-plugins")
 
     def __init__(self, data: Config):
         name = data["name"]

tutor/templates/config.yml

@@ -36,7 +36,7 @@ DOCKER_IMAGE_ELASTICSEARCH: "{{ DOCKER_REGISTRY }}elasticsearch:7.8.1"
 DOCKER_IMAGE_NGINX: "{{ DOCKER_REGISTRY }}nginx:1.19.9"
 DOCKER_IMAGE_REDIS: "{{ DOCKER_REGISTRY }}redis:6.2.1"
 DOCKER_IMAGE_SMTP: "{{ DOCKER_REGISTRY }}namshi/smtp:latest"
-LOCAL_PROJECT_NAME: "tutor_local"
+LOCAL_PROJECT_NAME: "{{ TUTOR_APP }}_local"
 ELASTICSEARCH_HOST: "elasticsearch"
 ELASTICSEARCH_PORT: 9200
 ELASTICSEARCH_SCHEME: "http"