Merge remote-tracking branch 'tracsis/master' into release

Author: dten

.github/workflows/integration-tests.yml

@@ -49,11 +49,21 @@ jobs:
           ~\AppData\Roaming\stack
           ~\AppData\Local\Programs\stack
         key: ${{ runner.os }}-${{ hashFiles('stack.yaml') }}-${{ matrix.cache-bust }}
+    - name: Update PATH on Windows
+      if: startsWith(runner.os, 'Windows')
+      run: |
+        # On Windows, `stack upgrade` fails to overwrite the Stack executable at
+        # C:\hostedtoolcache\windows\stack\2.9.1\x64\, so add location of
+        # upgraded Stack executable to the PATH for subsequent steps:
+        Add-Content $env:GITHUB_PATH "C:\Users\runneradmin\AppData\Roaming\local\bin"
     - name: Install deps and run checks
       shell: bash
       run: |
         set -ex
 
+        # Stack 2.9.3 is required to build Stack
+        stack upgrade
+
         if [[ "${{ matrix.os }}" == "ubuntu-latest" ]]
         then
           # Retry installing nix due to nondeterministic error
@@ -93,7 +103,8 @@ jobs:
 
     - name: Build bindist
       shell: bash
-      run: stack etc/scripts/release.hs build ${{ matrix.release-args }}
+      run: |
+        stack etc/scripts/release.hs build ${{ matrix.release-args }}
 
     - name: Upload bindist
       uses: actions/upload-artifact@v3

.github/workflows/unit-tests.yml

@@ -27,7 +27,10 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-
     - name: Pedantic build
-      run: stack --system-ghc build --pedantic
+      run: |
+        # Stack 2.9.3 is required to build Stack
+        stack upgrade
+        stack build --pedantic
   unit-tests:
     name: Unit tests
     runs-on: ${{ matrix.os }}
@@ -64,11 +67,21 @@ jobs:
           ~\AppData\Roaming\stack
           ~\AppData\Local\Programs\stack
         key: ${{ runner.os }}-${{ hashFiles('stack.yaml') }}-${{ matrix.extra-suffix }}
+    - name: Update PATH on Windows
+      if: startsWith(runner.os, 'Windows')
+      run: |
+        # On Windows, `stack upgrade` fails to overwrite the stack executable at
+        # C:\hostedtoolcache\windows\stack\2.9.1\x64\, so add location of
+        # upgraded Stack executable to the PATH for subsequent steps:
+        Add-Content $env:GITHUB_PATH "C:\Users\runneradmin\AppData\Roaming\local\bin"
     - name: Run tests
       shell: bash
       run: |
         set -ex
 
+        # Stack 2.9.3 is required to build Stack
+        stack upgrade
+
         if [[ "${{ matrix.extra-suffix }}" == "alpine" ]]
         then
             mkdir -p ~/.stack

CONTRIBUTING.md

@@ -275,14 +275,33 @@ updates with your pull request.
 
 ## Backwards Compatability
 
