RoleModel Rails

Executable Best Practices for Rails apps, based on RoleModel's best approaches

Attempts to solve the pain of:

• Setup of a new Rails app is harder than it needs to be
  • We've tried application templates, but only useful onetime
• Our BestPractice learns don't often get ported into other projects as it isn't straightforward to do so
• There is an emerging pattern of libraries using generators (e.g. webpacker) to migrate a setup between library versions

Precondition

The rolemodel_rails gem expects to be added to an existing Rails project. Typically those are started with:

rails new <app-name> --javascript=webpack --database=postgresql --skip-test

The Devise generator requires your database to exist before running.

rails db:create

Installation

Add this line to your application's Gemfile:

group :development do
  gem 'rolemodel_rails', github: 'RoleModel/rolemodel_rails'
end

And then execute:

$ bundle

Usage

Run all generators (useful on a new app)

bin/rails g rolemodel:all

Or run a single generator

bin/rails g rolemodel:webpack

Or run a category subset

bin/rails g rolemodel:testing:all

You can see complete list of available generators (including those under the RoleModel namespace) by running

bin/rails g

Generators

• Github
• Semaphore
• Heroku
• Readme
• Webpack
• React
• Slim
• Optics
  • Base
  • Icons
• Testing
  • RSpec
  • Jasmine Playwright
  • ViTest
  • Factory Bot
  • Test Prof
  • Parallel Test
• SimpleForm
• SoftDestroyable
• SaaS
  • Devise
• Mailers
• Linters
  • Rubocop
  • ESLint
• UI Components
  • Flash
  • Modals
  • Navbar
• Source Map
• Kaminari
• GoodJob
• Editors
• Tailored Select
• Lograge

Development

Install the versions of Node and Ruby specified in .node-version and .ruby-version on your machine. https://asdf-vm.com/ is a great tool for managing language versions. Then run npm install -g yarn.

Adding new Generators

Run bin/new_generator passing the name you want to use and a description. Consult the list of existing Generators in case your new generator belongs in one of the existing groups (folders).

e.g.

bin/new_generator testing/fantasitic_specs 'A Fantastic Testing Framework'

We use the embeded Rails apps (example_rails*) to test generators against. They reference the rolemodel_rails gem by local path, so you can navigate into one of them and run your generator for immediate feedback while developing.

Important

Before submitting a PR, run bin/bump_version to ensure the Gem builds successfully & that everything continues to stay in sync & up-to-date.

For very small changes & bug fixes, prefer bin/bump_version --patch.

Testing

Generator specs should be added to the spec directory.

Setup & Teardown of the test-dummy app is handled for you. All you need to do is run the provided helper method:

e.g.

RSpec.describe Rolemodel::MyGenerator, type: :generator do
  before { run_generator_against_test_app }
end

You may also provide command line arguments to the helper method as an array:

e.g.

RSpec.describe Rolemodel::Testing::JasminePlaywrightGenerator, type: :generator do
  before { run_generator_against_test_app(['--github-package-token=123']) }
end

Additional information about testing generators and the available assertions & matchers can be found at the following resources.

• Rails Guide
• API Documentation
• Generator Spec Gem

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/RoleModel/rolemodel_rails.

License

The gem is available as open source under the terms of the MIT License.