OEP-67: Standard Tools and Technologies#
Tools and Technology Standards
Feanil Patel <firstname.lastname@example.org>
Braden MacDonald <email@example.com>
2023-09-05 - 2023-10-10
The Open edX Platform is built using many first- and third-party tools and technologies. This document covers the current recommendations for which tools and technologies should be used.
The Open edX platform has a lot of first and third party tools and technology that it uses. The problems we’re trying to solve are:
It is difficult to know the current best practice for a given area.
It is unclear how to go about the discussion and decision-making process to change a best practice.
OEP-11 serves as a great example for the usefulness of this kind of OEP but limits itself to be relevant only to frontend technologies. This OEP would supersede OEP-11 and encompass not only front-end technology but any technology that:
Is considered a best practice for the Open edX Platform
Is relevant to a large subset of the Open edX Platform
We’ll fill this out before the OEP lands but leaving mostly blank for initial feedback.
General Technology Selection#
This technology is not specific to frontend or backend code.
Codecov should be used to report code coverage by unit tests
Rationale: It is important to measure the amount of code covered by our automated test suites. By striving for a high level of test coverage, we can reduce the number of bugs that can only be found via manual testing, and by using codecov to run coverage in CI, contributors are automatically reminded to include tests for any new code.
The Open edX community has standardized around Codecov as a coverage reporting service.
Use Github actions for CI Testing
Rationale: As a healthy open source project we need good continuous integration testing to prevent the introduction of obvious bugs into the platform code. The Github Actions tool should be used to perform Continuous Integration (CI) testing for all Open edX repositories that perform any sort of software testing.
Frontend Technology Selection#
Rationale: React must be used for building new UIs, as it is widely adopted by the community and strikes a balance between flexibility and feature richness.
When building in existing Django server-rendered pages, one can use the react_render helper method to bridge to React. This bridge provides an easy way to pass data into a React component from Django via props. For more information about react_render see ReactRender.
For state management of complex client-side interactions, Redux must be used. This library was chosen because it sees strong use in the React community, but is also flexible enough to be used in situations where a hybrid React/Backbone architecture exists.
Use Jest and React-Testing-Library to test React components
We use Jest and React-Testing-Library to test React components. We are deprecating the Enzyme library. New tests must not use Enzyme, and any repositories planning to move to React 18 or newer need to replace Enzyme.
Exception: Much of edX’s existing front end code is written conformant to the edition of ECMA-262 released in 2009 (ES5). Files written in ES5 should be gradually converted to the newer standard as new development in those feature areas requires.
Note: edX previously used CoffeeScript, but its use has now been deprecated. Community interest in TypeScript has also grown, but it and other languages that do not follow the ECMA-262 spec should not be used.
Keep dependencies up to date by using Greenkeeper
Rationale: Webpack is the tool of choice for code optimization and bundling, as it is widely used throughout the industry, and because it seamlessly handles modern code bases as well as all of the older technologies used by edX, such as AMD Modules. Webpack should be implemented to handle as much of the “asset pipeline” as possible, rather than passing this responsibility on to Django.
CSS should be generated using SCSS
Rationale: Sass’s SCSS syntax is an extension of CSS that adds power and elegance to the basic language. It makes the maintenance of large CSS files more manageable though the ability to use variables, mixins, imports and more. In particular, it makes theming possible with the ability to override variables that define colors, fonts etc.
You can find out more about Sass in the official Sass documentation.
API calls should be made with the edX Frontend Auth Client or Axios
Rationale: The edX Frontend Auth Client simplifies the process of talking to edX APIs by using Axios interceptors and handling JWT Cookie authentication. It also provides React components to handle private routes and should be used when possible. When making calls to non-edX APIs Axios should be used to provide a consistent API.
The fetch API was considered but Axios was chosen for its more intuitive API, particularly when handling HTTP errors with rejected promises.
Server-side content should be rendered with Django Templates
Rationale: Although it is advised to use client side templating with React, see Use React and Redux, when rendering on the server Django templates should be used. There are many template languages available for Django, but the simplest option is to use the built-in Django template engine. The Open edX codebase has a mixture of Django and Mako templates, but the former are easier to reason about because they don’t support arbitrary code evaluation.
Exception: Mako templates can continue to be used within edx-platform for consistency with the existing code base. This is because the base templates and theming support are all provided via Mako, so it is too much to expect a new feature to be implemented with a different framework. There is much desire to replace Mako within edx-platform so this exception may eventually be removed.
Backend Technology Selection#
This section will cover any technology or tools that are not considered a part of the frontend.
This section lists the decision records for any time a standard technology has been change in the system along with the reasons why and the alternatives considered.
- 1. Use React
- 2. Use Redux
- 3. Use Jest and React-Testing-Library to test React components
- 5. Render server-side content with Django Templates
- 6. Use Codecov to measure code covered by tests
- 7. Use BundleWatch to automate bundle size checking
- 8. Use TypeScript for static type checking
OEP-11 will be superseded.
All ADRs under OEP-11 will be moved to be under this OEP instead.
Future decisions for technology changes will require an ADR and an update to this OEP
The tech radar will serve as a snapshot of the current state of those decisions and to simplify making changes, we will co-locate it with the supporting documents for this OEP.