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

docs: add use luxon date library adr

.github/styles/vocab.txt

@@ -115,6 +115,7 @@ Kumar
 learnings
 lerna
 Lerna
+Luxon
 magiclink
 mailto
 maintainership

docs/architecture-decisions/adr000-template.md

@@ -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
 
 <!--

docs/architecture-decisions/adr010-luxon-date-library.md

@@ -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

microsite/sidebars.json

@@ -183,7 +183,8 @@
       "architecture-decisions/adrs-adr006",
       "architecture-decisions/adrs-adr007",
       "architecture-decisions/adrs-adr008",
-      "architecture-decisions/adrs-adr009"
+      "architecture-decisions/adrs-adr009",
+      "architecture-decisions/adrs-adr010"
     ],
     "Contribute": ["../CONTRIBUTING"],
     "Support": ["support/support", "support/project-structure"],

mkdocs.yml

@@ -118,6 +118,7 @@ nav:
       - ADR007 - Use MSW for Network Request Mocking: 'architecture-decisions/adr007-use-msw-to-mock-service-requests.md'
       - ADR008 - Default Catalog File Name: 'architecture-decisions/adr008-default-catalog-file-name.md'
       - ADR009 - Entity References: 'architecture-decisions/adr009-entity-references.md'
+      - ADR010 - Luxon Date Library: 'architecture-decisions/adr010-luxon-date-library.md'
   - Contribute: '../CONTRIBUTING.md'
   - Support:
       - 'support/support.md'