From 2d5701d4800323a4fd648ac7face19e29c28958e Mon Sep 17 00:00:00 2001 From: Julian Ospald Date: Sat, 30 Sep 2023 00:34:13 +0800 Subject: [PATCH] Improve README --- README.md | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 02c75a5..7c13f75 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,26 @@ # GHCup metadata -## Adding a new GHC version +## For end users + +### Metadata variants (distribution channels) + +* `ghcup-A.B.C.yaml`: this is the main metadata and what ghcup uses by default +* `ghcup-vanilla-A.B.C.yaml`: this is similar to `ghcup-A.B.C.yaml`, but only uses upstream bindists (no patches/fixes are applied, no missing platforms added) +* `ghcup-prereleases-A.B.C.yaml`: this contains pre-releases of all tools +* `ghcup-cross-A.B.C.yaml`: this contains (usually experimental) cross compilers + +### Using the metadata + +If you want access to both pre-releases and cross compilers, run: + +``` +ghcup config add-release-channel https://raw.githubusercontent.com/haskell/ghcup-metadata/master/ghcup-prereleases-0.0.7.yaml +ghcup config add-release-channel https://raw.githubusercontent.com/haskell/ghcup-metadata/master/ghcup-cross-0.0.8.yaml +``` + +## For contributors + +### Adding a new GHC version 1. open the latest `ghcup-.yaml` 2. find the latest ghc version (in yaml tree e.g. `ghcupDownloads -> GHC -> 8.10.7`) @@ -11,3 +31,17 @@ 7. run `cabal run ghcup-gen -- check-tarballs -f ghcup-.yaml -u 'ghc-8\.10\.8'` 8. run `cabal run ghcup-gen -- generate-hls-ghcs -f ghcup-.yaml --format json -o hls-metadata-0.0.1.json` 9. run `cabal run ghcup-gen -- generate-table -f ghcup-.yaml --stdout` and adjust [docs/install](https://gitlab.haskell.org/haskell/ghcup-hs/-/blob/master/docs/install.md) tables + +### During a pull request + +* make sure to always add new versions to both `ghcup-A.B.C.yaml` and `ghcup-vanilla-A.B.C.yaml` +* make sure to run the bindist action to check tool installation on all platforms: https://github.com/haskell/ghcup-metadata/actions/workflows/bindists.yaml + - this is a manual pipeline + - set the appropriate parameters +* make sure to sign the yaml files you edited, e.g.: `gpg --detach-sign -u ghcup-0.0.7.yaml` or ask a GHCup developer to sign + - PGP pubkeys need to be cross-signed by the GHCup team + - they need to be added to the CI: https://github.com/haskell/ghcup-metadata/blob/develop/.github/workflows/sigs + - and need to be documented on the homepage + * https://github.com/haskell/ghcup-hs/blob/master/docs/guide.md#gpg-verification + * https://github.com/haskell/ghcup-hs/blob/master/docs/install.md#unix +