|
| 1 | +# Contributing |
| 2 | + |
| 3 | +## Installation requirements |
| 4 | + |
| 5 | +The following should be installed: |
| 6 | + |
| 7 | +* The `libclang` C library from the [The LLVM |
| 8 | + project](https://github.com/llvm/llvm-project) |
| 9 | + |
| 10 | +* `autoreconf` and its dependencies |
| 11 | + * Ubuntu: |
| 12 | + ``` |
| 13 | + apt-get install build-essential |
| 14 | + ``` |
| 15 | + * MacOS: |
| 16 | + ``` |
| 17 | + brew install coreutils autoconf automake |
| 18 | + ``` |
| 19 | + * Windows (MSYS2): |
| 20 | + ``` |
| 21 | + pacman --noconfirm -Sy base-devel automake-wrapper autoconf-wrapper |
| 22 | + ``` |
| 23 | +
|
| 24 | +## Building |
| 25 | +
|
| 26 | +The project is built using `autoreconf`, `ghc` and `cabal`. |
| 27 | +
|
| 28 | +``` |
| 29 | +autoreconf -i |
| 30 | +cabal update |
| 31 | +cabal run clang-bootstrap |
| 32 | +cabal build all |
| 33 | +``` |
| 34 | +
|
| 35 | +`autoreconf` should be invoked manually to generate a configuration script for |
| 36 | +the Haskell library. The configuration script is run automatically when `cabal |
| 37 | +build` is invoked. |
| 38 | +
|
| 39 | +`clang-bootstrap` should be invoked manuall to generate C wrapper functions and |
| 40 | +Haskel foreign import declarations for the `libclang` C library. This code is |
| 41 | +automatically built when `cabal build` is invoked. |
| 42 | +
|
| 43 | +## Testing |
| 44 | +
|
| 45 | +Tests are run using `cabal`. |
| 46 | +
|
| 47 | +``` |
| 48 | +cabal build all |
| 49 | +cabal test all |
| 50 | +``` |
| 51 | +
|
| 52 | +## Code style |
| 53 | +
|
| 54 | +There is no strict code style, but try to keep the code style consistent |
| 55 | +throughout the repository and favour readability. Code should be well-documented |
| 56 | +and well-tested. |
| 57 | +
|
| 58 | +## Formatting |
| 59 | +
|
| 60 | +We use `stylish-haskell` to format Haskell files, and we use `cabal-fmt` to |
| 61 | +format `*.cabal` files. See the helpful scripts in the [scripts |
| 62 | +folder](./scripts/), and the [`stylish-haskell` configuration |
| 63 | +file](./.stylish-haskell.yaml). |
| 64 | +
|
| 65 | +To perform a pre-commit code formatting pass, run one of the following: |
| 66 | +
|
| 67 | +``` |
| 68 | +./scripts/ci/format-cabal-fmt.sh |
| 69 | +./scripts/ci/format-stylish-haskell.sh |
| 70 | +``` |
| 71 | +
|
| 72 | +## Pull requests |
| 73 | +
|
| 74 | +The following are requirements for merging a PR into `main`: |
| 75 | +* Each commit should be small and should preferably address one thing. Commit |
| 76 | + messages should be useful. |
| 77 | +* Document and test your changes. |
| 78 | +* The PR should have a useful description, and it should link issues that it |
| 79 | + resolves (if any). |
| 80 | +* Changes introduced by the PR should be recorded in the relevant changelog |
| 81 | + files. Ideally, each changelog entry should link to the PR that introduced the |
| 82 | + changes, and it should be placed in the relevant category (e.g., breaking |
| 83 | + changes, new features). |
| 84 | +* PRs should not bundle many unrelated changes. |
| 85 | +* The PR should pass all CI checks. |
| 86 | +
|
| 87 | +## Releases |
| 88 | +
|
| 89 | +Releases follow the [Haskell Package Versioning |
| 90 | +Policy](https://pvp.haskell.org/). We use version numbers consisting of 3 parts, |
| 91 | +like `A.B.C`. |
| 92 | +* `A.B` is the *major* version number. A bump indicates a breaking change. |
| 93 | +* `C` is the *minor* version number. A bump indicates a non-breaking change. |
| 94 | +
|
| 95 | +To publish a release for a package, follow the steps below: |
| 96 | +
|
| 97 | +* Changelog checks (`CHANGELOG.md`): |
| 98 | + * Check that all user-facing changes have been recorded. |
| 99 | + * Check that each changelog entry is in the correct category. |
| 100 | + * Check that each changelog entry links to a PR, if applicable. |
| 101 | + * Add or update the changelog's section header with the package version that |
| 102 | + is going to be released, and the date of the release. The version should be |
| 103 | + picked based on our package versioning policy. |
| 104 | +
|
| 105 | +* Cabal file checks (`*.cabal`): |
| 106 | + * Update the `version` field. |
| 107 | + * Update the `tag` field of the `source-repository this` stanza. |
| 108 | +
|
| 109 | +* Cabal project file checks (`cabal.project*`): |
| 110 | + * Update the `index-state` in the `cabal.project` file to the current |
| 111 | + date-time, or the closest valid date-time to the current date-time, so that |
| 112 | + CI builds and tests the libraries with the newest versions of dependencies. |
0 commit comments