Merge pull request #53 from cardano-scaling/formatting-spellcheck

Formatting & spell-checking

Author: ch1bo

.github/workflows/formatting.yaml

@@ -0,0 +1,34 @@
+name: Formating and spell-checking
+
+on:
+  pull_request:
+  push:
+    branches:
+    - main
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  treefmt:
+    name: Formatting and spell-checking
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install nix
+        uses: cachix/install-nix-action@V27
+        with:
+          extra_nix_config: |
+            accept-flake-config = true
+            log-lines = 1000
+
+      - name: Enter nix shell
+        uses: nicknovitski/nix-develop@v1
+
+      - name: Run treefmt
+        run: treefmt --ci

.github/workflows/link-check-config.json

@@ -3,5 +3,5 @@
   "retryOn429": true,
   "retryCount": 5,
   "fallbackRetryDelay": "30s",
-  "aliveStatusCodes": [200, 206]
+  "aliveStatusCodes": [200, 206, 403]
 }

.gitignore

@@ -3,6 +3,3 @@
 
 # Direnv cache
 /.direnv/
-
-# Trivial flake, no need to check in lock file
-/flake.lock

CONTRIBUTING.md

@@ -3,8 +3,9 @@
 Thank you for considering contributing and sharing your knowledge about the Cardano protocol in one capacity or another.
 
 There are basically two ways to contribute:
- - Validate and provide feedback about existing blueprints
- - Create or update blueprints
+
+- Validate and provide feedback about existing blueprints
+- Create or update blueprints
 
 ## Validate blueprints
 
@@ -44,10 +45,10 @@ Thank you for contributing your changes by opening a pull request!
 
 We do appreciate it if your pull request meets the following criteria:
 
-+ **Description of the changes**: providing a clear summary of the changes is beneficial
-+ **Quality of changes**: ensure that new or updated automated tests validate your changes
-+ **Scope**: we prefer multiple pull requests that are well-scoped rather than a single large one
-+ **Correctness**: the pull request should pass the continuous integration (CI) pipeline.
+- **Description of the changes**: providing a clear summary of the changes is beneficial
+- **Quality of changes**: ensure that new or updated automated tests validate your changes
+- **Scope**: we prefer multiple pull requests that are well-scoped rather than a single large one
+- **Correctness**: the pull request should pass the continuous integration (CI) pipeline.
 
 The project is currently in an expand-and-gather phase with no requirement of approvals, but consider requesting for reviews on Github-suggested reviewers.
 

README.md

@@ -14,14 +14,13 @@ wide developer audience to understand the protocol and build Cardano components.
 
 ## Building
 