-The Stack executable does not need to, and does not, strive for the same broad
-compatibility with versions of GHC that a library package (such as `pantry`)
-would seek. Instead, Stack aims to define a well-known combination of
-dependencies on which its executable relies. That applies in particular to the
-`Cabal` package, where Stack aims to support one, and only one, version of
-`Cabal` with each release of its executable. At the time of writing (September
-2022) that combination is defined by resolver `nightly-2022-11-14` (for
-GHC 9.2.4, and including `Cabal-3.6.3.0`) - see `stack.yaml`.
+The Stack package provides a library and an executable (`stack`) that depends on
+the library. The library is intended for use only by the executable.
+
+Consequently, the Stack package does not need to, and does not, strive for the
+compatibility with a range of versions of GHC that a library package (such as
+`pantry`) would seek.
+
+Stack aims to depend on well-known packages. The specific versions on which it
+depends at any time are specified by `package.yaml` and `stack.yaml`. It does
+not aim to be compatible with more than one version of the `Cabal` package at
+any time. At the time of writing (March 2023) the package versions are primarily
+ones in Stackage snapshot LTS Haskell 20.13 (for GHC 9.2.7), together with
+extra-dep `Cabal-3.8.1.0`.
+
+A Stack executable makes use of Cabal (the library) through a small 'Setup'
+executable that it compiles from Haskell source code. The executable compiles
+that code with a dependency on the version of Cabal that ships with the
+specified GHC compiler. Each release of Stack will aim to support all versions
+of GHC and the Cabal package in Stackage snapshots published within seven years
+of the release. For example, snapshot LTS Haskell 2.22, published on
+9 August 2015, was the last to provide GHC 7.8.4 which comes with
+`Cabal-1.18.1.5`. Until, at least, 9 August 2022, Stack releases would aim
+to support GHC 7.8.4 and `Cabal-1.18.1.5`.
+
+When a version of the Stack executable actually ceases to support a version of
+GHC and `Cabal`, that should be recorded in Stack's
+[ChangeLog](https://github.com/commercialhaskell/stack/blob/master/ChangeLog.md).
 
 ## Code Quality
 
@@ -329,6 +348,48 @@ Once installed, you can check your changes with command:
 stack exec -- sh ./etc/scripts/hlint.sh
 ~~~
 
+## Code Style
+
+A single code style is not applied consistently to Stack's code and Stack is not
+Procrustean about matters of style. Rules of thumb, however, are:
+
+* keep pull requests that simply reformat code separate from those that make
+  other changes to code; and
+* when making changes to code other than reformatting, follow the existing style
+  of the function(s) or module(s) in question.
+
+That said, the following may help:
+
+* Stack's code generally avoids the use of C preprocessor (CPP) directives.
+  Windows and non-Windows code is separated in separate source code directories
+  and distinguished in Stack's Cabal file. `Stack.Constants.osIsWindows :: Bool`
+  is provided. Multi-line strings are generally formatted on the assumption that
+  GHC's `CPP` language pragma is not being used.
+* Language pragmas usually start with `NoImplictPrelude`, where applicable, and
+  then all others are listed alphabetically. The closing `#-}` are aligned, for
+  purely aesthetic reasons.
+* Stack is compiled with GHC's `-Wall` enabled, which includes `-Wtabs` (no tabs
+  in source code). Most modules are based on two spaces (with one space for a
+  `where`) for indentation but older and larger modules are still based on four
+  spaces.
+* Stack's code and documentation tends to be based on lines of no more than 80
+  characters or, if longer, no longer than necessary.
+* Stack uses export lists.
+* Stack's imports are listed alphabetically, including `Stack.Prelude`, where
+  applicable. The module names are left aligned, with space left for `qualified`
+  where it is absent.
+* Stack's code is sufficiently stable that explict import lists can sensibly be
+  used. The exception is the import of `Stack.Prelude`. Not all modules have
+  comprehensive explicit import lists.
+* Short explicit import lists follow the module name. Longer lists start on the
+  line below the module name. Spaces are used to separate listed items from
+  their enclosing parentheses.
+* As noted above, the types used to implement Stack's exceptions and the related
+ `instance` definitions are usually located at the top of the relevant module.
+* In function type signatures, the `::` is kept on the same line as the
+  function's name. This format is Haskell syntax highlighter-friendly.
+* If `where` is used, the declarations follow on a separate line.
+
 ## Testing
 
 The Stack code has both unit tests and integration tests. Integration tests can

cabal.config

@@ -1,13 +1,14 @@
 constraints:
-  , Cabal ==3.6.3.0
-  , Cabal-syntax ==3.6.0.0
+  , Cabal ==3.8.1.0
+  , Cabal-syntax ==3.8.1.0
   , Glob ==0.10.2
   , OneTuple ==0.3.1
   , QuickCheck ==2.14.2
   , StateVar ==1.2.2
+  , Win32 ==2.12.0.1
   , aeson ==2.0.3.0
   , annotated-wl-pprint ==0.7.0
-  , ansi-terminal ==0.11.3
+  , ansi-terminal ==0.11.4
   , ansi-wl-pprint ==0.6.9
   , appar ==0.1.8
   , array ==0.5.4.0
@@ -19,126 +20,127 @@ constraints:
   , attoparsec ==0.14.4
   , attoparsec-iso8601 ==1.0.2.1
   , auto-update ==0.1.6
-  , base ==4.16.3.0
+  , base ==4.16.4.0
   , base-compat ==0.12.2
   , base-compat-batteries ==0.12.2
-  , base-orphans ==0.8.7
+  , base-orphans ==0.8.8.2
   , base16-bytestring ==1.0.2.0
   , base64-bytestring ==1.2.1.0
   , basement ==0.0.15
-  , bifunctors ==5.5.12
+  , bifunctors ==5.5.15
   , binary ==0.8.9.0
   , blaze-builder ==0.4.2.2
   , blaze-html ==0.9.1.2
   , blaze-markup ==0.8.2.8
   , byteorder ==1.0.4
-  , bytestring ==0.11.3.1
+  , bytestring ==0.11.4.0
   , casa-client ==0.0.1
   , casa-types ==0.0.2
   , case-insensitive ==1.2.1.0
   , cereal ==0.5.8.3
   , clock ==0.8.3
-  , cmdargs ==0.10.21
+  , cmdargs ==0.10.22
   , colour ==2.3.6
   , comonad ==5.0.8
-  , conduit ==1.3.4.2
+  , conduit ==1.3.4.3
   , conduit-combinators ==1.3.0
   , conduit-extra ==1.3.6
   , connection ==0.3.1
   , containers ==0.6.5.1
   , contravariant ==1.5.5
-  , cookie ==0.4.5
+  , cookie ==0.4.6
   , cryptohash-sha256 ==0.11.102.1
   , cryptonite ==0.30
   , cryptonite-conduit ==0.2.2
+  , data-array-byte ==0.1.0.1
   , data-default-class ==0.1.2.0
   , data-fix ==0.3.2
   , deepseq ==1.4.6.1
-  , digest ==0.0.1.3
+  , digest ==0.0.1.7
   , directory ==1.3.6.2
   , distributive ==0.6.2.1
   , dlist ==1.0
-  , easy-file ==0.2.2
+  , easy-file ==0.2.3
   , echo ==0.1.4
   , ed25519 ==0.0.5.0
   , exceptions ==0.10.4
-  , extra ==1.7.12
-  , fast-logger ==3.1.1
+  , extra ==1.7.13
+  , fast-logger ==3.1.2
   , file-embed ==0.0.15.0
   , filelock ==0.1.1.5
   , filepath ==1.4.2.2
   , fsnotify ==0.4.1.0
-  , generic-deriving ==1.14.2
+  , generic-deriving ==1.14.3
   , ghc-bignum ==1.2
-  , ghc-boot-th ==9.2.4
+  , ghc-boot-th ==9.2.7
   , ghc-prim ==0.8.0
-  , githash ==0.1.6.2
-  , hackage-security ==0.6.2.2
-  , hashable ==1.4.1.0
+  , githash ==0.1.6.3
+  , hackage-security ==0.6.2.3
+  , hashable ==1.4.2.0
   , hi-file-parser ==0.1.3.0
   , hinotify ==0.4.1
   , hourglass ==0.2.12
-  , hpack ==0.35.0
+  , hpack ==0.35.2
   , hpc ==0.6.1.0
   , http-api-data ==0.4.3
   , http-client ==0.7.13.1
   , http-client-tls ==0.3.6.1
   , http-conduit ==2.3.8
   , http-download ==0.2.0.0
   , http-types ==0.12.3
-  , indexed-traversable ==0.1.2
-  , indexed-traversable-instances ==0.1.1.1
+  , indexed-traversable ==0.1.2.1
+  , indexed-traversable-instances ==0.1.1.2
   , infer-license ==0.2.0
   , integer-gmp ==1.1
   , integer-logarithms ==1.0.3.1
   , iproute ==1.7.12
   , libyaml ==0.1.2
-  , lift-type ==0.1.0.1
+  , lift-type ==0.1.1.1
   , lifted-base ==0.2.3.12
   , lukko ==0.1.1.3
   , megaparsec ==9.2.2
   , memory ==0.17.0
   , microlens ==0.4.12.0
-  , microlens-mtl ==0.2.0.2
-  , microlens-th ==0.4.3.10
+  , microlens-mtl ==0.2.0.3
+  , microlens-th ==0.4.3.11
   , mime-types ==0.1.0.9
   , mintty ==0.1.4
   , monad-control ==1.0.3.1
