What I settled on, using [[Architecture Decision Records]] for my [[PDW]] re-write. # Type & Location - File_Type: Markdown - Location: `docs/adrs` - File_Names: `01 - option chosen name.md` ## Template ```markdown --- status: # accepted | proposed | superseded date: # ISO-8601 --- # <!-- short title, representative of solved problem and found solution --> ## Context and Problem Statement <!-- in a few sentences, what is the decision needed for --> ## Decision Drivers <!-- section optional --> * {decision driver 1, e.g., a force, facing concern, …} * {decision driver 2, e.g., a force, facing concern, …} * … <!-- numbers of drivers can vary --> ## Considered Options * <!-- chosen option --> * <!-- additional options --> ## Decision Outcome Chosen option: "", because ### Consequences * Good, because * Bad, because ### Confirmation <!-- section optional --> <!-- how to determine compliance with the decision --> ## Pros and Cons of the Options <!-- section optional --> ### <!-- title of option --> * Good, because * Neutral, because * Bad, because ## More Information <!-- section optional --> <!-- links and footnotes or whatever --> ``` - pull over ADRs ## Examples ### Full Example File name: `01 - Use Radix-36 Strings as Timestamps.md` ```markdown --- status: accepted date: 2024-08-21 --- # Use Radix-36 Strings as Timestamps ## Context and Problem Statement Elements in the PDW need to be timestamped with absolute references to *when* they were created & updated to enable data merging and general maintenance. Also PDW is meant to be uncoupled from and not bound to any **one** data tool. Different data tools approach timestamps differenty from one-another, and often are in conflict. Notably, Microsoft Excel causes problems with both storing timestamps as human-readable text dates and storing them as large numbers. A solution is needed to ensure a consistent canonical data model can be maintained without interpretation errors. The timestamp needs to be alphabetically sortable and relatively short. Also there is a desire for a lightweight solution that does not necessitate including large chunks of code for handling timestamping. ## Decision Drivers * Unambiguous * Portable * Tooling-independent * Consistent * Sortable ## Considered Options * Radix-36 Strings * ISO-8601 Strings ending with "Z" * ISO-8601 Strings ending with Timezone * ISO-8601 Strings using "wall clock" time ## Decision Outcome Chosen option: "Radix-36 Strings", because it is completely platform-independent and requires the same standard approach regardless of the tool being used. It is not interpreted by *any* tool as a date, therefore *every* tool will require translation into & out of. ### Consequences * Good, because they are portable, sortable, and consistent due to their tooling-independence * Bad, because they are not human-readable * Good, because they can be unambiguously to/from Dates with a single line of JS ## Pros and Cons of the Options ### Radix-36 Strings See Consequences, above. ### ISO-8601 Strings ending with "Z" * Good, because they are sortable and consistent * Good, because they are an ISO Standard * Neutral, because they are human-readable-*ish* * Bad, because they introduce timezone issues when the "Z" is imporperly handled * Bad, because *some* tools recognize them while others don't leading to inconsistency ### ISO-8601 Strings ending with Timezone * Good, because they are human-readable and consistent * Good, because they are an ISO Standard * Bad, because they are not sortable - **reason for rejection** * Bad, because they introduce timezone issues when the timezone suffix is imporperly handled * Bad, because *some* tools recognize them while others don't, leading to inconsistency ### ISO-8601 Strings using "wall clock" time * Good, because they are the most human-readable * Neutral, because they are ISO Standard-*ish* * Neutral, because they are consistent-*ish* * Bad, because they introduce timezone issues, which can be really difficult to correct * Bad, because they are not sortable due to timezone issues * Bad, because *some* tools recognize them while others don't, leading to inconsistency ## More Information The two lines of JavaScript necessary to translate in both directions. function makeEpochStrFrom(stringOrDate: string | Date): EpochStr | undefined { return new Date(stringOrDate).getTime().toString(36); } function parseDateFromEpochStr(epochStr: EpochStr): Date { return new Date(parseInt(epochStr, 36)) } ``` ### More Minimal Example File name: `02 - An Entry may utilize zero or many Defs.md` ```markdown --- status: accepted date: 2024-09-11 --- # An Entry may utilize zero or more Defs ## Context and Problem Statement The original formulation of the PDW used a 1:1 relationship for `Entry`s to `Def`s. An `Entry` was described by a single `Def`. `EntryPoints` were described by the `PointDefs` under that `Def`. This created the need for a 2-level hierarchy, which is not easy to manage via flat-files and introduced a lot of management overhead. ## Considered Options * An `Entry` may utilize zero or more `Def`s * An `Entry` has exactly one `Def`, with zero or mor `PointDefs` * An `Entry` has exactly one `Def`, and the `PointDef` concept is removed ## Decision Outcome Chosen option: "An `Entry` may utilize zero or more `Def`s", because it enables a consistent approach for all `Entry`s and the ability use very *natural* .csv files for storing, editing, and viewing data. It also removes the need for the common `Entry`-train occurrence where multiple `Entry`s were spawned for the same event *(e.g. New Experience + Ate Out + Went on a Date)*. ### Consequences * Good, because `Data Journal` now has a simpler, flat structure * Good, because the core data now lend themselves to PivotTables * Good, because multiple successive `Entry`s for the same event can now be one * Bad, because an `Entry` now is sparsely populated with an indeterminable set of expected keys * Bad, because there are strange `Def`s that don't make sense absent others (e.g. "Movie Is Rewatch" without "Movie title") ``` **** ## Source - Self ## Related - [[Architecture Decision Records]]