From 0ec4e09b935e5a395d9489b135131da411e4d7be Mon Sep 17 00:00:00 2001 From: Taranjeet Singh Date: Fri, 7 Sep 2018 00:29:28 +0530 Subject: [PATCH 1/6] Add OEP 29: Real Time Theming. --- oeps/oep-0029-arch-real-time-theming.rst | 76 ++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 oeps/oep-0029-arch-real-time-theming.rst diff --git a/oeps/oep-0029-arch-real-time-theming.rst b/oeps/oep-0029-arch-real-time-theming.rst new file mode 100644 index 000000000..023e5cf1f --- /dev/null +++ b/oeps/oep-0029-arch-real-time-theming.rst @@ -0,0 +1,76 @@ +=========================== +OEP-0029: Real Time Theming +=========================== + ++-----------------+----------------------------------------------------------------+ +| OEP | :doc:`OEP-0029 ` | +| | | +| | | +| | | +| | | ++-----------------+----------------------------------------------------------------+ +| Title | Real Time Theming | ++-----------------+----------------------------------------------------------------+ +| Last Modified | 2018-09-06 | ++-----------------+----------------------------------------------------------------+ +| Authors | Matjaz Gregoric , | +| | Taranjeet Singh | ++-----------------+----------------------------------------------------------------+ +| Arbiter | | ++-----------------+----------------------------------------------------------------+ +| Status | Draft | ++-----------------+----------------------------------------------------------------+ +| Type | Architecture | ++-----------------+----------------------------------------------------------------+ +| Created | 2018-09-06 | ++-----------------+----------------------------------------------------------------+ +| `Review Period` | 2018-09-06 - 2018-09-23 | ++-----------------+----------------------------------------------------------------+ + +Abstract +------- + +OEP-0023 [1] addresses the styling part of a theming system based on React. This proposal adds guidelines to allow updating theme dynamically and develop features that will allow to apply any theme from Open edX interface. + +Context +------- + +In Open edX style changes are currently applied by overriding sass variables and adding custom sass/css. This will remain true even after the switch to the new theming system based on edx-bootstrap. This further means that sass recompilation is required for typical style changes. In OEP-0023 [1], one of the consequences is listed as “The Open edX platform’s static asset size and build times will be greatly reduced.” This holds true as ``paver update_assets`` takes around 8 minutes on Hawthorn sandboxes. + +There is no reasonable way to avoid sass recompilation, since sass variables are used in multiple sass files in various repositories. The variables are not merely used as CSS values, but are also used in sass logic and computations. Simply generating a CSS file that overrides styles from the platform is therefore not reasonable. + +At times, multiple version of edx-platform are needed to run in parallel and so the theming system should make sure that the stylesheets don't conflict with each other. For example, when upgrading from one Open edX release to the next, we want to make sure that deploying appserver for the next release won’t suddenly make the old appservers use the new release’s stylesheets. + +Decision +-------- + +A dynamic theming system will work in the following way. + +* All stylesheets that are produced by sass compilation will be stored using the django File storage API. Files will be stored on local filesystem in devstack and on S3/Swift in production environment. This will allow the django app to use the most recently compiled stylesheets without having to run sass recompilation on all edxapp VMs. + +* A stylesheet would be named as a compound key consisting of ``site_id``, ``sass_overrides_id``,`` stylesheet_name`` and ``input_sass_md5``. This will keep the styles consistent and allow using multiple versions. + +* The ``sass_overrides_id`` field is a foreign key that points to customized sass variables. The sass overrides table will be similar to site configurations table in that any update will produce a new immutable record, with a new ID. Each record will have a status field that can be used for preview/publish control. We will reuse the existing LMS preview subdomain for previewing pending updates to the theme. + +* The ``input_sass_md5`` values is the MD5 hash of the raw contents of the sass input files (without the overrides). The ``input_sass_md5`` will change from release to release and will be used in aggressive caching. + +* Admin users will be able to override default values of edx-bootstrap sass variables from the django admin. The custom values get stored to the database. + +* Admin will click on “Update Theme” button once sass variables tweaking is finished. This will launch sass recompilation step in the background via a celery task. Sass compilation will use sass variables from the database. While sass compilation is in progress, the UI will display a notice and prevent user from triggering another recompilation until the current one completes. + +* When sass compilation completes, it will write the new stylesheets to storage, where django picks them up and starts using the new stylesheets. + +* The value of ``input_sass_md5`` calculated will be used to decide which file CSS file to read from the storage via any repository code. + +* When deploying a new instance, sass will still be complied using overridden values from the database. This will ensure that stylesheets are generated as part of the deployment process and not triggered via any admin action. The MD5 hashes will ensure that complied stylesheets don't interfere with each other. + +Consequences +------------ + + + +References +---------- + +1. OEP-0023 Style Customization + https://open-edx-proposals.readthedocs.io/en/latest/oep-0023-style-customization.html From a4c12809e67175f87b09e85735a73f188f1cda4c Mon Sep 17 00:00:00 2001 From: Taranjeet Singh Date: Mon, 17 Sep 2018 12:41:52 +0530 Subject: [PATCH 2/6] Add consequences. --- oeps/oep-0029-arch-real-time-theming.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/oeps/oep-0029-arch-real-time-theming.rst b/oeps/oep-0029-arch-real-time-theming.rst index 023e5cf1f..b79521044 100644 --- a/oeps/oep-0029-arch-real-time-theming.rst +++ b/oeps/oep-0029-arch-real-time-theming.rst @@ -48,7 +48,7 @@ A dynamic theming system will work in the following way. * All stylesheets that are produced by sass compilation will be stored using the django File storage API. Files will be stored on local filesystem in devstack and on S3/Swift in production environment. This will allow the django app to use the most recently compiled stylesheets without having to run sass recompilation on all edxapp VMs. -* A stylesheet would be named as a compound key consisting of ``site_id``, ``sass_overrides_id``,`` stylesheet_name`` and ``input_sass_md5``. This will keep the styles consistent and allow using multiple versions. +* A stylesheet would be named as a compound key consisting of ``site_id``, ``sass_overrides_id``, ``stylesheet_name`` and ``input_sass_md5``. This will keep the styles consistent and allow using multiple versions. * The ``sass_overrides_id`` field is a foreign key that points to customized sass variables. The sass overrides table will be similar to site configurations table in that any update will produce a new immutable record, with a new ID. Each record will have a status field that can be used for preview/publish control. We will reuse the existing LMS preview subdomain for previewing pending updates to the theme. @@ -67,7 +67,7 @@ A dynamic theming system will work in the following way. Consequences ------------ - +It's true that the real time theming systems are valuable and ideal from an admin/maintainer experience standpoint, but the technical complexity involved in enabling it for new and legacy systems may be a burden. References ---------- From c051573c642fa2435a11364fade879084e446ff0 Mon Sep 17 00:00:00 2001 From: Taranjeet Singh Date: Tue, 18 Sep 2018 16:18:52 +0530 Subject: [PATCH 3/6] Update proposal name to Near Real Time Theming. --- ...ng.rst => oep-0029-arch-near-real-time-theming.rst} | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename oeps/{oep-0029-arch-real-time-theming.rst => oep-0029-arch-near-real-time-theming.rst} (96%) diff --git a/oeps/oep-0029-arch-real-time-theming.rst b/oeps/oep-0029-arch-near-real-time-theming.rst similarity index 96% rename from oeps/oep-0029-arch-real-time-theming.rst rename to oeps/oep-0029-arch-near-real-time-theming.rst index b79521044..e10945dc7 100644 --- a/oeps/oep-0029-arch-real-time-theming.rst +++ b/oeps/oep-0029-arch-near-real-time-theming.rst @@ -1,15 +1,15 @@ -=========================== -OEP-0029: Real Time Theming -=========================== +================================ +OEP-0029: Near Real-Time Theming +================================ +-----------------+----------------------------------------------------------------+ -| OEP | :doc:`OEP-0029 ` | +| OEP | :doc:`OEP-0029 ` | | | | | | | | | | | | | +-----------------+----------------------------------------------------------------+ -| Title | Real Time Theming | +| Title | Near Real-Time Theming | +-----------------+----------------------------------------------------------------+ | Last Modified | 2018-09-06 | +-----------------+----------------------------------------------------------------+ From dc0f763c891d2d0ce3f695c8a58cfec95be04c04 Mon Sep 17 00:00:00 2001 From: Taranjeet Singh Date: Tue, 18 Sep 2018 16:20:04 +0530 Subject: [PATCH 4/6] Remove point about input_sass_md5 --- oeps/oep-0029-arch-near-real-time-theming.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/oeps/oep-0029-arch-near-real-time-theming.rst b/oeps/oep-0029-arch-near-real-time-theming.rst index e10945dc7..1c2d7fddb 100644 --- a/oeps/oep-0029-arch-near-real-time-theming.rst +++ b/oeps/oep-0029-arch-near-real-time-theming.rst @@ -60,8 +60,6 @@ A dynamic theming system will work in the following way. * When sass compilation completes, it will write the new stylesheets to storage, where django picks them up and starts using the new stylesheets. -* The value of ``input_sass_md5`` calculated will be used to decide which file CSS file to read from the storage via any repository code. - * When deploying a new instance, sass will still be complied using overridden values from the database. This will ensure that stylesheets are generated as part of the deployment process and not triggered via any admin action. The MD5 hashes will ensure that complied stylesheets don't interfere with each other. Consequences From 5ddfa54ace8a16a1f2dc5425e7dee1ec74a2ce35 Mon Sep 17 00:00:00 2001 From: Taranjeet Singh Date: Tue, 18 Sep 2018 16:23:26 +0530 Subject: [PATCH 5/6] Update consequences. --- oeps/oep-0029-arch-near-real-time-theming.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/oeps/oep-0029-arch-near-real-time-theming.rst b/oeps/oep-0029-arch-near-real-time-theming.rst index 1c2d7fddb..c164976c7 100644 --- a/oeps/oep-0029-arch-near-real-time-theming.rst +++ b/oeps/oep-0029-arch-near-real-time-theming.rst @@ -60,12 +60,12 @@ A dynamic theming system will work in the following way. * When sass compilation completes, it will write the new stylesheets to storage, where django picks them up and starts using the new stylesheets. -* When deploying a new instance, sass will still be complied using overridden values from the database. This will ensure that stylesheets are generated as part of the deployment process and not triggered via any admin action. The MD5 hashes will ensure that complied stylesheets don't interfere with each other. +* When deploying a new instance, sass will still get automatically complied using overridden values from the database. This will ensure that stylesheets are generated as part of the deployment process and not triggered via any admin action. The MD5 hashes will ensure that complied stylesheets don't interfere with each other. Consequences ------------ -It's true that the real time theming systems are valuable and ideal from an admin/maintainer experience standpoint, but the technical complexity involved in enabling it for new and legacy systems may be a burden. +It's true that the real time theming systems are valuable and ideal from an admin/maintainer experience standpoint. Site administrators will be able to change the look of Open edX without having to write theme code and redeploy their instance. References ---------- From 1d8fb8ba24a550db9232bd6932c38430298924d4 Mon Sep 17 00:00:00 2001 From: Taranjeet Singh Date: Thu, 20 Sep 2018 09:37:55 +0530 Subject: [PATCH 6/6] Update consequence. --- oeps/oep-0029-arch-near-real-time-theming.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/oeps/oep-0029-arch-near-real-time-theming.rst b/oeps/oep-0029-arch-near-real-time-theming.rst index c164976c7..78ce337f6 100644 --- a/oeps/oep-0029-arch-near-real-time-theming.rst +++ b/oeps/oep-0029-arch-near-real-time-theming.rst @@ -65,7 +65,7 @@ A dynamic theming system will work in the following way. Consequences ------------ -It's true that the real time theming systems are valuable and ideal from an admin/maintainer experience standpoint. Site administrators will be able to change the look of Open edX without having to write theme code and redeploy their instance. +Real time theming systems are valuable and ideal from an admin/maintainer experience standpoint. Site administrators will be able to change the look of Open edX without having to write theme code and redeploy their instance. References ----------