Merge branch 'main' into v3

.envrc

@@ -1 +1,2 @@
+PATH_add /opt/homebrew/opt/node@20/bin
 layout node

.github/dependabot.yml

@@ -1,10 +1,10 @@
 version: 2
 updates:
-  - package-ecosystem: "npm"
-    directory: "/"
+  - package-ecosystem: 'npm'
+    directory: '/'
     schedule:
-      interval: "weekly"
-  - package-ecosystem: "github-actions"
-    directory: "/"
+      interval: 'weekly'
+  - package-ecosystem: 'github-actions'
+    directory: '/'
     schedule:
-      interval: "weekly"
+      interval: 'weekly'

.github/workflows/test.yml

@@ -9,7 +9,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: "20.x"
           cache: "npm"

README.md

@@ -1,6 +1,7 @@
-An action that bumps a Homebrew formula after a new release.
+A minimal GitHub action that uses the GitHub API to bump a Homebrew formula
+after a new release in your repository.
 
-Minimal usage example:
+Usage example:
 
 ```yml
 on:
@@ -14,7 +15,10 @@ jobs:
     steps:
       - uses: mislav/bump-homebrew-formula-action@v3
         with:
-          # A PR will be sent to github.com/Homebrew/homebrew-core to update this formula:
+          # By default, this will edit the `my_formula.rb` formula in
+          # homebrew-core to update its "url" field to:
+          # `https://github.com/OWNER/REPO/archive/refs/tags/<tag-name>.tar.gz`
+          # The "sha256" formula field will get automatically recomputed.
           formula-name: my_formula
         env:
           # the personal access token should have "repo" & "workflow" scopes
