From 8724c835732b36f230d899395841d7304af254d9 Mon Sep 17 00:00:00 2001 From: Javier Neira Date: Tue, 7 Sep 2021 07:35:18 +0200 Subject: [PATCH 1/5] Complete contributing guide With the contents of ./CONTRIBUTING.md (mainly the pre commit hook to format) --- docs/contributing/contributing.md | 93 ++++++++++++++++++++++++++++++- 1 file changed, 90 insertions(+), 3 deletions(-) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index f3a4cda70b..9bfe7167e3 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -13,6 +13,48 @@ However, most editors will need some action to honour those settings automatical For example vscode needs to have installed a specific [extension](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig). Please, try to follow those basic settings to keep the codebase as uniform as possible. +## Formatter pre-commit hook + +We are using [pre-commit-hook.nix](https://github.com/cachix/pre-commit-hooks.nix) to configure git pre-commit hook for formatting. Although it is possible to run formatting manually, we recommend you to use it to set pre-commit hook as our CI checks pre-commit hook is applied or not. + +You can configure the pre-commit-hook by running + +``` bash +nix-shell +``` + +If you don't want to use [nix](https://nixos.org/guides/install-nix.html), you can instead use [pre-commit](https://pre-commit.com) with the following config. + +```json +{ + "repos": [ + { + "hooks": [ + { + "entry": "stylish-haskell --inplace", + "exclude": "(^Setup.hs$|test/testdata/.*$|test/data/.*$|^hie-compat/.*$|^plugins/hls-tactics-plugin/.*$)", + "files": "\\.l?hs$", + "id": "stylish-haskell", + "language": "system", + "name": "stylish-haskell", + "pass_filenames": true, + "types": [ + "file" + ] + } + ], + "repo": "local" + } + ] +} +``` + +### Why some components are excluded from automatic formatting? + +- `test/testdata` and `test/data` are there as we want to test formatting plugins. +- `hie-compat` is there as we want to keep its code as close to GHC as possible. +- `hls-tactics-plugin` is there as the main contributor of the plugin (@isovector) does not want auto-formatting. + ## Building haskell-language-server The project can be built with both `cabal build` and `stack build`. @@ -72,11 +114,52 @@ To create binaries: GHC 8.6.5 is not supported here because `nixpkgs-unstable` no longer maintains the corresponding packages set. -## Introduction tutorial +## Testing -See the [tutorial](./plugin-tutorial.md) on writing a plugin in HLS. +The tests make use of the [Tasty](https://github.com/feuerbach/tasty) test framework. + +There are two test suites in the main haskell-language-server package, functional tests, and wrapper tests. +Other project packages, like the core library or plugins, can have its own test suite. + +### Testing with Cabal + +Running all the tests + +```bash +$ cabal test +``` + +Running just the functional tests -## Test your hacked HLS in your editor +```bash +$ cabal test func-test +``` + +Running just the wrapper tests + +```bash +$ cabal test wrapper-test +``` + +Running a subset of tests + +Tasty supports providing +[Patterns](https://github.com/feuerbach/tasty#patterns) as command +line arguments, to select the specific tests to run. + +```bash +$ cabal test func-test --test-option "-p hlint" +``` + +The above recompiles everything every time you use a different test option though. + +An alternative is + +```bash +$ cabal run haskell-language-server:func-test -- -p "hlint enables" +``` + +### Test your hacked HLS in your editor If you want to test HLS while hacking on it, follow the steps below. @@ -97,6 +180,10 @@ To do every time you changed code and want to test it: - Restart HLS - With VS Code: `Haskell: Restart Haskell LSP Server` +## Introduction tutorial + +See the [tutorial](./plugin-tutorial.md) on writing a plugin in HLS. + ## Adding support for a new editor Adding support for new editors is fairly easy if the editor already has good support for generic LSP-based extensions. From 2be4ee3c7955e7bdc7fac9ff1e32fc685d0cb9fc Mon Sep 17 00:00:00 2001 From: Javier Neira Date: Tue, 7 Sep 2021 07:36:45 +0200 Subject: [PATCH 2/5] Delete CONTRIBUTING.md Included in the main documentation --- CONTRIBUTING.md | 86 ------------------------------------------------- 1 file changed, 86 deletions(-) delete mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 9aee9437f7..0000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,86 +0,0 @@ -# Contributors Guide - -## Pre-commit hook -We are using [pre-commit-hook.nix](https://github.com/cachix/pre-commit-hooks.nix) to configure git pre-commit hook for formatting. Although it is possible to run formatting manually, we recommend you to use it to set pre-commit hook as our CI checks pre-commit hook is applied or not. - -You can configure the pre-commit-hook by running - -``` bash -nix-shell -``` - -If you don't want to use [nix](https://nixos.org/guides/install-nix.html), you can instead use [pre-commit](https://pre-commit.com) with the following config. - -```json -{ - "repos": [ - { - "hooks": [ - { - "entry": "stylish-haskell --inplace", - "exclude": "(^Setup.hs$|test/testdata/.*$|test/data/.*$|^hie-compat/.*$|^plugins/hls-tactics-plugin/.*$)", - "files": "\\.l?hs$", - "id": "stylish-haskell", - "language": "system", - "name": "stylish-haskell", - "pass_filenames": true, - "types": [ - "file" - ] - } - ], - "repo": "local" - } - ] -} -``` - -### Why they are excluded? - -- `test/testdata` and `test/data` are there as we want to test formatting plugins. -- `hie-compat` is there as we want to keep its code as close to GHC as possible. -- `hls-tactics-plugin` is there as the main contributor of the plugin (@isovector) does not want auto-formatting. - -## Testing - -The tests make use of the [Tasty](https://github.com/feuerbach/tasty) test framework. - -There are two test suites, functional tests, and wrapper tests. - -### Testing with Cabal - -Running all the tests - -```bash -$ cabal test -``` - -Running just the functional tests - -```bash -$ cabal test func-test -``` - -Running just the wrapper tests - -```bash -$ cabal test wrapper-test -``` - -Running a subset of tests - -Tasty supports providing -[Patterns](https://github.com/feuerbach/tasty#patterns) as command -line arguments, to select the specific tests to run. - -```bash -$ cabal test func-test --test-option "-p hlint" -``` - -The above recompiles everything every time you use a different test option though. - -An alternative is - -```bash -$ cabal run haskell-language-server:func-test -- -p "hlint enables" -``` From 43456b21860b16370d704aa4a681c491d94c58b9 Mon Sep 17 00:00:00 2001 From: Javier Neira Date: Tue, 7 Sep 2021 07:40:41 +0200 Subject: [PATCH 3/5] Move style guidelines As building and testing are more important imo --- docs/contributing/contributing.md | 98 +++++++++++++++---------------- 1 file changed, 49 insertions(+), 49 deletions(-) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 9bfe7167e3..5a84c20caf 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -6,55 +6,6 @@ The Haskell tooling dream is near, we need your help! - Follow the [Haskell IDE team twitter account](https://twitter.com/IdeHaskell) for updates and help. - Join the [#haskell-tooling channel](https://discord.com/channels/280033776820813825/505370075402862594/808027763868827659) in the Functional Programming discord server. You can join the server via [this invitation](https://discord.gg/9spEdTNGrD). -## Style guidelines - -The project includes a [`.editorconfig`](https://editorconfig.org) [file](https://github.com/haskell/haskell-language-server/blob/master/.editorconfig) with the editor basic settings used by the project. -However, most editors will need some action to honour those settings automatically. -For example vscode needs to have installed a specific [extension](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig). -Please, try to follow those basic settings to keep the codebase as uniform as possible. - -## Formatter pre-commit hook - -We are using [pre-commit-hook.nix](https://github.com/cachix/pre-commit-hooks.nix) to configure git pre-commit hook for formatting. Although it is possible to run formatting manually, we recommend you to use it to set pre-commit hook as our CI checks pre-commit hook is applied or not. - -You can configure the pre-commit-hook by running - -``` bash -nix-shell -``` - -If you don't want to use [nix](https://nixos.org/guides/install-nix.html), you can instead use [pre-commit](https://pre-commit.com) with the following config. - -```json -{ - "repos": [ - { - "hooks": [ - { - "entry": "stylish-haskell --inplace", - "exclude": "(^Setup.hs$|test/testdata/.*$|test/data/.*$|^hie-compat/.*$|^plugins/hls-tactics-plugin/.*$)", - "files": "\\.l?hs$", - "id": "stylish-haskell", - "language": "system", - "name": "stylish-haskell", - "pass_filenames": true, - "types": [ - "file" - ] - } - ], - "repo": "local" - } - ] -} -``` - -### Why some components are excluded from automatic formatting? - -- `test/testdata` and `test/data` are there as we want to test formatting plugins. -- `hie-compat` is there as we want to keep its code as close to GHC as possible. -- `hls-tactics-plugin` is there as the main contributor of the plugin (@isovector) does not want auto-formatting. - ## Building haskell-language-server The project can be built with both `cabal build` and `stack build`. @@ -180,6 +131,55 @@ To do every time you changed code and want to test it: - Restart HLS - With VS Code: `Haskell: Restart Haskell LSP Server` +## Style guidelines + +The project includes a [`.editorconfig`](https://editorconfig.org) [file](https://github.com/haskell/haskell-language-server/blob/master/.editorconfig) with the editor basic settings used by the project. +However, most editors will need some action to honour those settings automatically. +For example vscode needs to have installed a specific [extension](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig). +Please, try to follow those basic settings to keep the codebase as uniform as possible. + +### Formatter pre-commit hook + +We are using [pre-commit-hook.nix](https://github.com/cachix/pre-commit-hooks.nix) to configure git pre-commit hook for formatting. Although it is possible to run formatting manually, we recommend you to use it to set pre-commit hook as our CI checks pre-commit hook is applied or not. + +You can configure the pre-commit-hook by running + +``` bash +nix-shell +``` + +If you don't want to use [nix](https://nixos.org/guides/install-nix.html), you can instead use [pre-commit](https://pre-commit.com) with the following config. + +```json +{ + "repos": [ + { + "hooks": [ + { + "entry": "stylish-haskell --inplace", + "exclude": "(^Setup.hs$|test/testdata/.*$|test/data/.*$|^hie-compat/.*$|^plugins/hls-tactics-plugin/.*$)", + "files": "\\.l?hs$", + "id": "stylish-haskell", + "language": "system", + "name": "stylish-haskell", + "pass_filenames": true, + "types": [ + "file" + ] + } + ], + "repo": "local" + } + ] +} +``` + +#### Why some components are excluded from automatic formatting? + +- `test/testdata` and `test/data` are there as we want to test formatting plugins. +- `hie-compat` is there as we want to keep its code as close to GHC as possible. +- `hls-tactics-plugin` is there as the main contributor of the plugin (@isovector) does not want auto-formatting. + ## Introduction tutorial See the [tutorial](./plugin-tutorial.md) on writing a plugin in HLS. From adbd955f061f03093bb2bedf6ebe00ac4021c469 Mon Sep 17 00:00:00 2001 From: Javier Neira Date: Tue, 7 Sep 2021 08:32:30 +0200 Subject: [PATCH 4/5] Correct grammar Co-authored-by: Jan Hrcek <2716069+jhrcek@users.noreply.github.com> --- docs/contributing/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 5a84c20caf..5cafecdc2d 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -70,7 +70,7 @@ GHC 8.6.5 is not supported here because `nixpkgs-unstable` no longer maintains t The tests make use of the [Tasty](https://github.com/feuerbach/tasty) test framework. There are two test suites in the main haskell-language-server package, functional tests, and wrapper tests. -Other project packages, like the core library or plugins, can have its own test suite. +Other project packages, like the core library or plugins, can have their own test suite. ### Testing with Cabal From b4166d292103d4e7cce0dcc8bb0d9df565694924 Mon Sep 17 00:00:00 2001 From: Javier Neira Date: Tue, 7 Sep 2021 09:12:17 +0200 Subject: [PATCH 5/5] Note cabal run behaviour Co-Authored-By: jhrcek --- docs/contributing/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 5cafecdc2d..f60ca27197 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -104,7 +104,7 @@ $ cabal test func-test --test-option "-p hlint" The above recompiles everything every time you use a different test option though. -An alternative is +An alternative, which only recompiles when tests (or dependencies) change: ```bash $ cabal run haskell-language-server:func-test -- -p "hlint enables"