bullet_train 1.0.36 → 1.0.37

data/docs/indirection.md

@@ -0,0 +1,53 @@
+# Dealing with Indirection
+
+## The Problem with Indirection
+
+In software development, indirection is everywhere and takes many forms.
+
+For example, in vanilla Rails development, you introduce a type of indirection when you extract a button label out of a view file and use the `t` helper to render the string from a translation YAML file. In the future, when another developer goes to update the button label, they will first open the view, they'll see `t(".submit")` and then have to reason a little bit about which translation file they need to open up in order to update that label.
+
+Our goal in Bullet Train is to improve developer experience, not reduce it, so it was important that along with any instances of indirection we were introducing, we also included new tooling to ensure it was never a burden to developers. Thankfully, in practice we found that some of this new tooling improves even layers of indirection that have always been with us in Rails development.
+
+## Solving Indirection in Views
+
+### Resolving Partial Paths with `bin/resolve`
+
+Even in vanilla Rails development, when you're looking at a view file, the path you see passed to a `render` call isn't the actual file name of the partial that will be rendered. This is even more true in Bullet Train where certain partial paths are [magically served from theme gems](/docs/themes.md).
+
+`bin/resolve` makes it easy to figure out where where a partial is being served from:
+
+```
+$ bin/resolve shared/box
+```
+
+### Exposing Rendered Views with Xray
+
+> TODO Is this still true in Rails 7? Does it not do something like this by default now?
+
+If you're looking at a rendered view in the browser, it can be hard to know which file to open in order to make a change. To help, Bullet Train includes [Xray](https://github.com/brentd/xray-rails) by default, so you can right click on any element you see, select "Inspect Element", and you'll see comments in the HTML source telling you which file is powering a particular portion of the view, like this:
+
+```
+<!--XRAY START 90 /Users/andrewculver/.rbenv/versions/3.1.1/lib/ruby/gems/3.1.0/gems/bullet_train-themes-light-1.0.10/app/views/themes/light/workflow/_box.html.erb-->
+```
+
+Note that in the example above, the view in question isn't actually coming from the application repository. Instead, it's being included from the `bullet_train-themes-light` package. For instructions on how to customize it, see [Overriding the Framework](/docs/override).
+
+### Drilling Down on Translation Keys
+
+Even in vanilla Rails applications, extracting strings from view files into I18N translation YAML files introduces a layer of indirection. Bullet Train tries to improve the resulting DX with a couple tools that make it easier to figure out where a translation you see in your browser is coming from.
+
+#### Show Translation Keys in the Browser with `?show_locales=true`
+
+You can see the full translation key of any string on the page by adding `?show_locales=true` to the URL.
+
+#### Log Translation Keys to the Console with `?log_locales=true`
+
+You can also log all the translation key for anything being rendered to the console by adding `?log_locales=true` to the request URL. This can make it easier to copy and paste translation keys for strings that are rendered in non-selectable UI elements.
+
+#### Resolving Translation Keys with `bin/resolve`
+
+Once you have the full I18N translation key, you can use `bin/resolve` to figure out which package and file it's coming from. At that point, if you need to customize it, you can also use the `--eject` option to copy the  the framework for customization in your local application:
+
+```
+$ bin/resolve en.account.onboarding.user_details.edit.header --eject --open
+```

data/docs/modeling.md

