Fix baseline badge level change detection, CDN purge, and email notification (#2763)

When a project earns or loses a baseline badge level, the system was not
detecting the change, so no congratulations/warning flash message or email
was sent. Things worked fine in the metal series, but while we were
adding baseline we stubbed out parts because we added only one baseline
level at first. However, that's no longer true.

Also, update_all_badge_percentages (run after criteria rule
changes) was not purging the CDN, leaving stale badge images cached.

Specific fixes:

- current_working_level: return project.baseline_badge_level (e.g.
  'in_progress', 'baseline-1') for baseline sections, not the fixed
  criteria_level string. This makes gain/loss detection work for
  baseline the same way it already worked for metal badges.

- update_all_badge_percentages: call FastlyRails.purge_all on completion.
  When criteria rules change and all badge percentages are recalculated,
  the CDN cache is now cleared automatically. No-op in test/development
  where Fastly credentials are absent. To force recalculation and purge
  the CDN cache in production:
    heroku run --app production-bestpractices rake update_all_badge_percentages

- email_owner: accept badge_suffix parameter ('badge' or 'baseline')
  from caller instead of deriving it internally, keeping structural
  decisions out of the mailer.

- Sections.badge_url_suffix: new single source of truth for the badge
  image URL path suffix per series type, backed by BADGE_URL_SUFFIX map.
  Both call sites (controller and view) now use this instead of
  independent ternary expressions.

- gained_level.text.erb: use @badge_suffix in badge embedding snippets
  so baseline badge earners see /baseline not /badge. Also fix a
  pre-existing bug where the HTML snippet had <% @hostname %> (missing =)
  silently dropping the hostname.

- docs/baseline_update.md: document the recalculation migration step
  needed when completing a baseline update transition (activating future
  criteria), and note that it automatically purges the CDN.

- Tests: fix broken current_working_level test (was asserting old wrong
  behavior), add explicit in_progress->baseline-1 test, add email_owner
  tests for metal vs baseline suffix.

Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: david-a-wheeler

app/controllers/projects_controller.rb

@@ -1569,22 +1569,24 @@ def successful_update(format, old_badge_level, criteria_level)
         new_badge_level: new_badge_level
       )
     end
+    badge_suffix = Sections.badge_url_suffix(criteria_level)
     ReportMailer.email_owner(
-      @project, old_badge_level, new_badge_level, lost_level
+      @project, old_badge_level, new_badge_level, lost_level, badge_suffix
     ).deliver_now
   end
   # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
   # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
   # Determines the current working level based on criteria level or badge level.
-  # For baseline levels, returns the criteria level being edited.
+  # For baseline levels, returns the project's actual achieved baseline badge level
+  # so that gains/losses are detected correctly (e.g., 'in_progress' -> 'baseline-2').
   # For traditional badge levels, returns the project's actual badge level.
   # @param criteria_level [String, nil] The criteria level being edited
   # @param project [Project] The project whose badge level to check
   # @return [String] The current working level
   def current_working_level(criteria_level, project)
-    if Project::CRITERIA_SERIES[:baseline].include?(criteria_level)
-      criteria_level
+    if Sections.section_type(criteria_level) == :baseline
+      project.baseline_badge_level
     else
       project.badge_level
     end

app/mailers/report_mailer.rb

@@ -70,9 +70,10 @@ def subject_for(old_badge_level, new_badge_level, lost_level)
   # @param old_badge_level [String] The previous badge level
   # @param new_badge_level [String] The new badge level
   # @param lost_level [Boolean] True if the project lost badge status
+  # @param badge_suffix [String] URL suffix for badge image ('badge' or 'baseline')
   # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
   # rubocop:disable Metrics/PerceivedComplexity
-  def email_owner(project, old_badge_level, new_badge_level, lost_level)
+  def email_owner(project, old_badge_level, new_badge_level, lost_level, badge_suffix)
     return if project.nil? || project.id.nil? || project.user_id.nil?
 
     @project = project
