Hi developers! Today I want to share my journey about contributing to Homebrew. I want to add Windsurf IDE to community. It was very fun journey and I did learn many new things!

What is Homebrew and Why You Need It? 🍻

Before I'm going to tell you about my journey, let me explain first about Homebrew! And no worry, it not real beer - which is good since I'm try to be a good Muslim and only brew code, not alcohol 🤣

Me brewing code, not beer - the only brewing that halal

People call Homebrew "The Missing Package Manager for macOS". It's kind of like magic helper that install software for you. For me as Muslim developer, this is only brew that make me happy (and stay halal of course 🙏) Instead of manual download and install software and check a regular updates, Homebrew do everything with one command:

brew install your-favorite-software

Why Ruby? 💎

Ruby: Make package manager simple since 2009

Maybe you questioning why Homebrew use Ruby language. Well, in my opinion here is several good reasons:

Easy to Read: Ruby code very simple to understand
Already in macOS: Ruby is exist on every Mac
Good for Making Rules: Ruby good for making special commands
Many People Use: Ruby have big community

How I Start This Journey 🚀

It's all begin when I find Windsurf from this youtube video Windsurf IDE: NEW AI Editor - Cursor Alternative That's FREE & LOCAL!, they call it "The first agentic IDE". From the windsurf website, it said: "The Windsurf Editor is where the work of developers and AI truly flow together, allowing for a coding experience that feels like literal magic."

My face when first time use Windsurf AI

After I tried it for several times, I think "Woah, wouldn't it will be nice if people can install this easy with Homebrew! since it's not officially supported by the Windsurf team". That's mark my journey of contribution to Homebrew started!

Step 1: Finding the Download URLs Like Detective 🕵️‍♂️

Attempt, first challenge: i am downloading right from the Windsurf website, i have to find the download URL, Windsurf supports both of Arm Mac and Intel Mac architecture. I found a nice google chrome extension called "OpenAPI DevTools" to help me for the first task. The extensions is here, it's really nice extension (very helpful tool!) that make it easy for me to get the API request, response and make it to OpenAPI spec. The first task done in less than 3 minutes!

Pov OpenAPI DevTools user

The Windsurf IDE have two different URL for different Mac:

For Arm archictecture Mac: https://windsurf-stable.codeium.com/api/update/darwin-arm64-dmg/stable/latest
For Intel archictecture Mac: https://windsurf-stable.codeium.com/api/update/darwin-x64-dmg/stable/latest

What API Give Back 📦

When we request to that API endpoint, it will give back this kind of JSON data:

{
  "url": "https://windsurf-stable.codeiumdata.com/darwin-arm64-dmg/stable/<sha-commit>/Windsurf-darwin-arm64-<version>.dmg",
  "name": "<version>",
  "version": "<sha-commit>",
  "productVersion": "<version>",
  "hash": "<hash>",
  "timestamp": <timestamp>,
  "sha256hash": "<sha256-hash>",
  "supportsFastUpdate": true,
  "windsurfVersion": "<version>"
}

Step 2: Make the Homebrew Formula 🍼

Me try to make Homebrew magic

Next step, I have to create a Homebrew formula. I don't know where to start, but the homebrew team created a really good documentation to help me through the process. I read Homebrew documentation - wow, so detail and deep! I also read The Formula Cookbook also very complete, it takes more than 20 minutes to read all of it, and I think i'm ready to start coding! As i want to add Windsurf as a cask, I need to know how to make cask. I read Cask cookbook - so very detail and deep!

Here is the Important Parts in Cask 📚

To make good cask, we need:

Version and SHA256: For make sure app download is safe
Support Different Mac: For Arm and Intel Mac
Download URL: Where to get the app
Install Rules: Where to put files
Clean Up: How to remove app clean

Step 3: My Code and Terminal Adventure 💻

Let me tell you about my command line journey! First, I try simple way:

brew install windsurf

When Homebrew say "not found"

Of course Homebrew cannot find it - because I not make it yet! The homebrew team make things simpler to just using brew create command. Here is the command of creating a cask package:

