diff --git a/docs/support/ghc-version-support.md b/docs/support/ghc-version-support.md index 488a5a1310..46eece5a34 100644 --- a/docs/support/ghc-version-support.md +++ b/docs/support/ghc-version-support.md @@ -75,26 +75,62 @@ Major versions of GHC which are not supported by HLS on master are extremely unl ## GHC version deprecation policy -### Major versions +### Base policy -A major GHC version is a "legacy" version if it is 3 or more major versions behind the latest GHC version that is +This is the static part of the policy that can be checked by a machine. -1. Fully supported by HLS -2. Used in the a Stackage LTS +#### Major versions -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. +HLS will support major versions of GHC until they are older than _both_ -HLS will support all non-legacy major versions of GHC. +1. The major version of GHC used in the current Stackage LTS; and +2. The major version of GHC recommended by GHCup -### Minor versions +For example, if + +1. Stackage LTS uses GHC 9.2; and +2. GHCUp recommends GHC 9.4 + +then HLS will support back to GHC 9.2. + +#### Minor versions For the latest supported major GHC version we will support at least 2 minor versions. 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). -### Announcements +### Extended policy + +This is the part of the policy that needs evaluation by a human and possibly followed +by a discussion. + +#### Ecosystem factors + +To establish and apply the policy we take the following ecosystem factors into account: + +- Support status of HLS +- The most recent [stackage](https://www.stackage.org/) LTS snapshot +- The GHC version recommended by GHCup +- The GHC versions used in the most popular [linux distributions](https://repology.org/project/ghc/versions) +- The reliability of different ghc versions on the major operating systems (Linux, Windows, MacOS) +- The [Haskell Survey results](https://taylor.fausak.me/2022/11/18/haskell-survey-results/#s2q4) -We will warn users about the upcoming deprecation of a GHC version in the notes of the release *prior* to the deprecation itself. +### Supporting a GHC version beyond normal deprecation time + +In cases where the base policy demands a deprecation, but ecosystem factors +suggest that it's still widely used (e.g. last [Haskell Survey results](https://taylor.fausak.me/2022/11/18/haskell-survey-results/#s2q4)), +the deprecation should be suspended for the next release and the situation be re-evaluated for the release after that. + +When we decide to keep on an old version, we should track it as follows: + +1. open a ticket on HLS issue tracker wrt discussing to deprecate said GHC version + - explain the reason the GHC version wasn't deprecated (context) + - explain the maintenance burden it causes (reason) + - evaluate whether it impacts the next HLS release (impact) +2. discuss whether ecosystem factors changed + - e.g. if Haskell Survey results show that 25% or more of users are still on the GHC version in question, then dropping should be avoided +3. if dropping is still undesired, but maintenance burden is also high, then set out a call-for-help and contact HF for additional funding to support this GHC version +4. if no help or funding was received within 2 releases (say, e.g. 3-6 months), then drop the version regardless ### Why deprecate older versions of GHC? @@ -107,12 +143,3 @@ We will warn users about the upcoming deprecation of a GHC version in the notes So we need to limit the GHC support to save maintainers and contributors time and reduce CI resources. At same time we aim to support the right balance of GHC versions to minimize the impact on users. - -### What factors do we take into account when deprecating a version? - -To establish and apply the policy we take into account: - -- Completeness: support includes all plugins and features -- The most recent [stackage](https://www.stackage.org/) LTS snapshot -- The GHC versions used in the most popular [linux distributions](https://repology.org/project/ghc/versions) -- The reliability of different ghc versions on the major operating systems (Linux, Windows, MacOS)