@@ -89,6 +90,7 @@ def email_owner(project, old_badge_level, new_badge_level, lost_level)
     @email_destination = user.email
     @new_level = new_badge_level
     @old_level = old_badge_level
+    @badge_suffix = badge_suffix
     @hostname = ENV.fetch('PUBLIC_HOSTNAME', 'localhost')
     set_standard_headers
     I18n.with_locale(user.preferred_locale.to_sym) do

app/models/project.rb

@@ -682,6 +682,12 @@ def self.update_all_badge_percentages(levels)
       end
     end
     Project.skip_callbacks = false
+    # Purge the entire CDN cache because badge levels may have changed for
+    # many projects, and we have no cheap way to know which ones changed.
+    # This method is run rarely (only when criteria rules change), so a
+    # full purge is acceptable. It is a no-op in test/development where
+    # Fastly credentials are absent.
+    FastlyRails.purge_all
   end
   # rubocop:enable Metrics/MethodLength
 

app/views/projects/_form_early.html.erb

@@ -24,7 +24,7 @@
     badge_img_src = is_baseline ? project.baseline_badge_src_url : project.badge_src_url
     badge_value = is_baseline ? project.baseline_badge_value : project.badge_level
     badge_level = is_baseline ? project.baseline_badge_level : project.badge_level
-    badge_url_suffix = is_baseline ? 'baseline' : 'badge'
+    badge_url_suffix = Sections.badge_url_suffix(criteria_level)
     badge_alt_text = is_baseline ? 'OpenSSF Baseline' : 'OpenSSF Best Practices'
   %>
   <%= t("projects.form_early.#{badge_i18n_key}.description_1") %>

app/views/report_mailer/gained_level.text.erb

@@ -3,9 +3,9 @@
 
 <%= t 'report_mailer.gained_level_part2' %>
 * <%= t 'report_mailer.in_markdown_add' %>
