bullet_train 1.0.42 → 1.0.45

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 438ec7c1fcc8aa67605106070f6aef746efa3b2cbdf007821f6f8067cf42484a
-  data.tar.gz: e81d6d7fe358d9faa19e546c61cf40ad51328e8bc817ad5701aac8fa1c59a79d
+  metadata.gz: 041e2b16ba7fe195c4622eca9f52ba3f2ece36e2ca4990e81091dcd7dce77f67
+  data.tar.gz: 4343cfb1d33be84c52dd412e335d15928ad13afb9d8a95eddbc41b751452c335
 SHA512:
-  metadata.gz: 25a0b0dbedef4259ca1b8f1d4429b441f6c2a2fd47e71128110b2580e04800950b65c68647e63caa7a0d570191bef3e8f04a97e32337dac12cac293ee7a26f7b
-  data.tar.gz: ac36a9a1179fec2ff1e1084279f2453aab59d64faf5cb6a21113f5a2dacc9c73945e3719167cd5ea8aa4534bdff804dd6f4c81bec8ae679e31a2dd752fabd870
+  metadata.gz: fa1d5423f1a3b3ab31ac94b2c75b6d298b9c0fb670f70178a2aec8e8638e9adaf07d3e8c77a2bb0e99edcc79961407058cbf0807a7972fbc50c08e008312de45
+  data.tar.gz: 7875607106a2cb2932a30a537717ac947e62121709a0389c2144be1f4c39366dbd799d5286d2548f8d2b513136992e1b526f5a66782eea4aebea0137ce2c3c9f

data/docs/indirection.md

@@ -8,6 +8,16 @@ For example, in vanilla Rails development, you introduce a type of indirection w
 
 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.
 
+## Figuring Out Class Locations
+
+Most of Bullet Train's functionality is distributed via Ruby gems, not the starter template. As a result, the power of fuzzy searching in your IDE is more limited. For example, `app/controllers/account/users_controller.rb` includes its base functionality from a concern called `Account::Users::ControllerBase`. If you try to fuzzy search for it, you'll quickly find the module isn't included in your application repository. However, you can quickly figure out which Ruby gem is providing that concern and inspect it's source by running:
+
+```
+bin/resolve Account::Users::ControllerBase --open
+```
+
+If you need to modify behavior in these framework-provided classes or modules, see the documentation for [Overriding Framework Defaults](/docs/overriding.md).
+
 ## Solving Indirection in Views
 
 ### Resolving Partial Paths with `bin/resolve`

data/docs/overriding.md

@@ -1,3 +1,21 @@
 # Overriding Framework Defaults
 
-> TODO This section needs to be written.
+Most of Bullet Train's functionality is distributed via Ruby gems, not the starter template. We provide the `bin/resolve` tool to help developers figure out which Ruby gem packages are providing which classes, modules, views, and translations, and its usage is covered in the [Dealing With Indirection](/docs/indirection.md) section of the documentation.
+
+However, sometimes you will need to do more than just understand where something is coming from and how it works in the framework. In some situations, you'll specifically want to change or override the default framework behavior. The primary workflow for doing this is much the same as the `bin/resolve` workflow for dealing with indirection in the first place, however, instead of just using `--open` to inspect the source of the framework-provided file, you can add `--eject` to have that file copied into the local repository. From there, it will act as a replacement for the framework-provided file, and you can modify the behavior as needed.
+
+## The Important Role of Active Support Concerns in Bullet Train Customization
+
+When it comes to object-oriented classes, wholesale copying framework files into your local repository just to be able to modify their behavior or extend them would quickly be untenable, as your app would no longer see upstream updates that would otherwise be incorporated into your application via `bundle update`.
+
+For this reason, common points of extension like framework-provided models and controllers actually exist as a kind of "stub" in the local repository, but include their base functionality from framework-provided concerns, like so:
+
+```
+class User < ApplicationRecord
+  include Users::Core
+
+  # ...
+end
+```
+
+In this case, for most customizations or extensions you would want to make, you don't need to eject `Users::Core` into your local repository. Instead, you can simply re-define methods from that concern in your local `User` model after the inclusion of the concern.

data/lib/bullet_train/version.rb

@@ -1,3 +1,3 @@
 module BulletTrain
-  VERSION = "1.0.42"
+  VERSION = "1.0.45"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train
 version: !ruby/object:Gem::Version
-  version: 1.0.42
+  version: 1.0.45
 platform: ruby
 authors:
 - Andrew Culver