From afafe251fbac35a253583a0704719d5da63b0212 Mon Sep 17 00:00:00 2001 From: Steve Polito Date: Fri, 26 Apr 2024 14:02:17 -0400 Subject: [PATCH] Install Generator: Generate `CONTRIBUTING.md` (#1196) Generate contributing guide when suspending a new Rails application. Update generated `README.md` to point to contributing guide. Co-authored-by: Sean Doyle --- .../suspenders/install/web_generator.rb | 2 + .../templates/install/web/CONTRIBUTING.md | 94 +++++++++++++++++++ lib/suspenders/cleanup/generate_readme.rb | 12 +++ 3 files changed, 108 insertions(+) create mode 100644 lib/generators/templates/install/web/CONTRIBUTING.md diff --git a/lib/generators/suspenders/install/web_generator.rb b/lib/generators/suspenders/install/web_generator.rb index 83427ca6d..0b5172272 100644 --- a/lib/generators/suspenders/install/web_generator.rb +++ b/lib/generators/suspenders/install/web_generator.rb @@ -5,6 +5,7 @@ class WebGenerator < Rails::Generators::Base include Suspenders::Generators::APIAppUnsupported include Suspenders::Generators::DatabaseUnsupported + source_root File.expand_path("../../../templates/install/web", __FILE__) desc <<~MARKDOWN Invokes all necessary generators for new Rails applications generated with Suspenders. @@ -55,6 +56,7 @@ def invoke_generators def cleanup rake "suspenders:cleanup:organize_gemfile" rake "suspenders:cleanup:generate_readme" + copy_file "CONTRIBUTING.md", "CONTRIBUTING.md" end def lint diff --git a/lib/generators/templates/install/web/CONTRIBUTING.md b/lib/generators/templates/install/web/CONTRIBUTING.md new file mode 100644 index 000000000..edf3161e6 --- /dev/null +++ b/lib/generators/templates/install/web/CONTRIBUTING.md @@ -0,0 +1,94 @@ +# Contributing + +## Accessibility Tooling + +Building accessible applications is a complex, multi-faceted, and mission critical endeavor. While tooling cannot guarantee an accessible experience, it can help raise the bar for the baseline experience in important ways. + +In addition to the W3C's [WAI Overview][], [WAI Authoring Practices Guide][], and [WAI-ARIA Specification][], along with MDN's [Accessibility Documentation][], the [thoughtbot handbook][] includes some high-level technical guidance. + +[WAI Overview]: https://www.w3.org/WAI/standards-guidelines/aria/ +[WAI Authoring Practices Guide]: https://www.w3.org/WAI/ARIA/apg/ +[WAI-ARIA Specification]: https://www.w3.org/TR/wai-aria/ +[Accessibility Documentation]: https://developer.mozilla.org/en-US/docs/Web/Accessibility +[thoughtbot guides]: https://github.com/thoughtbot/guides/blob/main/accessibility/README.md#development + +### Capybara and the System Test Suite + +[Capybara][] is responsible for driving the application's [System Test][] suite through Real Life browser sessions. + +Capybara drives the page and makes assertions about its state and content through utilities called [Selectors][]. They're a layer of abstraction that's a blend of HTML tag names and ARIA role semantics. For example, Capybara uses the `:link` selector whether it needs to locate and click on an `` element through a call to [click_link][] or make an assertion about the presence and content of an `` element through a call to [assert_link][]. + +Out of the box, Capybara provides a wide range of [built-in selectors][] that cover the majority of a System Test harness' needs. In addition to the out of the box selectors, this project also depends on the [capybara_accessible_selectors][] gem to expand Capybara's set of selectors. + +If you find yourself in a situation where you're reaching for CSS selectors or other means of resolving nodes, you might benefit from a built-in selector or one provided by `capybara_accessible_selectors`. Take this test block, for example: + +```ruby +#
+# Some fields +# +# +# +# +#
+ +# BEFORE +within ".some-css .selector-chain" do + find(".my-button").click + find(".my-text-field").set "Hello, world" +end + +# AFTER +within :fieldset, "Some field" do + click_button "Click me" + fill_in "Fill me in", with: "Hello, world" +end +``` + +The [Testing RSpec][] section of the `thoughtbot/guides` provides some general guidance for automated Acceptance Testing. + +[Capybara]: https://rubydoc.info/github/teamcapybara/capybara/master/ +[System Test]: https://guides.rubyonrails.org/testing.html#system-testing +[Selectors]: https://rubydoc.info/github/teamcapybara/capybara/master#selectors +[click_link]: https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Actions:click_link +[assert_link]: https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Minitest/Assertions:assert_link +[built-in selectors]: https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Selector#built-in-selectors +[capybara_accessible_selectors]: https://github.com/citizensadvice/capybara_accessible_selectors +[Testing RSpec]: https://github.com/thoughtbot/guides/blob/main/testing-rspec/README.md#acceptance-tests + +### `capybara_accessibility_audit` and `axe.js` + +This project depends on the [capybara_accessibility_audit][] gem to enhance the application's System Test suite to audit the browser's DOM for statically detectable accessibility violations. Under the hood, `capybara_accessibility_audit` utilizes [axe.js][] for auditing. + +The categories of violation that `capybara_accessibility_audit` can detect span a wide range from insufficient [color contrast][] to invalid or insufficient [landmark-based information hierarchy][landmark], to [unnamed form controls][] and beyond. + +Out of the box, `capybara_accessibility_audit` will extend Capybara to conduct an accessibility audit after a variety of actions like `visit` and `click_link`. That project can [be configured to suit this application's needs][capybara_accessibility_audit-configuration]. + +If you can integrate `capybara_accessibility_audit` from the project's inception, you can start with (and maintain!) accessibility violation bankruptcy. + +[capybara_accessibility_audit]: https://github.com/thoughtbot/capybara_accessibility_audit +[capybara_accessibility_audit-configuration]: https://github.com/thoughtbot/capybara_accessibility_audit?tab=readme-ov-file#frequently-asked-questions +[axe.js]: https://www.deque.com/axe/ +[color contrast]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast +[landmark]: https://developer.mozilla.org/en-US/blog/aria-accessibility-html-landmark-roles/ +[unnamed form controls]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Text_labels_and_names#form_elements_must_be_labeled + +### VoiceOver on macos + +VoiceOver is a screen reader integrated directly into the macOS operating system. You can learn more from [Apple's Accessibility Support][]. + +VoiceOver and Safari are tightly integrated. If you're developing this +application on a Mac, you should familiarize yourself with how to navigate in +Safari using VoiceOver. You can learn more about how to use VoiceOver from the +[Get started with VoiceOver on Mac][]. You might also enjoy [Screen Reader +Basics: VoiceOver][] in the A11ycasts series of videos from the "Chrome for Developers" YouTube channel. + +[![Watch Screen Reader Basics: VoiceOver](https://img.youtube.com/vi/5R-6WvAihms/maxresdefault.jpg)](https://www.youtube.com/watch?v=5R-6WvAihms) + +After you've written a System Test or have completed a feature, it can be **extremely** valuable to navigate to that part of the application and try your best to recreate the experience based on keyboard navigation and screen reader announcements alone. + +[Apple's Accessibility Support]: https://support.apple.com/accessibility +[Get started with VoiceOver on Mac]: https://support.apple.com/guide/voiceover/get-started-vo4be8816d70/10/mac/14.0 +[Screen Reader Basics: VoiceOver]: https://www.youtube.com/watch?v=5R-6WvAihms diff --git a/lib/suspenders/cleanup/generate_readme.rb b/lib/suspenders/cleanup/generate_readme.rb index ed302bb5a..d6de5fee7 100644 --- a/lib/suspenders/cleanup/generate_readme.rb +++ b/lib/suspenders/cleanup/generate_readme.rb @@ -59,6 +59,14 @@ def perform heading "Accessibility", level: 2 description_for Suspenders::Generators::AccessibilityGenerator + content <<~MARKDOWN + For more information, review the [Accessibility Tooling][] section in + the [CONTRIBUTING][] guide. + + [Accessibility Tooling]: ./CONTRIBUTING.md#accessibility-tooling + [CONTRIBUTING]: ./CONTRIBUTING.md + MARKDOWN + new_line heading "Advisories", level: 2 description_for Suspenders::Generators::AdvisoriesGenerator @@ -84,6 +92,10 @@ def perform private + def content(text) + @file.write text + end + def new_line @file.write "\n" end