Skip to content

feat: show backfill instructions in UI when script is selected - #20

Closed
miguellarranaga-factorial wants to merge 3 commits into
mainfrom
feat/backfill-description
Closed

feat: show backfill instructions in UI when script is selected#20
miguellarranaga-factorial wants to merge 3 commits into
mainfrom
feat/backfill-description

Conversation

@miguellarranaga-factorial

@miguellarranaga-factorial miguellarranaga-factorial commented Jun 2, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add self.instructions class method to DataDrip::Backfill (returns nil by default, backward-compatible)
  • Return instructions in the backfill_options JSON response alongside html
  • Render the instructions in a styled info box in the new backfill run form when a script is selected
  • Lightweight rich text formatter supporting # headers, **bold**, `inline code`, - bullet lists, and triple-backtick code blocks
  • Add commented self.instructions placeholder to the generator template
  • Update both test backfills with example instructions showcasing all formatting features

Motivation

When selecting a backfill script in the DataDrip UI, there was no way for script authors to communicate what the script does or how to fill in the options. This adds a standard, clean mechanism for that.

Backfill authors can now override self.instructions in their class using a simple markup syntax:

class MyBackfill < DataDrip::Backfill
  def self.instructions
    <<~INSTRUCTIONS
      # My Backfill
      Sets the default role on employees missing one.

      ## Options
      - `department`: limit to a **specific** department

      ## Finding the department ID
      ```
      SELECT id FROM departments WHERE name = 'Engineering';
      ```
    INSTRUCTIONS
  end
end

Supported formatting

Syntax Renders as
# Title Large heading
## Section Blue uppercase section header
### Subsection Subtle subheader
**text** Bold
`code` Inline code pill
- item or * item Bullet list
Triple backticks Code block with dark background

The instructions are HTML-escaped before formatting to prevent XSS.

Review feedback addressed

  • Renamed descriptioninstructions across the API, controller, JSON response, generator template, specs and test backfills.
  • Heredocs are now used for the example instructions in the test backfills (per review).
  • Markdown formatter moved out of the inline <script> into app/javascript/data_drip/markdown.js, and the form is now driven by a Stimulus controller (backfill_form_controller.js) — addressing the "leave it in the JS folder" suggestion. We kept our ~60-line renderer rather than pulling in marked: this is an importmap project (no npm/bundler) so marked isn't already available, and a full CommonMark parser isn't a tiny dependency for the small subset we render.
  • Inline styles kept on purpose. The engine's Tailwind build can't generate utilities for class names it never sees in a scanned template, and the instructions HTML is injected dynamically — so Tailwind utility classes wouldn't be compiled into tailwind.css. See the inline comment on the PR for details.

Test plan

  • spec/lib/data_drip/backfill_spec.rb — tests for .instructions
  • spec/controllers/data_drip/backfill_runs_controller_spec.rb — tests for the backfill_options instructions response
  • Full suite green (bundle exec rspec) — 113 examples, 0 failures

Add a self.description class method to DataDrip::Backfill so backfill
authors can provide a how-to guide shown in the UI when their script is
selected. The description is rendered in a styled info box above the
dynamic options, HTML-escaped for safety. Defaults to nil for backward
compatibility.

- Add DataDrip::Backfill.description class method (nil by default)
- Return description in backfill_options JSON response
- Render description container in new backfill run form with JS
- Add self.description commented placeholder to generator template
- Add example description to AddRoleToEmployee test backfill
- Add specs for Backfill.description and controller response

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@miguellarranaga-factorial
miguellarranaga-factorial marked this pull request as ready for review June 2, 2026 13:53
Replace plain text description rendering with a lightweight formatter
that supports headers (#/##/###), **bold**, `inline code`, bullet lists,
and triple-backtick code blocks. Uses inline styles to avoid Tailwind
CSS compilation issues with dynamically injected HTML.

Update example backfills to showcase all formatting features including
a SQL code block example in AddBirthdayToEmployee.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Comment thread spec/test_app/app/backfills/add_birthday_to_employee.rb Outdated
Comment thread spec/test_app/app/backfills/add_role_to_employee.rb Outdated
Comment thread app/views/data_drip/backfill_runs/new.html.erb Outdated
Comment thread app/views/data_drip/backfill_runs/new.html.erb Outdated
- Rename `self.description` -> `self.instructions` across the API, controller,
  JSON response, generator template, specs, and test backfills
- Use heredocs for the example instructions in the test backfills (review)
- Extract the markdown renderer out of the inline <script> into
  app/javascript/data_drip/markdown.js and drive the form via a Stimulus
  controller (backfill_form_controller.js), per the "leave it in the JS folder"
  review suggestion. Kept our tiny renderer instead of pulling in marked, since
  this is an importmap project (no npm) and marked is not a tiny dependency.
- Inline styles are kept on purpose: the engine's Tailwind build cannot
  generate utilities for class names it never sees in a scanned template, and
  the instructions HTML is injected dynamically.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@miguellarranaga-factorial miguellarranaga-factorial changed the title feat: show backfill description in UI when script is selected feat: show backfill instructions in UI when script is selected Jun 10, 2026
@miguellarranaga-factorial

Copy link
Copy Markdown
Contributor Author

Closing in favor of #21 — this branch (feat/backfill-description) has been merged into #21's branch (feat/add_description), where the instructions feature now ships alongside the description DSL and backfills catalog. See the 'Merged in #20' section of #21. Full combined suite is green (128 examples, 0 failures).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants