Skip to content

doc: supported-versions: add notes on adding new GHCs #2548

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: master
Choose a base branch
from
Draft

doc: supported-versions: add notes on adding new GHCs #2548

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d9d6fda
doc: contributing: m upd
Anton-Latukha Dec 27, 2021
623b023
doc: supported-versions: add note on 9.0.2
Anton-Latukha Dec 27, 2021
20c7f8e
doc: supported-versions: add initial notes on adding new GHCs
Anton-Latukha Dec 27, 2021
22775ed
doc: supported-versions: m upd
Anton-Latukha Dec 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/contributing/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,17 +51,17 @@ If you are using nix 2.4 style command (enabled by `experimental-features = nix-
you can use `nix develop` instead of `nix-shell` to enter the development shell. To enter the shell with specific GHC versions:

* `nix develop` or `nix develop .#haskell-language-server-dev` - default GHC version
* `nix develop .#haskell-language-server-8107-dev` - GHC 8.10.7
* `nix develop .#haskell-language-server-884-dev` - GHC 8.8.4
* `nix develop .#haskell-language-server-8107-dev` - GHC 8.10.7
* `nix develop .#haskell-language-server-901-dev` - GHC 9.0.1

If you are looking for a Nix expression to create haskell-language-server binaries, see https://github.com/haskell/haskell-language-server/issues/122

To create binaries:

* `nix build` or `nix build .#haskell-language-server` - default GHC version
* `nix build .#haskell-language-server-8107` - GHC 8.10.7
* `nix build .#haskell-language-server-884` - GHC 8.8.4
* `nix build .#haskell-language-server-8107` - GHC 8.10.7
* `nix build .#haskell-language-server-901` - GHC 9.0.1

GHC 8.6.5 is not supported here because `nixpkgs-unstable` no longer maintains the corresponding packages set.
Expand Down
21 changes: 21 additions & 0 deletions docs/supported-versions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ The current support for different GHC versions is given in the following table.
| GHC version | Last supporting HLS version | Deprecation status |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| 9.2.0 | [not supported](https://github.com/haskell/haskell-language-server/issues/2179) yet | |
| 9.0.2 | [not supported](https://github.com/haskell/haskell-language-server/issues/2536) yet | |
| 9.0.1 | [current](https://github.com/haskell/haskell-language-server/releases/latest) ([partial](https://github.com/haskell/haskell-language-server/issues/297)) | |
| 8.10.7 | [current](https://github.com/haskell/haskell-language-server/releases/latest) | |
| 8.10.6 | [current](https://github.com/haskell/haskell-language-server/releases/latest) | will be deprecated after LTS and HLS full support for ghc-9.0 |
Expand All @@ -25,6 +26,26 @@ GHC versions not in the list have never been supported by HLS, or are not planne

The policy for when we deprecate support for versions of GHC is given below. The table reflects that, but we may decide to deviate from it for good reasons.

### Support for the new GHC version
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this belongs in Contributing. The intended audience of this page is users, and this isn't of interest to users, but rather to contributors who would go through this process.

Copy link
Collaborator Author

@Anton-Latukha Anton-Latukha Dec 28, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

idk, the deprecation process described in this file, & the versioning information is here, so both support versions & deprecation of versions in this file, I thought it only logical to add an introduction of the new version here also to have the full GHC version lifecycle described in it.

I agree that I formulate it & present it as being useful for contributors. But that is one of agendas. (I imagine hypothetically) the majority of people who would search "why new version is not yet supported" - are users & hopefully would be directed to doc & would read the doc & majority of them would be satisfied with the answer that "it is complex, we working on it" & factually would not contribute, but some would get the cycle map & would try to contribute. And that is also why doc is formulated to encourage taking part in the activity.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The deprecation policy is in here because we expect users to want to know "why is version X of GHC (which I care about) not supported".

the majority of people who would search "why new version is not yet supported" - are users & hopefully would be directed to doc & would read the doc & majority of them would be satisfied with the answer that "it is complex, we working on it"

That's not what this piece of documentation conveys, though! I think it would make sense to have a section here describing the basic policy for when new versions are included (e.g. "upstream tools and packages must support it, and some compatibility work must be done, here are links to the tracking tickets"), but a detailed checklist of steps belongs in the contributing documentation IMO.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe the main content could go to contributing and link it here?


1. The platform installers of GHC must provide install support for the new GHC version.
* [ghcup-metadata](https://github.com/haskell/ghcup-metadata) for `ghcup`.
* [GhcChoco](https://github.com/Mistuke/GhcChoco) for Windows.
2. A report opened in [HLS reports](https://github.com/haskell/haskell-language-server/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22type%3A+distribution%22) with `type: distribution` label.
3. Provision the code for HLS to work with the new GHC version. That PR would:
* Have the code that supports the new GHC.
* Major GHC release support [is a complex task](https://github.com/haskell/haskell-language-server/pull/2503) & so would be often a crowdsource work, in that case in the branch do not force push.
* [Minor GHC release support example](https://github.com/haskell/haskell-language-server/pull/1899)
* Regardless of the type of GHC release the PR would need to (can be asked to crowdsource):
* Update to `.cabal` (at least `tested-with`), create new/update `.project` files (at least update `index-state`).
* Provide support through `stack*.yml` files.
* During work/builds GHC API changes would/may appear, they should be mirrored in `Compat*` modules.
* Enable CI to build-test with the new GHC release.
* Pass the CI.
4. A period of testing.
5. Doing [the HLS release](./contributing/releases.md).
6. `ghcup` to support the installation.

### Using deprecated GHC versions

Users who want to use a GHC version which is not supported by the latest HLS can still use older versions of HLS (consult the version support table above to identify the appropriate HLS version).
Expand Down