Merge pull request #1001 from primer/typescript-adr

TypeScript ADR

contributor-docs/adrs/adr-001-typescript.md

@@ -0,0 +1,23 @@
+# ADR 1: TypeScript
+
+## Status
+
+Approved 2021-01-15
+
+## Context
+
+Primer React components was originally released without TypeScript type definitions, making it difficult for engineers to consume the library in TypeScript applications. In [July 2019](https://github.com/primer/components/commit/2983c935ea9ad600c04078adb25e40c3624c11fa#diff-7aa4473ede4abd9ec099e87fec67fd57afafaf39e05d493ab4533acc38547eb8), we created an [ambient declaration](https://www.geeksforgeeks.org/typescript-ambients-declaration/) file (`index.d.ts`) file to provide type definitions for TypeScript applications without having to rewrite Primer React components in TypeScript. 
+
+`index.d.ts` has been an effective stopgap, enabling teams to build complex applications with Primer React components and TypeScript. However, because `index.d.ts` is disconnected from the implementation code, we've struggled to keep the type definitions up-to-date and accurate, as evidenced by [many](https://github.com/primer/components/issues/906) [TypeScript](https://github.com/primer/components/issues/540) [bug](https://github.com/primer/components/issues/520) [reports](https://github.com/primer/components/issues/534). As the library continues to grow in size and complexity, manually maintaining type definitions will become unsustainable.
+
+## Decision
+
+We will rewrite Primer React components in TypeScript.
+
+## Consequences
+
+- Type definitions can be generated by the TypeScript compiler, eliminating bugs caused by hand-written type definitions.
+- Engineers can upstream components from other TypeScript projects at GitHub without having to remove type annotations, improving the contributor experience.
+- We can refactor components with increased confidence.
+- Component prop documentation can be generated by [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript), eliminating inaccurate and out-of-date hand-written prop documentation.
+- New contributors will need some familiarity with TypeScript in order to make code contributions.