hsec-sync: document usage

code/hsec-sync/CHANGELOG.md

@@ -0,0 +1,7 @@
+## 0.2.0.0
+
+* Rewrite, using `hsec-tools` snapshots
+
+## 0.1.0.0
+
+* Introduction, `git`-based

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)

code/hsec-sync/hsec-sync.cabal

@@ -1,6 +1,6 @@
 cabal-version:   2.4
 name:            hsec-sync
-version:         0.1.0.0
+version:         0.2.0.0
 
 -- A short (one-line) description of the package.
 synopsis:        Synchronize with the Haskell security advisory database
@@ -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
 
@@ -30,25 +30,25 @@ library
     Security.Advisories.Sync.Url
 
   build-depends:
-    , base         >=4.14  && <4.20
-    , aeson        >=2.0   && <2.3
-    , bytestring            >=0.10    && <0.13
-    , directory    >=1.3   && <1.4
-    , either       >=5.0   && <5.1
-    , extra        >=1.7   && <1.8
-    , feed         >=1.3   && <1.4
-    , filepath     >=1.4   && <1.5
-    , hsec-core    ^>= 0.2
-    , http-client  >=0.7.0 && <0.8
-    , lens         >=5.1   && <5.3
-    , tar          >=0.5   && <0.7
-    , tar-conduit  >=0.3   && <0.5
-    , text         >=1.2   && <3
-    , time         >=1.9   && <1.14
-    , temporary    ==1.*
-    , transformers >=0.5   && <0.7
-    , wreq         >=0.5   && <0.6
-    , zlib         >=0.6   && <0.8
+    , aeson         >=2.0   && <2.3
+    , base          >=4.14  && <4.20
+    , bytestring    >=0.10  && <0.13
+    , directory     >=1.3   && <1.4
+    , either        >=5.0   && <5.1
+    , extra         >=1.7   && <1.8
+    , feed          >=1.3   && <1.4
+    , filepath      >=1.4   && <1.5
+    , hsec-core     ^>=0.2
+    , http-client   >=0.7.0 && <0.8
+    , lens          >=5.1   && <5.3
+    , tar           >=0.5   && <0.7
+    , tar-conduit   >=0.3   && <0.5
+    , temporary     >=1     && <2
+    , text          >=1.2   && <3
+    , time          >=1.9   && <1.14
+    , transformers  >=0.5   && <0.7
+    , wreq          >=0.5   && <0.6
+    , zlib          >=0.6   && <0.8
 
   hs-source-dirs:   src
   default-language: Haskell2010
@@ -87,11 +87,11 @@ test-suite spec
   build-depends:
     , base         <5
     , directory
-    , hsec-sync
     , filepath
+    , hsec-sync
     , tasty        <1.5
     , tasty-hunit  <0.11
-    , temporary    ==1.*
+    , temporary    >=1   && <2
     , text
     , time