Feature #25616
closedChange format of the changelog (both on redmine.org and in the shipped changelog file)
0%
Description
Currently the changelogs (both the ones on redmine.org and the one file bundled with the core) are hard to read, making them difficult to digest. I'd like to propose a change to alleviate that a bit.
Current changelog structure on redmine.org:
h1. Changelog x.x.x h2. x.x.x (YYYY-MM-DD) * Defect #xxxxx: ... * Defect #xxxxx+1: ... * Feature #xxxxx: ... * Feature #xxxxx+1: ... * Patch #xxxxx: ... * Patch #xxxxx+1: ...
Proposed changelog structure on redmine.org:
h1. Changelog x.x.x h2. x.x.x (YYYY-MM-DD) h3. [Category A] * Defect #xxxxx: ... * Defect #xxxxx+1: ... * Feature #xxxxx: ... h3. [Category B] * Feature #xxxxx+1: ... * Patch #xxxxx: ... * Patch #xxxxx+1: ...The pros of this structure are:
- we have some basic context of an issue without the need to open it
- translation issues don't clutter up the list
- the list is broken up into several logical domains instead of one big mixed list
- lists quickly get longer due to the many newlines between categories and issues
- it takes some more time to prepare instead of just copy-pasting the roadmap view
I also propose this new format for the bundled changelog file.
Now that it's always easier to judge these things by eye instead of just by words, I have created a 3.4.0 draft changelog updated until 16-04-2017 09:50: Changelog_3_4-draft. It's equivalent for the bundled changelog file would look like: View details...
Files
Updated by Mischa The Evil over 7 years ago
- Description updated (diff)
Updated until 16-04-2017 09:50.
Updated by Go MAEDA over 7 years ago
+1
I always use the proposed structure when I publish Japanese translation of Changelog.
http://blog.redmine.jp/articles/3_3/changelog/
Updated by Mischa The Evil over 7 years ago
- Target version set to 3.4.0
Let's see if we can make this change happen starting from 3.4.0 indeed; setting proposed target.
Please ping me when 3.4.0 is (planned to) being "freezed/freeze'ed/frozen" (:S), so I:- can update the proposals to the final release contents and,
- might have at least a short amount of time to make minor, last minute subject/category (readability) changes when needed.
Updated by Jean-Philippe Lang over 7 years ago
lists quickly get longer due to the many newlines between categories and issues
Yes, for patch release, we may have very small numbers of tickets for each category.
it takes some more time to prepare instead of just copy-pasting the roadmap view
This is a real issue. Maybe we could just add a link on the Changelog to the issue list grouped by categories?
Updated by Go MAEDA over 7 years ago
- File changelog-3_4.txt added
- File make-changelog.rb added
I made changelog-3_4.txt by using make-changelog.rb .
Note that make-changelog.rb cannot retrieve issues which are invisible to anonymous users.
Updated by Go MAEDA over 7 years ago
- File changelog-3_4.txt changelog-3_4.txt added
- File make-changelog.rb make-changelog.rb added
Slightly updated the script. Reuploading the files.
--- make-changelog.rb.orig 2017-07-02 13:18:19.000000000 +0900
+++ make-changelog.rb 2017-07-02 13:18:57.000000000 +0900
@@ -25,7 +25,7 @@
issue = Issue.new
issue.tracker = tr.css('td.tracker').first.text
issue.id = tr.css('td.id').first.text
- issue.subject = tr.css('td.subject').first.text
+ issue.subject = tr.css('td.subject').first.text.strip
issue.category = tr.css('td.category').first.text
issues << issue
end
@@ -36,6 +36,6 @@
issues_by_category.keys.sort.each do |category|
print "\n=== #{category}\n\n"
issues_by_category[category].sort_by {|v| [v.tracker, v.id.to_i]}.each do |issue|
- puts "* #{issue.tracker} #{issue.id}: #{issue.subject}"
+ puts "* #{issue.tracker} ##{issue.id}: #{issue.subject}"
end
end
Updated by Mischa The Evil over 7 years ago
- File changelog_generator.rb changelog_generator.rb added
- File 0001-Add-changelog-generator-script.patch 0001-Add-changelog-generator-script.patch added
- File 0001-Fix-changelog-markup.patch 0001-Fix-changelog-markup.patch added
- File 0001-Fix-changelog-markup.-3.2-stable-backport-of-rX.patch 0001-Fix-changelog-markup.-3.2-stable-backport-of-rX.patch added
- File 0001-Fix-changelog-markup.-3.3-stable-backport-of-rX.patch 0001-Fix-changelog-markup.-3.3-stable-backport-of-rX.patch added
- File 0002-Add-3.4.0-changelog.patch 0002-Add-3.4.0-changelog.patch added
Jean-Philippe Lang wrote:
it takes some more time to prepare instead of just copy-pasting the roadmap view
This is a real issue. Maybe we could just add a link on the Changelog to the issue list grouped by categories?
I agree this is a valid issue. I'd prefer though not to use issue queries for the changelog.
I came to the same conclusion as Go did: we need a script to generate a changelog. I'll attach my resulting script (which looks to me a bit more sophisticated than the script written by Go), and a patch which adds it to source:/trunk/script, to this issue. Impression of the usage page of the script...
While looking into this issue I also noticed that the formatting of the changelogs of the last 3.2.6 and 3.3.3 releases in the packaged CHANGLOG file is wrong. I've fixed it and I'll leave the three patch files attached to this issue:- 0001-Fix-changelog-markup.patch (for trunk, can be merged into 3.4-stable)
- 0001-Fix-changelog-markup.-3.2-stable-backport-of-rX.patch (for 3.2-stable)
- 0001-Fix-changelog-markup.-3.3-stable-backport-of-rX.patch (for 3.3-stable)
I have updated Changelog_3_4-draft upto today. I also updated the packaged CHANGELOG file; I'll leave a patch against trunk for that change (which requires patch 0001-Fix-changelog-markup.patch to be applied first).
Note: #26311 and #26312 (nor #25616) are not-yet included in the 3.4.0 changelogs I've generated. If any of these is actually getting included in 3.4.0 (and they are kept targeted to 3.4.0 version), they still need to be added (maybe nice to test the uploaded scripts...)
Updated by Mischa The Evil over 7 years ago
- Assignee changed from Mischa The Evil to Jean-Philippe Lang
Updated by Jean-Philippe Lang over 7 years ago
- Status changed from New to Closed
- Resolution set to Fixed
Patches applied and changelog generator committed, thanks.
Updated by Marius BĂLTEANU over 7 years ago
- File screenshot.png screenshot.png added
One mention if it's not too late: we should strip the subject text in order to avoid left/right empty spaces
Updated by Toshi MARUYAMA over 7 years ago
Marius BALTEANU wrote:
One mention if it's not too late: we should strip the subject text in order to avoid left/right empty spaces
FTR: #26388.