Adding Discourse Upcoming Changes

Overview

Upcoming changes are feature flags that allow gradual rollout of new Discourse features. They require a site setting, translation, optional image, and can be targeted to specific groups.

When to Use

Use when:

• Adding a new feature that needs gradual rollout
• Creating an experimental/alpha/beta feature flag

Checklist

0. Gather Required Information

REQUIRED: Before adding the site setting, use AskUserQuestion to gather missing information. Only ask questions for information the user has NOT already provided. The user can always type a value directly via the "Other" option.

Batch 1 (ask first, max 4 questions):

Note: For Status, "stable" and "permanent" are available via "Other". For Audience, "developers" is available via "Other".

After Batch 1: Gather any remaining information before continuing:

• If the flag name was not provided in the original message, ask for it
• If the user selected "I'll provide the path later" for Image, ask for the image path
• Ask if they have a Learn More URL to link to (optional)

1. Add Site Setting

IMPORTANT: Do NOT read the entire config/site_settings.yml file - it's too large. Instead, use Grep to search for upcoming_change: to find existing examples and the right location to add the new setting.

Add to config/site_settings.yml in the appropriate section (often under experimental:):

enable_your_feature_name:
  default: false
  hidden: true
  client: true
  upcoming_change:
    status: "<status from question>"
    impact: "<type>,<audience>"

Status options: conceptual, experimental, alpha, beta, stable, permanent

Impact format: <type>,<audience>

• Type: feature or other
• Audience: admin, moderators, staff, all_members, developers

Optional: Add learn_more_url: "https://..." for documentation link.

2. Add Translation

Add to config/locales/server.en.yml under site_settings::

en:
  site_settings:
    enable_your_feature_name: "Description of what this upcoming change enables or modifies"

3. Add Preview Image

Ask user to provide an image, then process it using the skill's optimization script:

1. Copy image to destination:

   bashCopy

   cp "<source_image>" "public/images/upcoming_changes/<setting_name>.png"
   

2. Convert, resize, and compress using the skill's optimization script:

   bashCopy

   bin/rails runner ~/.claude/skills/discourse-upcoming-changes/scripts/optimize_upcoming_change_image.rb public/images/upcoming_changes/<setting_name>.png
   

   This script:

   • Converts any image format to PNG using Discourse's ImageMagick integration
   • Resizes to max 1200px width using OptimizedImage.downsize
   • Compresses with pngquant via FileHelper.optimize_image!

3. Final path: public/images/upcoming_changes/<setting_name>.png

   • Filename must match the setting name exactly

4. Access in Code

Ruby - Check if enabled for user:

user.upcoming_change_enabled?(:enable_your_feature_name)

# Or with explicit user (nil for anonymous):
UpcomingChanges.enabled_for_user?(:enable_your_feature_name, user)
UpcomingChanges.enabled_for_user?(:enable_your_feature_name, nil)

JavaScript - Check setting value:

// In component/controller with @service siteSettings
this.siteSettings.enable_your_feature_name;

For Plugins

Plugins follow the same pattern with different file locations.

1. Add Site Setting

Add to plugins/your-plugin/config/settings.yml:

plugins:
  enable_your_feature_name:
    default: false
    hidden: true
    client: true
    upcoming_change:
      status: "experimental"
      impact: "feature,all_members"

2. Add Translation

Add to plugins/your-plugin/config/locales/server.en.yml:

en:
  site_settings:
    enable_your_feature_name: "Description of what this upcoming change enables or modifies"

3. Image

Images still go in core: public/images/upcoming_changes/enable_your_feature_name.png

Quick Reference

Common Mistakes