Misc #12283: Obsolete ChangeLog and commit message in Git-style

• Status: Closed
• Assignee: naruse (Yui NARUSE)

[naruse (Yui NARUSE)]

How about Git-style commit message instead of ChangeLog?

Proposal

After we reach the consensus

1. Write a commit message in Git-style.

• Line 1: summary of commit (around 80 characters or less, <50 is better)
• Line 2: empty line
• Line 3-: More detailed explanation of commit

See also: https://git-scm.com/book/ch5-2.html#Commit-Guidelines

2. Stop manually edit ChangeLog and auto-generate on make dist.

Rationale

A good commit message should include the objective of the commit.
Committers should write "what purpose the change is for".
In this sense, ChangeLog is not a good format. It lists per-file changes, so committers tend to write just "how the files were changed".

Also, ChangeLog causes commit conflicts frequently.
Though it is not related with the actual commit.
People who uses svn/git should see the log with it; ChangeLog is only for tarball users.

Status

mame made this proposal at the developers' meeting (13 Apr.), and there was no objection.

Matz agreed with this proposal, provided that a ChangeLog-like plain-text file is generated from the commit log.
The release manager will create the file when Ruby is released.

Note

This ticket does NOT propose a migration from SVN to Git. Never discuss that in this ticket.

[naruse (Yui NARUSE)]

• Tracker changed from Bug to Misc

[normalperson (Eric Wong)]

[e-mail] wrote:

How about Git-style commit message instead of ChangeLog?

Yes please :)

The current changelog format is a very annoying barrier to
making commits; especially for applying patches from others.

Matz agreed with this proposal, provided that a ChangeLog-like plain-text file is generated from the commit log.

I don't even think that's necessary; NEWS file with pointers to
SVN/git history is enough.

[duerst (Martin Dürst)]

I welcome this proposal. It makes committing easier. Can you please tell us when this proposal will actually start? I see people still committing ChangeLog changes.

[sonots (Naotoshi Seo)]

I am positive this proposal, too. ChangeLog often conflicts and I encountered with conflicts today, too.

[shyouhei (Shyouhei Urabe)]

Seems no one is against abandoning ChangeLog.

What about "a ChangeLog-like plain-text file" part?

[naruse (Yui NARUSE)]

Shyouhei Urabe wrote:

Seems no one is against abandoning ChangeLog.

What about "a ChangeLog-like plain-text file" part?

One idea is just svn log -rHEAD:53286, and we can customize the format further.
(I use git show git merge-base trunk origin/ruby_2_3 to show the commit)

TODO:

• How to get the beginning revision of the branch with subversion.
• What format the new ChangLog should be.

[normalperson (Eric Wong)]

[e-mail] wrote:

Shyouhei Urabe wrote:

Seems no one is against abandoning ChangeLog.

What about "a ChangeLog-like plain-text file" part?

I don't think it's useful given how prevalent git and SVN are
among developers. NEWS is much more useful to end users.

One idea is just svn log -rHEAD:53286, and we can customize the format further.
(I use git show git merge-base trunk origin/ruby_2_3 to show the commit)

TODO:

• How to get the beginning revision of the branch with subversion.

We can document that in NEWS.

[normalperson (Eric Wong)]

[e-mail] wrote:

1. Write a commit message in Git-style.

• Line 1: summary of commit (around 80 characters or less, <50 is better)
• Line 2: empty line
• Line 3-: More detailed explanation of commit

Fwiw, I already do that in my commits. I would also like
stable branch maintainers to maintain the summary when merging,
and refer to trunk commit in message body.
(Use "-x" in "git cherry-pick -x")

For example, oneline view of ten v2_3.0..v2_3_1 changes in Ruby
is not very informative by itself:

$ git log --abbrev-commit --pretty=oneline -10 v2_3_0..v2_3_1
5827d8e add tag v2_3_1
394fa89 version.h: bump up teeny. 2.3.0 -> 2.3.1.
52c883b merge revision(s) 53320,54756: [Backport #12246]
2d360c5 merge revision(s) 54755: [Backport #12313]
7f36210 merge revision(s) 54758:
6ccc9e9 merge revision(s) 54716,54719,54750: [Backport #12314]
7b70f0e merge revision(s) 54720: [Backport #12184]
ab3376b merge revision(s) 54681: [Backport #12302]
b8aa410 merge revision(s) 54141,54542,54548: [Backport #12082]
9224427 merge revision(s) 54423,54489: [Backport #12201] [Backport #12202]

Compare the above output with Linux v4.5.1..v4.5.2:

$ git log --abbrev-commit --pretty=oneline -10 v4.5.1..v4.5.2
92b8a3b Linux 4.5.2
9378a3b staging: android: ion: Set the length of the DMA sg entries in buffer
383b59f HID: usbhid: fix inconsistent reset/resume/reset-resume behavior
2fa2fc1 HID: wacom: fix Bamboo ONE oops
9bfe5a5 ALSA: usb-audio: Skip volume controls triggers hangup on Dell USB Dock
1b040b3 ALSA: usb-audio: Add a quirk for Plantronics BT300
4e088a6 ALSA: usb-audio: Add a sample rate quirk for Phoenix Audio TMX320
0e3d5c4 ALSA: hda/realtek - Enable the ALC292 dock fixup on the Thinkpad T460s
285947f ALSA: hda - Fix regression of monitor_present flag in eld proc file
9e91bf3 mmc: sdhci-pci: Add support and PCI IDs for more Broxton host controllers

Note: I suggest cloning linux.git with bundle for resumability and
to reduce server load:

https://www.kernel.org/cloning-linux-from-a-bundle.html

(Git hackers thinking of ways to make cloning large repos more
efficient and resumable :)

[shevegen (Robert A. Heiler)]

I personally have no preference either way.

I should however had also note that I like the current changelog format:

https://github.com/ruby/ruby/blob/trunk/ChangeLog

It sort of is easy for me to read what is new, what is changed, what
is being worked on etc...

For me who is more or less a casual ruby user, writing mostly just ruby
code, it allows me to keep track of that in a very easy manner.

Matz agreed with this proposal, provided that a ChangeLog-like plain-text file is generated from the commit log.

I don't even think that's necessary; NEWS file with pointers to
SVN/git history is enough.

I like the changelogs more than the NEWS file - I don't even look
at the news file much at all, easier to keep track of current
changes as they happen. :-)

[shyouhei (Shyouhei Urabe)]

I asked matz why he need a ChangeLog yesterday. He answered that the problem is svn log. It requires network connection, and is painfully slow.

At least until we give up subversion, there should be a file-based ChangeLog-ish mechanism. Matz said it's OK for him to auto-generate such thing from commit comments.

Once we equipped a subversion hook script to auto-generate a ChangeLog, we can start migrate this way.

[shyouhei (Shyouhei Urabe)]

• Status changed from Open to Assigned
• Assignee set to naruse (Yui NARUSE)

[naruse (Yui NARUSE)]

• Status changed from Assigned to Closed

Applied in changeset r56638.

---

• tool/vcs.rb (export_changelog): generate ChangeLog file from
  vcs's log. [Feature #12283]

• tool/make-snapshot (package): overwrite ChangeLog by generated
  ChangeLog.

[shyouhei (Shyouhei Urabe)]

!!!

So is it now open? Can we commit without ChangeLog entry?

[vo.x (Vit Ondruch)]

• Related to Bug #12908: make-snapshot is broken added