bullet_train 1.0.36 → 1.0.39

data/docs/super-scaffolding.md

@@ -0,0 +1,246 @@
+# Code Generation with Super Scaffolding
+
+Super Scaffolding is Bullet Train’s code generation engine. Its goal is to allow you to produce production-ready CRUD interfaces for your models while barely lifting a finger, and it handles a lot of other grunt-work as well.
+
+Here’s a list of what Super Scaffolding takes care of for you each time you add a model to your application:
+
+ - It generates a basic CRUD controller and accompanying views.
+ - It generates a Yaml locale file for the views’ translatable strings.
+ - It generates type-specific form fields for each attribute of the model.
+ - It generates an API controller and an accompanying entry in the application’s API docs.
+ - It generates a serializer that’s used by the API and when dispatching webhooks.
+ - It adds the appropriate permissions for multitenancy in CanCanCan’s configuration file.
+ - It adds the model’s table view to the show view of its parent.
+ - It adds the model to the application’s navigation (if applicable).
+ - It generates breadcrumbs for use in the application’s layout.
+ - It generates the appropriate routes for the CRUD controllers and API endpoints.
+
+When adding just one model, Super Scaffolding generates ~30 different files on your behalf.
+
+## Living Templates
+
+Bullet Train's Super Scaffolding engine is a unique approach to code generation, based on template files that are functional code instead of obscure DSLs that are difficult to customize and maintain. Super Scaffolding automates the most repetitive and mundane aspects of building out your application's basic structure. Furthermore, it does this without leaning on the magic of libraries that force too high a level of abstraction. Instead, it generates standard Rails code that is both ready for prime time, but is also easy to customize and modify.
+
+## Prerequisites
+
+Before getting started with Super Scaffolding, we recommend reading about [the philosophy of domain modeling in Bullet Train](/docs/topics/domain-modeling.md).
+
+## Usage
+
+The Super Scaffolding shell script provides its own documentation. If you're curious about specific scaffolders or parameters, you can run the following in your shell:
+
+```
+bin/super-scaffold
+```
+
+## Examples
+
+### 1. Basic CRUD Scaffolding with `crud`
+
+Let's implement the following feature:
+
+> An organization has many projects.
+
+First, generate the model with the standard Rails generator:
+
+```
+rails g model Project team:references name:string
+```
+
+In the above example, `team` represents the model that a `Project` primarily belongs to.
+
+⚠️ Don't run migrations right away. It would be fine in this case, but sometimes the subsequent Super Scaffolding step actually updates the migration as part of its magic.
+
+Next, run the `crud` scaffolder:
+
+```
+bin/super-scaffold crud Project Team name:text_field
+rake db:migrate
+```
+
+In the above example, `text_field` was selected from [the list of available field partials](/docs/field-partials.md). We'll show examples with `trix_editor` and `super_select` later.
+
+### 2. Nested CRUD Scaffolding with `crud`
+
+Building on that example, let's implement the following feature:
+
+```
+A project has many goals.
+```
+
+Again, we'll generate the model using the standard Rails generator:
+
+```
+rails g model Goal project:references description:string
+```
+
+You can see in the example above that there is no direct reference to team, but to `project` instead, since that's where a `Goal` belongs.
+
+Now, run the `crud` scaffolder:
+
+```
+bin/super-scaffold crud Goal Project,Team description:text_field
+rake db:migrate
+```
+
+You can see in the example above how we've specified `Project,Team`, because we want to specify the entire chain of ownership back to the `Team`. This allows Super Scaffolding to automatically generate the required permissions.
+
+### 3. Adding New Fields with `crud-field`
+
+One of Bullet Train's most valuable features is the ability to add new fields to existing scaffolded models. When you add new fields with the `crud-field` scaffolder, you don't have to remember to add that same attribute to table views, show views, translation files, API endpoints, serializers, tests, documentation, etc.
+
+Building on the earlier example, consider the following new requirement:
+
+> In addition to a name, a project can have a description.
+
+First, use the standard Rails migration generator to add the attribute in the database:
+
+```
+rails g migration add_description_to_projects description:text
+```
+
+Then, use the `crud-field` scaffolder to add it throughout the application:
+
+```
+bin/super-scaffold crud-field Project description:trix_editor
+rake db:migrate
+```
+
+As you can see, when we're using `crud-field`, we don't need to supply the chain of ownership back to `Team`.
+
+### 4. Adding Option Fields with Fixed, Translatable Options
+
+Continuing with the earlier example, let's address the following new requirement:
+
+> Users can specify the current project status.
+
+We have multiple [field partials](/docs/field-partials.md) that we could use for this purpose, including `buttons`, `options`, or `super_select`.
+
+In this example, let's add a status attribute and present it as buttons:
+
+```
+rails g migration add_status_to_projects status:string
+bin/super-scaffold crud-field Project status:buttons
+```
+
+By default, Super Scaffolding configures the buttons as "One", "Two", and "Three", but in this example you can edit those options in the `fields` section of `config/locales/en/projects.en.yml`. For example, you could specify the following options:
+
+```
+planned: Planned
+started: Started
+completed: Completed
+```
+
+If you want new `Project` models to be set to `planned` by default, you can add that to the migration file that was generated before running it, like so:
+
+```
+add_column :projects, :status, :string, default: "planned"
+```
+
+### 5. Scaffolding `belongs_to` Associations, Team Member Assignments
+
+Continuing with the example, consider the following requirement:
+
+> A project has one specific project lead.
+
+Although you might think this calls for a reference to `User`, we've learned the hard way that it's typically much better to assign resources on a `Team` to a `Membership` on the team instead. For one, this allows you to assign resources to new team members that haven't accepted their invitation yet (and don't necessarily have a `User` record yet.)
+
+We can accomplish this like so:
+
+```
+rails g migration add_lead_to_projects lead:references
+```
+
+Then, to add the field, we specify the following:
+
+```
+bin/super-scaffold crud-field Project lead_id:super_select[class_name=Membership]
+rake db:migrate
+```
+
+There are two important things to point out here:
+
+1. When we use `rails g model` or `rails g migration`, we specify the `references` column name as `lead`, but when we're specifying the _field_ we want to scaffold, we specify it as `lead_id`, because that's the name of the attribute on the form, in strong parameters, etc.
+2. We have to specify the model name with the `class_name` option so that Super Scaffolding can fully work it's magic. We can't reflect on the association, because at this point the association isn't properly defined yet. With this information, Super Scaffolding can handle that step for you.
+
+Finally, Super Scaffolding will prompt you to edit `app/models/project.rb` and implement the required logic in the `valid_leads` method. This is a template method that will be used to both populate the select field on the `Project` form, but also enforce some important security concerns in this multi-tenant system. In this case, you can define it as:
+
+```
+def valid_leads
+  team.memberships.current_and_invited
+end
+```
+
+(The `current_and_invited` scope just filters out people that have already been removed from the team.)
+
+### 6. Scaffolding Has-Many-Through Associations with `join-model`
+
+Finally, working from the same example, imagine the following requirement:
+
+> A project can be labeled with one or more project-specific tags.
+
+We can accomplish this with a new model, a new join model, and a `super_select` field.
+
+First, let's create the tag model:
+
+```
+rails g model Projects::Tag team:references name:string
+bin/super-scaffold crud Projects::Tag Team name:text_field
+```
+
+Note that project tags are specifically defined at the `Team` level. The same tag can be applied to multiple `Project` models.
+
+Now, let's create a join model for the has-many-through association:
+
+```
+rails g model Projects::AppliedTag project:references tag:references
+```
+
+We're not going to scaffold this model with the typical `crud` scaffolder, but some preparation is needed before we can use it with the `crud-field` scaffolder, so we need to do the following:
+
+```
+bin/super-scaffold join-model Projects::AppliedTag project_id[class_name=Project] tag_id[class_name=Projects::Tag]
+```
+
+All we're doing here is specifying the name of the join model, and the two attributes and class names of the models it joins. Note again that we specify the `_id` suffix on both of the attributes.
+
+Now that the join model has been prepared, we can use the `crud-field` scaffolder to create the multi-select field:
+
+```
+bin/super-scaffold crud-field Project tag_ids:super_select[class_name=Projects::Tag]
+rake db:migrate
+```
+
+Just note that the suffix of the field is `_ids` plural, and this is an attribute provided by Rails to interact with the `has_many :tags, through: :applied_tags` association.
+
+The `crud-field` step will ask you to define the logic for the `valid_tags` method in `app/models/project.rb`. You can define it like so:
+
+```
+def valid_tags
+  team.projects_tags
+end
+```
+
+Honestly, it's crazy that we got to the point where we can handle this particular use case automatically. It seems simple, but there is so much going on to make this feature work.
+
+## Additional Notes
+
+### `TangibleThing` and `CreativeConcept`
+
+In order to properly facilitate this type of code generation, Bullet Train includes two models in the `Scaffolding` namespace:
+
+1. `Scaffolding::AbsolutelyAbstract::CreativeConcept`
+2. `Scaffolding::CompletelyConcrete::TangibleThing`
+
+Their peculiar naming is what's required to ensure that their corresponding view and controller templates can serve as the basis for any combination of different model naming or [namespacing](https://blog.bullettrain.co/rails-model-namespacing/) that you may need to employ in your own application.
+
+### Hiding Scaffolding Templates
+
+You won't want your end users seeing the Super Scaffolding templates in your environment, so you can disable their presentation by setting `HIDE_THINGS` in your environment. For example, you can add the following to `config/application.yml`:
+
+```
+HIDE_THINGS: true
+```
+
+## Advanced Examples
+ - [Super Scaffolding with Delegated Types](/docs/super-scaffolding/delegated-types.md)

