discourse-upcoming-changes-authoring

Name: discourse-upcoming-changes-authoring
Availability: InStock
Author: Discourse

Guides modification and extension of the Discourse upcoming changes feature-flag framework internals.

47.8k|9.0k|Updated Jan 12, 2013

Search Tags:#Ruby #feature flags #discourse #site settings #ember #framework internals #upcoming changes

Ready to run

npx skills add https://github.com/discourse/discourse --skill discourse-upcoming-changes-authoring

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: discourse-upcoming-changes-authoring
Source: https://github.com/discourse/discourse/tree/main/.skills/discourse-upcoming-changes-authoring
Command: npx skills add https://github.com/discourse/discourse --skill discourse-upcoming-changes-authoring

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Working on the Discourse upcoming changes framework itself requires understanding a multi-layer system spanning a Ruby core, service objects, scheduled jobs, and an Ember admin UI, and this Skill provides the architectural map and behavioral rules needed to modify, debug, or extend that machinery safely.

Core Features & Use Cases

Architecture Reference: Documents the Ruby core (lib/upcoming_changes.rb), services layer (Toggle, Track, NotifyPromotion), scheduled jobs, controller endpoints, and Ember frontend components.
Metadata System Guidance: Explains framework-level behaviors such as default overrides, conditional display, plugin ownership gating, CSS body-class opt-in, permanent warnings, and hiding legacy settings.
Use Case: When adding a new policy to the NotifyPromotion service or changing how auto-promotion resolves setting values, use this Skill to understand caching keyed by git version, event audit trails, and notification merging before editing the code.

Quick Start

Explain how the upcoming changes auto-promotion logic works and where I should add a new notification policy.

Frequently Asked Questions about discourse-upcoming-changes-authoring

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How does auto-promotion work in the Discourse upcoming changes framework?▼

Auto-promotion lives in the resolved_value method: when a setting's status meets the promote_upcoming_changes_on_status threshold, it resolves to true regardless of the database value. The DB value only changes on explicit admin toggle, keeping promotion reversible without losing opt-in state.

How do I hide an upcoming change from the Discourse admin UI?▼

Define a should_display_<change_name>? class method on UpcomingChanges::ConditionalDisplay for core changes, or register a callback via register_upcoming_change_conditional_display in a plugin initializer. The List service and notification jobs consult should_display? and drop changes that return false.

When should a plugin-owned upcoming change set requires_plugin_enabled to false?▼

Set requires_plugin_enabled: false when the change's purpose is to get the plugin adopted, such as changes that are the plugin's own enabled_site_setting or that flip the plugin on via a default override. The default gate would otherwise hide the change from exactly the sites it targets.

Why are upcoming changes caches not invalidated by TTL in Discourse?▼

The current_statuses and permanent_upcoming_changes caches are keyed by Discourse.git_version, so every deploy naturally invalidates them. Within a deploy, TrackStatusChanges calls clear_caches! when it detects metadata changes, and tests must call clear_caches! after modifying metadata.

What is the difference between this authoring skill and adding a new feature flag?▼

This Skill covers the framework internals: the Ruby core, services, jobs, and admin UI machinery. Adding a new feature flag using the existing framework is handled by the separate discourse-upcoming-changes skill instead.