diff --git a/.github/workflows/ghc.yml b/.github/workflows/ghc.yml index 69d2f3dbb..abcbb95c9 100644 --- a/.github/workflows/ghc.yml +++ b/.github/workflows/ghc.yml @@ -299,7 +299,7 @@ jobs: if: env.branch_is_not_master && runner.os == 'Linux' run: | source scripts/lib.sh - files=('site' 'proposals' 'README.md') + files=('site' 'proposals' 'README.md' 'CONTRIBUTING.md') commit_and_push_if_changed "$files" "Markdown files" - name: Create a directory for docs diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..9eba55712 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,214 @@ +# Contributing + +## Issues + +Check open issues ([link](https://github.com/objectionary/eo-phi-normalizer/issues)). + +### 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. + +```sh +git clone https://github.com/objectionary/eo-phi-normalizer --recurse-submodules +cd eo-phi-normalizer +``` + +## Install stack + +We recommend using [stack](https://docs.haskellstack.org/en/stable) for quick local development and testing. + +## Build + +Build the project using `stack`. + +```sh +export LC_ALL=C.UTF-8 +stack build +``` + +## Test + +Run all tests + +```sh +export LC_ALL=C.UTF-8 +stack test +``` + +## Run + +Run the `eo-phi-normalizer` executable via `stack run`. + +```$ as console +stack run eo-phi-normalizer -- --help +``` + +```console +Usage: eo-phi-normalizer COMMAND + + Work with PHI expressions. + +Available options: + -h,--help Show this help text + --version Show version information + +Available commands: + rewrite Rewrite a PHI program. + metrics Collect metrics for a PHI program. + dataize Dataize a PHI program. + pipeline Run pipeline-related commands. + print-rules Print rules in LaTeX format. + test Run unit tests in given files with user-defined + rules. +``` + +Or, omit the executable name. + +```$ as console +stack run -- --help +``` + +```console +Usage: eo-phi-normalizer COMMAND + + Work with PHI expressions. + +Available options: + -h,--help Show this help text + --version Show version information + +Available commands: + rewrite Rewrite a PHI program. + metrics Collect metrics for a PHI program. + dataize Dataize a PHI program. + pipeline Run pipeline-related commands. + print-rules Print rules in LaTeX format. + test Run unit tests in given files with user-defined + rules. +``` + +## Docs + +### Math expressions + +Use the syntax supported by `mdBook` - see [docs](https://rust-lang.github.io/mdBook/format/mathjax.html). + +### mdsh + +We use [mdsh](https://github.com/zimbatm/mdsh) to document command outputs (see [Multiline Shell Code](https://github.com/zimbatm/mdsh#multiline-shell-code)). + +You can install `mdsh` via `cargo` or `nix` ([link](https://github.com/zimbatm/mdsh#installation)). + +### prettier + +We format docs with [prettier](https://prettier.io/). + +Run `npm i` to locally install the `prettier` version that we use. + +### Automatic updates + +In CI, on the `master` branch, we run a [script](https://github.com/objectionary/eo-phi-normalizer/blob/master/scripts/update-markdown.sh) 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](https://pre-commit.com/) hooks to ensure code quality. + +Collaborators **MUST** set up the hooks before commiting any code to our repository. + +### Set up pre-commit + +#### Single command + +```console +pip3 install +pre-commit install +stack install fourmolu +chmod +x scripts/run-fourmolu.sh +``` + +#### Step by step + +1. Install [Python 3](https://www.python.org/downloads/) (e.g., Python 3.10). +1. [Install pre-commit](https://pre-commit.com/#1-install-pre-commit). + - Alternatively, run `pip3 install`. +1. [Install the git hook scripts](https://pre-commit.com/#3-install-the-git-hook-scripts). +1. Install [fourmolu](https://github.com/fourmolu/fourmolu). + + ```console + stack install fourmolu + ``` + + - You can remove `fourmolu` later (see [SO post](https://stackoverflow.com/a/38639959)) + +1. Make a script executable. + + ```console + chmod +x scripts/run-fourmolu.sh + ``` + +### pre-commit configs + +See [docs](https://pre-commit.com/#adding-pre-commit-plugins-to-your-project). + +See [.pre-commit-config.yaml](https://github.com/objectionary/eo-phi-normalizer/blob/master/.pre-commit-config.yaml). + +You can run a specific hook (see [docs](https://pre-commit.com/#pre-commit-run)): + +```console +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](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_committing_workflow_hooks)) + + > 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](https://git-scm.com/docs/git-stash)) unstaged ([link](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_the_three_states)) files. + + ```console + [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.: + + ```md + Format Haskell (.hs) files...............................................Failed + + - hook id: fourmolu + - exit code: 102 + - files were modified by this hook + ``` + + - In case of the [fourmolu](https://github.com/fourmolu/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. diff --git a/flake.nix b/flake.nix index 417375958..c21f540df 100644 --- a/flake.nix +++ b/flake.nix @@ -199,9 +199,6 @@ let name = "update-markdown"; text = '' - # This file was generated automatically. - # You can edit the script in 'flake.nix' - mdsh ${lib.concatMapStringsSep "\n" (x: "mdsh -i site/docs/src/${x} --work_dir .") [ @@ -218,6 +215,8 @@ "contributing.md" ]} + cp site/docs/docs/markdown/contributing.md CONTRIBUTING.md + rm celsius.phi npm i @@ -228,8 +227,18 @@ stack install cat << EOF > scripts/${name}.sh + ${lib.trivial.pipe ./LICENSE.txt [ + builtins.readFile + (builtins.split "\n") + (builtins.filter (x: x != [ ])) + (builtins.map (x: "# ${x}")) + (builtins.concatStringsSep "\n") + ]} + # shellcheck disable=SC2148 + # This file was generated automatically. + # You can edit the script in 'flake.nix' ${text} EOF diff --git a/scripts/update-markdown.sh b/scripts/update-markdown.sh index da55e3508..1c98cd177 100755 --- a/scripts/update-markdown.sh +++ b/scripts/update-markdown.sh @@ -1,17 +1,17 @@ # The MIT License (MIT) - +# # Copyright (c) 2016-2024 Objectionary.com - +# # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to deal # in the Software without restriction, including without limitation the rights # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell # copies of the Software, and to permit persons to whom the Software is # furnished to do so, subject to the following conditions: - +# # The above copyright notice and this permission notice shall be included # in all copies or substantial portions of the Software. - +# # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE @@ -19,11 +19,12 @@ # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. +# + # shellcheck disable=SC2148 # This file was generated automatically. # You can edit the script in 'flake.nix' - mdsh mdsh -i site/docs/src/common/celsius.md --work_dir . @@ -38,6 +39,8 @@ mdsh -i site/docs/src/eo-phi-normalizer/print-rules.md --work_dir . mdsh -i site/docs/src/eo-phi-normalizer/test.md --work_dir . mdsh -i site/docs/src/contributing.md --work_dir . +cp site/docs/docs/markdown/contributing.md CONTRIBUTING.md + rm celsius.phi npm i