Project

General

Profile

Actions

Feature #25616

closed

Change format of the changelog (both on redmine.org and in the shipped changelog file)

Added by Mischa The Evil over 7 years ago. Updated over 7 years ago.

Status:
Closed
Priority:
Normal
Category:
Documentation
Target version:
Start date:
Due date:
% Done:

0%

Estimated time:
Resolution:
Fixed

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
The cons of this structure are:
  • 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

changelog-3_4.txt (14.9 KB) changelog-3_4.txt CHANGELOG 3.4 Go MAEDA, 2017-07-02 06:22
make-changelog.rb (1.12 KB) make-changelog.rb a script to make changelog of specified version Go MAEDA, 2017-07-02 06:22
changelog_generator.rb (10.7 KB) changelog_generator.rb Mischa The Evil, 2017-07-02 08:35
0001-Add-changelog-generator-script.patch (11.6 KB) 0001-Add-changelog-generator-script.patch Mischa The Evil, 2017-07-02 08:35
0001-Fix-changelog-markup.patch (3.42 KB) 0001-Fix-changelog-markup.patch Mischa The Evil, 2017-07-02 08:35
0001-Fix-changelog-markup.-3.2-stable-backport-of-rX.patch (2.99 KB) 0001-Fix-changelog-markup.-3.2-stable-backport-of-rX.patch Mischa The Evil, 2017-07-02 08:36
0001-Fix-changelog-markup.-3.3-stable-backport-of-rX.patch (3.45 KB) 0001-Fix-changelog-markup.-3.3-stable-backport-of-rX.patch Mischa The Evil, 2017-07-02 08:36
0002-Add-3.4.0-changelog.patch (15.7 KB) 0002-Add-3.4.0-changelog.patch Mischa The Evil, 2017-07-02 08:36
screenshot.png (192 KB) screenshot.png Marius BĂLTEANU, 2017-07-02 14:08
Actions #1

Updated by Mischa The Evil over 7 years ago

  • Description updated (diff)

Updated until 16-04-2017 09:50.

Actions #2

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/

Actions #3

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:
  1. can update the proposals to the final release contents and,
  2. might have at least a short amount of time to make minor, last minute subject/category (readability) changes when needed.
Actions #4

Updated by Jean-Philippe Lang over 7 years ago

  • Assignee set to Mischa The Evil

ping

Actions #5

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?

Actions #6

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.

Actions #7

Updated by Go MAEDA over 7 years ago

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
Actions #8

Updated by Go MAEDA over 7 years ago

  • File deleted (changelog-3_4.txt)
Actions #9

Updated by Go MAEDA over 7 years ago

  • File deleted (make-changelog.rb)
Actions #10

Updated by Mischa The Evil over 7 years ago

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...)

Actions #11

Updated by Go MAEDA over 7 years ago

Mischa, thank you for making the script!

Actions #12

Updated by Mischa The Evil over 7 years ago

  • Assignee changed from Mischa The Evil to Jean-Philippe Lang
Actions #13

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.

Actions #14

Updated by Marius BĂLTEANU over 7 years ago

One mention if it's not too late: we should strip the subject text in order to avoid left/right empty spaces

Actions #15

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.

Actions

Also available in: Atom PDF