From fa333bb45c968abf442bb52edebd551a33809629 Mon Sep 17 00:00:00 2001
From: Teo Camarasu <teo.camarasu@tracsis.com>
Date: Mon, 29 Jan 2024 07:57:45 +0000
Subject: [PATCH] Improve preview release documentation

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
---
 CONTRIBUTING.md | 19 +++++++++++++++++++
 README.md       | 22 +++++++++++++++++++++-
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index deb9b51cdf1..d639430354e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -337,6 +337,25 @@ Currently, [@emilypi](https://github.com/emilypi), [@fgaz](https://github.com/fg
 `haskell.org/cabal`, and [@Mikolaj](https://github.com/Mikolaj) is the point of contact for getting
 permissions.
 
+Preview Releases
+----------------
+
+We make preview releases available to facilitate testing of development builds.
+
+Artifacts can be found on the [`cabal-head` release page](https://github.com/haskell/cabal/releases/tag/cabal-head).
+The Validate CI pipeline generates tarballs with a `cabal` executable. The executable gets uploaded to this release by the pipelines that run on `master`.
+
+We currently make available builds for:
+  - Linux, dynamically linked (requiring `zlib`, `gmp`, `glibc`)
+  - Linux, statically linked
+  - MacOS
+  - Windows
+
+The statically linked Linux executables are built using Alpine.
+To reproduce these locally, set up an Alpine build environment using GHCup,
+and then build by calling `cabal build cabal-install --enable-executable-static`.
+
+
 API Documentation
 -----------------
 
diff --git a/README.md b/README.md
index b03daf3a74c..ef856af7efb 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,8 @@ Ways to get the `cabal-install` binary
 2. _[Download from official website](https://www.haskell.org/cabal/download.html)_:
     the `cabal-install` binary download for your platform should contain the `cabal` executable.
 
+#### Preview Releases
+
 _Getting unreleased versions of `cabal-install`_: gives you a chance to try out yet-unreleased features.
 Currently, we only provide binaries for `x86_64` platforms.
 
@@ -40,10 +42,28 @@ Currently, we only provide binaries for `x86_64` platforms.
     ```
 
     Replace "Linux" with "Windows" or "macOS" as appropriate.
+    
+    The default Linux build is dynamically linked against `zlib`, `gmp` and `glibc`.
+    You will need to have appropriate versions of these libraries installed to use it.
+    Alternatively a statically linked "Linux-static" binary is also provided.
+
+    You might need to add the following to your `cabal.project` file
+    if your build fails because of an out-of-date `Cabal` library:
+    ```
+    allow-newer: 
+      *:Cabal,
+      *:Cabal-syntax
+
+    source-repository-package
+        type: git
+        location: https://github.com/haskell/cabal.git
+        subdir: Cabal Cabal-syntax
+    ```
 
 
 2. Even more cutting-edge binaries built from pull requests are always available
-   from the `Validate` worklow page on GitHub, at the very bottom of the page.
+   from the `Validate` worklow page on GitHub, at the very bottom of the page,
+   or from the `build-alpine` workflow for statically linked Linux builds.
 
 Ways to build `cabal-install` for everyday use
 --------------------------------------------