Update top-level installation/configuration pages

1 files changed, 68 insertions, 36 deletions

diff --git a/packages.md b/packages.md
index 80b6550..28a3826 100644
--- a/packages.md
+++ b/packages.md
@@ -1,70 +1,102 @@
 ---
-title: Package mirrors
+title: Package Repositories
 ---
 
-sr.ht operates a number of automatically-updated package repositories where you
-can find packages for sr.ht software in various distributions at
+SourceHut operates a number of package repositories for sr.ht software. These
+repositories, which support various distributions, are available at
 [mirror.sr.ht](https://mirror.sr.ht).
 
-All of our package repositories accept patches as necessary on
-[sr.ht-packages](https://lists.sr.ht/~sircmpwn/sr.ht-packages).
+If you would like to contribute to the package repositories, we accept
+patches on the [sr.ht-packages](https://lists.sr.ht/~sircmpwn/sr.ht-packages)
+mailing list.
 
-# Package Repositories
+<div class="alert alert-warning">
+  <p>
+    <strong>Warning:</strong> SourceHut is still in alpha, and has no stable
+    releases. As such, we do not recommend packaging SourceHut for your upstream
+    distribution repositories until we have shipped stable versions of our
+    software.
+  </p>
+  <p>
+    If you are still interested in packaging it for your distribution, please
+    reach out to us for help in automating the maintenance of a third-party
+    distribution which is automatically updated following our (frequent)
+    upstream rolling releases.
+  </p>
+</div>
 
-## Alpine Linux
+# Alpine Linux
 
-This is the recommended distribution of SourceHut, and the one we use for the
-hosted instance upstream. This must be the first line in `/etc/apk/repositories`
-&mdash; we shadow some upstream packages with patched versions. You will need
-the community repository enabled.
+**Mirror**: https://mirror.sr.ht/alpine/v3.12/sr.ht
 
-**Mirror URL**: `https://mirror.sr.ht/alpine/v3.12/sr.ht`
-
-**Signing Key**: [alpine@sr.ht.pub](https://mirror.sr.ht/alpine/alpine%40sr.ht.rsa.pub)
-
-```
-$ wget -q -O /etc/apk/keys/alpine@sr.ht.rsa.pub https://mirror.sr.ht/alpine/alpine@sr.ht.rsa.pub
-```
+**Signing key**: [alpine@sr.ht.pub](https://mirror.sr.ht/alpine/alpine%40sr.ht.rsa.pub)
 
 **Maintainer**: Drew DeVault <sir@cmpwn.com>
 
 **Source**: https://git.sr.ht/~sircmpwn/sr.ht-apkbuilds
 
-## Arch Linux
+```sh
+# Add the following line to /etc/apk/repositories
+https://mirror.sr.ht/alpine/v3.12/sr.ht
 
-**Mirror URL**: `https://mirror.sr.ht/archlinux/sr.ht`
+# Install signing key
+wget -q -O /etc/apk/keys/alpine@sr.ht.rsa.pub https://mirror.sr.ht/alpine/alpine@sr.ht.rsa.pub
 
-```
-[sr.ht]
-Server = https://mirror.sr.ht/archlinux/sr.ht
+# Update package index
+apk update
 ```
 
-**Signing Key**: `C0AAFC1676BD998617C94C42DC59670F1EB0A189`
+<div class="alert alert-warning">
+  <strong>Warning:</strong> SourceHut shadows some upstream packages with
+  patched versions. The SourceHut mirror must be the <em>first</em> repository
+  in <code>/etc/apk/repositories</code>.
+</div>
 
-```
-$ pacman-key --recv-keys C0AAFC1676BD998617C94C42DC59670F1EB0A189
-$ pacman-key --lsign-key C0AAFC1676BD998617C94C42DC59670F1EB0A189
-```
+<div class="alert alert-warning">
+  <strong>Warning:</strong> The Alpine Linux community package repository must
+  be enabled.
+</div>
+
+# Arch Linux
+
+**Mirror**: https://mirror.sr.ht/archlinux/sr.ht
+
+**Signing key**: `C0AAFC1676BD998617C94C42DC59670F1EB0A189`
 
 **Maintainer**: Eli Schwartz <eschwartz@archlinux.org>
 
 **Source**: https://git.sr.ht/~sircmpwn/sr.ht-pkgbuilds
 
-## Debian
+```sh
+# Add the following two lines to /etc/pacman.conf
+[sr.ht]
+Server = https://mirror.sr.ht/archlinux/sr.ht
 
-**Mirror URL**: `https://mirror.sr.ht/debian`
+# Install signing key
+sudo pacman-key --recv-keys C0AAFC1676BD998617C94C42DC59670F1EB0A189
+sudo pacman-key --lsign-key C0AAFC1676BD998617C94C42DC59670F1EB0A189
 
-```
-deb https://mirror.sr.ht/debian sid main
+# Update package index
+sudo pacman -Syu
 ```
 
-**Signing Key**: [key.asc](https://mirror.sr.ht/debian/key.asc) `6B1296C65B24472674E7B6520585B50AC6A4914D`
+# Debian
 
+**Mirror**: https://mirror.sr.ht/debian
 
-```
-$ wget -q https://mirror.sr.ht/debian/key.asc  -O - | sudo apt-key --keyring /etc/apt/trusted.gpg.d/debian.sr.ht.gpg add -
-```
+**Signing key**: [key.asc](https://mirror.sr.ht/debian/key.asc) `6B1296C65B24472674E7B6520585B50AC6A4914D`
 
 **Maintainer**: Denis Laxalde <denis@laxalde.org>
 
 **Source**: https://git.sr.ht/~dlax/sr.ht-debbuilds
+
+```sh
+# Add the following line to /etc/apt/sources.list
+deb https://mirror.sr.ht/debian sid main
+
+# Install signing key
+wget -q https://mirror.sr.ht/debian/key.asc  -O - | sudo apt-key --keyring /etc/apt/trusted.gpg.d/debian.sr.ht.gpg add -
+
+# Update package index
+sudo apt update
+```