Project

General

Profile

Actions
Copy link

Feature #25616

closed

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

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

Status:
Closed
Priority:
Normal
Assignee:
Jean-Philippe Lang
Category:
Documentation
Target version:
3.4.0
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

Download all 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
Copy link
 #1

Updated by Mischa The Evil about 7 years ago

  • Description updated (diff)

Updated until 16-04-2017 09:50.

Actions
Copy link
 #2

Updated by Go MAEDA about 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
Copy link
 #3

Updated by Mischa The Evil almost 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
Copy link
 #4

Updated by Jean-Philippe Lang almost 7 years ago

  • Assignee set to Mischa The Evil

ping

Actions
Copy link
 #5

Updated by Jean-Philippe Lang almost 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
Copy link
 #6

Updated by Go MAEDA almost 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
Copy link
 #7

Updated by Go MAEDA almost 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
Copy link
 #8

Updated by Go MAEDA almost 7 years ago

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

Updated by Go MAEDA almost 7 years ago

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

Updated by Mischa The Evil almost 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
Copy link
 #11

Updated by Go MAEDA almost 7 years ago

Mischa, thank you for making the script!

Actions
Copy link
 #12

Updated by Mischa The Evil almost 7 years ago

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

Updated by Jean-Philippe Lang almost 7 years ago

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

Patches applied and changelog generator committed, thanks.

Actions
Copy link
 #14

Updated by Marius BĂLTEANU almost 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
Copy link
 #15

Updated by Toshi MARUYAMA over 6 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
Copy link

Also available in: Atom PDF