feat: show backfill instructions in UI when script is selected - #20
Closed
miguellarranaga-factorial wants to merge 3 commits into
Closed
feat: show backfill instructions in UI when script is selected#20miguellarranaga-factorial wants to merge 3 commits into
miguellarranaga-factorial wants to merge 3 commits into
Conversation
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
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>
- 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>
Contributor
Author
|
Closing in favor of #21 — this branch ( |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
self.instructionsclass method toDataDrip::Backfill(returnsnilby default, backward-compatible)instructionsin thebackfill_optionsJSON response alongsidehtml#headers,**bold**,`inline code`,-bullet lists, and triple-backtick code blocksself.instructionsplaceholder to the generator templateMotivation
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.instructionsin their class using a simple markup syntax:Supported formatting
# Title## Section### Subsection**text**`code`- itemor* itemThe instructions are HTML-escaped before formatting to prevent XSS.
Review feedback addressed
description→instructionsacross the API, controller, JSON response, generator template, specs and test backfills.<script>intoapp/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 animportmapproject (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.tailwind.css. See the inline comment on the PR for details.Test plan
spec/lib/data_drip/backfill_spec.rb— tests for.instructionsspec/controllers/data_drip/backfill_runs_controller_spec.rb— tests for thebackfill_optionsinstructions responsebundle exec rspec) — 113 examples, 0 failures