Merge pull request #576 from objectionary/563-how-to-contribute-secti…

…on-is-missing-in-the-documentation

563 how to contribute section is missing in the documentation

.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

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.

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
 

scripts/update-markdown.sh

@@ -1,29 +1,30 @@
 # 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
 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 # 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