From 31fea9c40ded877d1608432316634309efe2c2d3 Mon Sep 17 00:00:00 2001 From: Sam McCall Date: Mon, 17 Feb 2020 12:11:56 +0100 Subject: [PATCH] Document releases --- releases.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 releases.md diff --git a/releases.md b/releases.md new file mode 100644 index 0000000..68c11d0 --- /dev/null +++ b/releases.md @@ -0,0 +1,54 @@ +# Binary releases + +This repository has automation to build binary releases of clangd for the most +common platforms. This doesn't cover as many systems as the official releases +from http://releases.llvm.org/, and distro packages etc. The main advantages +is being able to cut releases easily whenever we want. + +The releases are just a zip archive containing the `clangd` binary, and the +clang builtin headers. They should be runnable immediately after extracting the +archive. The linux binary has `libstdc++` and other dependencies statically +linked for maximum portability. + +## Creating a release manually + +In GitHub, click the "Releases" tab and create a new release. +The tag name is significant, it's used in the directory name (`clangd_tagname`). + +Because clangd sources don't live in this repository, the release description +must contain a magic string indicating the revision to build at, e.g. + + Built at llvm/llvm-project@0399d5a9682b3cef71c653373e38890c63c4c365 + +This must be a full SHA, not a short-hash, a tag or branch name, etc. +The release must **not** be a draft release, as that won't trigger automation. + +## Building release binaries + +Creating the release will trigger the `autobuild` workflow, visible under the +"Actions" tab. This runs a sequence of steps: + +- First, the release is marked as a draft, so it's invisible to non-owners. +- Next, the sources are checked out and built on each of {mac, windows, linux}. + These run in parallel, and the results are zipped and added to the release. +- If all builds succeeded, the release is published (marked as non-draft) + +## Automatic snapshot releases + +The `periodic` workflow runs on a weekly schedule and creates a release based +on the last green revision at llvm/llvm-project. +This in turn triggers the `autobuild` workflow above to produce binaries. + +These snapshot releases are marked as "pre-release" - they don't undergo any +serious testing and so aren't particularly stable. However they're useful for +people to try the latest clangd. + +## Credentials + +Rather than the default GitHub Actions access token, these actions use a +Personal Access Token added to the repository as a secret. This is because: + +- The default access token expires after an hour. Builds take longer than that. +- Releases created using the default access token don't trigger workflows. + +If you fork the repository, you must provide the `RELEASE_TOKEN` secret.