From d45f88c6ac2601dd6ca273dec227a22775a22f17 Mon Sep 17 00:00:00 2001 From: Issy Long Date: Sun, 15 Sep 2019 13:43:33 +0100 Subject: [PATCH] Document how we pull bottles in Homebrew/linuxbrew-core - Also document some things that could go wrong and how to recover from them. --- ...omebrew-linuxbrew-core-Maintainer-Guide.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md b/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md index 1f277291c6..4d0bd9c236 100644 --- a/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md +++ b/docs/Homebrew-linuxbrew-core-Maintainer-Guide.md @@ -250,6 +250,59 @@ for Linuxbrew` to the top of the formula, pushes the branch to GitHub at the specified remote (default: `origin`), and opens a pull request using `hub pull-request`. +## Pulling bottles + +Pull requests are either raised by maintainers or users. In both +cases, how to merge them depends on whether or not a Linux bottle has +been built for the formula. + +We very rarely use the GitHub UI buttons. Instead, we "pull the +bottle". This means that the PR shows up as "closed" to the user, but +they still get authorship credit. This is done with the following +command: + +```bash +HOMEBREW_BOTTLE_DOMAIN=https://linuxbrew.bintray.com brew pull --bottle --bintray-org=linuxbrew --test-bot-user=LinuxbrewTestBot +``` + +It saves a lot of time to alias this in your shell config. One +possible alias is `lbrew-pull-bottle`. + +For PRs with the title "Build a bottle for Linuxbrew" and that have +only one commit with contents "# Build a bottle for Linuxbrew", these +have been created with `brew build-bottle-pr` and the commit from the +PR doesn't need preserving. We don't want to litter the codebase with +comments. In these cases, you can combine `brew pull --bottle` with +`brew squash-bottle-pr` (in the Linuxbrew/developer tap). This will +squash the first commit message, leaving just the commit with the +bottle SHA authored by `LinuxbrewTestBot`. It will still close the PR, +as `brew pull --bottle` adds `Closes` and `Signed-off-by` to the +commit message body. + +```bash +lbrew-pull-bottle && brew squash-bottle-pr +``` + +For PRs where there have been force pushes or extra commits to fix the +build or fix bottling syntax, we can't `brew squash-bottle-pr` as we +must keep the fixes. + +The `brew pull` command *publishes* the bottle to BinTray and verifies +that the SHA in the formula and the SHA of the downloaded file match. +To verify a bottle, the script downloads the bottle from BinTray - if +you're on an unstable connection, this may take a while or even time +out. Publishing the bottle means that it's available as the latest +version for users to download, so we have to be quick with pushing the +commits to `origin`. + +If something goes wrong with the bottle pull and you don't want to +publish the bottle and push the commit, `git reset --hard +origin/master` and login to BinTray and delete the new bottle (there's +a list of who published what recently). + +Once you've pushed to `origin`, there's no going back: you're a +maintainer now, you can't force-push to fix your mistakes! + ## Common build failures and how to handle them ### Bottling errors