fix: github workflow tooling installation and dev docs (#6)

* Initial plan

* Add gem installation to setup process with Ruby compatibility fixes

Co-authored-by: ivuorinen <11024+ivuorinen@users.noreply.github.com>

* Complete gem installation setup with improved documentation

Co-authored-by: ivuorinen <11024+ivuorinen@users.noreply.github.com>

* Update GitHub workflows to use new make setup and build targets

Co-authored-by: ivuorinen <11024+ivuorinen@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: ivuorinen <11024+ivuorinen@users.noreply.github.com>

.github/workflows/ci.yml

@@ -56,13 +56,9 @@ jobs:
         shell: bash
         run: brew install-bundler-gems
 
-      - name: Install project gems
+      - name: Setup project dependencies
         shell: bash
-        run: |
+        run: make setup
-          export GEM_HOME="$HOME/.gem"
-          export PATH="$GEM_HOME/bin:$PATH"
-          gem install bundler --user-install
-          bundle install
 
       - name: Run brew test-bot (cleanup)
         shell: bash

.github/workflows/pages-build.yml

@@ -32,15 +32,13 @@ jobs:
 
       - name: Setup Ruby
         uses: ruby/setup-ruby@0481980f17b760ef6bca5e8c55809102a0af1e5a # v1.263.0
-        with:
-          bundler-cache: true
 
-      - name: Parse Formulae and Build Site
+      - name: Setup project dependencies and build site
         shell: bash
         run: |
-          ruby scripts/parse_formulas.rb
+          make setup
+          make build
           echo "Generated formulae.json with $(jq '.formulae | length' docs/_data/formulae.json) formulae"
-          ruby scripts/build_site.rb
 
       - name: Setup Pages
         id: pages

Gemfile

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-ruby "3.4.6"
+ruby ">= 3.0.0"
 
 gem "cssminify2", "~> 2.0"
 gem "json", "~> 2.7"

Makefile

@@ -31,17 +31,36 @@ help: ## Show this help message
 
 build: ## Build the static documentation site
 	@echo "🏗️  Building homebrew tap documentation..."
-	@$(RUBY) $(SCRIPTS_DIR)/parse_formulas.rb
+	@if [ -f Gemfile ]; then \
-	@$(RUBY) $(SCRIPTS_DIR)/build_site.rb
+		RUBY_ABI_VERSION=$$($(RUBY) -e 'puts "#{RUBY_VERSION.split(".")[0]}.#{RUBY_VERSION.split(".")[1]}.0"'); \
+		export PATH="$$HOME/.local/share/gem/ruby/$$RUBY_ABI_VERSION/bin:$$PATH"; \
+		bundle exec $(RUBY) $(SCRIPTS_DIR)/parse_formulas.rb; \
+		bundle exec $(RUBY) $(SCRIPTS_DIR)/build_site.rb; \
+	else \
+		$(RUBY) $(SCRIPTS_DIR)/parse_formulas.rb; \
+		$(RUBY) $(SCRIPTS_DIR)/build_site.rb; \
+	fi
 	@echo "✅ Build complete!"
 
 serve: ## Start development server (default: localhost:4000)
 	@echo "🚀 Starting development server on http://$(HOST):$(PORT)"
-	@$(RUBY) $(SCRIPTS_DIR)/serve.rb $(PORT) $(HOST)
+	@if [ -f Gemfile ]; then \
+		RUBY_ABI_VERSION=$$($(RUBY) -e 'puts "#{RUBY_VERSION.split(".")[0]}.#{RUBY_VERSION.split(".")[1]}.0"'); \
+		export PATH="$$HOME/.local/share/gem/ruby/$$RUBY_ABI_VERSION/bin:$$PATH"; \
+		bundle exec $(RUBY) $(SCRIPTS_DIR)/serve.rb $(PORT) $(HOST); \
+	else \
+		$(RUBY) $(SCRIPTS_DIR)/serve.rb $(PORT) $(HOST); \
+	fi
 
 parse: ## Parse formulae and generate JSON data only
 	@echo "📋 Parsing formulae..."
-	@$(RUBY) $(SCRIPTS_DIR)/parse_formulas.rb
+	@if [ -f Gemfile ]; then \
+		RUBY_ABI_VERSION=$$($(RUBY) -e 'puts "#{RUBY_VERSION.split(".")[0]}.#{RUBY_VERSION.split(".")[1]}.0"'); \
+		export PATH="$$HOME/.local/share/gem/ruby/$$RUBY_ABI_VERSION/bin:$$PATH"; \
+		bundle exec $(RUBY) $(SCRIPTS_DIR)/parse_formulas.rb; \
+	else \
+		$(RUBY) $(SCRIPTS_DIR)/parse_formulas.rb; \
+	fi
 	@echo "✅ Formulae parsing complete!"
 
 clean: ## Clean all generated files
@@ -54,9 +73,25 @@ dev: parse build serve ## Full development workflow: parse, build, and serve
 setup: ## Initial project setup and dependency check
 	@echo "🔧 Setting up homebrew tap development environment..."
 	@which $(RUBY) > /dev/null || (echo "❌ Ruby not found. Please install Ruby first." && exit 1)
+	@echo "✅ Ruby found: $$($(RUBY) --version)"
 	@test -d $(FORMULA_DIR) || (echo "❌ Formula directory not found" && exit 1)
 	@test -d $(THEME_DIR) || (echo "❌ Theme directory not found" && exit 1)
 	@test -f $(THEME_DIR)/index.html.erb || (echo "❌ Theme templates not found" && exit 1)
+	@echo "📦 Installing Ruby dependencies..."
+	@if ! command -v bundle >/dev/null 2>&1; then \
+		echo "📥 Installing bundler..."; \
+		gem install bundler --user-install; \
+	fi
+	@if [ -f Gemfile ]; then \
+		echo "🔄 Running bundle install..."; \
+		RUBY_ABI_VERSION=$$($(RUBY) -e 'puts "#{RUBY_VERSION.split(".")[0]}.#{RUBY_VERSION.split(".")[1]}.0"'); \
+		(export PATH="$$HOME/.local/share/gem/ruby/$$RUBY_ABI_VERSION/bin:$$PATH" && \
+		 bundle config set path 'vendor/bundle' && \
+		 bundle install); \
+		echo "✅ Ruby dependencies installed!"; \
+	else \
+		echo "ℹ️  No Gemfile found, skipping dependency installation"; \
+	fi
 	@echo "✅ Environment setup complete!"
 
 check: ## Check if all required files and directories exist
@@ -81,7 +116,14 @@ test: check ## Run tests and validation
 install: ## Install development dependencies (if Gemfile exists)
 	@if [ -f Gemfile ]; then \
 		echo "📦 Installing Ruby dependencies..."; \
-		bundle install; \
+		if ! command -v bundle >/dev/null 2>&1; then \
+			echo "📥 Installing bundler..."; \
+			gem install bundler --user-install; \
+		fi; \
+		RUBY_ABI_VERSION=$$($(RUBY) -e 'puts "#{RUBY_VERSION.split(".")[0]}.#{RUBY_VERSION.split(".")[1]}.0"'); \
+		(export PATH="$$HOME/.local/share/gem/ruby/$$RUBY_ABI_VERSION/bin:$$PATH" && \
+		 bundle config set path 'vendor/bundle' && \
+		 bundle install); \
 		echo "✅ Dependencies installed!"; \
 	else \
 		echo "ℹ️  No Gemfile found, skipping dependency installation"; \
@@ -91,11 +133,12 @@ update: ## Update all gems to their latest versions (respecting Gemfile constrai
 	@if [ -f Gemfile ]; then \
 		echo "🔄 Updating Ruby dependencies..."; \
 		echo "📦 Running bundle update..."; \
-		bundle update; \
+		RUBY_ABI_VERSION=$$($(RUBY) -e 'puts "#{RUBY_VERSION.split(".")[0]}.#{RUBY_VERSION.split(".")[1]}.0"'); \
+		PATH="$$HOME/.local/share/gem/ruby/$$RUBY_ABI_VERSION/bin:$$PATH" bundle update; \
 		echo "✅ All gems updated to latest versions!"; \
 		echo ""; \
 		echo "💡 Current gem versions:"; \
-		bundle list | grep -E "^\s*\*" | head -10; \
+		PATH="$$HOME/.local/share/gem/ruby/$$RUBY_ABI_VERSION/bin:$$PATH" bundle list | grep -E "^\s*\*" | head -10; \
 	else \
 		echo "❌ No Gemfile found"; \
 		exit 1; \
@@ -110,7 +153,8 @@ update-bundler: ## Update bundler itself to the latest version
 outdated: ## Show outdated gems
 	@if [ -f Gemfile ]; then \
 		echo "📋 Checking for outdated gems..."; \
-		bundle outdated || true; \
+		RUBY_ABI_VERSION=$$($(RUBY) -e 'puts "#{RUBY_VERSION.split(".")[0]}.#{RUBY_VERSION.split(".")[1]}.0"'); \
+		PATH="$$HOME/.local/share/gem/ruby/$$RUBY_ABI_VERSION/bin:$$PATH" bundle outdated || true; \
 	else \
 		echo "❌ No Gemfile found"; \
 		exit 1; \

README.md

@@ -35,6 +35,22 @@ The CI will automatically validate your formula and update the documentation sit
 
 This tap uses a custom Ruby-based static site generator with zero external dependencies.
 
+### Quick Start
+
+For new contributors or first-time setup:
+
+```bash
+make setup    # Install Ruby dependencies and set up the environment
+make build    # Build the documentation site
+make serve    # Start development server
+```
+
+Or use the all-in-one development command:
+
+```bash
+make dev      # Full workflow: parse formulae, build site, and start server
+```
+
 ### Commands
 
 #### Using Make (Recommended)
@@ -51,12 +67,12 @@ make clean    # Clean all generated files
 
 **Development workflow:**
 ```bash
-make dev           # Full development workflow (parse + build + serve)
+make setup          # Initial setup: install Ruby dependencies and bundler
-make setup         # Check development environment setup
+make dev            # Full development workflow (parse + build + serve)
-make test          # Run validation tests
+make test           # Run validation tests
-make check         # Check project structure
+make check          # Check project structure
-make install       # Install Ruby dependencies (if Gemfile exists)
+make install        # Install Ruby dependencies (if Gemfile exists)
-make info          # Show project information
+make info           # Show project information
 ```
 
 **Server options:**