From ac2f9922dcb59c7d0e50a1e1beb6ce8b29e90093 Mon Sep 17 00:00:00 2001
From: Nemo <commits@captnemo.in>
Date: Wed, 24 Nov 2021 14:51:46 +0530
Subject: [PATCH] Document the schema structure

---
 HACKING.md | 39 +++++++++++++++++++++++++++++++++++++--
 README.md  |  8 ++++----
 2 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/HACKING.md b/HACKING.md
index fc0f8e5..0aceffa 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -1,6 +1,10 @@
 # HACKING
 
-`fingerprint.php` does all the work. Just run it. versions.txt is generated from a list of all usable tags on the electron repo. 
+There's two scripts:
+
+## `fingerprint.php`
+
+This downloads the relevant releases from GitHub, and generates hashes of all files contained within each release.
 
 This includes all releases that were not:
 
@@ -8,4 +12,35 @@ This includes all releases that were not:
 2. beta releases
 3. older than 0.24.0 (electron was called atom-shell before that)
 
-All generated hashes are kept in `hashes/`. The generated lookup table is saved at lookup.json
\ No newline at end of file
+All generated hashes are kept in `hashes/$version.json`. A sample snippet for the JSON structure:
+
+```json
+{
+    "LICENSE": "10bfa95a2f25df14dfe6a55a9e73d9fa5becdb60",
+    "LICENSES.chromium.html": "fa5b9f95d12b0044d6ae8dbf303ad46d43edea76",
+    "version": "0e2ef13d37fb9a81b63ab1babfa39635722366a3",
+    "Electron.app/Contents/PkgInfo": "9f9eea0cfe2d65f2c3d6b092e375b40782d08f31",
+}
+```
+
+## `lookup-table.php`
+
+This generates an inverted-lookup-table from all the hashes. So you can pass a hash and get a list of releases that specific hash was found in.
+These are stored in the following architecture specific files:
+
+- `lookup/darwin-arm64.json`
+- `lookup/darwin-x64.json`
+- `lookup/linux-arm64.json`
+- `lookup/linux-x64.json`
+- `lookup/win32-arm64.json`
+- `lookup/win32-x64.json`
+
+The schema for these files is fairly intuitive:
+
+```json
+{
+  "sha1_hash": ["list", "of", "versions"],
+  "sha1_hash": ["list", "of", "versions"]
+}
+```
+
diff --git a/README.md b/README.md
index 7827495..19a05a4 100644
--- a/README.md
+++ b/README.md
@@ -27,11 +27,11 @@ lookup['win32-x64']['baf786083f482c1f035e50e105b5f7475af1e00b']
 // ["v1.4.3", "v1.4.4", "v1.4.5"]
 ```
 
-You can sort or filter the returned versions if needed.
+You can sort or filter the returned versions if needed. If you'd like to access the raw data, see `HACKING.md` for a schema description.
 
 ## supported releases
 
-All Stable electron releases for the following architectures are fingerprinted:
+All *Stable* electron releases for the following architectures are fingerprinted:
 
 - linux-x64
 - linux-arm64
@@ -40,7 +40,7 @@ All Stable electron releases for the following architectures are fingerprinted:
 - win32-arm64 (Windows)
 - darwin-arm64 (Apple Silicon)
 
-A list of release fingerprints is under the `hashes` directory.
+A list of release fingerprints is under the `hashes` directory. Releases made when Electron was still called `atom-shell` are not supported (Before April 2015).
 
 ## which files are present?
 
@@ -100,4 +100,4 @@ electron
 
 Released under WTFPL.
 
-[we]: https://github.com/captn3m0/which-electron
\ No newline at end of file
+[we]: https://github.com/captn3m0/which-electron