Refresh the design of the 'Changelogs' pages #7479
Conversation
There was a problem hiding this comment.
Looks really good, do we need to have the link to the LTS upgrade guides page somewhere? https://www.jenkins.io/doc/upgrade-guide/ in case someone is upgrading across multiple versions? (not a blocker)
| = "Notable changes since #{release.lts_predecessor}:" | ||
| %ul.image | ||
| = partial('changelog-changes.html.haml', :changes => release.lts_changes) | ||
| %div |
There was a problem hiding this comment.
If you go back to 2.19.4 its still using the old design. FWIW I think we could archive going back a certain amount of time we don't need to keep growing this page infinitely
There was a problem hiding this comment.
its still using the old design
That's from the HTML archive, when we didn't use YAML yet:
I think this difference is acceptable and we don't need to rewrite ancient HTML for the new format.
It seems that all we're losing with this PR is the old changelog votes for 2.19.4 and earlier, that seems OK. (For weekly changelog, we didn't have votes in changelog-old already anyway.)
There was a problem hiding this comment.
Do we need to keep displaying it on the page or could we archive it?
There was a problem hiding this comment.
I don't think we should delete changelogs, but if we do, we should start with historical weekly changelogs.
There was a problem hiding this comment.
Weekly only displays x number already,
The oldest one is:
https://www.jenkins.io/changelog/#v2.445
(29 weeks)
Not saying delete them, we could have an archive page for older than a reasonable period.
There was a problem hiding this comment.
Makes sense, I read your suggestion as completely removing. I'd keep at least 2 years of changelogs around though for LTS.
Seems reasonable to - wasn't a fan of the big banners at the top pushing the release notes down. I've added a primary button to the app bar for the Upgrade Guide. 
|
|
Thanks for exploring ways to improve the presentation of the changelog. Much appreciated!
That technique is used in the original release of an LTS baseline (the ".1" release) to show that the LTS baseline contains two different types of changes.
I think it is a worthwhile question to ask if changelog readers gain enough benefit from that distinction to justify the separation of the initial LTS baseline changelog into two sections. As a changelog author, it is important that I collect changelog entries from both locations, but as a reader of the changelog, I'm not sure that I gain much benefit from the distinction. Both sections are telling me something that is new to me as an upgrade from a previous release. One case where that separation might be relevant is when a user decides to switch from Jenkins weekly that to Jenkins LTS and remains the transition is from a weekly release that is the same as the LTS baseline . For example, if they switched from weekly 2.462 to LTS 2.462.1, they would only need to read the backports section. However, I think that use case is so rare as to be almost non-existent. Later LTS releases do not include those two sections because they only contain backports. |
|
@daniel-beck and @darinpope have both been actively involved in the LTS changelog in the past and @kmartens27 is actively involved now. I'd love to have their insights. |
|
Maybe instead of "Bug" the heading should be "Bugs fixed" / "Bugfix" / ... to distinguisth "known bugs" and "fixed bugs". I like that the issue types are distinguished by using sections instead of colors 👍 |
Great suggestion - I've updated it like so: 
|
|
I like the overall look and feel of the page @janfaracik, thanks for creating this! I agree with @daniel-beck in regards to how things are organized and displayed, the distinction between what was done to create the .1 release vs all the changes that will happen as a result of the release do deserve that classification. Maybe there could be a title or header for the 2.xxx.1 changes that better introduces these items. Something along the line of "Baseline features" or "Baseline updates" might be something that helps clarify that these are specifically part of the LTS release. In regards to the "Notable changes in 2.xxx" that could be made more clear/specific as well. Perhaps "Updates and changes since the last baseline" would work better here? The last baseline can just be whatever the baseline version number is, but that would clue the reader in to the fact that there are differences from the previous LTS baseline and the next. Other than that though, I like the UI changes and think that it is a nice presentation. |
|
FWIW baseline is not user facing terminology I would use. Maybe 'Changes since 2.462' and 'Changes since 2.452.3' but that seems a bit repetitive, I'm still not convinced on why this is useful to the user.
why?
Can you expand on a scenario where this is impactful? A security fix would just be listed first wouldn't it? |
Time to rewrite https://www.jenkins.io/download/lts/ then, because the term is all over the page that explains how the LTS line works.
The currently live wording is "Changes since 2.462" and "Notable changes since 2.452.4" which is basically what you propose, except that it indicates that the second list is just a subset of changes.
I'm open for alternative suggestions. I mentioned above that we could hide-by-default or otherwise de-emphasize the list of backports, as they're less relevant to most users on the LTS line already, but it needs to be available IMO, and clearly labeled.
See the changelog of 2.414.1. Suppose a reader is on 2.401.3, and reads the changelog for 2.414.1. Currently, it is clearly labeled that the security fix in 2.414.1 is a backport over 2.414 weekly, and not new to LTS. If this were just a merged "changes" section, I expect that many readers would wonder whether they need to update or whether they have the security fixes already, based on them being listed in the "merged changelog" for 2.414.1. |
|
Perhaps this PR could restore the current two headers (existence + label) for LTS.1 releases? It currently has one separate header already, so it's not like they're impossible in the new design. Then this can be merged, and we follow up on that topic in a separate PR? |
|
Absolutely. Previous headings have been restored. |
| %a{:href => "https://github.com/jenkinsci/jenkins/pull/#{change.pull}" }<> | ||
| = "pull #{change.pull}" | ||
| ) | ||
| - page.changes.group_by { |message| message["type"] }.each do | type, logs | |
There was a problem hiding this comment.
I would recommend that at least the same grouping be done for the RSS/Atom changelog feed. I do not expect changelog authors to regularly look at that, so will likely miss if the experience there deteriorates (less grouping of entries in the data file).
|
Looks great, thanks! |
| - if release.changes and release.lts_changes | ||
| .app-releases__notable-changes | ||
| = "Notable changes since #{release.lts_predecessor}" | ||
| %div.app-releases__list__items | ||
| = partial('changelog-changes.html.haml', :changes => release.lts_changes) |
There was a problem hiding this comment.
This is not indented far enough, so https://www.jenkins.io/changelog-stable/ currently has "Notable changes" for an unreleased version of Jenkins.
This MR updates the interface of the 'Changelogs' pages, e.g. the LTS/Weekly pages. The intention is to greatly reduce visual clutter and to add visual hierarchy, improving readability and scan-ability.
What's changed
What's broken
Screenshots
Weekly changelog
Comparison
Before
After
LTS changelog
Comparison
Before
After
Individual changelog
Comparison
Before
After