brew create --cask https://windsurf-stable.codeiumdata.com/darwin-arm64-dmg/stable/<sha-commit>/Windsurf-darwin-arm64-<version>.dmg
Cask name [Windsurf-darwin-arm64-<version>]: windsurf
==> Downloading https://windsurf-stable.codeiumdata.com/darwin-arm64-dmg/stable/<sha-commit>/Windsurf-d
############################################################################################################################ 100.0%
Please run `brew audit --cask --new windsurf` before submitting, thanks.
Editing /opt/homebrew/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/w/windsurf.rb

Make sure you add --cask before the URL, also don't forget to empty some space because it will clone the big repository of homebrew-cask (it is about 400 MB in total) also with downloading the application. The command also opening your default editor to edit the cask file.

Here my code for Windsurf:

cask "windsurf" do
  arch arm: "darwin-arm64", intel: "darwin-x64"
  version "<version>,<sha-commit>"
  sha256 arm: "<sha256-hash-arm>",
         intel: "<sha256-hash-intel>"

  url "https://windsurf-stable.codeiumdata.com/#{arch}/stable/#{version.csv.second}/Windsurf-#{version.csv.first}.dmg"
  # more code here
end

After finished the code, I try to install it, first run to test the code didn't going well:

brew install --build-from-source windsurf
==> Downloading https://windsurf-stable.codeiumdata.com/darwin-arm64/stable/<sha-commit>/Windsurf-<version>
curl: (56) The requested URL returned error: 404                                                                                   

Error: Download failed on Cask 'windsurf' with message: Download failed: https://windsurf-stable.codeiumdata.com/darwin-arm64/stable/<sha-commit>/Windsurf-<version>.dmg

404 Error: what!?

I'm checking the error message, it said "The requested URL returned error: 404". It means the download URL is wrong. I fix some things and try to edit the code, it will open the editor again. I change the download URL to the correct one:

brew edit --cask windsurf
Editing /opt/homebrew/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/w/windsurf.rb

After I edit the code, I run brew install --build-from-source windsurf again, Alhamdulillah, it work! But still need more check...

brew install --build-from-source windsurf -f
==> Downloading https://windsurf-stable.codeiumdata.com/darwin-arm64-dmg/stable/<sha-commit>/Windsurf-d
Already downloaded: /Users/fathiraz/Library/Caches/Homebrew/downloads/<hash>--Windsurf-darwin-arm64-<version>.dmg
==> Installing Cask windsurf
Password:
==> Moving App 'Windsurf.app' to '/Applications/Windsurf.app'
🍺  windsurf was successfully installed!
Warning: No available formula with the name "windsurf".
==> Searching for similarly named formulae and casks...
==> Casks
windscribe                                                        windsurf ✔

To install windscribe, run:
  brew install --cask windscribe

Check Everything Strictly like a Detective 😎

Now most difficult part - the audit:

brew audit --strict --new --online windsurf
==> Downloading and extracting artifacts
==> Downloading https://windsurf-stable.codeiumdata.com/darwin-arm64-dmg/stable/<sha-commit>/Windsurf-d
Already downloaded: /Users/fathiraz/Library/Caches/Homebrew/downloads/<hash>--Windsurf-darwin-arm64-<version>.dmg
==> Downloading https://windsurf-stable.codeiumdata.com/darwin-arm64-dmg/stable/<sha-commit>/Windsurf-d
Already downloaded: /Users/fathiraz/Library/Caches/Homebrew/downloads/<hash>--Windsurf-darwin-arm64-<version>.dmg
audit for windsurf: failed
 - The URL's domain windsurf-stable.codeiumdata.com does not match the homepage domain www.codeium.com, a 'verified' parameter has to be added to the 'url' stanza. See https://docs.brew.sh/Cask-Cookbook#when-url-and-homepage-domains-differ-add-verified
 - Upstream defined :catalina as the minimum OS version but the cask declared :big_sur
windsurf
  * The URL's domain windsurf-stable.codeiumdata.com does not match the homepage domain www.codeium.com, a 'verified' parameter has to be added to the 'url' stanza. See https://docs.brew.sh/Cask-Cookbook#when-url-and-homepage-domains-differ-add-verified
  * Upstream defined :catalina as the minimum OS version but the cask declared :big_sur
Error: 2 problems in 1 cask detected.

Me want to fix problems one by one with dance

I Need to fix many things as informed by the audit, it is:

URL domain does not match homepage
macOS version need update, it should be Catalina or later, but the cask declare Big Sur

