From f71d62cd46797a78be384e73f6577913ea599014 Mon Sep 17 00:00:00 2001 From: Brian Smith Date: Wed, 13 Sep 2023 13:07:28 -0400 Subject: [PATCH] docs: [OEP-67] TypeScript for static type checking --- .../decisions/frontend/0004-js-ecma.rst | 33 +++++++------ .../decisions/frontend/0007-typescript.rst | 47 +++++++++++++++++++ 2 files changed, 65 insertions(+), 15 deletions(-) create mode 100644 oeps/best-practices/oep-0067/decisions/frontend/0007-typescript.rst diff --git a/oeps/best-practices/oep-0067/decisions/frontend/0004-js-ecma.rst b/oeps/best-practices/oep-0067/decisions/frontend/0004-js-ecma.rst index 5658e4466..16ac67c53 100644 --- a/oeps/best-practices/oep-0067/decisions/frontend/0004-js-ecma.rst +++ b/oeps/best-practices/oep-0067/decisions/frontend/0004-js-ecma.rst @@ -28,25 +28,28 @@ Rejected Alternatives .. _Reasons for rejecting CoffeeScript: -1. **CoffeeScript** +CoffeeScript +============ - The Open edX codebase made heavy use of CoffeeScript for several years, - but its use at edX has now been officially deprecated. Most of the language - benefits of CoffeeScript were made available in JavaScript as of the ES2015 spec, - and CoffeeScript's community has largely moved on. +The Open edX codebase made heavy use of CoffeeScript for several years, +but its use at edX has now been officially deprecated. Most of the language +benefits of CoffeeScript were made available in JavaScript as of the ES2015 spec, +and CoffeeScript's community has largely moved on. .. _Reasons for rejecting TypeScript: -2. **TypeScript** - - Several variants of typed JavaScript have grown in community popularity - recently, with `TypeScript`_ as the most popular. edX believes adding - typing to our JavaScript would raise the barrier to entry for less - experienced front end developers, and that using TypeScript in particular - would lock us into a tool with an uncertain future (as we experienced with - CoffeeScript). If typing is an absolute necessity for a feature - (e.g., an API client or sensitive business logic), `Flow`_ is recommended, - as it can be incrementally added and evaluated alongside non-typed code. +TypeScript +========== + +Several variants of typed JavaScript have grown in community popularity +recently, with `TypeScript`_ as the most popular. The Open edX community +believes adding typing to our JavaScript would raise the barrier to entry +for less experienced front end developers, and that using TypeScript in +particular would lock us into a tool with an uncertain future (as we +experienced with CoffeeScript). If typing is an absolute necessity for a +feature (e.g., an API client or sensitive business logic), `Flow`_ is +recommended, as it can be incrementally added and evaluated alongside +non-typed code. .. _Flow: https://flow.org/ .. _Typescript: https://www.typescriptlang.org/ diff --git a/oeps/best-practices/oep-0067/decisions/frontend/0007-typescript.rst b/oeps/best-practices/oep-0067/decisions/frontend/0007-typescript.rst new file mode 100644 index 000000000..260dc86c9 --- /dev/null +++ b/oeps/best-practices/oep-0067/decisions/frontend/0007-typescript.rst @@ -0,0 +1,47 @@ +Use TypeScript for static type checking +####################################### + +Status +****** + +Accepted + +Context +******* + +As documented in :doc:`OEP-0011-0004 <0004-js-ecma>`, the Open edX community has previously +:ref:`decided against adopting TypeScript `. In the time +since that decision was made, TypeScript has grown to be quite popular and commonplace for JavaScript developers. +This has led to more discussion within the community about the `pros and cons of adopting TypeScript`_. + +Decision +******** + +Considering the benefits of TypeScript, such as the ability to ensure proper API usage +through type definitions and to catch bugs at build time, the Open edX community has decided +to incorporate TypeScript into frontend repositories. + +Frontend repositories within the Open edX project will be updated to support the use of TypeScript, without +requiring existing frontend JavaScript code to be rewritten in TypeScript. + +Consequence +*********** + +TypeScript will be utilized in portions of frontend repositories where it can provide the most value. + +Rejected Alternatives +********************* + +1. **Continue without TypeScript** + + It is possible to use other tools to add some of the functionality TypeScript provides + to JavaScript code. However, considering the main point of opposition to TypeScript adoption + was keeping a low barrier of entry for frontend developers, this could be counterproductive. + +2. **Rewrite Open edX JavaScript in TypeScript** + + It would be possible to convert all JavaScript throughout the Open edX project (or any given + repository within the project) to TypeScript. It is not clear what the benefit of doing so would + be. + +.. _pros and cons of adopting TypeScript: https://github.com/openedx/paragon/discussions/1186