Skip to content

Commit f143cf1

Browse files
michaelpjmichaelpj
authored
Add policy on plugin support tiers (#3189)
Following discussion in #3123. This aims to make it more obvious what it means when we say we support a version of GHC.
1 parent b4abea7 commit f143cf1

File tree

8 files changed

+185
-140
lines changed

8 files changed

+185
-140
lines changed

‎docs/contributing/releases.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@ and it is being used in nix environments.
1818

1919
### prerelease sanity checks
2020

21-
- [ ] set the supported GHC versions and their corresponding cabal project-files in `bindist/ghcs` according to the [GHC version deprecation policy](../supported-versions.md#ghc-version-deprecation-policy)
21+
- [ ] check that all plugins work according to their [support tiers](../support/plugin-support.md)
22+
- [ ] set the supported GHC versions and their corresponding cabal project-files in `bindist/ghcs` according to the [GHC version deprecation policy](../support/ghc-version-support.md#ghc-version-deprecation-policy)
2223
- [ ] [trigger manually](https://docs.github.com/es/actions/managing-workflow-runs/manually-running-a-workflow) the hackage workflow *without* uploading the packages
2324
- [ ] trigger manually the build workflow
2425
- [ ] create a prerelease tag `${version}-check-gitlab` and push it to the [project repo in gitlab](https://gitlab.haskell.org/haskell/haskell-language-server) to check the build is fine

‎docs/features.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Many of these are standard LSP features, but a lot of special features are provi
2222
| [Rename](#rename) | `textDocument/rename` |
2323

2424
The individual sections below also identify which [HLS plugin](./what-is-hls.md#hls-plugins) is responsible for providing the given functionality, which is useful if you want to raise an issue report or contribute!
25-
Additionally, not all plugins are supported on all versions of GHC, see the [GHC version support page](supported-versions.md) for details.
25+
Additionally, not all plugins are supported on all versions of GHC, see the [plugin support page](./support/plugin-support.md) for details.
2626

2727
## Diagnostics
2828

‎docs/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Official Haskell Language Server implementation. :ref:`Read more<What is haskell
99
what-is-hls
1010
features
1111
installation
12-
supported-versions
12+
support/index
1313
configuration
1414
troubleshooting
1515
contributing/index

‎docs/support/ghc-version-support.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# GHC version support
2+
3+
## Current GHC version support status
4+
5+
The current support for different GHC versions is given in the following table.
6+
7+
Last supporting HLS version:
8+
- "next": this GHC version is supported in master, and will be in the next released version of HLS.
9+
- "latest": this GHC version is one of the actively supported versions (see below) and is supported in the latest released version of HLS.
10+
- specific version number: this GHC version is no longer one of the actively supported versions, and the last version of HLS which supports it is listed.
11+
12+
Support status (see the support policy below for more details):
13+
- "initial support": support for this GHC version is underway, but it is not ready to be released yet
14+
- "basic support": this GHC version is currently actively supported, and all [tier 1 plugins](./plugin-support.md) work
15+
- "full support": this GHC version is currently actively supported, and most [tier 2 plugins](./plugin-support.md) work
16+
- "deprecated": this GHC version was supported in the past, but is now deprecated
17+
18+
| GHC version | Last supporting HLS version | Support status |
19+
|--------------|------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
20+
| 9.4.2 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | basic support |
21+
| 9.4.1 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | basic support |
22+
| 9.2.4 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | full support |
23+
| 9.2.3 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | full support |
24+
| 9.2.(1,2) | [1.7.0.0](https://github.com/haskell/haskell-language-server/releases/tag/1.7.0.0) | deprecated |
25+
| 9.0.2 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | full support |
26+
| 9.0.1 | [1.6.1.0](https://github.com/haskell/haskell-language-server/releases/tag/1.6.1.0) | deprecated |
27+
| 8.10.7 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | full support |
28+
| 8.10.6 | [1.6.1.0](https://github.com/haskell/haskell-language-server/releases/tag/1.6.1.0) | deprecated |
29+
| 8.10.5 | [1.5.1](https://github.com/haskell/haskell-language-server/releases/tag/1.5.1) | deprecated |
30+
| 8.10.(4,3,2) | [1.4.0](https://github.com/haskell/haskell-language-server/releases/tag/1.4.0) | deprecated |
31+
| 8.10.1 | [0.9.0](https://github.com/haskell/haskell-language-server/releases/tag/0.9.0) | deprecated |
32+
| 8.8.4 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | full support, will be deprecated after LTS and HLS full support for ghc-9.2 |
33+
| 8.8.3 | [1.5.1](https://github.com/haskell/haskell-language-server/releases/1.5.1) | deprecated |
34+
| 8.8.2 | [1.2.0](https://github.com/haskell/haskell-language-server/releases/tag/1.2.0) | deprecated |
35+
| 8.6.5 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | full support, will be deprecated after LTS and HLS full suppot for ghc-9.2 |
36+
| 8.6.4 | [1.4.0](https://github.com/haskell/haskell-language-server/releases/tag/1.4.0) | deprecated |
37+
38+
GHC versions not in the list have never been supported by HLS.
39+
LTS stands for [Stackage](https://www.stackage.org/) Long Term Support.
40+
41+
The policy for when we deprecate support for versions of GHC is given below.
42+
The table reflects that, but we may decide to deviate from it for good reasons.
43+
44+
### Using deprecated GHC versions
45+
46+
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).
47+
In the future, we may extend the existing discovery mechanisms (`haskell-language-server-wrapper`, automatic download in vscode extension) to find and download older HLS binaries in this case.
48+
49+
Users of a deprecated minor version (where the major version is still supported) can try building the latest HLS from source, which will likely still work, since the GHC API tends to remain compatible across minor versions.
50+
51+
### Using GHC versions not yet supported in a HLS release
52+
53+
Some users may wish to use a version of GHC that is not yet supported by a released version of HLS.
54+
In particular, this means that pre-built binaries will not be available for that GHC version.
55+
56+
The easiest thing to do in this case is to build HLS from source yourself.
57+
This can be done easily with `ghcup`, see the examples for `ghcup compile` on the [installation page](../installation.md).
58+
59+
Generally, if a version of GHC is supported by HLS on master _or_ is a new minor version of a GHC version that is supported by HLS on master, then compiling from source is likely to work.
60+
Major versions of GHC which are not supported by HLS on master are extremely unlikely to work.
61+
62+
## GHC version deprecation policy
63+
64+
### Major versions
65+
66+
A major GHC version is a "legacy" version if it is 3 or more major versions behind the latest GHC version that is
67+
68+
1. Fully supported by HLS
69+
2. Used in the a Stackage LTS
70+
71+
For example, if 9.2 is the latest major version fully supported by HLS and used in a Stackage LTS, then the 8.8 major version and older will be legacy.
72+
73+
HLS will support all non-legacy major versions of GHC.
74+
75+
### Minor versions
76+
77+
For the latest supported major GHC version we will support at least 2 minor versions.
78+
79+
For the rest of the supported major GHC versions, we will support at least the latest minor version in Stackage LTS (so 1 minor version).
80+
81+
### Announcements
82+
83+
We will warn users about the upcoming deprecation of a GHC version in the notes of the release *prior* to the deprecation itself.
84+
85+
### Why deprecate older versions of GHC?
86+
87+
`haskell-language-server`(HLS) is highly tied to the GHC API. This imposes a high maintenance cost:
88+
89+
- The codebase is littered with conditional logic
90+
- We own auxiliary packages to support older versions of GHC
91+
- CI has to cover all the supported versions
92+
93+
So we need to limit the GHC support to save maintainers and contributors time and reduce CI resources.
94+
95+
At same time we aim to support the right balance of GHC versions to minimize the impact on users.
96+
97+
### What factors do we take into account when deprecating a version?
98+
99+
To establish and apply the policy we take into account:
100+
101+
- Completeness: support includes all plugins and features
102+
- The most recent [stackage](https://www.stackage.org/) LTS snapshot
103+
- The GHC versions used in the most popular [linux distributions](https://repology.org/project/ghc/versions)
104+
- The reliability of different ghc versions on the major operating systems (Linux, Windows, MacOS)

‎docs/support/index.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
GCH and Plugin Support
2+
======================
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
ghc-version-support
8+
plugin-support

‎docs/support/plugin-support.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Plugin support
2+
3+
## Plugin support tiers
4+
5+
Plugins vary in how well-supported they are, in particular how quickly they are updated to support new GHC versions.
6+
This is important to keep track of because we want to release new versions of HLS for new GHC versions quickly, but also to present a consistent set of features.
7+
8+
For this reason we group plugins into _support tiers_.
9+
10+
**Tier 1**
11+
12+
A tier 1 plugin is a plugin which we believe is so essential to the functioning of HLS that we should not release HLS unless the plugin is working for all supported GHC versions.
13+
14+
Tier 1 plugins must be well-supported, or else we will be blocked from releasing HLS.
15+
If we are not able to maintain tier 1 plugins, then we have a critical maintenance problem.
16+
Consequently, few plugins should be considered tier 1.
17+
18+
**Tier 2**
19+
20+
A tier 2 plugin is a plugin which is important or well-enough maintained that we usually will not release HLS unless the plugin is working for all supported GHC versions.
21+
22+
Tier 2 plugins should be well-supported enough to usually make the cut for HLS releases, but we will not hold a release for one.
23+
24+
Tier 2 plugins provide a decent experience for users, since they can (mostly) rely on them being present in a release.
25+
Hence, most plugins should ideally be tier 2.
26+
27+
**Tier 3**
28+
29+
A tier 3 plugin is anything else.
30+
31+
Tier 3 plugins are maintained on a best-effort basis, often by irregular contributors.
32+
A plugin may have to be tier 3 despite being well-maintained if it depends on a tool (e.g. a formatter) which is not itself reliably updated for new GHC versions.
33+
34+
Since we cannot make any guarantees that a tier 3 plugin will be working, they provide a bad experience for users.
35+
Hence a tier 3 plugin should ideally have some kind of plan for getting out of tier 3, either by getting the plugin to tier 2 or by sunsetting it.
36+
For example, a plugin to provide a formatter which has itself been abandoned has no hope of reaching tier 2, but may be gracefully sunset by only being supported for old versions of GHC, and deleted once those exit our GHC support window.
37+
38+
## Current plugin support tiers
39+
40+
| Plugin | Tier | Unsupported GHC versions |
41+
|-------------------------------------|------|--------------------------|
42+
| ghcide core plugins | 1 | |
43+
| `hls-call-hierarchy-plugin` | 1 | |
44+
| `hls-code-range-plugin` | 1 | |
45+
| `hls-explicit-imports-plugin` | 1 | |
46+
| `hls-pragmas-plugin` | 1 | |
47+
| `hls-refactor-plugin` | 1 | 9.4 |
48+
| `hls-alternate-number-plugin` | 2 | |
49+
| `hls-class-plugin` | 2 | 9.4 |
50+
| `hls-change-type-signature-plugin` | 2 | |
51+
| `hls-eval-plugin` | 2 | 9.4 |
52+
| `hls-expliit-fixity-plugin` | 2 | |
53+
| `hls-floskell-plugin` | 2 | 9.4 |
54+
| `hls-fourmolu-plugin` | 2 | 9.4 |
55+
| `hls-gadt-plugin` | 2 | 9.4 |
56+
| `hls-hlint-plugin` | 2 | 9.4 |
57+
| `hls-module-name-plugin` | 2 | |
58+
| `hls-qualify-imported-names-plugin` | 2 | |
59+
| `hls-ormolu-plugin` | 2 | 9.4 |
60+
| `hls-rename-plugin` | 2 | 9.4 |
61+
| `hls-refine-imports-plugin` | 2 | |
62+
| `hls-stylish-haskell-plugin` | 2 | 9.4 |
63+
| `hls-tactics-plugin` | 2 | 9.2, 9.4 |
64+
| `hls-brittany-plugin` | 3 | 9.2, 9.4 |
65+
| `hls-haddock-comments-plugin` | 3 | 9.2, 9.4 |
66+
| `hls-stan-plugin` | 3 | 8.6, 9.0, 9.2, 9.4 |
67+
| `hls-retrie-plugin` | 3 | 9.2, 9.4 |
68+
| `hls-splice-plugin` | 3 | 9.2, 9.4 |

0 commit comments

Comments
 (0)