CONTRIBUTING.md

   1 # Contributing to Homebrew
   2
   3 First time contributing to Homebrew? Read our [Code of Conduct](https://github.com/Homebrew/.github/blob/HEAD/CODE_OF_CONDUCT.md#code-of-conduct).
   4
   5 Ensure your commits follow the [commit style guide](https://docs.brew.sh/Formula-Cookbook#commit).
   6
   7 Thanks for contributing!
   8
   9 ### To report a bug
  10
  11 * run `brew update` (twice)
  12 * run and read `brew doctor`
  13 * read [the Troubleshooting Checklist](https://docs.brew.sh/Troubleshooting)
  14 * open an issue on the formula's repository
  15
  16 ### To submit a version upgrade for the `foo` formula
  17
  18 * check if the same upgrade has been already submitted by [searching the open pull requests for `foo`](https://github.com/Homebrew/homebrew-core/pulls?utf8=✓&q=is%3Apr+is%3Aopen+foo).
  19 * `brew tap homebrew/core`
  20 * `brew bump-formula-pr --strict foo` with one of the following:
  21   * `--url=...` and `--sha256=...`
  22   * `--tag=...` and `--revision=...`
  23   * `--version=...`
  24
  25 ### To add a new formula for `foo` version `2.3.4` from `$URL`
  26
  27 * read [the Formula Cookbook](https://docs.brew.sh/Formula-Cookbook) or: `brew create $URL` and make edits
  28 * `HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source foo`
  29 * `brew audit --new-formula foo`
  30 * `git commit` with message formatted `foo 2.3.4 (new formula)`
  31 * [open a pull request](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request) and fix any failing tests
  32
  33 Once you've addressed any potential feedback and a member of the Homebrew org has approved your pull request, the [BrewTestBot](https://github.com/BrewTestBot) will automatically merge it a couple of minutes later.
  34
  35 ### To contribute a fix to the `foo` formula
  36
  37 If you are already well-versed in the use of `git`, then you can work with the local
  38 copy of the `homebrew-core` repository as you are used to. You may need to run
  39 `brew tap homebrew/core` to clone it, if you haven't done so already; the repository
  40 will then be located in the directory `$(brew --repository homebrew/core)`.
  41 Modify the formula there using `brew edit foo`,
  42 leaving the section `bottle do ... end` unchanged, and prepare a pull request
  43 as you usually do.  Before submitting your pull request, be sure to test it
  44 with these commands:
  45
  46 ```
  47 brew uninstall --force foo
  48 HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source foo
  49 brew test foo
  50 brew audit --strict foo
  51 brew style foo
  52 ```
  53
  54 After testing, if you think it is needed to force the corresponding bottles to be
  55 rebuilt and redistributed, add a line of the form `revision 1` to the formula,
  56 or add 1 to the revision number already present.
  57
  58 If you are not already well versed in the use of `git`, then you may learn
  59 about it from the introduction at
  60 https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request and then proceed as
  61 follows:
  62
  63 * run `brew tap homebrew/core --force`, if you haven't done so previously
  64 * run `brew edit foo` and make edits
  65 * leave the section `bottle do ... end` unchanged
  66 * test your changes using the commands listed above
  67 * run `git commit` with message formatted `foo <insert new version number>` or `foo: <insert details>`
  68 * open a pull request as described in the introduction linked to above, wait for the automated test results, and fix any failing tests
  69
  70 Once you've addressed any potential feedback and a member of the Homebrew org has approved your pull request, the [BrewTestBot](https://github.com/BrewTestBot) will automatically merge it a couple of minutes later.
  71
  72 ### Dealing with CI failures
  73
  74 Pull requests with failing CI should not be merged, so the failures will need to be fixed. Start by looking for errors in the CI log. Some errors will show up as annotations in the "Files changed" tab of your pull request. If there are no annotations, or the annotations do not contain the relevant errors, then the complete build log can be found in the "Checks" tab of your pull request.
  75
  76 Once you've identified the error(s), check whether you can reproduce them locally. You should be able to do this with one or more of `HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source`, `brew audit --strict --online`, and `brew test`. Don't forget to checkout your PR branch before trying this! If you can reproduce the failure(s), then it is likely that the formula needs to be fixed. Read the error messages carefully. Many errors provide hints on how to fix them. Failing that: looking up the error message is often a fruitful source of hints for what to do next.
  77
  78 If you can't reproduce an error, then you need to identify what makes your local environment different from the build environment in CI. It is likely that one of those differences is driving the CI failure. It may help to try to make your local environment as similar to CI as possible to try to reproduce the failure. If the CI failure occurs on Linux, you can use the Homebrew Docker container to emulate the CI environment. See the next section for a guide on how to do this.
  79
  80 If you're still stuck: don't fret. Leave a comment on your PR describing what you've done to try to diagnose and fix the CI failure and we'll do our best to help you resolve them.
  81
  82 ### Homebrew Docker container
  83
  84 Linux CI runs on a Docker container running Ubuntu 22.04. If you have Docker installed, you can use our container with:
  85
  86 ```
  87 docker run --interactive --tty --rm --pull always homebrew/ubuntu22.04:latest /bin/bash
  88 ```
  89
  90 If you don't have Docker installed:
  91
  92 ```
  93 brew install --formula docker lima
  94 limactl start template://docker
  95 docker context create lima --docker "host=unix://${HOME}/.lima/docker/sock/docker.sock"
  96 docker context use lima
  97 ```
  98
  99 You should now be able to run the `docker` command shown above.