Fullstack 2016-08-24 - Contributing to Homebrew

A brief overview of Homebrew and how you can contribute!

Transcript

1. Contributing to Homebrew
2. Andrea Kao http://eirinikos.github.io http://twitter.com/eirinikos Slides will be available at: https://speakerdeck.com/eirinikos
3. What is Homebrew? ★ Homebrew is a open-source package manager for Mac OS written entirely in Ruby. (http://brew.sh) ★ It installs software with a single line of text in the command line. ◦ e.g., `brew install aften` ★ It also lets you install and manage multiple versions of the same program.
4. ★ Homebrew itself is a Git repo that lives in your /usr/local directory! ★ Running `brew update` syncs your Homebrew installation and Homebrew Taps (which are also Git repos) to their respective upstream remote master branches.
5. What are Taps? ★ Taps are collections of formula files in the form of Git repositories: homebrew-core is Homebrew’s core formula Tap. Other popular Taps include homebrew-science and homebrew-games. See https://github.com/Homebrew for a complete list of official Taps.
6. WTH are formulas/formulae? ★ Formulas (formerly known as “recipes”, also known as “formulae”) are the Ruby scripts that install and build software packages (aka “kegs”). ★ Formulas are responsible for managing dependencies, downloading source files, and configuring and compiling software.
7. An overview... ★ A Tap is a directory or collection of stored formulae. ★ A formula defines how to download, compile, and install a keg. ★ A keg is an installed Homebrew package version. Kegs are stored on racks in the Cellar. ★ A rack of kegs is a collection of package versions.
8. Filepaths! ★ Homebrew: /usr/local/Library/Homebrew/ ★ Tap: /usr/local/Library/Taps/homebrew/homebrew-core/ ★ Formula: /usr/local/Library/Taps/homebrew/homebrew-core/Formula/foo.rb ★ Cellar: /usr/local/Cellar/ ★ Rack: /usr/local/Cellar/foo/ ★ Keg: /usr/local/Cellar/foo/0.1/
9. Why is Homebrew awesome? ★ It installs software with a single line of command-line text! ★ It has friendly, welcoming maintainers. ★ It has a well-defined contribution process. ★ it’s also a convenient way to distribute software that you’ve written. ◦ i.e., create your own Tap and add formula files to it.
10. How have I contributed to Homebrew? Q&A: http://eirinikos.github.io/2016/08/17/fullstack-q-a/ ★ I applied to work on Homebrew for an Outreachy internship ★ I made 10 contributions before the start of the internship: ◦ 9 contributions to fix `brew audit` warnings in Homebrew’s core formulae ◦ 1 contribution to add a test to a formula
11. How have I contributed to Homebrew? ★ I had no idea what I was doing… ★ ...but, for each package that I worked with, it helped to: ◦ install it ◦ read its documentation ◦ run some of its commands ★ This helped me understand what each package actually did, as well as what the formula code was saying. ★ Figuring out how Homebrew works was (and has been) a gradual process of discovery (not a linear path)...
12. How have I contributed to Homebrew? Some of my formula fixes involved substituting Ruby’s Kernel#system method call with the equivalent Ruby FileUtils method...
13. How have I contributed to Homebrew? Some of my formula fixes replaced one Minitest assertion for another, e.g., `assert_match` instead of `assert...include?`...
14. How have I contributed to Homebrew? Once the internship began, I shifted my focus to adding integration and unit tests for various `brew` commands.
15. How have I contributed to Homebrew? I ran `brew tests --coverage` a thousand times… (or, `brew tests --only=<file>/<test> --coverage`)
16. How have I contributed to Homebrew? I did some refactoring...
17. How have I contributed to Homebrew? I made some embarrassing mistakes...
18. How have I contributed to Homebrew? ★ I laughed… ★ I cried… ★ I hit some dead ends...
19. How have I contributed to Homebrew? ★ Eventually, I helped increase overall test coverage from 50%... ★ …to 57%, something I’m proud of.
20. If you’re new to Homebrew and want to contribute... ★ First: head to http://brew.sh and install Homebrew (if you haven’t already). ◦ use Homebrew to install some packages ◦ read Homebrew’s man pages ★ Make sure to read Homebrew’s documentation, namely: ◦ the Code of Conduct ◦ the Formula Cookbook ◦ How to Open a Homebrew Pull Request (and get it merged)
21. How do you contribute to Homebrew? ★ Check out the README, which suggests that you: ◦ run `brew audit` (or `brew audit --strict`) with some of the packages you use ▪ (or run `brew audit` without arguments to audit formula files for all packages) ▪ make a fix that addresses the audit warning ★ Or: add a test to a formula file if it’s missing one.
22. How do you contribute to Homebrew? Even if (after lots of effort) you don’t yet have a 100% working or complete pull request, don’t hesitate to submit it (or initiate a discussion): The maintainers are happy to work with you to help get it to 100%! They want more contributors!
23. How do you contribute to Homebrew? ★ It's a long learning process. ★ Give yourself ample time to figure things out, read, ask questions, break things, and solve problems through trial & error. ★ It may be overwhelming in the beginning, but keep doing stuff that scares the shit out of you. ★ Don’t give up!
24. the end!