-  , monad-logger ==0.3.37
+  , monad-logger ==0.3.39
   , monad-loops ==0.4.3
   , mono-traversable ==1.0.15.3
   , mtl ==2.2.2
   , mtl-compat ==0.2.2
   , mustache ==2.4.1
   , neat-interpolation ==0.5.1.3
-  , network ==3.1.2.7
-  , network-uri ==2.6.4.1
+  , network ==3.1.2.8
+  , network-uri ==2.6.4.2
   , old-locale ==1.0.0.7
   , old-time ==1.1.0.3
   , open-browser ==0.2.1.0
   , optparse-applicative ==0.17.0.0
   , optparse-simple ==0.1.1.4
-  , pantry ==0.7.0
+  , pantry ==0.8.2.1
   , parsec ==3.1.15.0
   , parser-combinators ==1.3.0
   , path ==0.9.2
   , path-io ==1.7.0
   , path-pieces ==0.2.1
   , pem ==0.2.4
-  , persistent ==2.13.3.5
-  , persistent-sqlite ==2.13.1.0
+  , persistent ==2.14.5.0
+  , persistent-sqlite ==2.13.1.1
   , persistent-template ==2.12.0.0
   , pretty ==1.1.3.6
   , primitive ==0.7.3.0
-  , process ==1.6.13.2
+  , process ==1.6.16.0
   , project-template ==0.2.1.0
   , random ==1.2.1.1
   , resource-pool ==0.2.3.2
   , resourcet ==1.2.6
   , retry ==0.9.3.0
   , rio ==0.1.22.0
   , rio-orphans ==0.1.2.0
-  , rio-prettyprint ==0.1.1.0
+  , rio-prettyprint ==0.1.4.0
   , rts ==1.0.2
   , safe ==0.3.19
   , safe-exceptions ==0.1.7.3
@@ -152,10 +154,10 @@ constraints:
   , splitmix ==0.1.0.4
   , stack ==2.10.0
   , stm ==2.5.0.2
-  , stm-chans ==3.0.0.6
-  , streaming-commons ==0.2.2.4
+  , stm-chans ==3.0.0.9
+  , streaming-commons ==0.2.2.5
   , strict ==0.4.0.1
-  , syb ==0.7.2.1
+  , syb ==0.7.2.3
   , tagged ==0.8.6.1
   , tar ==0.5.1.1
   , tar-conduit ==0.3.2
@@ -164,10 +166,10 @@ constraints:
   , text ==1.2.5.0
   , text-metrics ==0.3.2
   , text-short ==0.1.5
-  , th-abstraction ==0.4.4.0
+  , th-abstraction ==0.4.5.0
   , th-compat ==0.1.4
-  , th-expand-syns ==0.4.10.0
-  , th-lift ==0.8.2
+  , th-expand-syns ==0.4.11.0
+  , th-lift ==0.8.3
   , th-lift-instances ==0.1.20
   , th-reify-many ==0.1.10
   , these ==1.1.1.1
@@ -177,14 +179,14 @@ constraints:
   , transformers ==0.5.6.2
   , transformers-base ==0.4.6
   , transformers-compat ==0.7.2
-  , typed-process ==0.2.10.1
-  , unicode-data ==0.3.0
+  , typed-process ==0.2.11.0
+  , unicode-data ==0.3.1
   , unicode-transforms ==0.4.0.1
   , unix ==2.7.2.2
   , unix-compat ==0.5.4
-  , unix-time ==0.4.7
-  , unliftio ==0.2.22.0
-  , unliftio-core ==0.2.0.1
+  , unix-time ==0.4.9
+  , unliftio ==0.2.24.0
+  , unliftio-core ==0.2.1.0
   , unordered-containers ==0.2.19.1
   , uuid-types ==1.0.5
   , vault ==0.3.1.5
@@ -195,6 +197,6 @@ constraints:
   , x509-store ==1.6.9
   , x509-system ==1.6.7
   , x509-validation ==1.6.12
-  , yaml ==0.11.8.0
-  , zip-archive ==0.4.2.1
+  , yaml ==0.11.11.0
+  , zip-archive ==0.4.3
   , zlib ==0.6.3.0