Contributing

Issues

Check open issues (link).

Issue labels

priority N - an issue with the priority N.
- 1 - The highest priority (the most important issues).
- 5 - The lowest priority (the least important issues).
(scope) - An issue concerning a particular part of the project. Note the parentheses.
[non-functional requirement] - An issue concerning a non-functional requirement. Note the square brackets.

Enter the repository

Clone and enter the project repository.

git clone https://github.com/objectionary/normalizer --recurse-submodules
cd normalizer

Install stack

We recommend using stack for quick local development and testing.

Build

Build the project using stack.

stack build

Run

Run the normalizer executable via stack run.

stack run normalizer -- --help

Usage: normalizer COMMAND

  Work with PHI expressions.

Available options:
  -h,--help                Show this help text

Available commands:
  transform                Transform a PHI program.
  metrics                  Collect metrics for a PHI program.
  dataize                  Dataize a PHI program.
  report                   Generate reports about initial and normalized PHI
                           programs.
  prepare-pipeline-tests   Prepare EO test files for the pipeline.

Or, omit the executable name.

stack run -- --help

Usage: normalizer COMMAND

  Work with PHI expressions.

Available options:
  -h,--help                Show this help text

Available commands:
  transform                Transform a PHI program.
  metrics                  Collect metrics for a PHI program.
  dataize                  Dataize a PHI program.
  report                   Generate reports about initial and normalized PHI
                           programs.
  prepare-pipeline-tests   Prepare EO test files for the pipeline.

Test

Run all tests

stack test

Docs

Math expressions

Use the syntax supported by mdBook - see docs.

mdsh

We use mdsh to document command outputs (see Multiline Shell Code).

You can install mdsh via cargo or nix (link).

prettier

We format docs with prettier.

Run npm i to locally install the prettier version that we use.

Automatic updates

In CI, on the master branch, we run a script to update Markdown files and then we commit changes.

So, no worries if you haven't run mdsh in your PR!

Code quality

Checks in CI

We run fourmolu and hlint checks in CI.

These checks are also implemented as pre-commit hooks.

pre-commit hooks

We use pre-commit hooks to ensure code quality.

Collaborators MUST set up the hooks before commiting any code to our repository.

Set up pre-commit

Single command

pip3 install
pre-commit install
stack install fourmolu
chmod +x scripts/run-fourmolu.sh

Step by step

Install Python 3 (e.g., Python 3.10).
Install pre-commit.
- Alternatively, run pip3 install.
Install the git hook scripts.
Install fourmolu.
```
stack install fourmolu
```
- You can remove fourmolu later (see SO post)
Make a script executable.
```
chmod +x scripts/run-fourmolu.sh
```

pre-commit configs

See docs.

See .pre-commit-config.yaml.

You can run a specific hook (see docs):

pre-commit run -c .pre-commit-config.yaml fourmolu-format --all

pre-commit workflow

pre-commit runs before a commit (at the pre-commit phase)

The pre-commit hook is run first, before you even type in a commit message. It's used to inspect the snapshot that's about to be committed, to see if you've forgotten something, to make sure tests run, or to examine whatever you need to inspect in the code. Exiting non-zero from this hook aborts the commit ...

pre-commit stashes (link) unstaged (link) files.

[WARNING] Unstaged files detected.
[INFO] Stashing unstaged files to /home/eyjafjallajokull/.cache/pre-commit/patch1705090051-437857.

pre-commit runs hooks.
A hook may exit with an error, e.g.:
```
Format Haskell (.hs) files...............................................Failed

- hook id: fourmolu
- exit code: 102
- files were modified by this hook
```
- In case of the fourmolu formatter, it's assumed that formatting a formatted Haskell file doesn't modify it. However, pre-commit runs the fourmolu hook and reports that it has modified some files. This error won't allow you to commit.
pre-commit unstashes files.
You should stage all changes so that pre-commit does not complain.
- In case of fourmolu, stage the formatted code regions.
Now, you can commit.

phi-normalizer