@@ -25,80 +29,81 @@ The `COMMITTER_TOKEN` secret is required because this action will want to write
 to an external repository. You can [generate a new Personal Access Token (classic)
 here](https://github.com/settings/tokens) and give it `repo` and `workflow` scopes.
 
-Comprehensive usage example:
+## How it works
 
-```yml
-on:
-  push:
-    tags: 'v*'
+Given a Homebrew formula `Formula/my_formula.rb` in the
+[homebrew-core](https://github.com/Homebrew/homebrew-core) repo:
 
-jobs:
-  homebrew:
-    name: Bump Homebrew formula
-    runs-on: ubuntu-latest
-    steps:
-      - name: Extract version
-        id: extract-version
-        run: |
-          echo "tag-name=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
-      - uses: mislav/bump-homebrew-formula-action@v3
-        if: ${{ !contains(github.ref, '-') }} # skip prereleases
-        with:
-          formula-name: my_formula
-          formula-path: Formula/m/my_formula.rb
-          homebrew-tap: Homebrew/homebrew-core
-          base-branch: master
-          download-url: https://example.com/foo/${{ steps.extract-version.outputs.tag-name }}.tar.gz
-          commit-message: |
-            {{formulaName}} {{version}}
+```rb
+class MyFormula < Formula
+  url "https://github.com/me/myproject/archive/refs/tags/v1.2.3.tar.gz"
+  sha256 "<OLDSHA>"
+  # ...
+end
+```
 
-            Created by https://github.com/mislav/bump-homebrew-formula-action
-        env:
-          COMMITTER_TOKEN: ${{ secrets.COMMITTER_TOKEN }}
-          # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+After we push a `v2.0.0` git tag to a project that has this action configured,
+the formula will be updated to:
+
+```rb
+class MyFormula < Formula
+  url "https://github.com/me/myproject/archive/refs/tags/v2.0.0.tar.gz"
+  sha256 "<NEWSHA>"
+  # ...
+end
 ```
 
-You should enable `GITHUB_TOKEN` only if the repository that runs this Action is
-private _and_ if `COMMITTER_TOKEN` has the `public_repo` scope only.
-`GITHUB_TOKEN` will be used for verifying the SHA256 sum of the downloadable
-archive for this release.
+This action can update the following Homebrew formula fields:
 
+- `version`
+- `url`
+- `sha256` - for non-git `download-url` action input
+- `tag` - for git-based `download-url`
+- `revision` - for git-based `download-url`
 
 ## Action inputs
 
 Formula parameters:
 
-* `formula-name`: the name of the Homebrew formula to bump. Defaults to
+- `formula-name`: the name of the Homebrew formula to bump. Defaults to
   lower-cased repository name.
 
-* `formula-path`: the relative path of the Homebrew formula file to edit within the `homebrew-tap` repository. Defaults to
+- `formula-path`: the relative path of the Homebrew formula file to edit within the `homebrew-tap` repository. Defaults to
   `Formula/<letter>/<formula-name>.rb` for homebrew-core formulae and `Formula/<formula-name>.rb` otherwise.
 
-* `tag-name`: the git tag name to bump the formula to. Defaults to the
+- `tag-name`: the git tag name to bump the formula to. Defaults to the
   currently pushed tag.
 
-* `download-url`: the package download URL for the Homebrew formula.
+- `download-url`: the package download URL for the Homebrew formula.
 
   Defaults to `https://github.com/OWNER/REPO/archive/refs/tags/<tag-name>.tar.gz`, where `OWNER/REPO` is the repository that is running the Actions workflow.
 
-* `download-sha256`: the SHA256 checksum of the archive at `download-url`.
+- `download-sha256`: the SHA256 checksum of the archive at `download-url`.
   Defaults to calculating the checksum by fetching the archive at run time.
 
 Repository parameters:
 
-* `homebrew-tap`: the full GitHub repository name (in the `NAME/OWNER` format) where the Homebrew formula should be updated. Defaults
+- `homebrew-tap`: the full GitHub repository name (in the `NAME/OWNER` format) where the Homebrew formula should be updated. Defaults
   to `Homebrew/homebrew-core`.
 
-* `push-to`: a specific fork of `homebrew-tap` where the edit should be pushed to. Defaults to creating or reusing a personal fork of the owner of COMMITTER_TOKEN.
+- `push-to`: a specific fork of `homebrew-tap` where the edit should be pushed to.
+  Defaults to creating or reusing a personal fork of the owner of COMMITTER_TOKEN.
+  (Note: avoid using an organization-owned fork, as that
+  [breaks automation for `homebrew-core`](https://github.com/foxglove/mcap/issues/1063)).
 
-* `base-branch`: the branch name in the `homebrew-tap` repository where the
+- `base-branch`: the branch name in the `homebrew-tap` repository where the
   formula should be updated. Defaults to the main branch of the repository.
 
-* `create-pullrequest`: a boolean value to either force or prohibit submitting
+- `create-pullrequest`: a boolean value to either force or prohibit submitting
   a pull request to `homebrew-tap`. Defaults to false if `COMMITTER_TOKEN` has
   the privileges to directly push to `base-branch` in `homebrew-tap`.
 
-* `commit-message`: the git commit message template to use when updating the
+- `create-branch`: a boolean value to either force or prohibit creating a
+  branch on `homebrew-tap`. Defaults to false if `COMMITTER_TOKEN` has
+  the privileges to directly push to `base-branch` in `homebrew-tap`.
+  You cannot set this to `false` if `create-pullrequest` is set to `true`.
+
+- `commit-message`: the git commit message template to use when updating the
   formula. The following placeholders be expanded:
 
   | Placeholder       | Description                                        |
@@ -112,60 +117,74 @@ Repository parameters:
   their automation.
 
   Defaults to:
+
   ```
   {{formulaName}} {{version}}
 
   Created by https://github.com/mislav/bump-homebrew-formula-action
   ```
 
+### Environment variables
 
-## How it works
+- `COMMITTER_TOKEN` (required): needs _write access_ to the repository specified
+  by the `homebrew-tap` input, or enough privileges to _fork the tap repo_
+  (usually `homebrew-core`) and submit a PR to it.
 
-Given a Homebrew formula `Formula/my_formula.rb` in the
-[homebrew-core](https://github.com/Homebrew/homebrew-core) repo:
+  Recommended "classic" token scopes: `repo` & `workflow`.
 
-```rb
-class MyFormula < Formula
-  url "https://github.com/me/myproject/archive/refs/tags/v1.2.3.tar.gz"
-  sha256 "<OLDSHA>"
-  # ...
-end
-```
+- `GITHUB_TOKEN` (optional): needs _read access_ to the contents of the
+  repository that is executing this action; will be used for verifying the
+  SHA256 checksum of the downloadable archive for this release. Useful only if
+  the repository that runs this Action is private _and_ if `COMMITTER_TOKEN` has
+  the `public_repo` scope only.
 
-After we push a `v2.0.0` git tag to a project that has this action configured,
-the formula will be updated to:
+## Examples
 
-```rb
-class MyFormula < Formula
-  url "https://github.com/me/myproject/archive/refs/tags/v2.0.0.tar.gz"
-  sha256 "<NEWSHA>"
-  # ...
-end
-```
-
-This action can update the following Homebrew formula fields:
-
-- `version`
-- `url`
-- `sha256` - for non-git `download-url`
-- `tag` - for git-based `download-url`
-- `revision` - for git-based `download-url`
+Comprehensive usage example:
 
-If the current `COMMITTER_TOKEN` doesn't have push access to the repo specified
-by the `homebrew-tap` input, the formula will be edited in a fork that is
-automatically created, and a pull request will be opened.
+```yml
+on:
+  push:
+    tags: 'v*'
+  # Alternatively, trigger this workflow after a stable release has been published:
+  #release:
+  #  types: [ released ]
 
-If the token has push access, but the default branch of the tap repo is
-protected, a pull request will be opened from a new branch in the same repo.
+jobs:
+  homebrew:
+    name: Bump Homebrew formula
+    # Skip this job in case of git pushes to prerelease tags
+    if: ${{ github.event_name != 'push' || !contains(github.ref, '-') }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Extract version
+        id: extract-version
+        # Strip a string prefix from the git tag name:
+        run: |
+          echo "tag-name=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
 
-Otherwise, the formula will be edited via a direct push to the default branch.
-This can be overriden by setting `create-pullrequest`.
+      - uses: mislav/bump-homebrew-formula-action@v3
+        with:
+          formula-name: my_formula
+          formula-path: Formula/m/my_formula.rb
+          homebrew-tap: Homebrew/homebrew-core
+          base-branch: master
+          download-url: https://example.com/packages/myformula-${{ steps.extract-version.outputs.tag-name }}.tar.gz
+          commit-message: |
+            {{formulaName}} {{version}}
 
+            Created by https://github.com/mislav/bump-homebrew-formula-action
+        env:
+          COMMITTER_TOKEN: ${{ secrets.COMMITTER_TOKEN }}
+          # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
 
-## Manual trigger
+### Manual trigger
 
-Here's an example of how to set up this action to be manually triggered instead
-of being triggered by pushing to a git tag:
+How to set up this action to be manually triggered instead of being triggered by
+pushing to a git tag:
 
 ```yml
 on:
@@ -184,7 +203,35 @@ jobs:
         with:
           formula-name: my_formula
           tag-name: ${{ github.event.inputs.tag-name }}
-          download-url: https://example.com/foo/${{ github.event.inputs.tag-name }}.tar.gz
+          download-url: https://example.com/foo/myproject-${{ github.event.inputs.tag-name }}.tar.gz
         env:
           COMMITTER_TOKEN: ${{ secrets.COMMITTER_TOKEN }}
 ```
+
+You could then use GitHub CLI to [trigger that workflow](https://cli.github.com/manual/gh_workflow_run):
+
+```sh
+gh workflow -R <OWNER>/<REPO> run release.yml --ref <BRANCH> -f "tag-name=v1.2.3"
+```
+
+## Known limitations
+
+This action is designed to be minimal, fast, and to run with very few
+requirements. For example, this action does not require a working Homebrew
+installation, nor cloning the Homebrew tap repository (since cloning the massive
+`Homebrew/homebrew-core` repository with git can take a long time). The only
+thing it does is using the GitHub API to make file edits to a Homebrew formula
+and to submit those edits as a PR.
+
+Because of said design, this action is less featured than the [official `brew
+bump-formula-pr` command][1] that ships with Homebrew. Known limitations are:
+
+- Limited support for [bumping Homebrew casks](https://github.com/mislav/bump-homebrew-formula-action/issues/42#issuecomment-1410441868)
+
+- Cannot bump formulae that need their versions to be [synced with other formulae](https://github.com/mislav/bump-homebrew-formula-action/issues/44)
+
+- Cannot bump formulae which use Ruby `if...else` conditions to determine [alternate download locations](https://github.com/mislav/bump-homebrew-formula-action/issues/5) at runtime
+
+- Cannot bump Python-based formulae which [declare their PyPI dependencies](https://github.com/ansible/ansible-lint/pull/3812#issuecomment-1747105780) as additional `resource` blocks
+
+[1]: https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request#submit-a-new-version-of-an-existing-formula

action.yml

@@ -24,6 +24,8 @@ inputs:
     description: The branch name in the homebrew-tap repository to update the formula in
   create-pullrequest:
     description: Set to a boolean value to either force or prohibit making a pull request to homebrew-tap
+  create-branch:
+    description: Set to a boolean value to either force or prohibit creating a separate branch on homebrew-tap
   commit-message:
     description: The git commit message template to use when updating the formula
     default: |

eslint.config.mjs

@@ -0,0 +1,12 @@
+// @ts-check
+
+import eslint from '@eslint/js'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  tseslint.configs.recommended,
+  {
+    ignores: ['lib/*', '.github/*'],
+  }
+)