-The blueprints are written using markdown and can be viewed
-[directly in Github](./src/introduction/README.md) or built into
-[the HTML site](https://cardano-scaling.github.io/cardano-blueprint)
-using [mdbook][mdbook].
+The blueprints are written using markdown and can be viewed [directly in
+Github](./src/introduction/README.md) or built into [the HTML
+site](https://cardano-scaling.github.io/cardano-blueprint) using [mdbook].
 
 ### With cargo
 
-You can install [mdbook][mdbook] and the plugins we use with `cargo`:
+You can install [mdbook] and the plugins we use with `cargo`:
 
 ```shell
 cargo install mdbook mdbook-katex mdbook-mermaid mdbook-alerts mdbook-toc
@@ -47,16 +46,16 @@ cargo binstall mdbook mdbook-katex mdbook-mermaid mdbook-alerts mdbook-toc
 
 ### With nix
 
-You can also use [nix][nix]:
+You can also use [nix]:
 
 ```shell
 nix build -o out
 ```
 
 ## Editing
 
-With [mdbook][mdbook] installed or inside a `nix develop` shell, you
-can live preview the result with:
+With [mdbook] installed or inside a `nix develop` shell, you can live preview
+the result with:
 
 ```shell
 mdbook serve --open
@@ -65,20 +64,39 @@ mdbook serve --open
 See the [mdbook manual][mdbook] or [github flavored markdown][gfm] for
 more information on what is available for editing.
 
-[mdbook]: https://rust-lang.github.io/mdBook/index.html
-[gfm]: https://github.github.com/gfm/
-[nix]: https://nixos.org/download.html
+### Formatting & spell checking
+
+We use `treefmt` that runs a few formatting and spell checking tools. This is
+also enforced through CI. See `formattingPkgs` in [`flake.nix`](./flake.nix) for
+a list of packages needed, then:
+
+```shell
+treefmt
+```
 
 ## License
 
-Cardano Blueprint created by [the Cardano Blueprint contributors](https://github.com/cardano-scaling/cardano-blueprint/graphs/contributors) is licensed under the [Apache 2.0 License](./LICENSE).
+Cardano Blueprint created by [the Cardano Blueprint
+contributors](https://github.com/cardano-scaling/cardano-blueprint/graphs/contributors)
+is licensed under the [Apache 2.0 License](./LICENSE).
 
 ## Logo
 
-The [logo and wordmark](./logo/README.md) for the Cardano Blueprint was created by Roberto Nicolo, Sebastian Nagel and Input Output Global Ltd. Obviously, the design is derived from the official Cardano logo and we hereby accept and intend to follow the [official trademark policy](https://www.cardanofoundation.org/policy/trademark-policy). Cardano Blueprint is NOT registered as a trademark, nor shall it represent a commercial product, but any artifacts produced are covered under an open source [license](./LICENSE).
+The [logo and wordmark](./logo/README.md) for the Cardano Blueprint was created
+by Roberto Nicolo, Sebastian Nagel and Input Output Global Ltd. Obviously, the
+design is derived from the official Cardano logo and we hereby accept and intend
+to follow the [official trademark
+policy](https://www.cardanofoundation.org/policy/trademark-policy). Cardano
+Blueprint is NOT registered as a trademark, nor shall it represent a commercial
+product, but any artifacts produced are covered under an open source
+[license](./LICENSE).
 
----
+______________________________________________________________________
 
 <p align="center">
 Thanks for visiting and hopefully the cardano blueprint is useful to you 💙!
 </p>
+
+[gfm]: https://github.github.com/gfm/
+[mdbook]: https://rust-lang.github.io/mdBook/index.html
+[nix]: https://nixos.org/download.html

flake.lock

@@ -10,29 +10,41 @@
     flake-utils.lib.eachSystem flake-utils.lib.defaultSystems (system:
       let
         pkgs = import nixpkgs { inherit system; };
+
+        formattingPkgs = with pkgs; [
+          treefmt
+          mdformat
+          python3Packages.mdformat-footnote
+          python3Packages.mdformat-gfm
+          python3Packages.mdformat-myst # for latex math
+          typos
+        ];
       in
       rec {
         inherit inputs;
         legacyPackages = pkgs;
-        packages.mdbook =
-          (
-            pkgs.stdenv.mkDerivation {
-              name = "cardano-blueprint-book";
-              src = ./.;
-              buildInputs = with pkgs; [
-                mdbook
-                mdbook-mermaid
-                mdbook-katex
-                mdbook-alerts
-                mdbook-toc
-              ];
-              phases = [ "unpackPhase" "buildPhase" ];
-              buildPhase = ''
-                mdbook build -d $out
-              '';
-            }
-          );
+
         defaultPackage = packages.mdbook;
+        packages.mdbook = pkgs.stdenv.mkDerivation {
+          name = "cardano-blueprint-book";
+          src = ./.;
+          buildInputs = with pkgs; [
+            mdbook
+            mdbook-mermaid
+            mdbook-katex
+            mdbook-alerts
+            mdbook-toc
+          ];
+          phases = [ "unpackPhase" "buildPhase" ];
+          buildPhase = ''
+            mdbook build -d $out
+          '';
+        };
+
+        devShells.default = pkgs.mkShell {
+          inputsFrom = [ packages.mdbook ];
+          buildInputs = formattingPkgs;
+        };
       }
     );
 }

flake.nix

@@ -9,7 +9,7 @@
     - [BlockFetch](network/node-to-node/blockfetch/README.md)
     - [TxSubmission2](network/node-to-node/txsubmission2/README.md)
     - [KeepAlive](network/node-to-node/keep-alive/README.md)
-    - [PeerSharing]()
+    - [PeerSharing](<>)
 - [Consensus](consensus/README.md)
   - [Chain validity](consensus/chainvalid.md)
   - [Chain selection](consensus/chainsel.md)
@@ -28,15 +28,15 @@
   - [Serialization](plutus/serialization.md)
 - [Client interfaces](client/README.md)
   - [NTC](client/node-to-client/README.md)
-    - [Handshake]()
+    - [Handshake](<>)
     - [LocalStateQuery](client/node-to-client/state-query/README.md)
-    - [LocalTxSubmission]()
-    - [TxMonitor]()
-    - [LocalChainSync]()
+    - [LocalTxSubmission](<>)
+    - [TxMonitor](<>)
+    - [LocalChainSync](<>)
   - [UTxO-RPC](client/utxo-rpc/README.md)
 - [Codec basics](codecs/README.md)
 
----
+______________________________________________________________________
 
 - [Styleguide](styleguide.md)
 - [Contributing](CONTRIBUTING.md)

src/SUMMARY.md

@@ -13,15 +13,15 @@ enabling this interaction:
 Below we present a table with clients and servers that implement each protocol:
 
 | Server         | NTC | UTxO RPC |
-|:---------------|-----|----------|
+| :------------- | --- | -------- |
 | [cardano-node] | ✅  | ❔       |
 | [dingo]        | ✅  | ✅       |
 | [amaru]        | ❔  | ❔       |
 
 <br/>
 
 | Client        | NTC | UTxO RPC |
-|:--------------|-----|----------|
+| :------------ | --- | -------- |
 | [cardano-cli] | ✅  | ⬜       |
 | [pallas]      | ✅  | ❔       |
 | [gouroboros]  | ✅  | ❔       |
@@ -30,9 +30,9 @@ Below we present a table with clients and servers that implement each protocol:
 >
 > Please help us keep this list up-to-date by [suggesting an edit](https://github.com/cardano-scaling/cardano-blueprint/edit/main/src/client/README.md).
 
-[cardano-node]: https://github.com/IntersectMBO/cardano-node
+[amaru]: https://github.com/pragma-org/amaru/
 [cardano-cli]: https://github.com/IntersectMBO/cardano-cli
+[cardano-node]: https://github.com/IntersectMBO/cardano-node
 [dingo]: https://github.com/blinklabs-io/dingo
 [gouroboros]: https://github.com/blinklabs-io/gouroboros
-[amaru]: https://github.com/pragma-org/amaru/
 [pallas]: https://github.com/txpipe/pallas

src/client/README.md

@@ -11,8 +11,8 @@ In particular, these mini-protocols will also be wrapped by a
 
 These mini-protocols are:
 
-- [Handshake](): to negotiate the versions used in the connection,
-- [LocalTxSubmission](): to submit transactions to the network,
+- [Handshake](<>): to negotiate the versions used in the connection,
+- [LocalTxSubmission](<>): to submit transactions to the network,
 - [LocalStateQuery](state-query): to query for information about the ledger state,
-- [TxMonitor](): to monitor the status of transactions,
-- [LocalChainSync](): to retrieve chains of blocks from the node.
+- [TxMonitor](<>): to monitor the status of transactions,
+- [LocalChainSync](<>): to retrieve chains of blocks from the node.