Merge remote-tracking branch 'origin/release'

.github/workflows/sync.yml

@@ -2,7 +2,9 @@ name: Sync with private repo
 
 on:
   push:
-    branches: [ master, main, nightly ]
+    branches:
+      - release
+      - main
 
 jobs:
   sync:

.github/workflows/test.yml

@@ -2,9 +2,13 @@ name: Run tests
 
 on:
   push:
-    branches: [ master, main, nightly ]
+    branches:
+      - release
+      - main
   pull_request:
-    branches: [ master, main, nightly ]
+    branches:
+      - release
+      - main
 
 jobs:
   tests:

README.rst

@@ -93,4 +93,4 @@ We welcome contributions to Tutor! To learn how you can contribute, please check
 License
 -------
 
-This work is licensed under the terms of the `GNU Affero General Public License (AGPL) <https://github.com/overhangio/tutor/blob/master/LICENSE.txt>`_.
+This work is licensed under the terms of the `GNU Affero General Public License (AGPL) <https://github.com/overhangio/tutor/blob/release/LICENSE.txt>`_.

changelog.d/20241107_144307_kyle_branch_rename.md

@@ -0,0 +1,4 @@
+- 💥[Improvement] Rename Tutor's two branches (by @kdmccormick):
+  * Rename **master** to **release**, as this branch runs the latest official Open edX release.
+  * Rename **nightly** to **main**, as this branch runs the Open edX master (a.k.a. main) branches, which are the basis fort the next Open edX release.
+  * For Tutor Nightly users who do not set a TUTOR_ROOT, both the project root (`~/.local/share/tutor-nightly` on Linux) and the plugins root (`~/.local/share/tutor-nightly-plugins` on Linux) will be automatically renamed. (by @regisb)

changelog.d/20241127_001212_kyle_tutor_branch_is_main.md

@@ -0,0 +1,2 @@
+- [Feature] Add the `TUTOR_BRANCH_IS_MAIN` variable to the template context, which is set to True for users running Tutor Main (by @kdmccormick).
+- [Bugfix] Use `TUTOR_BRANCH_IS_MAIN` rather than the edx-platform branch name in order to determine which patches to apply. This way, when developers are testing an edx-platform branch that is not master but which may be *based on* master, they will receive master patches rather than release patches, assuming they are running Tutor Main in the first place (by @kdmccormick).

docs/configuration.rst

@@ -132,7 +132,7 @@ Open edX customisation
 
 This defines the git repository from which you install Open edX platform code. If you run an Open edX fork with custom patches, set this to your own git repository. You may also override this configuration parameter at build time, by providing a ``--build-arg`` option.
 
-- ``OPENEDX_COMMON_VERSION`` (default: ``"open-release/redwood.3"``, or ``master`` in :ref:`nightly <nightly>`)
+- ``OPENEDX_COMMON_VERSION`` (default: ``"open-release/redwood.3"``, or ``master`` in :ref:`Tutor Main <main>`)
 
 This defines the default version that will be pulled from all Open edX git repositories.
 
@@ -392,7 +392,7 @@ Tutor builds images with the latest translations using the ``atlas pull`` `comma
 By default the translations are pulled from the `openedx-translations repository <https://github.com/openedx/openedx-translations>`_
 from the ``ATLAS_REVISION`` branch. You can use custom translations on your fork of the openedx-translations repository by setting the following configuration parameters:
 
-- ``ATLAS_REVISION`` (default: ``"main"`` on nightly and ``"{{ OPENEDX_COMMON_VERSION }}"`` if a named release is used)
+- ``ATLAS_REVISION`` (default: ``"main"`` for Tutor Main, or ``"{{ OPENEDX_COMMON_VERSION }}"`` if a named release is used)
 - ``ATLAS_REPOSITORY`` (default: ``"openedx/openedx-translations"``). There's a feature request to `support GitLab and other providers <https://github.com/openedx/openedx-atlas/issues/20>`_.
 - ``ATLAS_OPTIONS`` (default: ``""``) Pass additional arguments to ``atlas pull``. Refer to the `atlas documentations <https://github.com/openedx/openedx-atlas>`_ for more information.
 

docs/dev.rst

@@ -12,7 +12,7 @@ For detailed explanations on how to work on edx-platform and its dependencies, s
 First-time setup
 ----------------
 
