1968-1990s: Quality through PROCESS
The early focus was on disciplined processes to catch defects: Fagan Inspections (formal peer review), Cleanroom (defect prevention), and PSP (individual measurement).
1994-1997: Quality through DESIGN COMMUNICATION
Teams needed shared visual languages. UML unified competing notations into a standard for modeling software systems.
1996-2001: Quality through PRACTICE
Extreme Programming shifted focus to lightweight practices: TDD, pair programming, and continuous integration.
2001: The Agile Manifesto
Seventeen practitioners valued “working software over comprehensive documentation,” creating tension with UML-heavy approaches. Source: Agile Manifesto
2006-2011: Quality through LIGHTWEIGHT COMMUNICATION
Bridging business and technical teams: BDD (natural language specs), C4 Model (just enough diagrams), and Specification by Example (collaborative examples).
PROCESS --------> DESIGN --------> PRACTICE --------> LIGHTWEIGHT
1968-1990s 1994-1997 1996-2001 2006-2011
| | | |
v v v v
Inspections UML XP & TDD BDD & C4
Cleanroom Sequence Pair prog. SbE
PSP diagrams CI Example Map
The term “software crisis” was coined at the first NATO Software Engineering Conference in Garmisch, Germany in 1968. The conference, attended by over fifty experts from eleven countries including Edsger Dijkstra, Tony Hoare, and Niklaus Wirth, confronted a growing problem: software projects were consistently over budget, overdue, and unreliable.
As Dijkstra later observed in his 1972 Turing Award lecture:
“The major cause of the software crisis is that the machines have become several orders of magnitude more powerful… as long as there were no machines, programming was no problem at all; when we had a few weak computers, programming became a mild problem, and now we have gigantic computers, programming has become an equally gigantic problem.”
The conference deliberately adopted the provocative term “software engineering” to suggest that software development needed the rigor of traditional engineering disciplines. This event marked the beginning of systematic approaches to software quality.
That same year, Dijkstra published his famous letter “Go To Statement Considered Harmful” in Communications of the ACM, marking the beginning of structured programming.
Definition: A programming paradigm using block-based control flow instead of arbitrary jumps via goto statements.
Dijkstra showed that any program can be written using just three constructs:
Sequence - Statements execute one after another in order:
read_input()
process_data()
write_output()
Selection - Choose different paths based on a condition:
if user_is_authenticated:
show_dashboard()
else:
show_login_form()
Iteration - Repeat statements while a condition holds:
while items_remaining:
process_next_item()
Core principle: These three control structures are sufficient to express any computable function (the structured program theorem).
Key insight: Dijkstra observed that the quality of a programmer’s code was inversely proportional to the number of gotos used. Code without gotos can more easily be proven correct.
By the end of the 20th century, nearly all programming languages had adopted structured programming constructs. Languages that originally lacked them (FORTRAN, COBOL, BASIC) added support.
Michael Fagan at IBM developed formal software inspections as a systematic method for finding defects in documents, code, and specifications.
Definition: A formal peer review process with predefined roles, entry/exit criteria, and structured meetings focused solely on defect detection.
+----------+ +----------+ +----------+ +----------+ +----------+ +----------+
| Planning |--->| Overview |--->| Prep |--->|Inspection|--->| Rework |--->| Follow-up|
+----------+ +----------+ +----------+ +----------+ +----------+ +----------+
| | | | | |
v v v v v v
Select Author Individual Team finds Author Verify
material, presents review by defects fixes fixes
assign roles context inspectors (NOT solutions) defects
Results: IBM reported that inspections located 82% of all errors. The company doubled lines of code shipped while reducing defects per thousand lines by two-thirds. Studies showed 80-90% of defects found with up to 25% resource savings.
Key principle: The inspection meeting finds defects only–solutions come later during rework.
Harlan Mills at IBM developed Cleanroom as a theory-based process for producing software with certifiable reliability levels.
Definition: A software development process emphasizing defect prevention over defect removal, using formal methods and statistical quality control.
+---------------+ +---------------+ +---------------+
| SPECIFICATION | ---> | DEVELOPMENT | ---> | CERTIFICATION |
+---------------+ +---------------+ +---------------+
DEFECT PREVENTION > DEFECT REMOVAL
Traditional Cleanroom
---------- ---------
Code -> Debug -> Test Verify -> Certify
Find & fix defects Prevent defects
Three phases:
Key principle: Developers verify correctness through formal reasoning, not debugging. A separate certification team performs all testing.
Results: IBM’s COBOL/SF tool (85,000 lines of code) showed a ten-fold reduction in defects during testing and five-fold improvement in developer productivity. Only seven errors in three years of production use.
The term “Cleanroom” borrowed from semiconductor manufacturing reflects the focus on preventing contamination (defects) rather than filtering it out later.
Watts Humphrey at the Software Engineering Institute created PSP to apply process improvement principles to individual developers.
Definition: A structured self-improvement framework where engineers measure and analyze their own performance to reduce defects and improve predictability.
“You cannot improve what you do not measure”
PSP0 --> PSP1 --> PSP2 --> PSP2.1
| | | |
v v v v
Baseline Size & Code & Design
measure- time design templates,
ment estimation reviews verification
Key principle: By tracking personal data, engineers identify their own defect patterns and improve systematically.
Humphrey, known as “the father of software quality,” also created the Capability Maturity Model (CMM) for organizational process improvement.
User stories originated in Extreme Programming in the late 1990s as a lightweight alternative to formal requirements documents. Dan North later established a template that connects behavior to business value:
As a [role]
I want [feature]
So that [benefit]
Example:
As a homeowner
I want to schedule recurring cleaning appointments
So that I don't have to remember to book each time
This format keeps the focus on who needs what and why, rather than jumping straight to implementation details. Stories serve as placeholders for conversations, not detailed specifications.
Kent Beck developed Extreme Programming while leading the Chrysler Comprehensive Compensation System (C3) payroll project, starting in March 1996. He refined the methodology with Ward Cunningham and Ron Jeffries, publishing Extreme Programming Explained in October 1999.
Definition: A software development methodology that improves quality and responsiveness to changing requirements through short development cycles, continuous feedback, and close customer collaboration.
Planning practices:
Development practices:
Team practices:
+--------------------------------------------------+
| WORKSTATION |
| +--------------------------------------------+ |
| | | |
| | shared screen | |
| | | |
| +--------------------------------------------+ |
+--------------------------------------------------+
| |
v v
+-----------+ +-----------+
| DRIVER | | NAVIGATOR |
+-----------+ +-----------+
| Writes | | Reviews |
| code, | <------> | continuously,
| thinks | rotate | thinks |
| tactical | roles | strategic |
+-----------+ +-----------+
Two programmers work together at one workstation. The driver writes code and thinks tactically about the current line. The navigator reviews continuously and thinks strategically about the overall approach. Pairs rotate roles frequently, and partners switch often so knowledge spreads across the team.
Studies showed ~15% more time investment but higher quality and faster knowledge transfer.
On-site Customer: A real customer sits with the development team full-time to answer questions, clarify requirements, and provide immediate feedback. This was radical–previous methodologies treated requirements as documents thrown over a wall.
Planning Game: Business and development collaborate to maximize value. Business writes User Stories on index cards describing desired features. Development estimates effort. Business prioritizes based on value and cost. Planning happens each iteration.
Collective Code Ownership: No individual owns any code. Anyone can modify any part of the system. This requires coding standards and comprehensive tests to work safely.
Continuous Integration: Developers integrate code into a shared repository multiple times per day, with automated builds and tests. This catches integration problems immediately rather than in a painful “integration phase.”
Small Releases: Release to production frequently–weeks, not months. Each release delivers concrete business value. Short cycles mean faster feedback and easier course correction.
Key insight: XP takes practices that work and turns them to “extreme” levels–if testing is good, test constantly; if code review helps, review continuously via pairing; if integration is painful, integrate continuously.
The C3 project was cancelled in February 2000 after Daimler-Benz acquired Chrysler, but XP had already spread. Beck was among the seventeen signatories of the Agile Manifesto in 2001.
While process-focused approaches evolved, another stream addressed quality through visual design communication. The Unified Modeling Language emerged from the “method wars” of the early 1990s, when competing object-oriented notations made it difficult for teams to share designs.
Definition: A standardized visual modeling language for specifying, constructing, and documenting software system artifacts.
In 1994-1996, three leading methodologists unified their competing approaches:
They joined at Rational Software and released UML 1.1 in 1997, which was adopted by the Object Management Group (OMG) on November 14, 1997.
UML defines 14 diagram types in two categories:
Structural diagrams (static system view):
Behavioral diagrams (dynamic system view):
Of all UML diagrams, sequence diagrams proved most valuable and survived the agile backlash against heavy documentation. They show how objects interact over time:
+--------+ +--------+ +--------+
| Client | | Server | |Database|
+---+----+ +---+----+ +---+----+
| | |
| 1. request() | |
|------------------>| |
| | 2. query() |
| |------------------>|
| | |
| | 3. results |
| |<------------------|
| | |
| 4. response | |
|<------------------| |
| | |
As Martin Fowler noted: “The primary value of drawing diagrams is communication. Because the purpose is communication, it’s essential to strip away some information so as to clarify other information.”
UML emerged from the “big design up front” tradition–create detailed models before coding. The Agile Manifesto (2001) explicitly valued “working software over comprehensive documentation.”
Many agile teams abandoned UML entirely. Others adopted “agile modeling”–using diagrams for communication without treating them as formal deliverables.
TDD emerged as one of XP’s core technical practices but became influential in its own right.
Definition: A development technique where you write a failing test before writing the code that makes it pass, followed by refactoring.
+-------+
| WRITE |
| TEST |
+---+---+
|
v
+-----------+
| RED | <-- Test fails
| (fail) |
+-----+-----+
|
| write minimal code
v
+-----------+
| GREEN | <-- Test passes
| (pass) |
+-----+-----+
|
| improve structure
v
+-----------+
| REFACTOR | <-- Keep tests green
| |
+-----+-----+
|
+---------> repeat
As Martin Fowler notes, the most common mistake is neglecting the third step– skipping refactoring leads to messy code accumulation.
Two primary benefits:
Theoretical foundation: J.B. Rainsberger grounds TDD in queuing theory–when process B requires reworking process A, efficiency improves by performing part of B before A begins. This eliminates wasteful rework cycles.
The Given-When-Then syntax became the dominant format for expressing specifications. According to Gojko Adzic’s 2020 survey, this format accounts for 71% of usage versus less than 10% for table-based formats.
Example:
Given a registered user with valid credentials
When they submit the login form
Then they should see their dashboard
The format won adoption due to a good balance between expressiveness and developer productivity. Its simplicity enabled broader tooling support and better IDE integration.
Dan North introduced Behavior-Driven Development as an evolution of TDD that addresses a common problem: developers struggling with where to start testing, what to test, and how much to test at once.
TDD Question: BDD Question:
"How do we test this code?" "What behavior should this system exhibit?"
CODE BEHAVIOR
| |
v v
Implementation User outcomes
details and value
BDD shifts focus from implementation details to behavior and user outcomes. The key insight was applying the same queuing theory principle at the analysis level–implementing features reveals insights about other features.
This practice involves business and technical people writing examples together to establish shared understanding.
Gojko Adzic’s Specification by Example (SbE) formalized the collaborative approach where teams use concrete examples to define acceptance criteria, guide development, and create executable tests.
Key findings from his 2020 survey after 10 years of SbE adoption:
Simon Brown developed the C4 model between 2006-2011 as a response to teams abandoning architecture diagrams entirely. While agile practitioners rejected heavyweight UML, they still needed ways to communicate system structure.
Definition: A hierarchical approach to visualizing software architecture at four levels of abstraction: Context, Containers, Components, and Code.
Level 1: CONTEXT Level 2: CONTAINERS
"What is the system?" "What's inside the system?"
+-------------------------+ +-------------------------+
| | | +-----+ +-----+ |
| [Users]--->[System] | | | Web | | API | |
| / \ | | | App | | | |
| v v | | +--+--+ +--+--+ |
| [External] [Mail] | | | | |
| System Service | | v v |
| | | +-------------+ |
+-------------------------+ | | Database | |
For: Everyone | +-------------+ |
(business + technical) +-------------------------+
For: Technical people
Level 3: COMPONENTS Level 4: CODE
"What's inside a container?" "How is component implemented?"
+-------------------------+ +-------------------------+
| API Container | | |
| +--------+ +--------+ | | Class diagrams |
| | Auth | | Order | | | (usually auto- |
| |Handler | |Service | | | generated from |
| +--------+ +--------+ | | source code) |
| \ / | | |
| v v | | Rarely used--too |
| +----------+ | | detailed for most |
| |Repository| | | purposes |
| +----------+ | | |
+-------------------------+ +-------------------------+
For: Developers/architects For: Detailed design
Key principle: Good diagrams are about communication, not compliance with a notation standard. Use whatever helps the team understand the system.
Brown has taught the C4 model to over 10,000 people in ~40 countries, reflecting demand for lightweight architecture visualization that agile teams will use.
Example Mapping emerged as a structured conversation technique for exploring user stories before development begins. Teams use colored cards to capture different elements of a story.
Story (Yellow):
As a homeowner
I want to reschedule a cleaning appointment
So that I can adjust to changes in my calendar
Rule 1 (Blue): Rescheduling must be done at least 24 hours in advance
Rule 2 (Blue): Customers can only reschedule to available time slots
Rule 3 (Blue): Rescheduling is free for the first change, then costs $15
Questions (Red):
This approach surfaces ambiguity and missing requirements early, when changes are cheapest. If a story has too many red cards, it needs more discovery. If it has too many blue cards, it might need to be split into smaller stories.
Aspect TDD BDD
------ --- ---
Focus Implementation details User behavior
Language Programming language Natural language
Audience Developers Stakeholders + developers
Scope Unit level System interactions
Primary use Code quality/design Requirements communication
Both methodologies write tests before implementing code and create automated test suites.
Use TDD when: prioritizing code quality and design, working in continuous integration environments, or needing rapid developer feedback.
Use BDD when: requiring non-technical stakeholder involvement, building user-centric applications, or dealing with complex business logic needing clear communication.
See Further Reading for links to their work.
This example combines User Stories, Given-When-Then, and BDD techniques into a complete specification.
Story:
As a Customer
I want to book a cleaning appointment online
So that I can schedule cleaning without calling
Scenario 1: Available slot selected
Given the customer has selected "Tuesday 10am"
And Tuesday 10am is available
And the customer has a valid payment method
When the customer confirms the booking
Then the system should create an appointment for Tuesday 10am
And the system should charge a $25 deposit
And the customer should receive a confirmation email
Scenario 2: Slot is no longer available
Given the customer has selected "Tuesday 10am"
And Tuesday 10am was booked by another customer moments ago
When the customer confirms the booking
Then the system should not create an appointment
And the system should say "This slot is no longer available"
And the system should show the next 3 available slots
Scenario 3: Payment method is declined
Given the customer has selected "Tuesday 10am"
And Tuesday 10am is available
And the customer's card is declined
When the customer confirms the booking
Then the system should not create an appointment
And the slot should remain available for others
And the system should say "Payment could not be processed"
Scenario 4: Customer is blocked
Given the customer has 3 previous no-shows
When the customer attempts to book any slot
Then the system should not show available slots
And the system should say "Please contact support to reactivate booking"
Each scenario tests a different constraint: availability (race condition), payment processing, and account standing. The happy path comes first, followed by edge cases that each isolate a single failure mode with verifiable outcomes.
]]>Git
Line of code:
Method
Class
Most important was maintaining the history, so that included:
Tool used: https://github.com/piceaTech/node-gitlab-2-github
Have fun.
]]>After analyzing multiple Rails boilerplates, these are the minimal features they all share:
| Feature | Common Choice | Notes |
|---|---|---|
| Authentication | Devise | Often with OmniAuth for social logins |
| Authorization | Pundit | Role-based access control |
| Testing | RSpec | With FactoryBot, system specs |
| Code Quality | RuboCop | Plus ERB linting, Brakeman |
| Background Jobs | Sidekiq/Solid Queue | Async processing |
| CSS Framework | Tailwind CSS | Some use Bootstrap |
| Security Scanning | Brakeman | Static analysis |
| Deployment | Multiple | Render, Heroku, Fly.io, Kamal |
Most boilerplates also include:
gem install iruby
iruby register --force
brew install jupyter
Later, you can check the installed versions of IRuby with:
for version in $(rbenv versions --bare); do echo "=== Ruby $version ===" && RBENV_VERSION=$version gem list iruby 2>/dev/null | grep -E "^iruby" || echo "iruby not installed"; done
Local usage:
jupyter lab
Webbrowser usage: http://localhost:8888/lab
Create your notebook (.ipynb file) - either via Jupyter Lab or by writing the JSON directly
Convert to HTML:
/opt/homebrew/opt/jupyterlab/bin/jupyter nbconvert --to html notebooks/your-notebook.ipynb
Extract the <main> content from the generated HTML
Add the Jupyter CSS to your site’s stylesheet (see assets/css/codeblock.css)
Embed the HTML directly in your blog post
puts writes to stdout:
puts "This is stdout"
This is stdout
Two ways to write to stderr:
warn "Using warn"
Using warn
$stderr.puts "Using $stderr.puts"
Using $stderr.puts
The last expression's value shows with Out label:
"This is a return value"
"This is a return value"
Output order: stdout, stderr, then return value:
puts "1. stdout via puts"
warn "2. stderr via warn"
$stderr.puts "3. stderr via $stderr.puts"
"4. return value"
1. stdout via puts
2. stderr via warn 3. stderr via $stderr.puts
"4. return value"
# Searches in a single file only
grep "search_term" filename
# Recursive search, search in the directory and all files in it and its subdirectories
grep -r "search_term" directory
# Case insensitive
grep -ri "search_term" directory
# Show line numbers
grep -rn "search_term" directory
git grep "search_term"
# Find files by name
find . -name "*.rb"
# Find files containing text in name
find . -name "*controller*"
Ripgrep is a faster grep tool.
# Search for a word
rg "search_term"
# Case insensitive
rg -i "search_term"
# Show line numbers
rg -n "search_term"
# Show line numbers and context
rg -C 3 "search_term"
# list files
ls
# long listing of files and directories
ll
# show the alias for ll
type -a ll
=> ll is an alias for ls -lh
# list all files and directories, typically an alias for ls -a
la
# show the alias for la
type -a la
la is an alias for ls -lAh
Further reading on Bourne-Again SHell and Z Shell.
# show the man page for ls
man ls
# show the man page for man
man man
# show the man page for bash
man bash
# show the man page for zsh
man zsh
That’s it for now.
]]>Starting with a summary of Rails Wizards Part 1-5 by Jon Sullivan. This is a great introduction to multi-step forms in Rails. Then we’ll look at different approaches to implement them in Rails.
Many apps have multiple steps to complete a task:
Multi-step forms (wizards) make these flows manageable.
Scope:
Acceptance Criteria:
Three options:
ID/Key-in-URL:
Database:
object/:id/steps/:step_name
Cache:
object/p1rsn93/steps/:step_name
ID/Key-in-Session:
object/wizard/steps/:step_name
The goal is to validate each step against its subset of fields while maintaining capability to validate the whole object.
Example scaffold:
rails g scaffold House address exterior_color interior_color current_family_last_name rooms:integer square_feet:integer
The model uses an enum to define form steps and context-specific validators: required_for_step? is a helper method to determine if the current step is required based on the form step. with_options is a Rails helper method to group validations by context.
# app/models/house.rb
class House < ApplicationRecord
enum form_steps: {
address_info: [:address, :current_family_last_name],
house_info: [:interior_color, :exterior_color],
house_stats: [:rooms, :square_feet]
}
attr_accessor :form_step
with_options if: -> { required_for_step?(:address_info) } do
validates :address, presence: true, length: { minimum: 10, maximum: 50 }
validates :current_family_last_name, presence: true, length: { minimum: 2, maximum: 30 }
end
with_options if: -> { required_for_step?(:house_info) } do
validates :interior_color, presence: true
validates :exterior_color, presence: true
end
with_options if: -> { required_for_step?(:house_stats) } do
validates :rooms, presence: true, numericality: { gt: 1 }
validates :square_feet, presence: true
end
def required_for_step?(step)
return true if form_step.nil?
ordered_keys = self.class.form_steps.keys.map(&:to_sym)
ordered_keys.index(step) <= ordered_keys.index(form_step)
end
end
Use a separate controller per wizard (e.g., app/controllers/steps_controllers/house_steps_controller.rb). The examples below use the wicked gem.
Routes:
resources :houses do
resources :steps, only: [:show, :update], controller: 'steps_controllers/house_steps'
end
# URLs: /houses/1/steps/address_info
Houses controller:
class HousesController < ApplicationController
def new
@house = House.new
@house.save!(validate: false)
redirect_to house_step_path(@house, House.form_steps.keys.first)
end
end
Steps controller:
module StepsControllers
class HouseStepsController < ApplicationController
include Wicked::Wizard
steps *House.form_steps.keys
def show
@house = House.find(params[:house_id])
render_wizard
end
def update
@house = House.find(params[:house_id])
@house.assign_attributes(house_params)
render_wizard @house
end
private
def house_params
params.require(:house).permit(House.form_steps[step]).merge(form_step: step.to_sym)
end
def finish_wizard_path
house_path(@house)
end
end
end
View template:
<!-- app/views/steps_controllers/house_steps/address_info.html.erb -->
<%= form_with model: @house, url: wizard_path do |f| %>
<% if f.object.errors.any? %>
<div class="error_messages">
<% f.object.errors.full_messages.each do |error| %>
<p><%= error %></p>
<% end %>
</div>
<% end %>
<fieldset>
<legend>Address Info</legend>
<div>
<%= f.label :address %>
<%= f.text_field :address %>
</div>
<div>
<%= f.label :current_family_last_name %>
<%= f.text_field :current_family_last_name %>
</div>
<div>
<%= f.submit 'Next Step' %>
</div>
</fieldset>
<% end %>
The .permit(House.form_steps[step]) trick ensures users can’t inject attributes not meant for the current step.
For prettier URLs:
Routes:
resources :houses
resources :build_house, only: [:show, :update], controller: 'steps_controllers/house_steps'
# URLs: /build_house/address_info
Houses controller:
class HousesController < ApplicationController
def new
unless house_id = session[:house_id]
@house = House.new
@house.save!(validate: false)
session[:house_id] = @house.id
end
redirect_to build_house_path(House.form_steps.keys.first)
end
end
Steps controller:
module StepsControllers
class HouseStepsController < ApplicationController
include Wicked::Wizard
steps *House.form_steps.keys
def show
@house = House.find(session[:house_id])
render_wizard
end
def update
@house = House.find(session[:house_id])
@house.assign_attributes(house_params)
render_wizard @house
end
private
def house_params
params.require(:house).permit(House.form_steps[step]).merge(form_step: step.to_sym)
end
def finish_wizard_path
house_path(@house)
end
end
end
Note: Enable Rails cache for local development with rails dev:cache.
Routes:
resources :houses
resources :build_house, only: [] do
resources :step, only: [:update, :show], controller: 'steps_controllers/house_steps'
end
# URLs: /build_house/abc-xyz/steps/address_info
Houses controller:
class HousesController < ApplicationController
def new
house_builder_key = SecureRandom.urlsafe_base64(6)
Rails.cache.fetch(house_builder_key) { Hash.new }
redirect_to build_house_step_path(house_builder_key, House.form_steps.keys.first)
end
end
For Rails.cache.fetch(house_builder_key) { Hash.new }: If the key exists in the cache, it returns the stored value. If the key doesn’t exist in the cache, it executes the block { Hash.new } which creates a new empty hash, stores it in the cache with the given key, and returns it. So fetch either returns the stored value or the new empty hash.
Steps controller:
module StepsControllers
class HouseStepsController < ApplicationController
include Wicked::Wizard
steps *House.form_steps.keys
def show
# If the key exists in the cache, it returns the stored value. If the key doesn't exist in the cache, it returns nil
house_attrs = Rails.cache.read(params[:build_house_id])
@house = House.new(house_attrs)
render_wizard
end
def update
# It reads the cache, merges the house_params, and writes the result back to the cache
house_attrs = Rails.cache.read(params[:build_house_id]).merge(house_params)
@house = House.new(house_attrs)
if @house.valid?
Rails.cache.write(params[:build_house_id], house_attrs)
redirect_to_next next_step
else
render_wizard
end
end
private
# Only allow the params for specific attributes allowed in this step.
def house_params
params.require(:house).permit(House.form_steps[step]).merge(form_step: step.to_sym)
end
def finish_wizard_path
house_attrs = Rails.cache.read(params[:build_house_id])
@house = House.new house_attrs
# end of the wizard we save the house to the database
@house.save!
# delete the cache
Rails.cache.delete params[:build_house_id]
# redirect to the house path
house_path(@house)
end
end
end
In our cache-based wizard:
For cache-based wizards, explicitly set the form method to PATCH since the object isn’t persisted until the very end of the wizard:
<%= form_with model: @house, url: wizard_path, method: :patch do |f| %>
<%# form fields... %>
<% end %>
Routes:
resources :houses
resources :build_house, only: [:update, :show], controller: 'steps_controllers/house_steps'
# URLs: /build_house/address_info
Houses controller:
class HousesController < ApplicationController
def new
Rails.cache.fetch(session.id) { Hash.new }
redirect_to build_house_path(House.form_steps.keys.first)
end
end
Steps controller:
module StepsControllers
class HouseStepsController < ApplicationController
include Wicked::Wizard
steps *House.form_steps.keys
def show
house_attrs = Rails.cache.read(session.id)
@house = House.new(house_attrs)
render_wizard
end
def update
house_attrs = Rails.cache.read(session.id).merge(house_params)
@house = House.new(house_attrs)
if @house.valid?
Rails.cache.write(session.id, house_attrs)
redirect_to_next next_step
else
render_wizard
end
end
private
def house_params
params.require(:house).permit(House.form_steps[step]).merge(form_step: step.to_sym)
end
def finish_wizard_path
house_attrs = Rails.cache.fetch(session.id)
@house = House.new(house_attrs)
@house.save!
Rails.cache.delete(session.id)
house_path(@house)
end
end
end
For the full series with more details, visit jonsully.net/blog/rails-wizards-part-one.
Then an implementation using cache persistence + in-URL routing without the Wicked gem. This approach gives you full control over the wizard flow.
Source: multi-step-form commit 49a365c
┌───────┐ ┌──────────┐ ┌───────┐ ┌──────┐
│Browser│ │Controller│ │ Cache │ │Model │
└───┬───┘ └────┬─────┘ └───┬───┘ └──┬───┘
│ │ │ │
│ GET /houses/new │ │ │
│──────────────────>│ │ │
│ │ │ │
│ │ generate cache_key │ │
│ │ write({}) │ │
│ │───────────────────>│ │
│ │ │ │
│ redirect /build_house/:key/steps/address_info │
│<──────────────────│ │ │
│ │ │ │
│ GET /build_house/:key/steps/address_info │
│──────────────────>│ │ │
│ │ │ │
│ │ read(cache_key) │ │
│ │───────────────────>│ │
│ │ house_attrs │ │
│ │<───────────────────│ │
│ │ │ │
│ │ House.new(attrs) │ │
│ │─────────────────────────────────────>│
│ │ @house │ │
│ │<─────────────────────────────────────│
│ │ │ │
│ render show │ │ │
│<──────────────────│ │ │
│ │ │ │
│ PATCH (form data) │ │ │
│──────────────────>│ │ │
│ │ │ │
│ │ read(cache_key) │ │
│ │───────────────────>│ │
│ │ house_attrs │ │
│ │<───────────────────│ │
│ │ │ │
│ │ merge(params) │ │
│ │ House.new(attrs) │ │
│ │─────────────────────────────────────>│
│ │ @house │ │
│ │<─────────────────────────────────────│
│ │ │ │
│ │ @house.valid? │ │
│ │─────────────────────────────────────>│
│ │ true │ │
│ │<─────────────────────────────────────│
│ │ │ │
│ │ write(key, attrs) │ │
│ │───────────────────>│ │
│ │ │ │
│ │ [if final_step?] │ │
│ │ @house.save │ │
│ │─────────────────────────────────────>│
│ │ │ │
│ │ delete(cache_key) │ │
│ │───────────────────>│ │
│ │ │ │
│ redirect │ │ │
│<──────────────────│ │ │
The model defines form steps and conditional validations:
# app/models/house.rb
class House < ApplicationRecord
FORM_STEPS = {
address_info: [:address, :current_family_last_name],
house_info: [:interior_color, :exterior_color],
house_stats: [:rooms, :square_feet]
}.freeze
attr_accessor :form_step
with_options if: -> { required_for_step?(:address_info) } do
validates :address, presence: true, length: { minimum: 5, maximum: 50 }
validates :current_family_last_name, presence: true, length: { minimum: 2, maximum: 30 }
end
with_options if: -> { required_for_step?(:house_info) } do
validates :interior_color, presence: true
validates :exterior_color, presence: true
end
with_options if: -> { required_for_step?(:house_stats) } do
validates :rooms, presence: true, numericality: { greater_than: 1 }
validates :square_feet, presence: true
end
def required_for_step?(step)
return true if form_step.nil?
ordered_keys = self.class::FORM_STEPS.keys.map(&:to_sym)
!!(ordered_keys.index(step) <= ordered_keys.index(form_step))
end
end
# config/routes.rb
resources :houses
resources :build_house, only: [] do
resources :steps, only: [:show, :update], controller: "steps_controllers/house_steps" do
member do
get :back
end
end
end
Initiates the wizard by generating a cache key:
# app/controllers/houses_controller.rb
class HousesController < ApplicationController
before_action :set_house, only: %i[show edit update destroy]
def index
@houses = House.all
end
def show
end
def new
house_cache_key = "house_form_#{session.id}_#{Random.urlsafe_base64(6)}"
Rails.cache.write(house_cache_key, {}, expires_in: 1.hour)
redirect_to build_house_step_path(house_cache_key, House::FORM_STEPS.keys.first)
end
# edit, create, update, destroy...
private
def set_house
@house = House.find(params.expect(:id))
end
def house_params
params.expect(house: [:address, :exterior_color, :interior_color,
:current_family_last_name, :rooms, :square_feet])
end
end
Handles form navigation and validation:
# app/controllers/steps_controllers/house_steps_controller.rb
module StepsControllers
class HouseStepsController < ApplicationController
before_action :set_house_cache_key
before_action :load_house_from_cache
STEPS = House::FORM_STEPS.keys.freeze
def show
@current_step = params[:id].to_sym
@step_index = STEPS.index(@current_step)
@total_steps = STEPS.length
unless STEPS.include?(@current_step)
redirect_to build_house_step_path(@house_cache_key, STEPS.first)
end
end
def update
@current_step = params[:id].to_sym
@step_index = STEPS.index(@current_step)
@total_steps = STEPS.length
# Load existing data and merge with new params
house_attrs = Rails.cache.read(@house_cache_key) || {}
house_attrs = house_attrs.merge(house_params)
@house = House.new(house_attrs)
@house.form_step = @current_step
if @house.valid?
Rails.cache.write(@house_cache_key, house_attrs, expires_in: 1.hour)
if final_step?
@house.form_step = nil
if @house.save
Rails.cache.delete(@house_cache_key)
redirect_to house_path(@house), notice: "House was successfully created."
else
render :show, status: :unprocessable_entity
end
else
next_step = STEPS[STEPS.index(@current_step) + 1]
redirect_to build_house_step_path(@house_cache_key, next_step)
end
else
render :show, status: :unprocessable_entity
end
end
def back
@current_step = params[:id].to_sym
previous_step_index = STEPS.index(@current_step) - 1
if previous_step_index >= 0
previous_step = STEPS[previous_step_index]
redirect_to build_house_step_path(@house_cache_key, previous_step)
else
redirect_to houses_path
end
end
private
def set_house_cache_key
@house_cache_key = params[:build_house_id] || generate_cache_key
end
def generate_cache_key
"house_form_#{session.id}_#{Random.urlsafe_base64(6)}"
end
def load_house_from_cache
house_attrs = Rails.cache.read(@house_cache_key) || {}
@house = House.new(house_attrs)
end
def house_params
allowed_fields = House::FORM_STEPS[@current_step] || []
params.expect(house: [*allowed_fields]).merge(form_step: @current_step)
end
def final_step?
@current_step == STEPS.last
end
end
end
# app/helpers/houses_helper.rb
module HousesHelper
def step_title(step)
case step.to_sym
when :address_info
"Address Information"
when :house_info
"House Information"
when :house_stats
"House Statistics"
else
"Unknown Step"
end
end
def step_button_text(step)
if step.to_sym == House::FORM_STEPS.keys.last
"Complete House"
else
"Continue"
end
end
def first_step?(current_step = nil)
step = current_step || @current_step
step == House::FORM_STEPS.keys.first
end
def last_step?(current_step = nil)
step = current_step || @current_step
step == House::FORM_STEPS.keys.last
end
end
Main show template:
<!-- app/views/steps_controllers/house_steps/show.html.erb -->
<div class="house-wizard-container">
<%= turbo_frame_tag "wizard_step" do %>
<div class="progress-bar-container">
<div class="progress-bar">
<div class="progress-fill" style="width: <%= ((@step_index + 1) * 100.0 / @total_steps).round(1) %>%"></div>
</div>
<p class="progress-text">Step <%= @step_index + 1 %> of <%= @total_steps %></p>
</div>
<div class="step-content">
<h2><%= step_title(@current_step) %></h2>
<%= form_with model: @house,
url: build_house_step_path(@house_cache_key, @current_step),
method: :patch,
data: {
controller: "multi-step-form",
turbo_frame: last_step? ? "_top" : "wizard_step"
},
class: "wizard-form" do |f| %>
<% if @house.errors.any? %>
<div class="error-messages">
<% @house.errors.full_messages.each do |error| %>
<p class="error"><%= error %></p>
<% end %>
</div>
<% end %>
<%= render "steps_controllers/house_steps/#{@current_step}", form: f %>
<div class="form-actions">
<% unless first_step? %>
<%= link_to "Back",
back_build_house_step_path(@house_cache_key, @current_step),
class: "btn btn-secondary" %>
<% end %>
<%= f.submit step_button_text(@current_step), class: "btn btn-primary" %>
</div>
<% end %>
</div>
<% end %>
</div>
Step partial:
<!-- app/views/steps_controllers/house_steps/_address_info.html.erb -->
<fieldset>
<legend>Address Information</legend>
<div class="form-group">
<%= form.label :address %>
<%= form.text_field :address, placeholder: "Enter your full address" %>
</div>
<div class="form-group">
<%= form.label :current_family_last_name, "Family Last Name" %>
<%= form.text_field :current_family_last_name %>
</div>
</fieldset>
This implementation works, but has some issues:
House model contains wizard-specific logic (FORM_STEPS, form_step, required_for_step?)next_step, previous_step, final_step?) lives in the controllerConsidering the issues with the Model + Controller approach, let’s extract the wizard logic to a Form Object. This is a more Rails-y way to handle multi-step forms.
Source: multi-step-form commit c0523d5
| Before (Model + Controller) | After (Form Object) |
|---|---|
FORM_STEPS in model |
FORM_STEPS in form object |
form_step attr_accessor in model |
form_step attribute in form object |
required_for_step? in model |
required_for_step? in form object |
| Step validations in model | Step validations in form object |
| Navigation methods in controller | Navigation methods in form object |
House.new(house_attrs) |
House::MultiStepHouseForm.from_cache(cache_data) |
@house.valid? |
@form.valid? |
The model now only contains data integrity validations:
# app/models/house.rb
class House < ApplicationRecord
validates :address, presence: true, length: { minimum: 10, maximum: 50 }
validates :current_family_last_name, presence: true, length: { minimum: 2, maximum: 30 }
validates :interior_color, presence: true
validates :exterior_color, presence: true
validates :rooms, presence: true, numericality: { greater_than: 1 }
validates :square_feet, presence: true, numericality: { greater_than: 0 }
end
# app/forms/application_form.rb
class ApplicationForm
include ActiveModel::Model
include ActiveModel::Attributes
include ActiveModel::Validations
# For form_with compatibility
def persisted?
false
end
def to_key
nil
end
def to_param
nil
end
def model_name
ActiveModel::Name.new(self.class, nil, self.class.name.demodulize.gsub(/Form$/, ""))
end
end
The form object handles step definitions, validations, navigation, and persistence:
# app/forms/house/multi_step_house_form.rb
class House::MultiStepHouseForm < ApplicationForm
FORM_STEPS = {
address_info: [:address, :current_family_last_name],
house_info: [:interior_color, :exterior_color],
house_stats: [:rooms, :square_feet]
}.freeze
# Define all form attributes
attribute :address, :string
attribute :current_family_last_name, :string
attribute :interior_color, :string
attribute :exterior_color, :string
attribute :rooms, :integer
attribute :square_feet, :integer
# Form state management
attribute :form_step, :string
attribute :house_id, :integer
# Step-specific validations
with_options if: -> { required_for_step?(:address_info) } do
validates :address, presence: true, length: { minimum: 10, maximum: 50 }
validates :current_family_last_name, presence: true, length: { minimum: 2, maximum: 30 }
end
with_options if: -> { required_for_step?(:house_info) } do
validates :interior_color, presence: true
validates :exterior_color, presence: true
end
with_options if: -> { required_for_step?(:house_stats) } do
validates :rooms, presence: true, numericality: { greater_than: 1 }
validates :square_feet, presence: true
end
def self.steps
FORM_STEPS.keys
end
def self.first_step
steps.first
end
def self.last_step
steps.last
end
def initialize(attributes = {})
if attributes[:house_id].present?
house = House.find(attributes[:house_id])
house_attrs = house.attributes.symbolize_keys.slice(*FORM_STEPS.values.flatten)
house_attrs[:house_id] = house.id
attributes = house_attrs.merge(attributes)
end
super
end
def form_step
@form_step&.to_sym
end
def form_step=(step)
@form_step = step&.to_sym
end
def current_step_fields
FORM_STEPS[form_step] || []
end
def required_for_step?(step)
return true if form_step.nil?
ordered_keys = self.class.steps
!!(ordered_keys.index(step) <= ordered_keys.index(form_step))
end
def first_step?
form_step == self.class.first_step
end
def last_step?
form_step == self.class.last_step
end
def next_step
current_index = self.class.steps.index(form_step)
return nil if current_index.nil? || current_index >= self.class.steps.length - 1
self.class.steps[current_index + 1]
end
def previous_step
current_index = self.class.steps.index(form_step)
return nil if current_index.nil? || current_index <= 0
self.class.steps[current_index - 1]
end
def step_index
self.class.steps.index(form_step) || 0
end
def total_steps
self.class.steps.length
end
def progress_percentage
((step_index + 1) * 100.0 / total_steps).round(1)
end
def to_cache
{
address: address,
current_family_last_name: current_family_last_name,
interior_color: interior_color,
exterior_color: exterior_color,
rooms: rooms,
square_feet: square_feet,
form_step: form_step,
house_id: house_id
}
end
def self.from_cache(cache_data)
new(cache_data || {})
end
def save
return false unless valid?
house_attributes = {
address: address,
current_family_last_name: current_family_last_name,
interior_color: interior_color,
exterior_color: exterior_color,
rooms: rooms,
square_feet: square_feet
}
if house_id.present?
house = House.find(house_id)
house.update(house_attributes)
else
house = House.create(house_attributes)
self.house_id = house.id if house.persisted?
end
house
end
def save!
house = save
raise ActiveRecord::RecordInvalid, house unless house&.persisted?
house
end
def model_name
ActiveModel::Name.new(self.class, nil, "House")
end
end
# app/controllers/steps_controllers/house_steps_controller.rb
module StepsControllers
class HouseStepsController < ApplicationController
before_action :set_house_cache_key
before_action :load_form_from_cache
def show
@current_step = params[:id].to_sym
@form.form_step = @current_step
unless House::MultiStepHouseForm.steps.include?(@current_step)
redirect_to build_house_step_path(@house_cache_key, House::MultiStepHouseForm.first_step)
nil
end
end
def update
@current_step = params[:id].to_sym
@form.form_step = @current_step
@form.assign_attributes(form_params)
if @form.valid?
Rails.cache.write(@house_cache_key, @form.to_cache, expires_in: 1.hour)
if @form.last_step?
@form.form_step = nil
house = @form.save!
Rails.cache.delete(@house_cache_key)
redirect_to house_path(house), notice: "House was successfully created."
else
redirect_to build_house_step_path(@house_cache_key, @form.next_step)
end
else
render :show, status: :unprocessable_entity
end
end
def back
@current_step = params[:id].to_sym
@form.form_step = @current_step
if @form.previous_step
redirect_to build_house_step_path(@house_cache_key, @form.previous_step)
else
redirect_to houses_path
end
end
private
def set_house_cache_key
@house_cache_key = params[:build_house_id] || generate_cache_key
end
def generate_cache_key
"house_form_#{session.id}_#{Random.urlsafe_base64(6)}"
end
def load_form_from_cache
cache_data = Rails.cache.read(@house_cache_key) || {}
@form = House::MultiStepHouseForm.from_cache(cache_data)
end
def form_params
params.expect(house: [*@form.current_step_fields])
end
end
end
# config/routes.rb
resources :houses
resources :build_house, only: [] do
resources :steps, only: [:show, :update], controller: "steps_controllers/house_steps" do
member do
get :back
end
end
end
# URLs: /build_house/:cache_key/steps/:step_name
# app/helpers/houses_helper.rb
module HousesHelper
def step_title(step)
case step.to_sym
when :address_info
"Address Information"
when :house_info
"House Information"
when :house_stats
"House Statistics"
else
"Unknown Step"
end
end
def step_button_text(step)
if step.to_sym == House::MultiStepHouseForm.last_step
"Complete House"
else
"Continue"
end
end
end
Main show template:
<!-- app/views/steps_controllers/house_steps/show.html.erb -->
<div class="house-wizard-container">
<%= turbo_frame_tag "wizard_step" do %>
<div class="progress-bar-container">
<div class="progress-bar">
<div class="progress-fill" style="width: <%= @form.progress_percentage %>%"></div>
</div>
<p class="progress-text">Step <%= @form.step_index + 1 %> of <%= @form.total_steps %></p>
</div>
<div class="step-content">
<h2><%= step_title(@current_step) %></h2>
<%= form_with model: @form,
url: build_house_step_path(@house_cache_key, @current_step),
method: :patch,
data: {
controller: "multi-step-form",
turbo_frame: @form.last_step? ? "_top" : "wizard_step"
},
class: "wizard-form" do |f| %>
<% if @form.errors.any? %>
<div class="error-messages">
<% @form.errors.full_messages.each do |error| %>
<p class="error"><%= error %></p>
<% end %>
</div>
<% end %>
<%= render "steps_controllers/house_steps/#{@current_step}", form: f %>
<div class="form-actions">
<% unless @form.first_step? %>
<%= link_to "Back",
back_build_house_step_path(@house_cache_key, @current_step),
class: "btn btn-secondary" %>
<% end %>
<%= f.submit step_button_text(@current_step), class: "btn btn-primary" %>
</div>
<% end %>
</div>
<% end %>
</div>
Step partial example:
<!-- app/views/steps_controllers/house_steps/_address_info.html.erb -->
<fieldset>
<legend>Address Information</legend>
<div class="form-group">
<%= form.label :address %>
<%= form.text_field :address, placeholder: "Enter your full address" %>
</div>
<div class="form-group">
<%= form.label :current_family_last_name, "Family Last Name" %>
<%= form.text_field :current_family_last_name, placeholder: "Enter family last name" %>
</div>
</fieldset>
| Approach | Pros | Cons |
|---|---|---|
| Wicked gem | Less boilerplate, battle-tested | External dependency, less control |
| Model + Controller | No dependencies, straightforward | Model pollution, scattered logic |
| Form Object | Clean model, centralized logic, testable | More initial code to write |
Pre-commit hooks are becoming annoyingly slow when they check all erb files.
ERB Lint caching skips re-analysis of unchanged files. This helps with quicker pre-commit hooks, which will reduce time in local development. Just a flag that was available but not enabled by default.
The PR enables ERB Lint’s --cache flag across the project:
--cache to the erb_lint rake task.erb_lint_cache to gitignore# Before
sh "bin/erb_lint --lint-all"
# After
sh "bin/erb_lint --lint-all --cache"
Looking at the download stats, nextgen sees around 284 weekly downloads and has 29K total downloads. That means this small change might save a few seconds here and there for a decent number of projects.
| Metric | Value |
|---|---|
| Weekly downloads | ~284 |
| Monthly downloads | ~4,500 |
| Total downloads | 29,000+ |
If you use a gem regularly and spot something that could be slightly better, consider opening a PR. It doesn’t have to be a big feature. Sometimes enabling a flag is enough.
]]>This can be used as (Github) template for issues.
Add file in repo_name/.github/ISSUE_TEMPLATE/bug_report.md
]]>