-  [![OpenSSF Best Practices](https://<%= @hostname %>/projects/<%= @project.id %>/badge)](https://<%= @hostname %>/projects/<%= @project.id %>)
+  [![OpenSSF Best Practices](https://<%= @hostname %>/projects/<%= @project.id %>/<%= @badge_suffix %>)](https://<%= @hostname %>/projects/<%= @project.id %>)
 * <%= t 'report_mailer.in_html_add' %>
-  <a href="https://<%= @hostname %>/projects/<%= @project.id %>"><img src="https://<% @hostname %>/projects/<%= @project.id %>/badge"></a>
+  <a href="https://<%= @hostname %>/projects/<%= @project.id %>"><img src="https://<%= @hostname %>/projects/<%= @project.id %>/<%= @badge_suffix %>"></a>
 
 <%= t 'report_mailer.gained_level_part3' %>
 

config/initializers/01_section_names.rb

@@ -159,4 +159,20 @@ module Sections
   def self.section_type(section)
     SECTION_TYPE_MAP[section.to_s]
   end
+
+  # Authoritative mapping from badge series type to its badge image URL suffix.
+  # This is the single source of truth for badge URL path endings
+  # (e.g., /projects/1/badge vs /projects/1/baseline).
+  # Add an entry here when introducing a new badge series.
+  BADGE_URL_SUFFIX = {
+    metal: 'badge',
+    baseline: 'baseline'
+  }.freeze
+
+  # Returns the badge image URL suffix for the given section.
+  # @param section [String] the section name (canonical, obsolete, or internal)
+  # @return [String] the URL suffix, e.g. 'badge' or 'baseline'
+  def self.badge_url_suffix(section)
+    BADGE_URL_SUFFIX.fetch(section_type(section), 'badge')
+  end
 end

docs/baseline_update.md

@@ -439,10 +439,52 @@ criteria from display, and close out the version notice.
    ```
 
 5. **Restart the application.** The newly activated criteria will be
-   included in `Criteria.active(level)` and will count toward badge
-   percentages. Obsolete criteria will no longer appear on the form.
+   included in `Criteria.active(level)`. Obsolete criteria will no
+   longer appear on the form.
 
-6. **Verify** from the Rails console:
+6. **Recalculate badge percentages and purge the CDN.** After the
+   application restarts, the stored `badge_percentage_baseline_*`
+   values in the database are stale — they were computed under the old
+   set of active criteria. Projects will be corrected one-by-one as
+   their owners save changes, but you must force an immediate bulk
+   recalculation so that every project's badge reflects the new active
+   criteria right away.
+
+   Create a migration:
+
+   ```bash
+   rails generate migration RecalcBaselineBadgePercentages
+   ```
+
+   Edit the generated file (in `db/migrate/`) to contain:
+
+   ```ruby
+   # frozen_string_literal: true
+
+   class RecalcBaselineBadgePercentages < ActiveRecord::Migration[8.0]
+     def change
+       # Baseline criteria set has changed (futures activated, obsoletes
+       # removed), so stored badge_percentage_baseline_* values are stale.
+       # Recalculate for all projects at all baseline levels.
+       # update_all_badge_percentages also calls FastlyRails.purge_all,
+       # so the CDN cache is cleared and badges update immediately.
+       Project.update_all_badge_percentages(Sections::BASELINE_LEVEL_NAMES)
+     end
+   end
+   ```
+
+   Apply the migration:
+
+   ```bash
+   rails db:migrate
+   ```
+
+   `update_all_badge_percentages` calls `FastlyRails.purge_all` on
+   completion, so the CDN badge cache is purged automatically — no
+   manual cache invalidation is needed. The next request for any
+   project's `/baseline` badge will fetch the freshly computed value.
+
+7. **Verify** from the Rails console:
 
    ```ruby
    # Previously-future criteria should now be active:

test/controllers/projects_controller_test.rb

@@ -2064,11 +2064,20 @@ def repos(_user, **)
   end
 
   # Unit tests for private helper methods
-  test 'current_working_level returns criteria_level for baseline levels' do
+  test 'current_working_level returns baseline_badge_level for baseline levels' do
     controller = ProjectsController.new
     project = projects(:perfect_passing)
     result = controller.send(:current_working_level, 'baseline-1', project)
-    assert_equal 'baseline-1', result
+    assert_equal project.baseline_badge_level, result
+  end
+
+  test 'current_working_level returns in_progress for baseline when no baseline earned' do
+    # Ensures in_progress is returned for baseline series (not just metal),
+    # so earning baseline-1 from scratch is detected as a level change.
+    controller = ProjectsController.new
+    project = projects(:perfect_passing) # no badge_percentage_baseline_* set
+    result = controller.send(:current_working_level, 'baseline-1', project)
+    assert_equal 'in_progress', result
   end
 
   test 'current_working_level returns project badge_level for non-baseline' do

test/mailers/report_mailer_test.rb

@@ -26,6 +26,24 @@ class ReportMailerTest < ActionMailer::TestCase
     assert_predicate email.subject, :present?
   end
 
+  test 'email_owner gained metal badge uses /badge suffix' do
+    email = ReportMailer.email_owner(
+      @perfect_project, 'in_progress', 'passing', false, 'badge'
+    ).deliver_now
+    assert_not ActionMailer::Base.deliveries.empty?
+    assert_includes email.body.to_s, '/badge'
+    assert_not_includes email.body.to_s, '/baseline'
+  end
+
+  test 'email_owner gained baseline badge uses /baseline suffix' do
+    email = ReportMailer.email_owner(
+      @perfect_project, 'in_progress', 'baseline-1', false, 'baseline'
+    ).deliver_now
+    assert_not ActionMailer::Base.deliveries.empty?
+    assert_includes email.body.to_s, '/baseline'
+    assert_not_includes email.body.to_s, '/badge'
+  end
+
   test 'Does the monthly announcement run?' do
     # This is a quick sanity test, not an in-depth test.
     # Use 'example.org' per RFC 2606