docs: iterating

oeps/architectural-decisions/oep-0057-cores-and-extensions.rst

@@ -31,23 +31,7 @@ OEP-57: Cores and Extensions
 Abstract
 ********
 
-We designate four classes of Open edX repositories:
-
-1. logistical repositories,
-2. kernel repositories,
-3. bundled extension repositories,
-4. official extension repositories, and
-5. unofficial extension repositories.
-
-We mandate that:
-
-* The `openedx GitHub organization` shall contain precisely classes 1-4.
-* All code in the `openedx GitHub organization` is subject the decisions made in OEPs.
-* The Open edX Named Release shall include classes 2-4.
-* The *Core Product Offering*, as defined by the Product Working Group, shall be supported by the code in classes 2-3.
-* The *Exteneded Product Offering*, as defined by the Product Working Group, shall be supported by the code in classes 2-4.
-
-.. _openedx GitHub organization: https://github.com/openedx
+.. to do
 
 
 Motivation
@@ -56,13 +40,178 @@ Motivation
 The Open edX project is comprised of nearly two hundred repositories that, together, contain millions of lines of code.
 Each repository increases the effort required to maintain the project and the cognitive load required to understand the project.
 
+.. to do
+
 
 Specification
 *************
 
-.. The specification describes the technical details of the Architecture, Best
-.. Practice or Process proposed by the OEP. If the proposal includes a new API,
-.. specify its syntax and semantics.
+
+Product Offerings
+=================
+
+The Open edX Product Working Group (PWG) shall create and maintain two product specifications:
+the **Core Product Offering** and the **Extended Product Offering**.
+The PWG may document these specifications in any format, provided that:
+
+* they are always easy-to-find and publicly visible,
+* they are reviewed and updated at least every six months, and
+* a public revision history is maintained.
+
+Core Product Offering
+---------------------
+
+This is an articulation of which features should come fully supported by the community Open edX installation *without any additional configuration steps*. In other words, it is the desired "out-of-the-box" Open edX experience. Ensuring the support, maintenance, security, and quality of these features is of highest priority to the Open edX community.
+
+Extended Product Offering
+-------------------------
+
+This is an articulation of which features should come supported by the community Open edX installation *without installing any additional software*, although configuration (overriding settings, toggling Waffle flags, etc.) may be necessary. By definition, this is a superset of the Core Product Offering. Ensuring the support, maintenance, security, and quality of these features is important, although secondary to ensuring so for the features in the Core Product Offering.
+
+
+Repository Tiers
+================
+
+Based on the Product Offering specifications,
+we designate four tiers of Open edX repositories:
+
+1. **Clerical** repositories exist solely to help manage the Open edX project itself.
+   For example, they may contain process documentation,
+   hold code for project administration tools,
+   or serve as a task-tracking repository.
+   However, they may *not* contain code or documentation intended for *users* of
+   Open edX, whether that be operators, educators, or otherwise.
+
+2. **Kernel** repositories are necessary and sufficient to run a functioning
+   instance of the Open edX LMS. In other words, the Kernel is the minimal set of
+   repositories upon which Open edX depends. We recognize that it is ideal
+   to minimize the size of this tier over time.
+   (At the time of writing, this includes edx-platform
+   and every Open edX repository upon which edx-platform has a hard dependency,
+   of which they are currently very many.)
+
+3. **Bundled** repositories, together with the kernel repositories,
+   are necessary and sufficient to support the Core Product Offering.
+   In other words, bundled repositories are part of the core product, but are
+   not strictly necessary in order to run the LMS. For example, several
+   XBlocks may be core to the Open edX product but may not be requirements of the LMS;
+   they would be considered bundled repositories.
+
+4. **Supplemental** repositories, together with the kernel and bundled repositories,
+   are necessary and sufficient to support the Extended Product Offering.
+   In other words, supplemental repositories are part of the extended product
+   but no the core product. For example, a micro-service that operators could optionally
+   enable in the Open edX community release would be considered a supplemental repository.
+
+5. **External** repositories describe all remaining repositories related to Open edX.
+   They are neither used in the Extended Product Offering nor for clerical purposes.
+   There are an unbounded number of repositories in this tier.
+
+
+Repository Kinds
+================
+
+Depending on how a repository is used, we release it to the community in
+one of two different ways:
+
+* **Primary** repositories are the entry points for software that deploys and runs Open edX. These include:
+
+  * backend services,
+  * frontend applications,
+  * optional plugins that are *not* listed as explicit requirements by other repositories,
+  * tools that are *not* invoked by other repositories, and
+  * top-level documentation projects.
+
+* **Secondary** repositories are referenced and used by primary repositories,
+  either by numerical version or by git hash. These include:
+
+  * libraries that are listed as explicit requirements by other repositories,
+  * tools that are loaded and used by other repositories, and
+  * documentation that is included into another documentation project.
+
+Note that a reposity's "kind" is just a tactical technical distinction;
+it does not indicate the repository's importance, support level, or anything else qualitative.
+
+
+
+Repository Support Levels
+=========================
+
+.. todo table
+
+We designate seven support levels for repositories powering the Extended Product Offering
+(that is: kernel, bundled and supplemental repositories):
+
+.. list-table::
+   :header-rows: 1
+
+   * - Support Level
+     - Open edX release?
+     - Production ready?
+     - Forwards compatibility?
+     - Documention?
+     - Continuous improvement?
+     - Community support?
+   * - **Pre-Alpha**
+     - ❌ Not in release
+     - ❌ Not ready
+     - ❌ Frequent breaking changes
+     - ❌ Sparse
+     - ✔️  Yes
+     - ❌ No support
+   * - **Alpha**
+     - ✔️  In release
+     - ⚠️  Ready for early adopters, expect issues
+     - ❌ Frequent breaking changes
+     - ⚠️  Basic documentation
+     - ✔️  Yes
+     - ⚠️  Low-priority support
+   * - **Beta**
+     - ✔️  In release
+     - ✔️  Ready for general use, but expect some issues.
+     - ⚠️  Expect some (communicated) breaking changes
+     - ⚠️  Mostly documented
+     - ⚠️  Some
+     - ✔️  Supported
+   * - **Stable**
+     - ✔️  In release
+     - ✔️  Ready for general use
+     - ✔️  Breaking changes are minimized & communicated 
+     - ✔️  Documented
+     - ⚠️  Some
+     - ✔️  Supported
+   * - **Sustained**
+     - ✔️  In release
+     - ✔️  Still good for general use
+     - ✔️  Breaking changes are minimized & communicated 
+     - ✔️  Documented
+     - ❌ Little or none
+     - ✔️  Supported
+   * - **Deprecated**
+     - ✔️  In release
+     - ⚠️  Suitable, but migration encouraged
+     - ❌ Expect upcoming removal
+     - ⚠️  Might be documented
+     - ❌ Little or none
+     - ❌ No support guarantee
+
+.. 1. **Alpha** repositories are available for production trial by early adopters,
+..    but instability should be anticipated and significant breaking changes should
+..    be expected between releases. Documentation will provided when possible, but
+..    due to the repository's frequent change rate, may not be comprehensive.
+..    Support may be provided by maintainers but is not guaranteed.
+.. 2. **Beta** repositories are ready for production use,
+..    Documentation should be mostly complete.
+..    Maintainers should provide support.
+.. 3. **Stable** repositories are ideal for production use.
+..    Complete documentation should be available and maintainers should provide support.
+..    Breaking changes should be be minimized and notified with
+..    adequate lead time between releases.
+
+
+.. _openedx GitHub organization: https://github.com/openedx
+
+.. to do
 
 Rationale
 *********