data/docs/teams.md

@@ -0,0 +1,8 @@
+# Teams
+
+Please read the article providing [an overview of organizational teams in Bullet Train](https://blog.bullettrain.co/teams-should-be-an-mvp-feature/). This article doesn't just explain how `Team`, `Membership`, `Invitation` and `Role` relate and function in Bullet Train, but it also explains how to properly think about resource ownership even in complex scenarios. Furthermore, it touches on ways in which Bullet Train's organizational structure has been successfully extended in more complicated systems.
+
+Rather than simply duplicating the content of that blog article here, we'll focus on keeping that article up-to-date so it can benefit not only incoming Bullet Train developers, but also the broader developer ecosystem.
+
+## Related Topics
+ - [Permissions](/docs/permissions.md)

data/docs/testing.md

@@ -0,0 +1,34 @@
+# Automated Test Suite
+All of Bullet Train’s core functionality is verifiable using the provided test suite. This foundation of headless browser integration tests took a ton of time to write, but they can give you the confidence and peace of mind that you haven't broken any key functionality in your application before a deploy.
+
+You can run the test suite with the following command in your shell:
+
+```
+rails test:system
+```
+
+## Fixing Broken Tests
+
+### 1. Run Chrome in Non-Headless Mode
+
+When debugging tests, it's important to be able to see what Capybara is seeing. You can disable the headless browser mode by prefixing `rails test` like so:
+
+```
+MAGIC_TEST=1 rails test
+```
+
+When you run the test suite with `MAGIC_TEST` set in your environment like this, the browser will appear on your screen after the first Capybara test starts. (This may not be the first test that runs.) Be careful not to interact with the window when it appears, as sometimes your interactions can cause the test to fail needlessly.
+
+### 2. Insert `binding.pry`.
+
+Open the failing test file and insert `binding.pry` right before the action or assertion that is causing the test to fail. After doing that, when you run the test, it will actually stop and open a debugging console while the browser is still open to the appropriate page where the test is beginning to fail. You can use this console and the open browser to try and figure out why the test is failing. When you're done, hit <kbd>Control</kbd> + <kbd>D</kbd> to exit the debugger and continue letting the test run.
+
+## Super Scaffolding Test Suite
+In addition to the standard application test suite, there is a separate test available that doesn't run by default that you can run in CI to ensure you haven't accidentally broken the full function of Super Scaffolding in your application. Before the test runs, there is a setup script that runs a number of Super Scaffolding commands, so you should never run the test in anything but a clean working copy that can be reset when you're done.
+
+You can run the setup script and test like so:
+
+```
+test/bin/setup-super-scaffolding-system-test
+rails test test/system/super_scaffolding_test.rb
+```

data/docs/themes.md

@@ -0,0 +1,101 @@
+# Themes
+
+Bullet Train has a theme subsystem designed to allow you the flexibility to either extend or completely replace the stock “Light” and “Clean” UI templates.
+
+## Inheritance Structure
+
+To reduce duplication of code across themes, Bullet Train implements an inheritance structure. For example, the official Bullet Train themes are structured hierarchically like so:
+
+- “Base”
+  - “Bootstrap” (in the future)
+    - “Clean” (in the future)
+  - “Tailwind CSS”
+    - “Light”
+
+Any component partials that can be shared are pushed up the inheritance structure. For example, [Bullet Train's library of field partials](/docs/field-partials.md) provide a good example of this, illustrating the power of the approach we’ve taken here:
+
+ - The most general field styling varies substantially between Tailwind CSS and Bootstrap, so a `_field.html.erb` component partial exists in both the foundational “Tailwind CSS” and “Bootstrap” themes, but also a further customized version exists in themes like “Light”.
+ - However, many concrete field types like `_text_field.html.erb` and `_phone_field.html.erb` leverage `_field.html.erb`, and they themselves are completely framework agnostic as a result. These partials can live in the shared “Base” theme.
+
+At run-time, this means:
+
+- When rendering `_text_field.html.erb`, it renders from “Base”.
+- However, when `_text_field.html.erb` references `_field.html.erb`, that renders from “Light”.
+- If you extend “Light” and override `_field.html.erb`, rendering `_text_field.html.erb` will now use your theme’s `_field.html.erb`.
+
+## Theme Component Usage
+
+To use a theme component, simply include it from "within" `shared` like so:
+
+```
+<%= render 'shared/fields/text_field', method: :text_field_value %>
+```
+
+We say "within" because while a `shared` view partial directory does exist, the referenced `shared/fields/_text_field.html.erb` doesn't actually exist within it. Instead, the theme engine picks up on `shared` and also works its way through the theme directories to find the appropriate match.
+
+### Dealing with Indirection
+
+This small piece of indirection buys us an incredible amount of power in building and extending themes, but as with any indirection, it could potentially come at the cost of developer experience. That's why Bullet Train includes additional tools for smoothing over this experience. Be sure to read the section on [dealing with indirection].
+
+
+## Theme Configuration
+
+You can specify the theme you’d like to use and its inheritance structure in `app/helpers/theme_helper.rb`. The code there is well commented to help you.
+
+## Theme Structure
+
+Themes are represented in a few places. Taking “Light” as an example, we have:
+
+- A directory of theme-specific component partials in `app/views/themes/light`, including a layout ERB template.
+- A theme-specific stylesheet in `app/javascript/stylesheets/light/application.scss`.
+- A theme-specific pack in `app/javascript/packs/light.js`. You’ll see there that the actual JavaScript dependencies and code are shared across all themes. The whole purpose of this theme-specific pack is to serve up the theme-specific stylesheet.
+- Theme-specific logos and images in `app/javascript/images/light`.
+
+## Adding a New Theme
+
+To extend the “Light” theme in a new theme called “Tokyo”, we would:
+
+1. Copy `app/javascript/packs/light.js` to `app/javascript/packs/tokyo.js` and update references to `light` therein to `tokyo`.
+2. Copy `app/views/themes/light/layouts` to `app/views/themes/tokyo/layouts` and update references to `light` in the contained files to `tokyo`. It's possible this is too much duplication, but in practice most people want to customize these two layouts in their custom themes.
+3. Create a new file at `app/javascript/stylesheets/tokyo/application.scss`. To start just add `@import "../light/application";` at the top, which represents the fact that “Tokyo” extends “Light”. Any custom styles can be added below that.
+4. Add `"tokyo"` as the first item in the `THEME_DIRECTORY_ORDER` array in `app/helpers/theme_helper.rb`.
+
+You should be good to go! We'll try to add a generator for this in the future.
+
+## Additional Guidance and Principles
+
+### Should you extend or replace?
+
+For most development projects, the likely best path for customizing the UI is to extend “Light” or another complete Bullet Train theme. It’s difficult to convey how many hours have gone into making the Bullet Train themes complete and coherent from end to end. Every type of field partial, all the third-party libraries, all the responsiveness scenarios, etc. It’s taken many hours and many invoices.
+
+Extending an existing theme is like retaining an option on shipping. By extending a theme that is already complete, you allow yourself to say “enough is enough” at a certain point and just living with some inherited defaults in exchange for shipping your product sooner. You can always do more UI work later, but it doesn’t look unpolished now!
+
+On the other hand, if you decide to try to build a theme from the ground up, you risk getting to that same point, but not being able to stop because there are bits around the edges that don’t feel polished and cohesive.
+
+### Don’t reference theme component partials directly, even within the same theme!
+
+#### ❌ Don’t do this, even in theme partials:
+
+```
+<%= render "themes/light/box" do |p| %>
+  ...
+<% end %>
+```
+
+#### ✅ Instead, always do this:
+
+```
+<%= render "shared/box" do |p| %>
+  ...
+<% end %>
+```
+
+This allows the theme engine to resolve which theme in the inheritance chain to include the `box` partial from. For example:
+
+ - It might come from the “Light” theme today, but if you switch to the “Bold” theme later, it’ll can start pulling it from there.
+ - If you start extending “Light”, you can override its `box` implementation and your application will pick up the new customized version from your theme automatically.
+ - If (hypothetically) `box` became generalized and move into the parent “Tailwind CSS” theme, your application would pick it up from the appropriate place.
+
+### Let your designer name their theme.
+
+You're going to have to call your theme something and there are practical reasons to not call it something generic. If you're pursuing a heavily customized design, consider allowing the designer or designers who are creating the look-and-feel of your application to name their own masterpiece. Giving it a distinct name will really help differentiate things when you're ready to start introducing additional facets to your application or a totally new look-and-feel down the road.

data/docs/tunneling.md

@@ -0,0 +1,29 @@
+# HTTP Tunneling with ngrok
+
+Before your application can take advantage of features that depend on incoming webhooks, you'll need to setup an HTTP tunnel using a service like [ngrok](https://ngrok.com).
+
+## Use a Paid Plan
+
+You should specifically sign up for a paid account. Although ngrok offers a free plan, their $5/month paid plan will allow you to reserve a custom subdomain for reuse each time you spin up your tunnel. This is a critical productivity improvement, because in practice you'll end up configuring your tunnel URL in a bunch of different places like `config/application.yml` but also in external systems like when you [configure payment providers to deliver webhooks to you](docs/billing/stripe.md).
+
+## Usage
+
+Once you have ngrok installed, you can start your tunnel like so, replacing `your-subdomain` with whatever subdomain you reserved in your ngrok account:
+
+```
+ngrok http 3000 -subdomain=your-subdomain
+```
+
+## Updating Your Configuration
+
+Before your Rails application will accept connections on your tunnel hostname, you need to update `config/application.yml` with:
+
+```
+BASE_URL: https://your-subdomain.ngrok.io
+```
+
+You'll also need to restart your Rails server:
+
+```
+rails restart
+```

data/docs/upgrades.md

@@ -0,0 +1,69 @@
+# Upgrading Your Bullet Train Application
+
+## Upgrading the Framework
+
+The vast majority of Bullet Train's functionality is distributed via Ruby gems, so you can pull the latest updates by running `bundle update`.
+
+## Pulling Updates from the Starter Repository
+
+There are times when you'll want to pull updates from the starter repository into your local application. Thankfully, `git merge` provides us with the perfect tool for just that. You can simply merge the upstream Bullet Train repository into your local repository. If you haven’t tinkered with the starter repository defaults at all, then this should happen with no meaningful conflicts at all. Simply run your automated tests (including the comprehensive integration tests Bullet Train ships with) to make sure everything is still working as it was before.
+
+If you _have_ modified some starter repository defaults _and_ we also happened to update that same logic upstream, then pulling the most recent version of the starter repository should cause a merge conflict in Git. This is actually great, because Git will then give you the opportunity to compare our upstream changes with your local customizations and allow you to resolve them in a way that makes sense for your application.
+
+### 1. Make sure you're working with a clean local copy.
+
+```
+git status
+```
+
+If you've got uncommitted or untracked files, you can clean them up with the following.
+
+```
+# ⚠️ This will destroy any uncommitted or untracked changes and files you have locally.
+git checkout .
+git clean -d -f
+```
+
+### 2. Fetch the latest and greatest from the Bullet Train repository.
+
+```
+git fetch starter-repo
+````
+
+### 3. Create a new "upgrade" branch off of your main branch.
+
+```
+git checkout main
+git checkout -b updating-starter-repo
+```
+
+### 4. Merge in the newest stuff from Bullet Train and resolve any merge conflicts.
+
+```
+git merge starter-repo/main
+```
+
+It's quite possible you'll get some merge conflicts at this point. No big deal! Just go through and resolve them like you would if you were integrating code from another developer on your team. We tend to comment our code heavily, but if you have any questions about the code you're trying to understand, let us know on Slack!
+
+```
+git diff
+git add -A
+git commit -m "Upgrading Bullet Train."
+```
+
+### 5. Run Tests.
+
+```
+rails test
+```
+
+### 6. Merge into `main` and delete the branch.
+
+```
+git checkout main
+git merge updating-starter-repo
+git push origin main
+git branch -d updating-starter-repo
+```
+
+Alternatively, if you're using GitHub, you can push the `updating-starter-repo` branch up and create a PR from it and let your CI integration do it's thing and then merge in the PR and delete the branch there. (That's what we typically do.)

data/docs/webhooks/incoming.md

@@ -0,0 +1,3 @@
+# Incoming Webhooks
+
+> TODO This section needs to be written and should probably delegate a lot of details to the README of the [Bullet Train Incoming Webhooks repository](https://github.com/bullet-train-co/bullet_train-incoming_webhooks).

data/docs/webhooks/outgoing.md

@@ -0,0 +1,3 @@
+# Outgoing Webhooks
+
+> TODO This section needs to be written and should probably delegate a lot of details to the README of the [Bullet Train Outgoing Webhooks repository](https://github.com/bullet-train-co/bullet_train-outgoing_webhooks).

data/lib/bullet_train/version.rb

@@ -1,3 +1,3 @@
 module BulletTrain
-  VERSION = "1.0.36"
+  VERSION = "1.0.39"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train
 version: !ruby/object:Gem::Version
-  version: 1.0.36
+  version: 1.0.39
 platform: ruby
 authors:
 - Andrew Culver
@@ -535,6 +535,35 @@ files:
 - db/migrate/20210816072508_add_locale_to_teams.rb
 - db/migrate/20211020200855_add_doorkeeper_application_to_memberships.rb
 - db/migrate/20211027002944_add_doorkeeper_application_to_users.rb
+- docs/api.md
+- docs/authentication.md
+- docs/billing/stripe.md
+- docs/desktop.md
+- docs/field-partials.md
+- docs/field-partials/buttons.md
+- docs/field-partials/super-select.md
+- docs/font-awesome-pro.md
+- docs/getting-started.md
+- docs/heroku.md
+- docs/i18n.md
+- docs/index.md
+- docs/indirection.md
+- docs/modeling.md
+- docs/namespacing.md
+- docs/oauth.md
+- docs/onboarding.md
+- docs/overriding.md
+- docs/permissions.md
+- docs/seeds.md
+- docs/super-scaffolding.md
+- docs/super-scaffolding/delegated-types.md
+- docs/teams.md
+- docs/testing.md
+- docs/themes.md
+- docs/tunneling.md
+- docs/upgrades.md
+- docs/webhooks/incoming.md
+- docs/webhooks/outgoing.md
 - lib/bullet_train.rb
 - lib/bullet_train/engine.rb
 - lib/bullet_train/resolver.rb