docs/upgrade.md
This guide covers upgrading SourceMonitor to a new gem version in your host Rails application.
bundle update source_monitorbin/rails source_monitor:upgradebin/rails db:migratebin/rails source_monitor:setup:verify# 1. Update the gem
bundle update source_monitor
# 2. Run the upgrade command (handles migrations, generator, verification)
bin/rails source_monitor:upgrade
# 3. Migrate if needed
bin/rails db:migrate
# 4. Restart
# (restart web server and Solid Queue workers)
When upgrading, you may see deprecation warnings in your Rails log:
[SourceMonitor] DEPRECATION: 'http.old_option' was deprecated in v0.5.0 and replaced by 'http.new_option'.
To resolve:
config/initializers/source_monitor.rbconfig.http.old_option = value)config.http.new_option = value)If a removed option raises an error (SourceMonitor::DeprecatedOptionError), you must update the initializer before the app can boot.
What changed:
view_component dependency constraint widens from >= 3.0, < 4.0 to >= 3.0, < 5.0, so host apps can now resolve ViewComponent 4.x (the engine's lockfile moves to 4.5.0). The engine's components use only stable ViewComponent APIs unaffected by the v4 upgrade, but host apps with their own ViewComponent 3.x customizations should review the ViewComponent v4 release notes before running bundle update.AGENTS.md as the canonical cross-agent reference; CLAUDE.md now points to it.Action items:
bundle update source_monitorbin/rails source_monitor:upgradeWhat changed:
403 Forbidden on every mounted route unless the host app has configured an authentication or authorization handler. Previously routes were publicly accessible when no handler was configured.source_monitor_notifications ActionCable stream (which every connected tab subscribed to); they now render inline on full-page loads and append to the turbo_stream response, reaching only the requesting tab. Background operational toasts remain global but carry no per-user request context..claude internals (#131). Only .claude/skills/sm-* SourceMonitor skills are packaged; agents, hooks, agent-memory, settings.json, commands, and non-sm-* skills are excluded.Upgrade steps:
bundle update source_monitor
bin/rails source_monitor:upgrade
Action required (BREAKING):
Open config/initializers/source_monitor.rb. If neither config.authentication.authenticate_with nor config.authentication.authorize_with is configured, the engine will return 403 on all routes after upgrade. Either:
config.authentication.authenticate_with :authenticate_user!
config.authentication.authorize_with ->(controller) { controller.current_user&.admin? }
config.authentication.open_access = true # NOT for production
No database migrations are required. The flash and packaging changes apply transparently.
What changed:
after_fetch_completed callbacks continue to receive FeedFetcher::Result; the fetch outcome extraction remains internal.Upgrade steps:
bundle update source_monitor
bin/rails source_monitor:upgrade
No migrations, configuration changes, or breaking changes required.
What changed:
Upgrade steps:
bundle update source_monitor
bin/rails source_monitor:upgrade
No migrations, configuration changes, or breaking changes required.
What changed:
health_status default value alignment.Scraping::Runner, Images::Processor, Favicons::Fetcher, Health::SourceHealthCheckOrchestrator, ImportSessions::HealthCheckUpdater). Jobs now contain only deserialization and delegation — business logic lives in lib/.StatusBadgeComponent and IconComponent for consistent badge and icon rendering.SourceDetailsPresenter and SourcesFilterPresenter for view-specific formatting.Source.enable_scraping!(ids) bulk-enables scraping for a list of source IDs; Item#restore! reverses a soft delete and updates the source counter cache; health_status now validated against the 4 permitted values (working, declining, improving, failing).Upgrade steps:
bundle update source_monitor
bin/rails source_monitor:install:migrations
bin/rails db:migrate
Notes:
Item#restore! is the symmetric counterpart to soft_delete! — it clears deleted_at and increments the source items_count counter cache.What changed:
Upgrade steps:
bundle update source_monitor
Notes:
What changed:
Upgrade steps:
bundle update source_monitor
Notes:
What changed:
working/failing) across all components so the OPML import progress counter updates correctly instead of staying stuck at 0/N.Upgrade steps:
bundle update source_monitor
Notes:
What changed:
healthy, warning, critical, declining, improving, auto_paused, unknown) to 4 (working, declining, improving, failing).warning_threshold configuration setting removed entirely.auto_paused_at/auto_paused_until columns) rather than as a health status value. Sources can be both "failing AND auto-paused".determine_status decision tree uses rate thresholds and streak detection.consecutive_fetch_failures column on sources for streak-based health detection.error_category column on fetch logs for classifying failure types (e.g., timeout, DNS, blocked).config.scraping.scrape_recommendation_threshold setting (default 200) controls the word-count threshold for scrape recommendations on the dashboard.Upgrade steps:
bundle update source_monitor
bin/rails source_monitor:upgrade
bin/rails db:migrate
Notes:
config.health.warning_threshold, remove that line. The setting no longer exists and will raise an error.healthy/auto_paused/unknown become working, warning/critical become failing. This is reversible.health_status directly (e.g., Source.where(health_status: "healthy")), update those queries to use the new values.auto_paused? method and auto_paused_at/auto_paused_until columns still exist and work the same way. Only the health_status column values changed.healthy_threshold config setting still exists but now drives the working status (renamed from healthy).consecutive_fetch_failures and error_category columns are added via migrations and require no configuration.What changed:
source_monitor_maintenance separates non-fetch jobs from the fetch pipeline. Health checks, cleanup, favicon, image download, and OPML import jobs now use the maintenance queue.config.fetching.scheduler_batch_size (default reduced from 100 to 25).config.fetching.stale_timeout_minutes (default reduced from 10 to 5).next_fetch_at.ensure block guarantees status reset.source_monitor:maintenance:stagger_fetch_times distributes overdue sources across a time window.Upgrade steps:
bundle update source_monitor
bin/rails source_monitor:upgrade
bin/rails db:migrate
Notes:
solid_queue.yml to include the new maintenance queue. Add:
source_monitor_maintenance:
concurrency: <%= ENV.fetch("SOURCE_MONITOR_MAINTENANCE_CONCURRENCY", 1) %>
bin/rails source_monitor:maintenance:stagger_fetch_times to break the thundering herd.config.fetching.scheduler_batch_size and config.fetching.stale_timeout_minutes for larger deployments.What changed:
SourceMonitor/<version> to a browser-like string (Mozilla/5.0 (compatible; SourceMonitor/<version>)) with Accept-Language, DNT, and Referer headers. This prevents bot-blocking by feed servers.max_in_flight_per_source changed from 25 to nil (unlimited). If you relied on the previous default, add config.scraping.max_in_flight_per_source = 25 to your initializer.config.favicons section).Upgrade steps:
bundle update source_monitor
bin/rails source_monitor:upgrade
bin/rails db:migrate
Notes:
max_in_flight_per_source defaults changed, but both are backward-compatible.config.http.user_agent in your initializer, your custom value is preserved.config.scraping.max_in_flight_per_source explicitly.Released: 2026-02-12
What changed:
Procfile.dev with a Solid Queue jobs: entryconfig/queue.yml dispatcher with recurring_schedule: config/recurring.ymlUpgrade steps:
bundle update source_monitor
bin/rails source_monitor:upgrade
bin/rails db:migrate
Notes:
bin/rails generate source_monitor:install) will add missing Procfile.dev and queue.yml entries without overwriting existing config.config.images.download_to_active_storage = true, config.http.ssl_ca_file, config.http.ssl_ca_path, config.http.ssl_verify.Released: 2026-02-10
What changed:
sm-* Claude Code skills)Upgrade steps:
bundle update source_monitor
bin/rails source_monitor:upgrade
bin/rails db:migrate
Notes:
SourceMonitor::FeedFetcher internals), verify your code against the new module structure.bin/rails source_monitor:skills:installReleased: 2025-11-25
What changed:
ImportHistory model and associated migrationsUpgrade steps:
bundle update source_monitor
bin/rails railties:install:migrations FROM=source_monitor
bin/rails db:migrate
Notes:
bundle show source_monitorGemfile.lock for the resolved version.source_monitor_version marker was manually edited, delete it and re-run upgradedb/migrate/ (keep the newer one)bin/rails db:migratebin/rails db:migrateProcfile.dev for a jobs: entry.bin/rails generate source_monitor:install to patch config/queue.ymlFor additional help, see Troubleshooting.