From e8b0cd030e4efbe0d5a6b7ba859a18f543f94a47 Mon Sep 17 00:00:00 2001 From: Rick Barrette Date: Sun, 15 Nov 2026 13:38:45 -0500 Subject: [PATCH] What's new stays short as releases pile up MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Admin → About shows the running version's release notes, with a link to all releases. - The What's new page keeps the running version (and any newer) open and folds each older release to one line, grouped by month: its version and a count of its changes, fixes and notes for administrators. - CHANGELOG.md itself is unchanged and reads the same on GitHub; the app splits it into releases when shown (Changelog). Co-Authored-By: Claude Opus 5.5 --- app/helpers/help_helper.rb | 11 +++++ app/models/changelog.rb | 57 +++++++++++++++++++++++ app/models/help_guide.rb | 6 ++- app/views/admin/about/show.html.erb | 11 +++++ app/views/help/_changelog.html.erb | 20 ++++++++ app/views/help/show.html.erb | 4 +- config/locales/en.yml | 17 +++++++ test/integration/changelog_page_test.rb | 31 +++++++++++++ test/integration/versioning_test.rb | 2 +- test/models/changelog_test.rb | 62 +++++++++++++++++++++++++ 10 files changed, 218 insertions(+), 3 deletions(-) create mode 100644 app/models/changelog.rb create mode 100644 app/views/help/_changelog.html.erb create mode 100644 test/integration/changelog_page_test.rb create mode 100644 test/models/changelog_test.rb diff --git a/app/helpers/help_helper.rb b/app/helpers/help_helper.rb index a67b7b9..96821b7 100644 --- a/app/helpers/help_helper.rb +++ b/app/helpers/help_helper.rb @@ -7,4 +7,15 @@ module HelpHelper html = HelpGuide.html(page, title: title, link: (links ? method(:help_page_url_for) : nil)) tag.div(html.html_safe, class: "markdown guide") # rubocop:disable Rails/OutputSafety -- sanitized in HelpGuide end + + # A piece of the guide's Markdown (an intro, one release's notes). + def guide_markdown(markdown, class: nil) + html = HelpGuide.render(markdown, link: method(:help_page_url_for)) + tag.div(html.html_safe, class: [ "markdown guide", binding.local_variable_get(:class) ]) # rubocop:disable Rails/OutputSafety -- sanitized in HelpGuide + end + + # "4 changes · 3 fixes · 2 for administrators" + def release_summary(release) + release.counts.map { |key, count| t("help.changelog.counts.#{key}", count: count) }.join(" · ") + end end diff --git a/app/models/changelog.rb b/app/models/changelog.rb new file mode 100644 index 0000000..384d978 --- /dev/null +++ b/app/models/changelog.rb @@ -0,0 +1,57 @@ +# The release notes (CHANGELOG.md) split into releases, so the app can show +# the running version's notes on their own and fold away older ones. The +# file stays one plain Markdown document (it reads the same on GitHub): +# +# # What's new +# intro... +# ## 2026.11.5 +# ### Changes +# - ... +# ### Fixes +# - ... +class Changelog + PATH = Rails.root.join("CHANGELOG.md") + # The section headings counted in a release's one-line summary; items + # under any other heading (the first release's highlights) count as notes. + SECTIONS = { "Changes" => :changes, "Fixes" => :fixes, "For administrators" => :administrators }.freeze + + Release = Data.define(:version, :markdown) do + def year = version.split(".")[0].to_i + def month = version.split(".")[1].to_i + def month_start = Date.new(year, month, 1) + def anchor = "v#{version.tr('.', '-')}" + + # { changes: 4, fixes: 3 }: the top-level items under each heading. + def counts + counts = markdown.split(/^### /).drop(1).each_with_object(Hash.new(0)) do |section, tally| + heading, body = section.split("\n", 2) + tally[SECTIONS.fetch(heading.strip, :notes)] += body.to_s.scan(/^- /).size + end + (SECTIONS.values + [ :notes ]).filter_map { |key| [ key, counts[key] ] if counts[key].positive? }.to_h + end + end + + def self.load = new(PATH.file? ? PATH.read : "") + + attr_reader :title, :intro, :releases + + def initialize(markdown) + head, *parts = markdown.split(/^## /) + @title = head[/\A# (.+)$/, 1] || "What's new" + @intro = head.sub(/\A# .+\n+/, "").strip + @releases = parts.filter_map do |part| + version, body = part.split("\n", 2) + version = version.strip + Release.new(version: version, markdown: body.to_s.strip) if version.match?(/\A\d{4}\.\d{1,2}\.\d+\z/) + end + end + + def release(version) = releases.find { _1.version == version } + + # Shown open: the running version and any newer (or the newest, when the + # running version has no notes, such as in development). + def open?(release, running:) + index = releases.index { _1.version == running } || 0 + releases.index(release) <= index + end +end diff --git a/app/models/help_guide.rb b/app/models/help_guide.rb index d008089..2bc0ac5 100644 --- a/app/models/help_guide.rb +++ b/app/models/help_guide.rb @@ -27,7 +27,11 @@ class HelpGuide # Sanitized HTML. Links to other guide pages ("records.md#mistakes") go # through `link` (slug, anchor) -> URL, or become plain text when nil. def self.html(page, link:, title: true) - source = title ? page.markdown : page.markdown.sub(/\A# .+\n+/, "") + render(title ? page.markdown : page.markdown.sub(/\A# .+\n+/, ""), link: link) + end + + # Any Markdown from the guide (or a part of it, such as one release of the changelog). + def self.render(source, link:) html = Commonmarker.to_html(source, options: OPTIONS, plugins: { syntax_highlighter: nil }) html = Rails::HTML5::SafeListSanitizer.new.sanitize(html, tags: TAGS, attributes: ATTRIBUTES) html.gsub(%r{(.*?)}m) do diff --git a/app/views/admin/about/show.html.erb b/app/views/admin/about/show.html.erb index e18355a..67ae058 100644 --- a/app/views/admin/about/show.html.erb +++ b/app/views/admin/about/show.html.erb @@ -20,6 +20,17 @@ +<% if (notes = Changelog.load.release(info.version)) %> + <%# This version's release notes; older ones are on the What's new page. %> +
+
+

<%= t(".whats_new_in", version: info.version) %>

+ <%= link_to t(".all_releases"), help_page_path("changelog"), class: "link text-sm" %> +
+ <%= guide_markdown(notes.markdown, class: "card-body") %> +
+<% end %> +

<%= t(".runtime") %>

diff --git a/app/views/help/_changelog.html.erb b/app/views/help/_changelog.html.erb new file mode 100644 index 0000000..7c5011b --- /dev/null +++ b/app/views/help/_changelog.html.erb @@ -0,0 +1,20 @@ +<%# The release notes (CHANGELOG.md, see Changelog): the running version and + any newer open, older releases folded to one line each, by month. %> +

<%= changelog.title %>

+<%= guide_markdown(changelog.intro, class: "mb-2") if changelog.intro.present? %> +<% changelog.releases.group_by(&:month_start).each do |month, releases| %> +

<%= l(month, format: "%B %Y") %>

+
+ <% releases.each do |release| %> +
> + + +

<%= release.version %>

+ <% if release.version == running %><%= t(".this_version") %><% end %> + <%= release_summary(release) %> +
+ <%= guide_markdown(release.markdown, class: "px-4 pb-4") %> +
+ <% end %> +
+<% end %> diff --git a/app/views/help/show.html.erb b/app/views/help/show.html.erb index bcf8e94..5ee9246 100644 --- a/app/views/help/show.html.erb +++ b/app/views/help/show.html.erb @@ -10,5 +10,7 @@ aria: { current: (p == @page ? "page" : nil) } %><% end %> -
<%= guide_html(@page) %>
+
+ <%= @page.slug == "changelog" ? render("help/changelog", changelog: Changelog.load, running: SystemInfo.new.version) : guide_html(@page) %> +
diff --git a/config/locales/en.yml b/config/locales/en.yml index c8b2c81..80ae640 100644 --- a/config/locales/en.yml +++ b/config/locales/en.yml @@ -1287,6 +1287,8 @@ en: this_commit_on_github: This commit on GitHub build_html: Build %{build} what_s_new: What's new + whats_new_in: What's new in %{version} + all_releases: All releases disclaimer: Disclaimer source_code: Source code built: Built @@ -2485,6 +2487,21 @@ en: past_30_days: Past 30 days this_year: This year help: + changelog: + this_version: This version + counts: + changes: + one: 1 change + other: "%{count} changes" + fixes: + one: 1 fix + other: "%{count} fixes" + administrators: + one: 1 for administrators + other: "%{count} for administrators" + notes: + one: 1 note + other: "%{count} notes" show: help: 'Help: %{title}' help_pages: Help pages diff --git a/test/integration/changelog_page_test.rb b/test/integration/changelog_page_test.rb new file mode 100644 index 0000000..85a01c2 --- /dev/null +++ b/test/integration/changelog_page_test.rb @@ -0,0 +1,31 @@ +require "test_helper" + +# What's new: the running version's notes on About, and the history with +# older releases folded to one line each, by month. +class ChangelogPageTest < ActionDispatch::IntegrationTest + test "the history opens this version and folds older releases, grouped by month" do + log = Changelog.load + version = SystemInfo.new.version + sign_in create_user + get help_page_path("changelog") + assert_response :success + assert_select "details.release", log.releases.size + assert_select "details.release[open]##{log.release(version).anchor}" do + assert_select "summary .badge-blue", text: "This version" + end + older = log.releases.drop(log.releases.index { _1.version == version } + 1) + older.each { |r| assert_select "details.release:not([open])##{r.anchor} summary", text: /#{Regexp.escape(r.version)}.*(change|fix|for administrators|note)/m } + assert_select "h2", text: "November 2026" + end + + test "About shows what's new in the running version, linking to all releases" do + version = SystemInfo.new.version + sign_in create_user("admin@example.com", admin: true) + get admin_about_path + assert_select "#whats-new" do + assert_select "h2", text: "What's new in #{version}" + assert_select "a[href='#{help_page_path('changelog')}']", text: "All releases" + assert_select "h3", minimum: 1 # its sections (Changes, Fixes, ...) + end + end +end diff --git a/test/integration/versioning_test.rb b/test/integration/versioning_test.rb index e8b6cf1..33b50e5 100644 --- a/test/integration/versioning_test.rb +++ b/test/integration/versioning_test.rb @@ -19,7 +19,7 @@ class VersioningTest < ActionDispatch::IntegrationTest get help_page_path("changelog") assert_response :success assert_select "h1", text: /What.s new/ - assert_select "h2", text: version # the current version has release notes + assert_select "details[open] summary h3", text: version # the current version has release notes end test "each recorded software build remembers its version" do diff --git a/test/models/changelog_test.rb b/test/models/changelog_test.rb new file mode 100644 index 0000000..a5ab474 --- /dev/null +++ b/test/models/changelog_test.rb @@ -0,0 +1,62 @@ +require "test_helper" + +class ChangelogTest < ActiveSupport::TestCase + SAMPLE = <<~MD + # What's new + + The newest release is first. + + ## 2026.12.0 + + ### Changes + + - One + - Two + - (a nested point, not counted) + + ### Fixes + + - A fix + + ## 2026.11.1 + + ### For administrators + + - Set `TZ` + + ## 2026.11.0 + + ### Flying + + - First + - Second + MD + + setup { @log = Changelog.new(SAMPLE) } + + test "splits the file into its title, intro and releases, newest first" do + assert_equal "What's new", @log.title + assert_equal "The newest release is first.", @log.intro + assert_equal %w[2026.12.0 2026.11.1 2026.11.0], @log.releases.map(&:version) + assert_equal Date.new(2026, 11, 1), @log.release("2026.11.1").month_start + assert_equal "v2026-11-1", @log.release("2026.11.1").anchor + end + + test "counts the top-level items under each section" do + assert_equal({ changes: 2, fixes: 1 }, @log.release("2026.12.0").counts) + assert_equal({ administrators: 1 }, @log.release("2026.11.1").counts) + assert_equal({ notes: 2 }, @log.release("2026.11.0").counts) # other headings + end + + test "the running version and newer are open; the newest when the running one has no notes" do + assert_equal [ true, true, false ], @log.releases.map { @log.open?(_1, running: "2026.11.1") } + assert_equal [ true, false, false ], @log.releases.map { @log.open?(_1, running: "unreleased") } + end + + test "the real CHANGELOG.md parses, with notes for the current version" do + log = Changelog.load + assert log.releases.size >= 1 + assert log.release(SystemInfo.new.version), "CHANGELOG.md has no section for VERSION" + log.releases.each { assert_predicate _1.counts.values.sum, :positive?, "#{_1.version} has no counted items" } + end +end