Merge pull request #3980 from andrewthauer/date-lib-adr

docs: add use luxon date library adr
2021-01-19 12:42:53 -05:00
parent 9ecb63a743 6878af026e
commit 54dd7b3003
5 changed files with 42 additions and 5 deletions
@@ -8,10 +8,6 @@ description: Architecture Decision Record (ADR) for [TITLE] [DESCRIPTION]

 <!-- These documents have names that are short noun phrases. For example, "ADR001: Deployment on Ruby on Rails 3.0.10" or "ADR009: LDAP for Multitenant Integration" -->

-## Status
-
-<!-- A decision may be "proposed" if the project stakeholders haven't agreed with it yet, or "accepted" once it is agreed. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement. -->
-
 ## Context

 <!--
@@ -0,0 +1,38 @@
+---
+id: adrs-adr010
+title: ADR010: Use the Luxon Date Library
+description: Architecture Decision Record (ADR) for Luxon Date Library
+---
+
+# ADR010: Use the Luxon Date Library
+
+## Context
+
+Date formatting (e.g. `a day ago`) and calculations are common within Backstage.
+Some of these useful features are not supported by the standard JavaScript
+`Date` object. The popular [Moment.js](https://momentjs.com/) library has been
+commonly used to fill this gap but suffers from large bundle sizes and mutable
+state issues. On top of this, `momentjs` is
+[being sunset](https://momentjs.com/docs/#/-project-status/) and the project
+recommends using one of the more modern alternative libraries.
+
+See
+[[RFC] Standardized Date & Time Library](https://github.com/backstage/backstage/issues/3401).
+
+## Decision
+
+We will use [Luxon](https://moment.github.io/luxon/index.html) as the standard
+date library within Backstage.
+
+`Luxon` provides a similar feature set and API to `Moment.js`, but improves on
+its design through immutability and the usage of modern JavaScript APIs (e.g.
+`Intl`). This results in smaller bundle sizes while providing a full feature set
+and avoids the need for using additional libraries for common date & time tasks.
+
+## Consequences
+
+- All core packages and plugins within Backstage should use `Luxon` for any date
+  manipulation or formatting that cannot be easily accomplished with the native
+  JavaScript `Date` object.
+- Using a single date library avoids having to learn multiple library APIs
+- Having a single date library will reduce bundle sizes