mirror of
https://github.com/rickbarrette/simple-aircraft-manager-rails.git
synced 2026-11-17 15:50:36 -05:00
What's new stays short as releases pile up
- 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 <noreply@anthropic.com>
This commit is contained in:
1 parent
e4bc3a5b7b
commit
e8b0cd030e
10 files changed
+218
-3
No files matched your search
@@ -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
|
||||
@@ -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
|
||||
@@ -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{<a href="([a-z-]+|README)\.md(?:#([a-z0-9-]+))?">(.*?)</a>}m) do
|
||||
|
||||
@@ -20,6 +20,17 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<% if (notes = Changelog.load.release(info.version)) %>
|
||||
<%# This version's release notes; older ones are on the What's new page. %>
|
||||
<section class="card mb-5" id="whats-new">
|
||||
<div class="card-header">
|
||||
<h2 class="card-title"><%= t(".whats_new_in", version: info.version) %></h2>
|
||||
<%= link_to t(".all_releases"), help_page_path("changelog"), class: "link text-sm" %>
|
||||
</div>
|
||||
<%= guide_markdown(notes.markdown, class: "card-body") %>
|
||||
</section>
|
||||
<% end %>
|
||||
|
||||
<div class="grid gap-5 lg:grid-cols-2">
|
||||
<section class="card">
|
||||
<div class="card-header"><h2 class="card-title"><%= t(".runtime") %></h2></div>
|
||||
|
||||
@@ -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. %>
|
||||
<h1 class="mb-3 text-2xl font-bold"><%= changelog.title %></h1>
|
||||
<%= guide_markdown(changelog.intro, class: "mb-2") if changelog.intro.present? %>
|
||||
<% changelog.releases.group_by(&:month_start).each do |month, releases| %>
|
||||
<h2 class="mt-6 mb-2 text-xs font-semibold uppercase tracking-wide text-slate-500"><%= l(month, format: "%B %Y") %></h2>
|
||||
<div class="divide-y divide-slate-200 rounded-md ring-1 ring-slate-200">
|
||||
<% releases.each do |release| %>
|
||||
<details id="<%= release.anchor %>" class="group release" <%= "open" if changelog.open?(release, running: running) %>>
|
||||
<summary class="flex cursor-pointer list-none flex-wrap items-baseline gap-x-3 gap-y-1 px-4 py-3 hover:bg-slate-50 [&::-webkit-details-marker]:hidden">
|
||||
<span aria-hidden="true" class="inline-block text-xs text-slate-400 transition-transform group-open:rotate-90">▶</span>
|
||||
<h3 class="font-mono text-base font-semibold"><%= release.version %></h3>
|
||||
<% if release.version == running %><span class="badge-blue"><%= t(".this_version") %></span><% end %>
|
||||
<span class="text-sm text-slate-500"><%= release_summary(release) %></span>
|
||||
</summary>
|
||||
<%= guide_markdown(release.markdown, class: "px-4 pb-4") %>
|
||||
</details>
|
||||
<% end %>
|
||||
</div>
|
||||
<% end %>
|
||||
@@ -10,5 +10,7 @@
|
||||
aria: { current: (p == @page ? "page" : nil) } %></li><% end %>
|
||||
</ul>
|
||||
</nav>
|
||||
<article class="card card-body min-w-0 max-w-3xl"><%= guide_html(@page) %></article>
|
||||
<article class="card card-body min-w-0 max-w-3xl">
|
||||
<%= @page.slug == "changelog" ? render("help/changelog", changelog: Changelog.load, running: SystemInfo.new.version) : guide_html(@page) %>
|
||||
</article>
|
||||
</div>
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
Reference in new issue
Block a user