diff --git a/AGENTS.md b/AGENTS.md index 6be3e75..019c96e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,9 +25,18 @@ resources. ## Setup Commands ```bash -# Install dependencies locally (no sudo required) +# Install rbenv (macOS) and the project Ruby version +brew install rbenv ruby-build +rbenv install # reads .ruby-version (currently 3.4.9) +eval "$(rbenv init - zsh)" # add to ~/.zshrc for persistence + +# Install gems (no sudo required) bundle install +# Install pre-commit hooks +brew install pre-commit +pre-commit install + # Docker BuildKit is enabled by default in Rakefile # Verify Docker is running docker info @@ -61,6 +70,9 @@ bundle exec rake --trace │ └── npm_tests.rb # Shared npm tests ├── Rakefile # Test runner with parallel execution ├── Gemfile # Ruby dependencies +├── .ruby-version # rbenv Ruby version pin (3.4.9) +├── .rubocop.yml # Rubocop configuration +├── .pre-commit-config.yaml # Pre-commit hook definitions └── .github/workflows/ruby.yml # CI with Ruby 3.4 & 4.0 matrix ``` @@ -96,19 +108,24 @@ bundle update ## Documentation Standards -### Markdown Linting +### Pre-commit Hooks -All markdown files must pass markdownlint validation before committing. +All commits must pass pre-commit hooks. The hooks run automatically on `git commit`. +To run them manually: ```bash -# Check all markdown files -npx markdownlint-cli *.md +# Run all hooks against all files +pre-commit run --all-files -# Auto-fix issues where possible -npx markdownlint-cli --fix *.md +# Run a specific hook +pre-commit run rubocop --all-files +pre-commit run markdownlint-cli2-docker --all-files ``` -**Configuration**: See `.markdownlint.json` for project rules. +**Active hooks**: actionlint, gitleaks, hadolint, markdownlint-cli2, rubocop, zizmor, +and standard file hygiene checks (trailing whitespace, end-of-file, YAML, merge conflicts). + +**Markdown configuration**: See `.markdownlint.json` for project rules. **Key Rules**: @@ -156,20 +173,22 @@ end - Use 2 spaces for indentation - Follow existing patterns in spec files -- Use double quotes for strings +- Use single quotes for strings (rubocop enforces this) - Keep helper methods in `spec_helper.rb` +- All Ruby files must pass rubocop — run `pre-commit run rubocop --all-files` to check +- Configuration is in `.rubocop.yml`; Metrics cops are excluded for `spec/` ### Serverspec Patterns ```ruby # Use shared test methods -test_node("24.13.0") # Preferred +test_node('24.13.0') # Preferred test_npm # Preferred # Resource types commonly used -describe command("node --version") -describe package("curl") -describe file("/usr/local/bin/node") +describe command('node --version') +describe package('curl') +describe file('/usr/local/bin/node') ``` ### Dockerfile Conventions @@ -201,7 +220,7 @@ Both versions must pass before merge. - Test all changes locally before committing - Run full test suite: `bundle exec rake` -- Lint markdown files: `npx markdownlint-cli *.md` +- Run all pre-commit hooks before pushing: `pre-commit run --all-files` - Keep Node.js versions on LTS releases - Update README.md when changing versions - Use version pinning in Gemfile (`~>` operator) @@ -330,22 +349,18 @@ bundle exec rake --trace bundle exec rspec spec/24/Dockerfile_spec.rb --format documentation ``` +## Future Improvements + +Potential areas for future work: + +- Add Node.js v26 when it enters LTS +- Add Ruby 4.1 to the CI matrix when it releases +- Container image caching between test runs for faster CI +- Performance benchmarking automation + ## Resources - **Serverspec Documentation**: - **Docker API Gem**: - **Node.js Releases**: - **Ruby Releases**: - -## Questions? - -When working on this project: - -1. Check existing patterns in similar files -2. Run tests locally before committing -3. Review CI output for multi-version compatibility -4. Keep changes focused and well-tested - ---- - -**Note**: For historical information about AI contributions to this project, see [AI-CONTRIBUTIONS.md](./AI-CONTRIBUTIONS.md). diff --git a/AI-CONTRIBUTIONS.md b/AI-CONTRIBUTIONS.md deleted file mode 100644 index 1aa9890..0000000 --- a/AI-CONTRIBUTIONS.md +++ /dev/null @@ -1,239 +0,0 @@ -# AI Agent Contributions - -This document tracks improvements made to this project with the assistance of AI agents. - -> **Note**: For instructions on how AI agents should work on this codebase, see [AGENTS.md](./AGENTS.md). - -## Overview - -Between February 2026, this project underwent a comprehensive modernization -effort with AI assistance. The collaboration resulted in 11 merged pull requests -that transformed the codebase from having critical bugs and outdated dependencies -to being a modern, efficient, and future-proof testing infrastructure. - -## Improvements Summary - -### 🔒 Critical Bug Fixes - -#### PR #56: Fixed Unsafe Container Cleanup - -- **Issue**: `delete_image` was stopping ALL Docker containers on the system, including unrelated ones -- **Fix**: Updated to only stop containers created from the test image -- **Impact**: Prevented dangerous system-wide container disruptions - -### ⚡ Performance Enhancements - -#### PR #58: Parallel Test Execution - -- **Change**: Implemented Rake multitask for parallel test execution -- **Improvement**: ~47% faster test runs (35s → 18s) -- **Method**: Tests run in separate subprocesses with isolated environments - -#### PR #62: Docker BuildKit - -- **Change**: Enabled Docker BuildKit for image builds -- **Benefits**: Faster builds, better caching, improved layer management - -### 📦 Dependency Updates - -#### PR #57: Updated Gem Dependencies - -- Updated to latest stable versions with version pinning -- Gems: docker-api ~> 2.4, rake ~> 13.0, rspec ~> 3.13, serverspec ~> 2.43 -- Includes security patches and bug fixes - -#### PR #63: Logger Gem for Ruby 4.0 - -- Added explicit `logger` gem dependency -- Fixes Ruby 4.0 deprecation warning -- Ensures forward compatibility - -### 🧪 Testing Improvements - -#### PR #64: Ruby Version Matrix - -- Implemented GitHub Actions matrix testing -- Tests on Ruby 3.4 (maintenance) and Ruby 4.0 (latest) -- Ensures compatibility across Ruby versions -- fail-fast: false allows all versions to complete - -#### PR #65: Node.js LTS Updates - -- Updated from Node.js 20 & 22 to 22 & 24 -- Node.js 22.22.0 (Maintenance LTS) -- Node.js 24.13.0 (Active LTS "Krypton") -- Includes latest security patches (January 2026) - -### 🛡️ Reliability & Error Handling - -#### PR #61: Comprehensive Error Handling - -- Added try/catch blocks in `create_image` and `delete_image` -- Guards against nil @image references -- Clear error messages for debugging -- Informative status messages - -#### PR #60: Removed Redundant Tagging - -- Removed unused `@image.tag()` call -- Simplified image lifecycle management - -### 🔧 Developer Experience - -#### PR #59: Bundler Config & .gitignore - -- Added `.bundle/config` for local gem installation -- Created `.gitignore` to exclude vendor/bundle, .DS_Store, etc. -- Enables `bundle install` without sudo -- Cleaner repository - -### 📚 Documentation - -#### PR #66: Updated README - -- Updated directory references from (20 and 22) to (22 and 24) -- Keeps documentation in sync with code changes - -## Metrics - -### Before AI Assistance - -- Critical container cleanup bug (system-wide impact) -- Sequential test execution (~35 seconds) -- Outdated dependencies -- No Ruby version matrix testing -- Node.js 20 & 22 (outdated) -- No error handling -- Deprecation warnings -- Sudo required for gem installation - -### After AI Assistance - -- Safe, isolated container cleanup -- Parallel test execution (~18 seconds, 47% faster) -- Latest stable dependencies with version pinning -- Multi-version Ruby testing (3.4 & 4.0) -- Node.js 22.22.0 & 24.13.0 LTS with latest security patches -- Comprehensive error handling -- Zero deprecation warnings -- Easy local setup without sudo - -## Technology Stack Updates - -### Ruby Versions Tested - -- Ruby 3.4.x (Stable maintenance) -- Ruby 4.0.x (Latest stable) - -### Node.js Versions Tested - -- Node.js 22.22.0 (Maintenance LTS "Jod") -- Node.js 24.13.0 (Active LTS "Krypton") - -### Gem Versions - -- docker-api ~> 2.4 -- rake ~> 13.0 -- rspec ~> 3.13 -- serverspec ~> 2.43 -- logger (explicit for Ruby 4.0 compatibility) - -## AI Agent Methodology - -### Analysis Phase - -1. Comprehensive code review of existing implementation -2. Identification of bugs, inefficiencies, and technical debt -3. Prioritization of issues by severity and impact -4. Research of current best practices and latest versions - -### Implementation Phase - -1. Incremental improvements via focused pull requests -2. Testing at each step before proceeding -3. CI/CD validation for all changes -4. Clear documentation in commit messages and PR descriptions - -### Verification Phase - -1. Local testing before each commit -2. GitHub Actions CI validation -3. Multi-version compatibility testing -4. Security patch verification - -## Pull Request Links - -All improvements are documented in individual pull requests: - -- [PR #56](../../pull/56) - Fixed unsafe container cleanup -- [PR #57](../../pull/57) - Updated gem dependencies -- [PR #58](../../pull/58) - Parallel test execution -- [PR #59](../../pull/59) - Bundler config & .gitignore -- [PR #60](../../pull/60) - Removed redundant tagging -- [PR #61](../../pull/61) - Error handling -- [PR #62](../../pull/62) - Docker BuildKit -- [PR #63](../../pull/63) - Logger gem -- [PR #64](../../pull/64) - Ruby version matrix -- [PR #65](../../pull/65) - Node.js LTS updates -- [PR #66](../../pull/66) - README updates - -## Best Practices Demonstrated - -### Code Quality - -- Comprehensive error handling -- Resource cleanup in all code paths -- Clear, informative logging -- No technical debt - -### Testing - -- Multi-version testing (Ruby 3.4 & 4.0) -- Multi-platform testing (Node.js 22 & 24) -- Parallel execution for efficiency -- CI/CD automation - -### Dependencies - -- Version pinning for reproducibility -- Regular updates for security -- Explicit dependencies (no implicit defaults) -- Forward compatibility considerations - -### Documentation - -- Clear commit messages -- Detailed PR descriptions -- Updated README -- This AGENTS.md file for transparency - -## Lessons Learned - -1. **Incremental changes are safer**: Small, focused PRs are easier to review and rollback if needed -2. **Testing is critical**: Multi-version testing catches compatibility issues early -3. **Security matters**: Regular dependency updates include important security patches -4. **Developer experience**: Simple setup (no sudo) encourages contribution -5. **Documentation ages**: Keep docs in sync with code changes - -## Future Considerations - -While the project is now in excellent shape, potential future improvements could include: - -- Additional Node.js LTS version testing (e.g., v26 when released) -- Ruby 4.1 when it enters LTS -- Container image caching between test runs -- Performance benchmarking automation - -## Acknowledgments - -This project benefited from AI assistance using Factory's Droid agent, which -helped identify issues, research solutions, implement fixes, and ensure -comprehensive testing. All changes were reviewed and approved by the project -maintainer. - ---- - -**Last Updated**: February 2026 -**AI Agent**: Factory Droid -**Total PRs**: 11 -**Impact**: Project transformed from legacy code to modern, production-ready infrastructure diff --git a/README.md b/README.md index fd6c3d7..8bffe08 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,40 @@ This is an example of using Serverspec to test Dockerfiles ## Setup -Install Serverspec and the require gems with bundler: +This example assumes you have Docker installed, running and configured. + +### Ruby + +This project uses [rbenv](https://github.com/rbenv/rbenv) to manage Ruby versions. +Install it and the required Ruby version: + +```shell +brew install rbenv ruby-build +rbenv install # installs the version from .ruby-version +``` + +Add rbenv to your shell (add to `~/.zshrc` or `~/.bashrc`): + +```shell +eval "$(rbenv init - zsh)" +``` + +### Dependencies + +Install gems with bundler: ```shell bundle install ``` -This example assumes you have Docker installed, running and configured. +### Pre-commit Hooks + +Install [pre-commit](https://pre-commit.com/) and set up the hooks: + +```shell +brew install pre-commit +pre-commit install +``` ## Usage (running the tests)