Feature #25616

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

Added by Mischa The Evil 5 months ago. Updated about 1 month ago.

Status:ClosedStart date:
Priority:NormalDue date:
Assignee:Jean-Philippe Lang% Done:

0%

Category:Documentation
Target version:3.4.0
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:

changelog-3_4.txt Magnifier - CHANGELOG 3.4 (14.9 KB) Go MAEDA, 2017-07-02 06:22

make-changelog.rb Magnifier - a script to make changelog of specified version (1.12 KB) Go MAEDA, 2017-07-02 06:22

changelog_generator.rb Magnifier (10.7 KB) Mischa The Evil, 2017-07-02 08:35

0001-Add-changelog-generator-script.patch Magnifier (11.6 KB) Mischa The Evil, 2017-07-02 08:35

0001-Fix-changelog-markup.patch Magnifier (3.42 KB) Mischa The Evil, 2017-07-02 08:35

0001-Fix-changelog-markup.-3.2-stable-backport-of-rX.patch Magnifier (2.99 KB) Mischa The Evil, 2017-07-02 08:36

0001-Fix-changelog-markup.-3.3-stable-backport-of-rX.patch Magnifier (3.45 KB) Mischa The Evil, 2017-07-02 08:36

0002-Add-3.4.0-changelog.patch Magnifier (15.7 KB) Mischa The Evil, 2017-07-02 08:36

screenshot.png (192 KB) Marius BALTEANU, 2017-07-02 14:08

Associated revisions

Revision 16740
Added by Jean-Philippe Lang 3 months ago

Fix changelog markup (#25616).

Patch by Mischa The Evil.

Revision 16742
Added by Jean-Philippe Lang 3 months ago

Fix changelog markup (#25616).

Patch by Mischa The Evil.

Revision 16743
Added by Jean-Philippe Lang 3 months ago

Fix changelog markup (#25616).

Patch by Mischa The Evil.

Revision 16744
Added by Jean-Philippe Lang 3 months ago

Adds changelog generator (#25616).

Patch by Mischa The Evil.

History

#1 Updated by Mischa The Evil 5 months ago

  • Description updated (diff)

Updated until 16-04-2017 09:50.

#2 Updated by Go MAEDA 5 months ago

+1
I always use the proposed structure when I publish Japanese translation of Changelog.
http://blog.redmine.jp/articles/3_3/changelog/

#3 Updated by Mischa The Evil 3 months 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.

#4 Updated by Jean-Philippe Lang 3 months ago

  • Assignee set to Mischa The Evil

ping

#5 Updated by Jean-Philippe Lang 3 months 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?

#6 Updated by Go MAEDA 3 months 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.

#7 Updated by Go MAEDA 3 months 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

#8 Updated by Go MAEDA 3 months ago

  • File deleted (changelog-3_4.txt)

#9 Updated by Go MAEDA 3 months ago

  • File deleted (make-changelog.rb)

#10 Updated by Mischa The Evil 3 months 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.

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

#11 Updated by Go MAEDA 3 months ago

Mischa, thank you for making the script!

#12 Updated by Mischa The Evil 3 months ago

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

#13 Updated by Jean-Philippe Lang 3 months ago

  • Status changed from New to Closed
  • Resolution set to Fixed

Patches applied and changelog generator committed, thanks.

#14 Updated by Marius BALTEANU 3 months ago

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

#15 Updated by Toshi MARUYAMA about 1 month 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.

Also available in: Atom PDF