Try to Fix the Code 🔧

I fixed the code, and try to running audit command again:

brew audit --strict --new --online windsurf
==> Downloading and extracting artifacts
==> Downloading https://windsurf-stable.codeiumdata.com/darwin-arm64-dmg/stable/<sha-commit>/Windsurf-darwin-arm64-<version>.dmg
Already downloaded: /Users/fathiraz/Library/Caches/Homebrew/downloads/<hash>--Windsurf-darwin-arm64-<version>.dmg
==> Downloading https://windsurf-stable.codeiumdata.com/darwin-arm64-dmg/stable/<sha-commit>/Windsurf-darwin-arm64-<version>.dmg
Already downloaded: /Users/fathiraz/Library/Caches/Homebrew/downloads/<hash>--Windsurf-darwin-arm64-<version>.dmg

Make Code Look Nice ✨

Last step, make code look good by using brew style command:

brew style --fix windsurf
Taps/homebrew/homebrew-cask/Casks/w/windsurf.rb:29:14: C: [Corrected] Cask/ArrayAlphabetization: The array elements should be ordered alphabetically
  zap trash: [ ...
             ^
Taps/homebrew/homebrew-cask/Casks/w/windsurf.rb:36:5: C: [Corrected] Style/TrailingCommaInArrayLiteral: Put a comma after the last item of a multiline array.
    "------------------------------------------------------------------------"
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Taps/homebrew/homebrew-cask/Casks/w/windsurf.rb:38:4: C: [Corrected] Layout/TrailingEmptyLines: Final newline missing.
end


1 file inspected, 3 offenses detected, 3 offenses corrected

Fix the syntax error and trailing comma, try to running the style command again:

brew style --fix windsurf
1 file inspected, no offenses detected

Finally success

Step 4: Send Pull Request Time 🖥️

With bismillah, I click "Submit" on my pull request. Masyaallah, what journey!

windsurf 1.0.5 (new cask) #193585

fathiraz posted on Nov 28, 2024

Important: Do not tick a checkbox if you haven’t performed its action. Honesty is indispensable for a smooth review process.

In the following questions <cask> is the token of the cask you're submitting.

After making any changes to a cask, existing or new, verify:

[x] The submission is for a stable version or documented exception.
[x] brew audit --cask --online <cask> is error-free.
[x] brew style --fix <cask> reports no offenses.

Additionally, if adding a new cask:

[x] Named the cask according to the token reference.
[x] Checked the cask was not already refused (add your cask's name to the end of the search field).
[x] brew audit --cask --new <cask> worked successfully.
[x] HOMEBREW_NO_INSTALL_FROM_API=1 brew install --cask <cask> worked successfully.
[x] brew uninstall --cask <cask> worked successfully.

View on GitHub

My brain try process all Homebrew docs

You know what crazy? I spend almost 1 hour just to learn how everything work. First, i have to be a detective to find Windsurf download URLs. Then read many Homebrew docs!

While I learn and try make good contribution, I see my PR keep saying - "Update Branch" because many people already merged their PR by the maintainer. In short time, maybe 12 PR already merged, what a busy repository!

Me: "Almost ready!" Homebrew: "Done, merged 3 PR more!"

What I Learn from This? 🧠

Every day chance for learn!

Technical Things:
- How the Homebrew formula work
- How good documentation of the Homebrew
- How to create Homebrew formula for cask
Good Practice:
- Test everything
- Follow rules strict
Soft Skills:
- Read documentation patient
- Keep spirit in process

Tips for New Contributors

Read Docs First: Seriously, Homebrew docs very good
Test Local: Use brew audit and brew style before submit
Be Patient: Review process strict because it has reason

What Next? 🚀

This experience make me more motivated to contribute to open source. Amazing think my small contribution can help other developers install Windsurf easy. Now looking for next project to contribute!

Future Ideas

Add more tools to Homebrew
Contribute to other project

Remember: every big journey start from first step. Wanna contribute? Just do it! Community welcome you with open arms.

Resources for Start 📚

You ever contribute to open source? How your first time? Share your story in comments!

Thank you for reading! Now go brew something cool!

Blog

My First Time Contributing to Homebrew: Adding Windsurf IDE

Fathiraz Arthuro