Merge pull request #41 from IntersectMBO/coot/haddocks

Haddocks, docs & release scripts

Author: coot

.github/workflows/github-page.yml

@@ -30,9 +30,17 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
 
     steps:
+    - name: Install pandoc
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y pandoc
+
     - name: Checkout dmq-node repository
       uses: actions/checkout@v6
 
+    - name: Prologue
+      run: pandoc -f markdown -t haddock README.md -o README.haddock
+
       # we need nix to later build the spec documents
     - name: Install Nix
       uses: cachix/install-nix-action@v31
@@ -70,7 +78,7 @@ jobs:
 
     - name: Build documents
       run: |
-        cabal haddock-project --hackage all
+        cabal haddock-project --prologue=./README.haddock --hackage all
 
     - name: Upload artifacts
       uses: actions/upload-pages-artifact@v4

CONTRIBUTING.md

@@ -89,17 +89,11 @@ is very helpful to diagnose build time compiler errors.
 Any contributions should be well documented.  APIs should have well-written
 `haddocks`.  If a particular function expects a precondition to be satisfied it
 should be explicitly mentioned.  The inline documentation is published at
-
--- TODO link
-
-<https://ouroboros-network.cardano.intersectmbo.org>.  When writing haddocks
-it's always good to put oneself in the position of somebody who hasn't yet
+<https://dmq-node.cardano.intersectmbo.org>.  When writing haddocks it's always
+good to put oneself in the position of somebody who hasn't yet
 interacted with your code changes.  It's good to explain the key design choices
 as well as implementation-level comments.
 
-If changes would modify any existing design the contributor might be expected
-to be asked to also update the standalone documentation (written in `tex`).
-
 ## Changelogs
 
 We maintain changelogs for all our packages.
@@ -139,7 +133,7 @@ The last command should fail with an error that the current revision is not on
 the `master` or a `release/*` branch.  After running both commands, you will
 need to delete branch created in `cardano-haskell-packages`.
 
-### Release from master or release/* branch
+### Release from main or release/* branch
 
 * First run `./script/release-to-chap.sh -r` to see which changes can be
   published.

README.md

