docs: [OEP-67] TypeScript for static type checking

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/

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 <Reasons for rejecting 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