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>
2026-01-26 03:14:04 +00:00 · 2025-09-25 17:37:04 +03:00
parent 972d09ea0f
commit a7e987ba2e
8 changed files with 80 additions and 26 deletions
--- a/.github/workflows/ci.yml
+++ b/.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: |
-          export GEM_HOME="$HOME/.gem"
-          export PATH="$GEM_HOME/bin:$PATH"
-          gem install bundler --user-install
-          bundle install
+        run: make setup

      - name: Run brew test-bot (cleanup)
        shell: bash
--- a/.github/workflows/pages-build.yml
+++ b/.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
--- a/2
+++ b/2
@@ -2,7 +2,7 @@

 source "https://rubygems.org"

-ruby "3.4.6"
+ruby ">= 3.0.0"

 gem "cssminify2", "~> 2.0"
 gem "json", "~> 2.7"
--- a/60
+++ b/60
@@ -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
-	@$(RUBY) $(SCRIPTS_DIR)/build_site.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; \
+		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; \
--- a/README.md
+++ b/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         # Check development environment setup
-make test          # Run validation tests
-make check         # Check project structure
-make install       # Install Ruby dependencies (if Gemfile exists)
-make info          # Show project information
+make setup          # Initial setup: install Ruby dependencies and bundler
+make dev            # Full development workflow (parse + build + serve)
+make test           # Run validation tests
+make check          # Check project structure
+make install        # Install Ruby dependencies (if Gemfile exists)
+make info           # Show project information
 ```

 **Server options:**
--- a/docs/.gitkeep
+++ b/docs/.gitkeep
--- a/docs/_data/.gitkeep
+++ b/docs/_data/.gitkeep
--- a/docs/assets/.gitkeep
+++ b/docs/assets/.gitkeep