-Firstly, either :ref:`install Tutor <install>` (for development against the named releases of Open edX) or :ref:`install Tutor Nightly <nightly>` (for development against Open edX's master branches).
+Firstly, either :ref:`install Tutor <install>` (for development against the named releases of Open edX) or :ref:`install Tutor Main <main>` (for development against Open edX's master branches).
 
 Then, optionally, tell Tutor to use a local fork of edx-platform::
 

docs/index.rst

@@ -40,7 +40,7 @@ Tutor: the Docker-based Open edX distribution designed for peace of mind
    Source code <https://github.com/overhangio/tutor>
    Community forums <https://discuss.openedx.org/tag/tutor>
    Pypi releases <https://pypi.org/project/tutor>
-   Changelog <https://github.com/overhangio/tutor/blob/master/CHANGELOG.md>
+   Changelog <https://github.com/overhangio/tutor/blob/release/CHANGELOG.md>
 
 Source code
 -----------
@@ -58,7 +58,7 @@ The complete source code for Tutor is available on Github: https://github.com/ov
 License
 -------
 
-This work is licensed under the terms of the `GNU Affero General Public License (AGPL) <https://github.com/overhangio/tutor/blob/master/LICENSE.txt>`_.
+This work is licensed under the terms of the `GNU Affero General Public License (AGPL) <https://github.com/overhangio/tutor/blob/release/LICENSE.txt>`_.
 
 The AGPL license covers the Tutor code, including the Dockerfiles, but not the content of the Docker images which can be downloaded from https://hub.docker.com. Software other than Tutor provided with the docker images retain their original license.
 

docs/install.rst

@@ -113,7 +113,7 @@ Upgrading to a new Open edX release
 
 Major Open edX releases are published twice a year, in June and December, by the Open edX `Build/Test/Release working group <https://discuss.openedx.org/c/working-groups/build-test-release/30>`__. When a new Open edX release comes out, Tutor gets a major version bump (see :ref:`versioning`). Such an upgrade typically includes multiple breaking changes. Any upgrade is final because downgrading is not supported. Thus, when upgrading your platform from one major version to the next, it is strongly recommended to do the following:
 
-1. Read the changes listed in the `CHANGELOG.md <https://github.com/overhangio/tutor/blob/master/CHANGELOG.md>`__ file. Breaking changes are identified by a "💥".
+1. Read the changes listed in the `CHANGELOG.md <https://github.com/overhangio/tutor/blob/release/CHANGELOG.md>`__ file. Breaking changes are identified by a "💥".
 2. Perform a backup (see the :ref:`backup tutorial <backup_tutorial>`). On a local installation, this is typically done with::
 
     tutor local stop

docs/troubleshooting.rst

@@ -91,7 +91,7 @@ If that does not work, then check if there are any other Docker containers runni
 
     docker ps -a
 
-For example, if you have ever used :ref:`Tutor Nightly <nightly>`, check whether there are still ``tutor_nightly_`` containers running. Conversely, if trying to run Tutor Nightly now, check whether there are non-Nightly ``tutor_`` containers running. If so, switch to that other version of Tutor, run ``tutor (dev|local|k8s) stop``, and then switch back to the preferred version of Tutor.
+For example, if you have ever used :ref:`Tutor Main <main>`, check whether there are still ``tutor_main_`` containers running. Conversely, if trying to run Tutor Main now, check whether there are non-Main ``tutor_`` containers running. If so, switch to that other version of Tutor, run ``tutor (dev|local|k8s) stop``, and then switch back to the preferred version of Tutor.
 
 Alternatively, if there are any other non-Tutor containers using port 3306, then stop and remove them::
 

docs/tutor.rst

@@ -98,7 +98,7 @@ When making a new Tutor release, increment the:
 - 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-nightly" 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 Nightly <nightly>`).
+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-main" 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 Main <main>`).
 
 `Officially-supported plugins <https://edly.io/tutor/plugins-and-themes/>`__ 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.
 

docs/tutorials/edx-platform.rst

@@ -25,7 +25,7 @@ Check out the right version of the upstream repository. If you are working on th
     # I.e: aspen, birch, cypress, etc.
     git checkout open-release/zebulon.master
 
-On the other hand, if you are working on the Tutor :ref:`"nightly" <nightly>` branch then you should checkout the master branch::
+On the other hand, if you are using :ref:`Tutor Main <main>`, then you should checkout the master branch::
 
     git checkout master
 

docs/tutorials/index.rst

@@ -12,7 +12,7 @@ Open edX customization
    edx-platform
    edx-platform-settings
    google-smtp
-   nightly
+   main
 
 System administration
 ---------------------

docs/tutorials/main.rst

@@ -0,0 +1,64 @@
+.. _main:
+
+Running Open edX on the master branch ("Tutor Main")
+====================================================
+
+Tutor was designed to make it easy for everyone to run the latest release of Open edX. But sometimes, you want to run the latest, bleeding-edge version of Open edX. This is what we call "running master", as opposed to running the release branch. Running the master branch in production is strongly **not** recommended unless you are an Open edX expert and you really know what you are doing. But Open edX developers frequently need to run the master branch locally to implement and test new features. Thus, Tutor makes it easy to run Open edX on the master branch: this is called "Tutor Main".
+
+Installing Tutor Main
+---------------------
+
+Running Tutor Main requires more than setting a few configuration variables: because there are so many Open edX settings, version numbers, etc. which may change between the latest release and the current master branch, Tutor Main is actually maintained as a separate branch of the Tutor repository. To install Tutor Main, you should install Tutor from the "main" branch of the source repository. To do so, run::
+
+    git clone --branch=main https://github.com/overhangio/tutor.git
+    pip install -e "./tutor[full]"
+
+As usual, it is strongly recommended to run the command above in a `Python virtual environment <https://docs.python.org/3/tutorial/venv.html>`__.
+
+In addition to installing Tutor Main itself, this will install automatically the main versions of all official Tutor plugins (which are enumerated in `plugins.txt <https://github.com/overhangio/tutor/tree/main/requirements/plugins.txt>`_). Alternatively, if you wish to hack on an official plugin or install a custom plugin, you can clone that plugin's repository and install it. For instance::
+
+    git clone --branch=main https://github.com/myorganization/tutor-contrib-myplugin.git
+    pip install -e ./tutor-contrib-myplugin
+
+Once Tutor Main is installed, you can run the usual ``tutor`` commands::
+
+    tutor dev launch
+    tutor dev run lms bash
+    # ... and so on
+
+Upgrading to the latest version of Open edX
+-------------------------------------------
+
+To pull the latest upstream changes, you should first upgrade Tutor Main::
+
+    cd ./tutor
+    git pull
+
+Then, you will have to generate a more recent version of the main Docker images. Images for running Tutor Main are published daily to docker.io (see `here <https://hub.docker.com/r/overhangio/openedx/tags?page=1&ordering=last_updated&name=main>`__). You can fetch the latest images with::
+
+    tutor images pull all
+
+Alternatively, you may want to build the images yourself. As usual, this is done with::
+
+        tutor images build all
+
+However, these images include the application master branch at the point in time when the image was built. The Docker layer caching mechanism might cause the ``git clone`` step from the build to be skipped. In such cases, you will have to bypass the caching mechanism with::
+
+    tutor images build --no-cache all
+
+Running Tutor Main alongside the latest release
+--------------------------------------------------
+
+When running Tutor Main, you usually do not want to override your existing Tutor installation. That's why a Tutor Main installation has the following differences from a regular release installation:
+
+- The default Tutor project root is different in Tutor Main. By default it is set to ``~/.local/share/tutor-main`` on Linux (instead of ``~/.local/share/tutor``). To modify this location check the :ref:`corresponding documentation <tutor_root>`.
+- The plugins root is set to ``~/.local/share/tutor-main-plugins`` on Linux (instead of ``~/.local/share/tutor-plugins``). This location may be modified by setting the ``TUTOR_PLUGINS_ROOT`` environment variable.
+- The default docker-compose project name is set to ``tutor_main_local`` (instead of ``tutor_local``). This value may be modified by manually setting the ``LOCAL_PROJECT_NAME``.
+
+Making changes to Tutor Main
+----------------------------
+
+In general pull requests should be open on the "release" branch of Tutor: the "release" branch is automatically merged on the "main" branch at every commit, such that changes made to Tutor releases find their way to Tutor Main as soon as they are merged. However, sometimes you want to make changes to Tutor Main exclusively, and not to the Tutor releases. This might be the case for instance when upgrading the running version of a third-party service (for instance: Elasticsearch, MySQL), or when the release branch requires specific changes. In that case, you should follow the instructions from the :ref:`contributing` section of the docs, with the following differences:
+
+- Open your pull request on top of the "main" branch instead of "release".
+- Add a description of your changes by creating a changelog entry with `make changelog-entry`, as in the release branch.

docs/tutorials/nightly.rst

@@ -1,64 +1,8 @@
-.. _nightly:
-
-Running Open edX on the master branch ("nightly")
-=================================================
-
-Tutor was designed to make it easy for everyone to run the latest release of Open edX. But sometimes, you want to run the latest, bleeding-edge version of Open edX. This is what we call "running master", as opposed to running the release branch. Running the master branch in production is strongly **not** recommended unless you are an Open edX expert and you really know what you are doing. But Open edX developers frequently need to run the master branch locally to implement and test new features. Thus, Tutor makes it easy to run Open edX on the master branch: this is called "Tutor Nightly".
-
-Installing Tutor Nightly
-------------------------
-
-Running Tutor Nightly requires more than setting a few configuration variables: because there are so many Open edX settings, version numbers, etc. which may change between the latest release and the current master branch, Tutor Nightly is actually maintained as a separate branch of the Tutor repository. To install Tutor Nightly, you should install Tutor from the "nightly" branch of the source repository. To do so, run::
-
-    git clone --branch=nightly https://github.com/overhangio/tutor.git
-    pip install -e "./tutor[full]"
-
-As usual, it is strongly recommended to run the command above in a `Python virtual environment <https://docs.python.org/3/tutorial/venv.html>`__.
-
-In addition to installing Tutor Nightly itself, this will install automatically the nightly versions of all official Tutor plugins (which are enumerated in `plugins.txt <https://github.com/overhangio/tutor/tree/nightly/requirements/plugins.txt>`_). Alternatively, if you wish to hack on an official plugin or install a custom plugin, you can clone that plugin's repository and install it. For instance::
-
-    git clone --branch=nightly https://github.com/myorganization/tutor-contrib-myplugin.git
-    pip install -e ./tutor-contrib-myplugin
-
-Once Tutor Nightly is installed, you can run the usual ``tutor`` commands::
-
-    tutor dev launch
-    tutor dev run lms bash
-    # ... and so on
-
-Upgrading to the latest version of Open edX
--------------------------------------------
+:orphan:
 
-To pull the latest upstream changes, you should first upgrade Tutor Nightly::
-
-    cd ./tutor
-    git pull
-
-Then, you will have to generate a more recent version of the nightly Docker images. Images for running Tutor Nightly are published daily to docker.io (see `here <https://hub.docker.com/r/overhangio/openedx/tags?page=1&ordering=last_updated&name=nightly>`__). You can fetch the latest images with::
-
-    tutor images pull all
-
-Alternatively, you may want to build the images yourself. As usual, this is done with::
-
-        tutor images build all
-
-However, these images include the application master branch at the point in time when the image was built. The Docker layer caching mechanism might cause the ``git clone`` step from the build to be skipped. In such cases, you will have to bypass the caching mechanism with::
-
-    tutor images build --no-cache all
-
-Running Tutor Nightly alongside the latest release
---------------------------------------------------
-
-When running Tutor Nightly, you usually do not want to override your existing Tutor installation. That's why a Tutor Nightly installation has the following differences from a regular release installation:
-
-- The default Tutor project root is different in Tutor Nightly. By default it is set to ``~/.local/share/tutor-nightly`` on Linux (instead of ``~/.local/share/tutor``). To modify this location check the :ref:`corresponding documentation <tutor_root>`.
-- The plugins root is set to ``~/.local/share/tutor-nightly-plugins`` on Linux (instead of ``~/.local/share/tutor-plugins``). This location may be modified by setting the ``TUTOR_PLUGINS_ROOT`` environment variable.
-- The default docker-compose project name is set to ``tutor_nightly_local`` (instead of ``tutor_local``). This value may be modified by manually setting the ``LOCAL_PROJECT_NAME``.
-
-Making changes to Tutor Nightly
--------------------------------
+.. _nightly:
 
-In general pull requests should be open on the "master" branch of Tutor: the "master" branch is automatically merged on the "nightly" branch at every commit, such that changes made to Tutor releases find their way to Tutor Nightly as soon as they are merged. However, sometimes you want to make changes to Tutor Nightly exclusively, and not to the Tutor releases. This might be the case for instance when upgrading the running version of a third-party service (for instance: Elasticsearch, MySQL), or when the master branch requires specific changes. In that case, you should follow the instructions from the :ref:`contributing` section of the docs, with the following differences:
+Obsolete: Tutor nightly
+=======================
 
-- Open your pull request on top of the "nightly" branch instead of "master".
-- Add a description of your changes by creating a changelog entry with `make changelog-entry`, as in the master branch.
+The "nightly" branch was renamed to "main". See :ref:`Tutor Main <main>`.

tutor/__about__.py

@@ -6,8 +6,8 @@
 
 # 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 "nightly" in
-# the nightly branch.
+# the versions from other branches. For instance: set the suffix to "main" in
+# the main branch.
 # The suffix is cleanly separated from the __version__ in this module to avoid
 # conflicts when merging branches.
 __version_suffix__ = "nightly"
@@ -19,7 +19,7 @@
 __app__ = os.environ.get("TUTOR_APP", "tutor")
 
 # Package version, as installed by pip, does not include the version suffix.
-# Otherwise, nightly plugins will automatically install non-nightly Tutor
+# Otherwise, Tutor Main plugins will automatically install non-Main Tutor
 # version.
 __package_version__ = __version__