Prep for gemlogification

[rbdr/blog] / doc / specs / 20200601-serving-different-versions.md

diff --git a/doc/specs/20200601-serving-different-versions.md b/doc/specs/20200601-serving-different-versions.md
index 351cc8cbe13d85ecb0b11e3a6da59c655b66f72b..9eb1bd8b76e68be6ca372dd72907067bd272a7bf 100644 (file)
--- a/doc/specs/20200601-serving-different-versions.md
+++ b/doc/specs/20200601-serving-different-versions.md
@@ -73,8 +73,9 @@ Given I add a new entry to the blog, the entries will be updated.
 
 # Solution Proposal
 
-(Note: This solution is incomplete. We need to add guid and pubDate
-generation, as this is required for the RSS to be usable)
+We will add a new step in the creation process to create metadata for the
+post that will allow each post to be uniquely identified, as well as
+having a publish date related to them.
 
 We will split the current generator function into generators, and create
 a new generator that will generate an RSS 2.0 file
@@ -82,30 +83,56 @@ a new generator that will generate an RSS 2.0 file
 # Blackbox
 
 ```
-                      ┌─────────────────┐           ┌───────────────┐
-                      │                 │           │               │
-               ┌─────▶│ StaticGenerator │──────────▶│ Static Assets │
-               │      │                 │           │               │
-               │      └─────────────────┘           └───────────────┘
-┌───────┐      │      ┌───────────────┐             ┌───────────┐
-│       │      │      │               │             │           │
-│ Blog  │──────┼─────▶│ HTMLGenerator │────────────▶│ HTML File │
-│       │      │      │               │             │           │
-└───────┘      │      └───────────────┘             └───────────┘
-               │      ┌──────────────┐              ┌──────────┐
-               │      │              │              │          │
-               └─────▶│ RSSGenerator │─────────────▶│ RSS File │
-                      │              │              │          │
-                      └──────────────┘              └──────────┘
+                   ╔══════════════════════╗
+                   ║  When Adding a Post  ║
+                   ╚══════════════════════╝
+                      ┌───────────────┐          ┌───────────────┐
+                      │               │          │               │
+    ┌────────────────▶│ writeMetadata │─────────▶│ Metadata File │
+    │                 │               │          │               │
+    │                 └───────────────┘          └───────────────┘
+    │
+    │
+    │             ╔════════════════════════╗
+    │             ║ When Generating Output ║
+    │             ╚════════════════════════╝
+    │                 ┌─────────────────┐        ┌───────────────┐
+    │                 │                 │        │               │
+    │          ┌─────▶│ StaticGenerator │───────▶│ Static Assets │
+    │          │      │                 │        │               │
+    │          │      └─────────────────┘        └───────────────┘
+┌───────┐      │      ┌───────────────┐          ┌───────────┐
+│       │      │      │               │          │           │
+│ Blog  │──────┼─────▶│ HTMLGenerator │─────────▶│ HTML File │
+│       │      │      │               │          │           │
+└───────┘      │      └───────────────┘          └───────────┘
+               │      ┌──────────────┐           ┌──────────┐
+               │      │              │           │          │
+               └─────▶│ RSSGenerator │──────────▶│ RSS File │
+                      │              │           │          │
+                      └──────────────┘           └──────────┘
 ```
 
 # Theory of Operation
 
-When the generate function of the blog is triggered, it will iterate over
-a list of generator functions and call them with the source and target
-directories, and an array containing the parsed markdown from the post.
-Each generator function will do its work, throwing an exception if they
-encounter an error.
+## When Adding a Post
+
+When the add function of the blog is triggered, it will shift the posts
+as it currently does and then will generate a new unique ID and take the
+current timestamp. This will be saved in a JSON file in the output
+directory called "metadata.json"
+
+## When Generating Output
+
+When the generate function of the blog is triggered, it will iterate
+over every post. For each of them it will parse the markdown content,
+and the metadata, creating an object of type `tPost` and pushing it
+to an array.
+
+Next, it will iterate from a list of generator functions and call them
+with the source and target directories, and an array containing the `tPost`
+objects. Each generator function will do its work, throwing an exception
+if they encounter an error.
 
 When the static generator is called, it will remove the current assets
 directory in the target directory, and recursively copy the assets from
@@ -121,6 +148,22 @@ directory.
 
 # Technical Specification
 
+## The Post Data Structure
+
+This spec introduces a data structure to help generate output.
+
+```
+tPost <Object>
+  +html <String> // The markup of the post
+  +publishedOn <Number> // The timestamp when this post was added
+  +id <String> // The Unique ID for this post
+```
+
+Given that posts won't come in at a high enough rate, and that the
+purpouse is only to help feed readers identify each unique piece of
+content, for this version the `id` will be the same number as the
+`publishedOn`.
+
 ## The Generator Interface
 
 Every generator must implement this interface in order to work with