@@ -1,3 +1,10 @@
+[![x86\_64-linux](https://img.shields.io/endpoint?url=https://ci.iog.io/job/IntersectMBO-dmq-node/main/x86_64-linux.required/shield&style=for-the-badge&label=x86_64-linux)](https://ci.iog.io/job/IntersectMBO-dmq-node/main/x86_64-linux.required)
+[![x86\_64-darwin](https://img.shields.io/endpoint?url=https://ci.iog.io/job/IntersectMBO-dmq-node/main/x86_64-darwin.required/shield&style=for-the-badge&label=x86_64-darwin)](https://ci.iog.io/job/IntersectMBO-dmq-node/main/x86_64-darwin.required)
+[![aarch64-darwin](https://img.shields.io/endpoint?url=https://ci.iog.io/job/IntersectMBO-dmq-node/main/aarch64-darwin.required/shield&style=for-the-badge&label=aarch64-linux)](https://ci.iog.io/job/IntersectMBO-dmq-node/main/aarch64-darwin.required)
+[![mingw64](https://img.shields.io/github/actions/workflow/status/intersectmbo/dmq-node/build.yml?branch=main&label=mingw64&style=for-the-badge)](https://github.com/intersectmbo/dmq-node/actions/workflows/build.yml)
+[![Haddocks](https://img.shields.io/github/actions/workflow/status/intersectmbo/dmq-node/github-page.yml?branch=main&label=Haddocks&style=for-the-badge)](https://dmq-node.cardano.intersectmbo.org/)
+[![Discord](https://img.shields.io/discord/1136727663583698984?style=for-the-badge&color=blue)](https://discord.com/channels/1136727663583698984/1239889324745429122)
+
 # Decentralized Message Queue
 
 The DMQ node allows for client peers to communicate efficiently by publishing
@@ -6,19 +13,12 @@ and consuming messages which are diffused over a P2P network to other nodes.
 This repository provides the `dmq-node` executable to participate in the DMQ
 network.
 
-The `dmq-node` is developed with respect to the [CIP#0137].
+The `dmq-node` is developed with respect to the [CIP#137].
 
 __NOTE__: This is still an early version of DMQ node, which comes with some
 quirks:
 
-* issue#6 - no support for ledger peers, which requires setting up static peers
-            using local roots.  We are aiming to add this feature for the
-            `cardano-node-10.7` release.
-* issue#13 - using `TxSubmission` mini-protocol for which roles are swapped,
-             e.g. server requests data, client servers the data.  This makes
-             configuration awekward, since your local roots specify who will get data from
-             you, rather than who you get data from.  We are working on a new
-             mini-protocol to address this.
+* [issue#6] - experimental support for ledger peers see [Ledger Peers](#ledger-peers) below.
 
 # Instructions
 
@@ -115,7 +115,7 @@ To use ledger peers, as `cardano-node` does there are additional requrements:
 
 * You need `cardano-node-10.7` or newer to support ledger peer snapshot query
   over `cardano-node`'s node-to-client protocol.
-* You need to configure `cardano-node` & `dmq-node` to use SRV records according to [CIP#0155]
+* You need to configure `cardano-node` & `dmq-node` to use SRV records according to [CIP#155]
 * You need to set `LedgerPeers: true` in the configuration file.
 
 Currently ledger peers are disabled by default, but in a near future we will
@@ -133,7 +133,7 @@ To enter a development shell with all dependencies available, use:
 To run the test suite, one can use:
 
 ``` bash
-> cabal test all
+> cabal run dmq-node:dmq-tests
 ```
 
 ### CDDL
@@ -158,7 +158,8 @@ The code of conduct is available [here][code-of-conduct].
 [code-of-conduct]: ./CODE_OF_CONDUCT.md
 [style-guide]: https://github.com/IntersectMBO/ouroboros-network/blob/main/docs/StyleGuide.md
 [musl]: https://musl.libc.org/
-[CIP#0137]: https://cips.cardano.org/cip/CIP-0137
-[CIP#0155]: https://cips.cardano.org/cip/CIP-0155
+[CIP#137]: https://cips.cardano.org/cip/CIP-0137
+[CIP#155]: https://cips.cardano.org/cip/CIP-0155
 [topology-file]: https://developers.cardano.org/docs/get-started/infrastructure/node/topology/
 [defaultConfiguration]: http://intersectmbo.github.io/dmq-node/dmq-node/src/DMQ.Configuration.html#defaultConfiguration
+[issue#6]: https://github.com/intersectMBO/dmq-node/issues/6

scripts/build-with-chap.sh

@@ -45,8 +45,8 @@ fi
 cabal_files=$(fd -ae 'cabal')
 for cf in $cabal_files; do
   name=$(cat $cf | grep '^name:' | awk '{ print $2 }')
-  if [[ -d "$CHAP_DIR/_sources/$name" ]]; then
-    version=$(ls -1 $CHAP_DIR/_sources/$name | sort -V | tail -1)
+  version=$(cat $cf | grep '^version:' | awk '{ print $2 }')
+  if [[ -d "$CHAP_DIR/_sources/$name/$version" ]]; then
     rev=$(yq .github.rev $CHAP_DIR/_sources/$name/$version/meta.toml)
     git restore --source=$rev -- $name
     tb=0
@@ -57,7 +57,7 @@ for cf in $cabal_files; do
       cp $revdir/$rev "$name/$name.cabal"
     fi
   else
-    echo "WARNING: $name not in cardano-haskell-packages"
+    echo "WARNING: $name-$version not in cardano-haskell-packages"
   fi
 done
 
@@ -82,5 +82,5 @@ fi
 
 pushd $CHAP_DIR
 if [[ $TEST == 0 && $(git symbolic-ref --short HEAD) =~ ^dmq-node\/release- ]] then
-  gh pr comment --body "* [x] checked with \`build-with-chap.sh\` in \`dmq-network\`"
+  gh pr comment --body "* [x] checked with \`build-with-chap.sh\` in \`dmq-node\`"
 fi

scripts/release-to-chap.sh

@@ -81,24 +81,27 @@ else
     git switch main
     git pull
   fi
-  BRANCH="dmq-node/release-$(date -I)"
+  BRANCH="dmq-node/release-$(date +%Y%m%d-%H%M%S)"
   if [[ $TEST == 1 ]];then
     BRANCH="${BRANCH}-DO_NOT_MERGE"
   fi
   git switch -c $BRANCH
 
+  # Gather packages to publish on CHaP
+  publish=""
   for cf in $cabal_files; do
     name=$(cat $cf | grep '^name:' | awk '{ print $2 }')
     version=$(cat $cf | grep '^version:' | awk '{ print $2 }')
     dir="$CHAP_DIR/_sources/$name/$version"
     if [[ !(-d $dir) ]];then
-      trace "publishing $name-$version"
-      ./scripts/add-from-github.sh $REPO_URL $gitsha $name
+      publish="$publish $name"
       if [[ $TEST == 0 ]];then
         git --git-dir "$gitdir/.git" tag "$name-$version" $gitsha
       fi
     fi
   done
+  trace "Publishing:$publish"
+  ./scripts/add-from-github.sh $REPO_URL $gitsha $publish
 
   git --no-pager log --oneline origin/main..HEAD