Skip to content

Latest commit

 

History

History
140 lines (83 loc) · 3.88 KB

CONTRIBUTING.md

File metadata and controls

140 lines (83 loc) · 3.88 KB
Raw

Developper Guide

Design decisions

Zuul Weeder is written using the Haskell Language. Haskell provides a powerfull type system to safely manipulate and transform data.

The user interface is written using the HTMX library. HTMX provides access to modern browser features without using Javascript.

The project can be deployed with nix reproducible build.

Main dependencies

These elements are essentials for the project.

GHC2021

Automatically derive instances and use flexible contexs.

Learn more about GHC2021.

OverloadedRecordDot and DuplicateRecordFields: record.field syntax

Better record ergonomics:

data Job
  = Job {
    name : JobName,
    id : JobId
  }

data Node
 = Node {
   name : NodeName,
   path : FilePathT
 }

isSamePath :: Node -> Node -> Bool
isSamePath n1 n2 = n1.path == n2.path

Though HLS doesn't support auto completion yet.

algebraic-graphs: Algebraic graph construction and transformation

The configuration is loaded into an algebraic graph that is used to query the reachable dependencies between elements. See the ZuulWeeder.Graph.Analysis data type.

Learn more about algebraic-graphs

lucid: Clear to write, read and edit DSL for HTML

The web interface is writen using a DSL. See the ZuulWeeder.UI module.

Learn more about lucid

servant: A family of combinators for defining webservices APIs

The HTTP API is defined as a Type. See the ZuulWeeder.UI.API type.

Learn more about servant

witch: Convert values from one type into another

Rust inspired ergonomic to convert types:

textPack :: String -> Text
textPack = Witch.from

encodeText :: Text -> ByteString
encodeText = Witch.from

Extra libraries

These libraries are helpful, but they could be removed if they really hurts maintenance.

lens: Lenses, Folds and Traversals

The lenses are defined using generic-lens and the OverloadedLabels extension.

Learn more about lens

string-qq for multiline strings

Using the QuasiQuotes language extensions.

Quality of life extensions

  • BlockArgument: omit $ before do block.
  • LambdaCase: shorter pattern match, e.g. f = \cases instead of f x = case x of.
  • TypeApplications: type variable specialization: into @Int64.
  • NegativeLiterals: better syntax, -1 (instead of (-1)).
  • NamedFieldPuns: enable X { result } instead of X { result = result }.
  • ImportQualifiedPost: enable imports alignments: import Data.Text qualified.

Code Contribution

Checkout the haddock code documentation: zuul-weeder

Run nix develop to setup the project dependencies (ghc, language server, linters, ...)

Auto reload the web ui with a demo config:

ghcid -W --test "ZuulWeeder.runDemo"

After adding css class, run nix run .#tailwind to update the tailwind.css file. Then hard refresh the web page.

Validate your changes:

./bin/run-tests