@@ -0,0 +1,93 @@
+# Domain Modeling in Bullet Train
+
+Domain modeling is one of the most important activities in software development. With [Super Scaffolding](/docs/super-scaffolding.md), it's also one of the highest leverage activities in Bullet Train development.
+
+## What is a "Domain Model"?
+
+In software application development, your domain model is the object-oriented representation (or "abstraction") of the problem space you're solving problems for. In Rails, the classes that represent your domain model live in `app/models`.
+
+## What is "Domain Modeling"?
+
+"Domain modeling" refers to the process by which you decide which entities to introduce into your application's domain model, how those models relate to each other, and which attributes belong on which models.
+
+Because in Rails most of your models will typically be backed by tables in a database, the process of domain modeling substantially overlaps with "database design". This is especially true in systems like Rails that implement their domain model with the Active Record pattern, because your table structure and object-oriented models are pretty much mapped one-to-one[<sup>*</sup>](https://en.wikipedia.org/wiki/Object–relational_impedance_mismatch).
+
+## The Importance of Domain Modeling
+
+### Usability
+
+Generally speaking, the better your domain model is mapped to the real-world problem space, the more likely it is to map to your own users conceptual model of the problem space in their own head. Since the structure of your domain model ends up having such a large influence on the default structure and navigation of your application UI, getting the domain model "right" is the first step in creating an application that is easy for users to understand and use.
+
+### Extendability
+
+Feature requests come from the real world, and specifically from the parts of reality your application doesn't already solve for. The better your existing domain model captures the existing real-world problem space you've tried to solve problems for, the easier it will be for your application to add new models for features that solve the new problems your users are actually experiencing in real life. Inversely, if you take the wrong shortcuts when representing the problem space, it will be difficult to find the right place to add new features in a way that makes sense to your users.
+
+## Important Bullet Train Concepts
+
+### The "Parent Model"
+
+The idea of a "parent model" is different than [a "parent class" in an object-oriented sense](https://en.wikipedia.org/wiki/Inheritance_\(object-oriented_programming\)). When we say "parent model", we're referring to the model that another model primarily belongs to. For example, a `Task` might primarily belong to a `Project`. Although this type of hierarchy isn't an entirely natural concept in object-oriented programming itself, (where our UML diagrams have many types of relationships flying in different directions,) it's actually a very natural concept in the navigation structure of software, which is why breadcrumbs are such a popular tool for navigation. It's also a concept that is very natural in traditional Rails development, expressed in the definition of nested RESTful routes for resources.
+
+## Philosophies
+
+### Take your time and get it right.
+
+Because Super Scaffolding makes it so easy to bring your domain model to life, you don't have to rush into that implementation phase of writing code. Instead, you can take your sweet time thinking through your proposed domain model and mentally running it through the different scenarios and use cases it needs to solve for. If you get aspects of your domain model wrong, it can be really hard to fix later.
+
+### More minds are better.
+
+Subject your proposed domain model to review from other developers or potential users and invite their thoughts.
+
+### Tear it down to get it right.
+
+In traditional Rails development, it can be so much work to bring your domain model to life in views and controllers that if you afterward realize you missed something or got something wrong structurally, it can be tempting not to fix it or refactor it. Because Super Scaffolding eliminates so much of the busy work of bringing your domain model to life in the initial implementation phase, you don't have to worry so much about tearing down your scaffolds, reworking the domain model, and running through the scaffolding process again.
+
+### Focus on the structure and namespacing. Don't worry about every attribute.
+
+One of the unique features of Super Scaffolding is that it allows you to scaffold additional attributes with `bin/super-scaffold crud-field` after the initial scaffolding of a model with `bin/super-scaffold crud`. That means that you don't have to worry about figuring out every single attribute that might exist on a model before running Super Scaffolding. Instead, the really important piece is:
+
+1. Naming the model.
+2. Determining which parent model it primarily belongs to.
+3. Determining whether the model should be [in a topic namespace](https://blog.bullettrain.co/rails-model-namespacing/).
+
+### Start with CRUD, then polish.
+
+Even if you know there's an attribute or model that you're going to want to polish up the user experience for, still start with the scaffolding. This ensures that any model or attribute is also represented in your REST API and you have feature parity between your web-based experience and what developers can integrate with and automate.
+
+### Pluralize preemptively.
+
+> Before you write any code — ask if you could ever possibly want multiple kinds of the thing you are coding. If yes, just do it. Now, not later.
+
+— [Shawn Wang](https://twitter.com/swyx)
+
+> I've done this refactoring a million times. I'll be like, I thought there would only ever be one subscription team, user plan, name, address, and it always ends up being like, "Oh, actually there's more." I almost never go the other way. What if you just paid the upfront cost of thinking "This is just always a collection"?
+
+— [Ben Orenstein](https://twitter.com/r00k)
+
+[I believe this is one of the most important articles in software development in the last ten years.](https://www.swyx.io/preemptive-pluralization/) However, with great domain modeling power comes great UX responsibility, which we'll touch on later.
+
+## A Systematic Approach
+
+### 1. Write `rails g` and `bin/super-scaffold` commands in a scratch file.
+
+See the [Super Scaffolding documentation](/docs/super-scaffolding.md) for more specific guidance. Leave plenty of comments in your scratch file describing anything that isn't obvious and providing examples of values that might populate attributes.
+
+### 2. Review with other developers.
+
+Push up a pull request with your scratch file and invite review from other developers. They might bring up scenarios and use cases you didn't think of, better ways of representing something, or generate questions that don't have an obvious answer and require feedback from a subject matter expert.
+
+### 3. Review with non-developer stakeholders.
+
+Engage with product owners or potential users and talk through each part of the domain model in your scratch file without showing it to them or getting too technical. Just talk through which entities you chose to represent, which attributes and options are available. Talk through the features those models and attributes allow you to provide and which use cases you think you've covered.
+
+In these discussions, you're looking for inspiration of additional nouns, verbs, and use cases you may not have considered in your initial modeling. Even if you choose not to incorporate certain ideas or feature requests immediately, you're at least taking into consideration whether they would fit nicely into the mental model you have represented in your domain model.
+
+### 4. Run the commands.
+
+Be sure to commit your results at this point. This helps isolate the computer generated code from the work you'll do in the next step (which you may want to have someone review.)
+
+### 5. Polish the UI.
+
+By default, Bullet Train produces a very CRUD-y user experience. The intention has always been that the productivity gains provided by Super Scaffolding should be reinvested into the steps that come before and after. Spend more time domain modeling, and then spend more time polishing up the resulting UX.
+
+This is especially true in situations where you've chosen to pluralize preemptively. Ask yourself: Does every user need this option in the plural? If not, should we try to simplify the conceptual model by representing it as a "has one" until they opt-in to complexity? Doing this allows you to have the best of both worlds: Simplicity for those who can fit within it, and advanced functionality that users can opt into.

data/docs/namespacing.md

@@ -0,0 +1,11 @@
+# Namespacing in Bullet Train
+
+## The `Account` Namespace for Controllers and Views
+Bullet Train comes preconfigured with an `Account` and controller and view namespace. This is the place where Super Scaffolding will, by default, put new resource views and controllers. The intention here is to ensure that in systems that have both authenticated resource workflows and public-facing resources, those two different facets of the application are served by separate resource views and controllers. (By default, public-facing resources would be in the `Public` namespace.)
+
+## Alternative Authenticated Namespaces
+In Bullet Train applications with [multiple team types](/docs/teams.md), you may find it helpful to introduce additional controller and view namespaces to represent and organize user interfaces and experiences for certain team types that vary substantially from the `Account` namespace default. In Super Scaffolding, you can specify a namespace other than `Account` with the `--namespace` option, for example:
+
+```
+$ bin/super-scaffold crud Event Team name:text_field --namespace=customers
+```

data/docs/oauth.md

@@ -0,0 +1,27 @@
+# OAuth Providers
+Bullet Train includes [Omniauth](https://github.com/omniauth/omniauth) by default which enables [Super Scaffolding](/docs/super-scaffolding) to easily add [any of the third-party OAuth providers in its community-maintained list of strategies](https://github.com/omniauth/omniauth/wiki/List-of-Strategies) for user-level authentication and team-level integrations via API and incoming webhooks.
+
+For specific instructions on adding new OAuth providers, run the following on your shell:
+
+> TODO This scaffolder still needs to be updated to support the new way we distribute the Stripe Connect example via Ruby gem.
+
+```
+bin/super-scaffold oauth-provider
+```
+
+## Stripe Connect Example
+Similar to the "Tangible Things" template for [Super Scaffolding CRUD workflows](/docs/super-scaffolding.md), Bullet Train includes a Stripe Connect integration by default and this example also serves as a template for Super Scaffolding to implement other providers you might want to add.
+
+## Dealing with Last Mile Issues
+
+You should be able to add many third-party OAuth providers with Super Scaffolding without any manual effort. However, there are sometimes quirks from provider to provider, so if you need to dig in to get things working on a specific provider, here are the files you'll probably be looking for:
+
+### Core Functionality
+ - `config.omniauth` in `config/initializers/devise.rb`
+   - Third-party OAuth providers are registered at the top of this file.
+ - `app/controllers/account/oauth/omniauth_callbacks_controller.rb`
+   - This controller contains all the logic that executes when a user returns back to your application after working their way through the third-party OAuth provider's workflow.
+ - `omniauth_callbacks` in `config/routes.rb`
+   - This file just registers the above controller with Devise.
+ - `app/views/devise/shared/_oauth.html.erb`
+   - This partial includes all the buttons for presentation on the sign in and sign up pages.

data/docs/onboarding.md

@@ -0,0 +1,41 @@
+# Onboarding
+Bullet Train provides an easy to understand and modifiable structure for defining required onboarding steps and forms. This system makes it easy for users to complete required steps before seeing your application's full account interface. The code for this feature is well documented in the code with comments, so rather than duplicating that document here, we'll simply direct you to the relevant files.
+
+## Included Onboarding Steps
+
+### Collect User Details
+
+The included "user details" onboarding step is intended to collect any fields that are required for a user account to be "complete" while not requiring those fields to be collected on the initial sign up form. This is a deliberate UX decision to try and increase conversions on the initial form.
+
+### Collect User Email
+
+The "user email" onboarding step is specifically used in situations where a user signs up with an OAuth provider that either doesn't supply their email address to the application or doesn't have a verified email address for the user. In this situation, we want to have an email address on their account, so we prompt them for it.
+
+## Relevant Files
+
+> TODO This section needs to be updated now that a bunch of these files are coming in from gems.
+
+### Controllers
+ - `ensure_onboarding_is_complete` in `app/controllers/account/application_controller.rb`
+ - `app/controllers/account/onboarding/user_details_controller.rb`
+ - `app/controllers/account/onboarding/user_email_controller.rb`
+
+### Views
+ - `app/views/account/onboarding/user_details/edit.html.erb`
+ - `app/views/account/onboarding/user_email/edit.html.erb`
+
+### Models
+ - `user#details_provided?` in `app/models/user.rb`
+
+### Routes
+ - `namespace :onboarding` in `config/routes.rb`
+
+## Adding Additional Steps
+Although you can implement onboarding steps from scratch, we always just copy and paste one of the existing steps as a starting point, like so:
+
+1. Copy, rename, and modify of the existing onboarding controllers.
+2. Copy, rename, and modify the corresponding `edit.html.erb` view.
+3. Copy and rename the route entry in `config/routes.rb`.
+4. Add the appropriate gating logic in `ensure_onboarding_is_complete` in `app/controllers/account/application_controller.rb`
+
+Onboarding steps aren't limited to targeting `User` models. It's possible to add onboarding steps to help flesh out team `Membership` records or `Team` records as well. You can use this pattern for setting up any sort of required data for either the user or the team.

data/docs/permissions.md

@@ -0,0 +1,18 @@
+# Roles, Permissions, Abilities, and Authorization
+
+## CanCanCan
+Bullet Train leans heavily on [CanCanCan](https://github.com/CanCanCommunity/cancancan) for implementing authorization and permissions. (We’re also proud sponsors of its ongoing maintenance.) The original CanCan library by Ryan Bates was, in our opinion, a masterpiece and a software engineering marvel that has stood the test of time. It's truly a diamond among Ruby Gems. If you're not already familiar with CanCanCan, you should [read its documentation](https://github.com/CanCanCommunity/cancancan) to get familiar with its features and DSL.
+
+## Bullet Train Roles
+Over many years of successfully implementing applications with CanCanCan, it became apparent to us that a supplemental level of abstraction could help streamline and simplify the definition of many common permissions, especially in large applications. We've since extracted this functionality into [a standalone Ruby Gem](https://github.com/bullet-train-co/bullet_train-roles) and moved the documentation that used to be here into [the README for that project](https://github.com/bullet-train-co/bullet_train-roles/blob/main/README.md). Should you encounter situations where this abstraction doesn't meet your specific needs, you can always implement the permissions you need using standard CanCanCan directives in `app/models/ability.rb`.
+
+## Additional Notes
+
+### Caching
+Because abilities are being evaluated on basically every request, it made sense to introduce a thin layer of caching to help speed things up. When evaluating permissions, we store a cache of the result in the `ability_cache` attribute of the `User`. By default, making changes to a model that includes the `Roles::Support` concern will invalidate that user's cache.
+
+### Naming and Labeling
+What we call a `Role` in the domain model is referred to as “Special Privileges” in the user-facing application. You can rename this to whatever you like in `config/locales/en/roles.en.yml`.
+
+## Note About Pundit
+There’s nothing stopping you from utilizing Pundit in a Bullet Train project for specific hard-to-implement cases in your permissions model, but you wouldn’t want to try and replace CanCanCan with it. We do too much automatically with CanCanCan for that to be recommended. That said, in those situations where there is a permission that needs to be implemented that isn’t easily implemented with CanCanCan, consider just writing vanilla Ruby code for that purpose.

data/docs/seeds.md

@@ -0,0 +1,48 @@
+# Database Seeds
+
+Bullet Train introduces a new, slightly different expectation for Rails seed data: **It should be possible to run `rake db:seed` multiple times without creating duplicate data.**
+
+## The Rails Default
+
+This is different than the Rails default, [as evidenced by the Rails example](https://guides.rubyonrails.org/v6.1.1/active_record_migrations.html#migrations-and-seed-data) which uses `Product.create`:
+
+```
+5.times do |i|
+  Product.create(name: "Product ##{i}", description: "A product.")
+end
+```
+
+## Bullet Train Example
+
+In Bullet Train applications, you would implement that same `db/seeds.rb` logic like so:
+
+```
+5.times do |i|
+  Product.find_or_create_by(name: "Product ##{i}") do |product|
+    # this only happens if on a `create`.
+    production.description = "A product."
+  end
+end
+```
+
+## Why?
+We do this so Bullet Train applications can re-use the logic in `db/seeds.rb` for three purposes:
+
+1. Set up new local development environments.
+2. Ensure the test suite has the same configuration for features whose configuration is backed by Active Record (e.g. [subscriptions](/docs/subscriptions.md) and [outgoing webhooks](/docs/webhooks/outgoing.md)).
+3. Ensure any updates to the baseline configuration that have been tested both locally and in CI are the exact same updates being executed in production upon deploy.
+
+This makes `db/seeds.rb` a single source of truth for this sort of baseline data, instead of having this concern spread and sometimes duplicated across `db/seeds.rb`, `db/migrations/*`, and `test/fixtures`.
+
+## Seeds for Different Environments
+In some cases, you may have core seed data like roles that needs to exist in every environment, but you also have development data to populate in your non-production environments. Bullet Train makes this easy by supporting per-environment seed files in the `db/seeds` folder like `db/seeds/test.rb` and `db/seeds/development.rb`.
+
+Then in `db/seeds.rb`, you can load all of the shared core seed data at the beginning of `db/seeds.rb` and then load the environment-specific seeds only when you've specified one of those environments.
+
+```
+load "#{Rails.root}/db/seeds/development.rb" if Rails.env.development?
+load "#{Rails.root}/db/seeds/test.rb" if Rails.env.test?
+```
+
+## Feedback
+We're always very hesitant to stray from Rails defaults, so it must be said that our commitment to this approach isn't set in stone. It's worked very well for us in a number of applications, so we've standardized on it, but the approach is certainly open to discussion.

data/docs/super-scaffolding/delegated-types.md

@@ -0,0 +1,328 @@
+# Super Scaffolding with Delegated Types
+
+## Introduction
+In this guide, we’ll cover how to use Super Scaffolding to build views and controllers around models leveraging delegated types. As a prerequisite, you should read the [native Rails documentation for delegated types](https://edgeapi.rubyonrails.org/classes/ActiveRecord/DelegatedType.html). The examples in that documentation only deal with using delegated types at the Active Record level, but they lay a foundation that we won’t be repeating here.
+
+## Terminology
+For the purposes of our discussion here, and building on the Rails example, we’ll call their `Entry` model the **“Abstract Parent”** and the `Message` and `Comment` models the **“Concrete Children”**.
+
+## One of Multiple Approaches
+It’s worth noting there are at least two different approaches you can take for implementing views and controllers around models using delegated types:
+
+1. Centralize views and controllers around the Abstract Parent (e.g. `Account::EntriesController`).
+2. Create separate views and controllers for each Concrete Child (e.g. `Account::MessagesController`, `Account::CommentsController`, etc.)
+
+**In this guide, we’ll be covering the first approach.** This might not seem like an obvious choice for the `Message` and `Comment` examples we’re drawing on from the Rails documentation (it's not), but it is a very natural fit for other common use cases like:
+
+ - “I’d like to add a field to this form and there are many kinds of fields.”
+ - “I’d like to add a section to this page and there are many kinds of sections.”
+
+It’s not to say you can’t do it the other way described above, but this approach has specific benefits:
+
+1. It’s a lot less code. We only have to use Super Scaffolding for the Abstract Parent. It's the only model with views and controllers generated. For the Concrete Children, the only files required are the models, tests, and migrations generated by `rails g model` and some locale Yaml files for each Concrete Child.
+2. Controller permissions can be enforced the same way they always are, by checking the relationship between the Abstract Parent (e.g. `Entry`) and `Team`. All permissions are defined in `app/models/ability.rb` for `Entry` only, instead of each Concrete Child.
+
+## Steps
+
+### 1. Generate Rails Models
+
+Drawing on the [canonical Rails example](https://edgeapi.rubyonrails.org/classes/ActiveRecord/DelegatedType.html), we begin by using Rails' native model generators:
+
+```
+rails g model Entry team:references entryable:references{polymorphic}:index
+rails g model Message subject:string
+rails g model Comment content:text
+```
+
+Note that in this specific approach we don't need a `team:references` on `Message` and `Comment`. That's because in this approach there are no controllers specific to `Message` and `Comment`, so all permissions are being inforced by checking the ownership of `Entry`. (That's not to say it would be wrong to add them for other reasons, we're just keeping it as simple as possible here.)
+
+### 2. Super Scaffolding for `Entry`
+
+```
+bin/super-scaffold crud Entry Team entryable_type:buttons
+```
+
+We use `entryable_type:buttons` because we're going to allow people to choose which type of `Entry` they're creating with a list of buttons. This isn't the only option available to us, but it's the easiest to implement for now.
+
+### 3. Defining Button Options
+
+Super Scaffolding will have generated some initial button options for us already in `config/locales/en/entries.en.yml`. We'll want to update the attribute `name`, field `label` (which is shown on the form) and the available options to reflect the available Concrete Children like so:
+
+```
+fields: &fields
+  entryable_type:
+    name: &entryable_type Entry Type
+    label: What type of entry would you like to create?
+    heading: *entryable_type
+    options:
+      "Message": Message
+      "Comment": Comment
+```
+
+<small>TODO Insert a live example of what `shared/fields/buttons` looks like with these options passed in.</small>
+
+### 4. Add Our First Step to `new.html.erb`
+
+By default, `app/views/account/entries/new.html.erb` has this reference to the shared `_form.html.erb`:
+
+```
+<%= render 'form', entry: @entry %>
+```
+
+However, in this workflow we actually need two steps:
+
+1. Ask the user what type of `Entry` they're creating.
+2. Show the user the `Entry` form with the appropriate fields for the type of entry they're creating.
+
+The first of these two forms is actually not shared between `new.html.erb` and `edit.html.erb`, so we'll copy the contents of `_form.html.erb` into `new.html.erb` as a starting point, like so:
+
+```
+<% if @entry.entryable_type %>
+  <%= render 'form', entry: @entry %>
+<% else %>
+  <%= form_with model: @entry, url: [:new, :account, @team, :entry], method: :get, local: true, class: 'form' do |form| %>
+    <%= render 'account/shared/forms/errors', form: form %>
+    <% with_field_settings form: form do %>
+      <%= render 'shared/fields/buttons', method: :entryable_type, html_options: {autofocus: true} %>
+    <% end %>
+    <div class="buttons">
+      <%= form.submit t('.buttons.next'), class: "button" %>
+      <%= link_to t('global.buttons.cancel'), [:account, @team, :entries], class: "button-secondary" %>
+    </div>
+  <% end %>
+<% end %>
+```
+
+Here's a summary of the updates required when copying `_form.html.erb` into `new.html.erb`:
+
+1. Add the `if @entry.entryable_type` branch logic, maintaining the existing reference to `_form.html.erb`.
+2. Add `@` to the `entry` references throughout. `@entry` is an instance variable in this view, not passed in as a local.
+3. Update the form submission `url` and `method` as seen above.
+4. Remove the Super Scaffolding hooks. Any additional fields that we add to `Entry` would be on the actual `_form.html.erb`, not this step.
+5. Simplify button logic because the form is always for a new object.
+
+### 5. Update Locales
+
+We need to add a locale entry for the "Next Step" button in `config/locales/en/entries.en.yml`. This goes under the `buttons: &buttons` entry that is already present, like so:
+
+```
+buttons: &buttons
+  next: Next Step
+```
+
+Also, sadly, the original locale file wasn't expecting any buttons in `new.html.erb` directly, so we need to include buttons on the `new` page in the same file, below `form: *form`, like so:
+
+```
+new:
+  # ...
+  form: *form
+  buttons: *buttons
+```
+
+### 6. Add Appropriate Validations in `entry.rb`
+
+In `app/models/entry.rb`, we want to replace the default validation of `entryable_type` like so:
+
+```
+ENTRYABLE_TYPES = I18n.t('entries.fields.entryable_type.options').keys.map(&:to_s)
+
+validates :entryable_type, inclusion: {
+  in: ENTRYABLE_TYPES, allow_blank: false, message: I18n.t('errors.messages.empty')
+}
+```
+
+This makes the locale file, where we define the options to present to the user, the single source of truth for what the valid options are.
+
+<small>TODO We should look into whether reflecting on the definition of the delegated types is possible.</small>
+
+Also, to make it easy to check the state of this validation, we'll add `entryable_type_valid?` as well:
+
+```
+def entryable_type_valid?
+  ENTRYABLE_TYPES.include?(entryable_type)
+end
+```
+
+I don't like this method. If you can think of a way to get rid of it or write it better, please let us know!
+
+### 7. Accept Nested Attributes in `entry.rb` and `entries_controller.rb`
+
+In preparation for the second step, we need to configure `Entry` to accept [nested attributes](https://edgeapi.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html). We do this in three parts:
+
+In `app/models/entry.rb`, like so:
+
+```
+accepts_nested_attributes_for :entryable
+```
+
+Also in `app/models/entry.rb`, [Rails will be expecting us](https://stackoverflow.com/questions/45295202/cannot-build-nested-polymorphic-associations-are-you-trying-to-build-a-polymor) to define the following method on the model:
+
+```
+def build_entryable(params = {})
+  raise 'invalid entryable type' unless entryable_type_valid?
+  self.entryable = entryable_type.constantize.new(params)
+end
+```
+
+Finally, in the [strong parameters](https://edgeguides.rubyonrails.org/action_controller_overview.html#strong-parameters) of `app/controllers/account/entries_controller.rb`, _directly below_ this line:
+
+```
+# 🚅 super scaffolding will insert new arrays above this line.
+```
+
+And still within the `permit` parameters, add:
+
+```
+entryable_attributes: [
+  :id,
+
+  # Message attributes:
+  :subject,
+
+  # Comment attributes:
+  :content,
+],
+```
+
+<small>(Eagle-eyed developers will note an edge case here where you would need to take additional steps if you had two Concrete Children classes that shared the same attribute name and you only wanted submitting form data for that attribute to be permissible for one of the classes. That situation should be exceedingly rare, and you can always write a little additional code here to deal with it.)</small>
+
+### 8. Populate `@entry.entryable` in `entries_controller.rb`
+
+Before we can present the second step to users, we need to react to the user's input from the first step and initialize either a `Message` or `Comment` object and associate `@entry` with it. We do this in the `new` action of `app/controllers/account/entries_controller.rb` and we can also use the `build_entryable` method we created earlier for this purpose, like so:
+
+```
+def new
+  if @entry.entryable_type_valid?
+    @entry.build_entryable
+  elsif params[:commit]
+    @entry.valid?
+  end
+end
+```
+
+### 9. Add the Concrete Children Fields to the Second Step in `_form.html.erb`
+
+Since we're now prompting for the entry type on the first step, we can remove the following from the second step in `app/views/account/entries/_form.html.erb`:
+
+```
+<%= render 'shared/fields/buttons', method: :entryable_type, html_options: {autofocus: true} %>
+```
+
+But we need to keep track of which entry type they selected, so we replace it with:
+
+```
+<%= form.hidden_field :entryable_type %>
+```
+
+Also, below that (and below the Super Scaffolding hook), we want to add the `Message` and `Comment` fields as [nested forms](https://guides.rubyonrails.org/form_helpers.html#nested-forms) like so:
+
+```
+<%= form.fields_for :entryable, entry.entryable do |entryable_form| %>
+  <%= entryable_form.hidden_field :id %>
+  <% with_field_settings form: entryable_form do %>
+    <% case entryable_form.object %>
+    <% when Message %>
+      <%= render 'shared/fields/text_field', method: :subject %>
+    <% when Comment %>
+      <%= render 'shared/fields/trix_editor', method: :content %>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
+We add this _below_ the Super Scaffolding hook because we want any additional fields being added to `Entry` directly to appear in the form _above_ the nested form fields.
+
+### 10. Add Attributes of the Concrete Children to `show.html.erb`
+
+Under the Super Scaffolding hook in `app/views/account/entries/show.html.erb`, add the following:
+
+```
+<% with_attribute_settings object: @entry.entryable, strategy: :label do %>
+  <% case @entry.entryable %>
+  <% when Message %>
+    <%= render 'shared/attributes/text', attribute: :subject %>
+  <% when Comment %>
+    <%= render 'shared/attributes/html', attribute: :content %>
+  <% end %>
+<% end %>
+```
+
+This will ensure the various different attributes of the Concrete Children are properly presented. However, the `label` strategy for these attribute partials depend on the locales for the individual Concrete Children being defined, so we need to create those files now, as well:
+
+`config/locales/en/messages.en.yml`:
+```
+en:
+  messages: &messages
+    fields:
+      subject:
+        _: &subject Subject
+        label: *subject
+        heading: *subject
+  account:
+    messages: *messages
+  activerecord:
+    attributes:
+      message:
+        subject: *subject
+```
+
+`config/locales/en/comments.en.yml`:
+```
+en:
+  comments: &comments
+    fields:
+      content:
+        _: &content Content
+        label: *content
+        heading: *content
+  account:
+    comments: *comments
+  activerecord:
+    attributes:
+      comment:
+        content: *content
+```
+
+### 11. Actually Use Delegated Types?
+
+So everything should now be working as expected, and here's the crazy thing: **We haven't even used the delegated types feature yet.** That was part of the beauty of delegated types when it was released in Rails 6.1: It was really just a formalization of an approach that folks had already been doing in Rails for years.
+
+<center>
+<br>
+<blockquote class="twitter-tweet"><p lang="en" dir="ltr">Really loving the PR for Rails 6.1&#39;s Delegated Types. From the application developer level, very little of it feels &quot;new&quot;. Instead, the experience reads very similar to what many of us were already doing with the existing tools, but even smoother! <a href="https://t.co/6UkxXNCvaa">https://t.co/6UkxXNCvaa</a></p>&mdash; Andrew Culver (@andrewculver) <a href="https://twitter.com/andrewculver/status/1338189146213543951?ref_src=twsrc%5Etfw">December 13, 2020</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
+<br>
+</center>
+
+To now incorporate delegated types as put forward in the original documentation, we want to remove this line in `app/models/entry.rb`:
+
+```
+belongs_to :entryable, polymorphic: true
+```
+
+And replace it with:
+
+```
+delegated_type :entryable, types: %w[ Message Comment ]
+```
+
+We also want to follow the other steps seen there, such as defining an `Entryable` concern in `app/models/concerns/entryable.rb`, like so:
+
+```
+module Entryable
+  extend ActiveSupport::Concern
+
+  included do
+    has_one :entry, as: :entryable, touch: true
+  end
+end
+```
+
+And including the `Entryable` concern in both `app/models/message.rb` and `app/models/comment.rb` like so:
+
+```
+include Entryable
+```
+
+## Conclusion
+
+That's it! You're done! As mentioned at the beginning, this is only one of the ways to approach building views and controllers around your models with delegated types, but it's a common one, and for the situations where it is the right fit, it requires a lot less code and is a lot more [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) than scaffolding views and controllers around each individual delegated type class.