Skip to content

Latest commit

 

History

History
145 lines (88 loc) · 4.46 KB

CONTRIBUTING.md

File metadata and controls

145 lines (88 loc) · 4.46 KB

Contributing

Prerequisites

Nix and direnv (recommended) are used to provide all necessary developments tools: cabal, GHC, formatters, etc.

Nix

Install Nix (recommended). Then activate Flakes support for Nix (mandatory).

The nix setup (flake.nix and everything under cells) in this repo use the Standard framework (std), please refer to its documentation for general maintenance.

We also use Haskell.nix for building haskell packages with nix. See haskell.nix configuration file and the Haskell.nix documentation for maintenance.

Development environment: direnv or nix develop.

Development environments are provided for the following compilers:

  • GHC 9.2.x (default)
  • GHC 8.10.x

Upon entering a development environment for the first time, nix may ask you to activate the necessary option and the IOG nix cache (see nixConfig attribute in flake.nix).

Direnv

direnv is recommended, install it for your OS and hook it to your shell.

Then

$ direnv allow
Use alternative compiler configuration

Check available alternatives with:

$ std list | grep -Eo '//_automation/devshells/.*:enter'
//_automation/devshells/default:enter
//_automation/devshells/ghc8107:enter

Then you can enter one of the alternative shell with, eg.:

$ std //_automation/devshells/ghc8107:enter

(here the shell will provide GHC 8.10.7)

or use it permanently:

$ echo DEVSHELL_TARGET=ghc8107 >> .envrc.local
$ direnv reload

Nix develop

use nix develop or nix develop .#ghc8107 to enter a development shell.

Development workflows

Available tools

Available tools (cabal, ghcid, hlint, weeder, etc.) are displayed upon entering the development shell. Type menu to see them again.

Adding or modifying the list of development tools can be done from devshellProfiles.nix.

Build and test

using cabal:

$ cabal update
$ cabal build all
$ cabal test all

or std (nix):

$ source <(std _carapace) # (Optional, for completion on zsh).
$ std //prelude/packages/cardano-prelude:lib:cardano-prelude:build
$ std //prelude/apps/cardano-prelude-test:test:prelude-tests:run

(the std/nix build will use default compiler).

Formatting

The source tree is to be formatted with the treefmt command (which use fourmolu for haskell code).

This is checked by Lefthook which will prevent commit of non-compliant files (it will also format those, so that you can retry to commit immediately).

Commit message

Commit messages should ideally be of the form <type>[(<scope>)]: <short description>] (conventionnal commit message). Available commit types are from std presets.

This is NOT enforced (but could be at a later point, cf. nixago.nix) by Lefhook.

CI

Running CI jobs locally can be done with tullia:

$ tullia run ci

If this does not work (still WIP for local execution), then use std to build the required nix job:

$ std //_automation/ciJobs/required:build

Updating cabal index-state

If you need to update cabal.project index-state, you will probably need to update the nix pin for hackage so that the new index-state be available to the nix build:

$ nix flake lock --update-input hackage

You may also check what is the last index-state available within the current hackage pin by running:

$ nix eval .#last-index-state

Roles and Responsibilities

The cardano-prelude package is collectively mainntained by the cardano-core team. If you open a PR expect a review from one of the core contributors.

Releases

cardano-prelude is released to Cardano Haskell Packages (CHaP).

If you want to include it as a dependency of your project see CHaP documentation.