hsec-sync: add doc usage

haskell · Jul 30, 2024 · 674e0b0 · 674e0b0
1 parent 801740e
commit 674e0b0
Show file tree

Hide file tree

Showing 4 changed files with 23 additions and 1 deletion.
diff --git a/code/hsec-sync/README.md b/code/hsec-sync/README.md
@@ -5,3 +5,25 @@ Synchronize with the [Haskell advisories database](https://github.com/haskell/se
 ## Building
 
 We aim to support both regular cabal-based and nix-based builds.
+
+## Design
+
+[hsec-tools](../hsec-tools/) is the main entry point for dealing with [security advisories](https://github.com/haskell/security-advisories).
+
+Libraries implementors and services providers will mainly be interested by
+`Security.Advisories.Queries` and `hsec-tools query` which allows querying
+against a directory containing the advisories.
+
+There are two ways for maintaining this local directory up-to-date:
+
+* Manually (based on `git` of fetching archive from GitHub)
+* Relying on `hsec-sync` (either via `Security.Advisories.Sync.sync` or `hsec-sync sync`)
+
+![overview](./overview.png)
+
+The recommended workflow is:
+
+1. Use `hsec-sync` to ensure having an up-to-date advisories directory (created or updated)
+2. Use `hsec-tools` to perform queries against it
+
+![recommended-workflow](./recommended-workflow.png)
diff --git a/code/hsec-sync/hsec-sync.cabal b/code/hsec-sync/hsec-sync.cabal
@@ -19,7 +19,7 @@ maintainer:      [email protected]
 -- A copyright notice.
 -- copyright:
 category:        Data
-extra-doc-files: CHANGELOG.md
+extra-doc-files: CHANGELOG.md, overview.png, recommended-workflow.png
 tested-with:
   GHC ==8.10.7 || ==9.0.2 || ==9.2.8 || ==9.4.8 || ==9.6.3 || ==9.8.1
 

diff --git a/code/hsec-sync/overview.png b/code/hsec-sync/overview.png
diff --git a/code/hsec-sync/recommended-workflow.png b/code/hsec-sync/recommended-workflow.png