Skip to content

TEMPLATE_UPDATES_SUMMARY.md

Latest commit

 

History

History
130 lines (96 loc) · 4.14 KB

TEMPLATE_UPDATES_SUMMARY.md

File metadata and controls

130 lines (96 loc) · 4.14 KB
Raw

Generator Template Updates Summary

This document summarizes the updates made to the Rails Accessibility Testing generator templates based on production best practices from Margarita Barvinok's implementation.

Overview

The generator templates have been updated to incorporate production-tested best practices that improve CI/CD safety, production deployment safety, and developer experience.

Files Updated

1. lib/generators/rails_a11y/install/templates/accessibility.yml.erb

Changes:

  • ✅ Changed accessibility_enabled default from true → false
  • ✅ Added comprehensive documentation explaining CI/CD behavior
  • ✅ Updated documentation URL to correct GitHub Pages link
  • ✅ Added detailed comments explaining when to enable/disable

Impact:

  • Prevents accessibility test failures from blocking CI/CD pipelines
  • Allows other RSpec tests to pass even if accessibility tests fail
  • Gives developers explicit control over when to run accessibility checks

2. lib/generators/rails_a11y/install/templates/initializer.rb.erb

Changes:

  • ✅ Added production safety guard: if defined?(RailsAccessibilityTesting)
  • ✅ Changed auto_run_checks default from true → false
  • ✅ Updated documentation URL to correct GitHub Pages link
  • ✅ Added @see tag for better documentation

Impact:

  • Prevents errors if gem is not available in production
  • Allows gem to be excluded from production bundle
  • Gives developers explicit control over automatic checks
  • Safe deployment even if gem configuration is present

3. lib/generators/rails_a11y/install/templates/all_pages_accessibility_spec.rb.erb

Changes:

  • ✅ Changed RSpec type from type: :system → type: :accessibility
  • ✅ Improved error formatting with unified format_issues_by_file helper method
  • ✅ Changed test assertion to use expect(errors).to be_empty with formatted message
  • ✅ Better success message formatting

Impact:

  • Proper RSpec integration with accessibility helpers
  • Better test organization and filtering
  • Cleaner test output
  • Improved error messages with better structure

New Documentation

GUIDES/best_practices.md

Created comprehensive best practices guide covering:

  • Configuration best practices
  • CI/CD integration patterns
  • Development workflow recommendations
  • Production deployment safety
  • Real-world usage examples

Updated Documentation

  • ✅ README.md - Added link to Best Practices guide
  • ✅ GUIDES/continuous_integration.md - Added best practice about disabling by default
  • ✅ CHANGELOG.md - Documented template updates

Key Improvements

1. CI/CD Safety

  • Accessibility tests disabled by default
  • Won't block other RSpec tests in CI
  • Manual invocation when needed

2. Production Safety

  • Conditional configuration prevents errors
  • Safe deployment even without gem
  • No production dependencies

3. Developer Control

  • Explicit control over automatic checks
  • Manual testing when needed
  • Better error formatting

4. Better UX

  • Improved error messages
  • Proper RSpec integration
  • Cleaner test output

Migration Notes

For existing installations:

  1. Update config/accessibility.yml:

    accessibility_enabled: false  # Add this if not present

  2. Update config/initializers/rails_a11y.rb:

    if defined?(RailsAccessibilityTesting)
  RailsAccessibilityTesting.configure do |config|
    config.auto_run_checks = false  # Change from true if needed
  end
end

  3. Update spec/accessibility/all_pages_accessibility_spec.rb:

    • Change type: :system to type: :accessibility
    • Update error formatting to use unified helper method

Credits

These improvements are based on production-tested configurations from:

  • Margarita Barvinok - Production configuration improvements
  • Real-world usage in Rails applications
  • Community feedback and testing

Next Steps

  1. Test generator with rails generate rails_a11y:install
  2. Verify templates generate correct configuration
  3. Update existing projects using migration notes above
  4. Share feedback and improvements

Date: February 2026
Version: Unreleased (will be in next release)