View Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 0000723 | LDMud | Documentation | public | 2010-02-10 14:17 | 2021-04-16 21:00 |
| Reporter | zesstra | Assigned To | zesstra | ||
| Priority | normal | Severity | text | Reproducibility | N/A |
| Status | closed | Resolution | fixed | ||
| Summary | 0000723: Generate CHANGELOG from SCM-Changelogs | ||||
| Description | I want to discuss our workflow of committing stuff. We always add something to CHANGELOG (which is basically a duplicated commit message) and for more important changes to HISTORY. I argue for not maintaining CHANGELOG manually any more. The basic reasoning is the same as given at: http://live.gnome.org/Git/ChangeLog "Using ChangeLog files adds usability issues to developers and translators. First, the information that goes to the ChangeLog is duplicated when adding the commit message. In usability terms, it makes sense to cut the workflow steps to those that are essential. In addition, the ChangeLog is a shared file and you are likely more that any other file to have a conflict when pushing your commits." (Note: this is actually independent of git.) Especially the last is important: that CHANGELOG is a shared file and if you work on several branches simultaneously or several people work in different things in parallel it always leads to a conflict you have to resolve manually and you have to merge in your branches exactly in the planned order. I suggest to concentrate on writing HISTORY and generate CHANGELOG ('all changes in glory detail') for releases automagically from the SCM changelog/commit messages. All users who use our SCM repository anyway don't need CHANGELOG but use svn instead. For releases we can generate CHANGELOG like to generate version.sh, configure etc. Given our usual convention of writing commit messages, I would even think 'svn log' is sufficient without any complicated processing. | ||||
| Additional Information | http://blog.cryos.net/archives/202-Git-and-Automatic-ChangeLog-Generation.html http://snipplr.com/view/6261/ruby-git-changelog/ https://github.com/visionmedia/git-extras http://binarystatic.wordpress.com/2010/02/18/how-to-convert-git-log-to-changelog/ http://aartemenko.com/texts/automated-changelog-generation-for-git/ #!/bin/bash # Generates changelog day by day NEXT=$(date +%F) echo "CHANGELOG" echo ---------------------- git log --no-merges --format="%cd" --date=short | sort -u -r | while read DATE ; do echo echo [$DATE] GIT_PAGER=cat git log --no-merges --format=" * %s" --since=$DATE --until=$NEXT NEXT=$DATE done | ||||
| Tags | No tags attached. | ||||
| External Data (URL) | |||||
| has duplicate | 0000681 | closed | Auto-generate CHANGELOG from commit logs? |
|
|
Gnomi told me he is indifferent in this matter. Is anybody strongly against this? |
|
|
This is a good question. I took a glimpse through the last 0000009:0000020 commit messages, it might be possible to create new CHANGELOG entries by a script using the commit messages but I believe that it won't be possible to have an automatical CHANGELOG as compact as it is now. A good example for _not_ using the commit messages are e.g. the lot of commit messages from 28-May-2009 (for 3.3.719). Each message alone is okay, but taken alltogether they are by far not as readable as the CHANGELOG entry of that day. --> The quality of the CHANGELOG would stand or fall with the reading (and understanding) quality of multiple commit messages. Hmm. |
|
|
I don't really see the problem with the commit messages from 28-May-2009. ;-) A commit message has to describe the commit sufficiently on its own - suppose you look later at only one single commit. This holds true even if several commits in a row deal with the same topic, but different parts of the code. If we combine the messages from them, you can't look at only one of the commits. Combining commits is also a bad idea, because it makes review more difficult and it is not easily possible to remove a part of that joint commit (while you can just revert one of originals commits it consisted of). Therefore I actually have the policy to make commits as small as possible. So I argue against reducing/combining information in the commit messages. Ok, then you might argue for maintaining three different logs: HISTORY for important changes user may notice, the commit log for details and CHANGELOG for something in between (although we advertise the CHANGELOG as 'everything in glory detail')... To be honest, I am simply not motivated for doing this, because of reasons stated above (workflow, shared file, conflicts) and because I then have to write up to three logs with different information for even simple changes. In the end, I anyway copy the commit message to CHANGELOG. There were some patches for which it took notably longer to write the three log entries than the patch. Then there are patches which I develop in a separate branch. I can't write the CHANGELOG+HISTORY in the branch while working on the branch, because it is a shared file and the patches would not be independent anymore. Then I have to look later (sometimes weeks/months later), when I finish the work through all the patches+commit messages and write the two logs and possibly rewrite the commits retroactively to include the changes to the logs. Then, if you want to revert a patch containing a change to CHANGELOG later, you can just revert it, because it will change the CHANGELOG as well (which it should not!), so you have to manually work on that again! It is just a PITA. |
|
|
Please calm down :) You wanted feedback, you've got feedback! |
|
|
I'm calm. ;-) Sorry, if it appeared too harsh, that was not my intention. I just wanted to elaborate in more detail why I am not happy with CHANGELOG. |
|
|
I googled a bit yesterday and there are a lot of scripts for auto-generating a Changelog from the git/svn/whatever commit messages/logs which might be suitable with small adaptations. The difficult thing is to use a suitable format in the commit message. In this respect I don't think the habit of hard-coding the format ("- blabla") ist too convenient: you can't re-indent/re-break the lines to a different length easily. In addition, git has a convenient thing: a subject line, which describes the commit very briefly. This is always the first line of the commit. The body is then the rest (most often separated by an empty line). In 'git log' you can then show only the subject or only the body etc. by using the available %s, %b placeholders. Or show the subject line without indentation and indent the body. And one more remark: Anybody willing and able to read and understand CHANGELOG has also access to git/svn log and can just look at the interesting parts of the history. And can use whatever format he likes. (Therefore I nowadays alway look in the history instead of CHANGELOG.) The only purpose the CHANGELOG has are basically the release tarballs. |
|
|
Issue was obsoleted by time - we don't maintain a separate CHANGELOG anymore. |
| Date Modified | Username | Field | Change |
|---|---|---|---|
| 2010-02-10 14:17 | zesstra | New Issue | |
| 2010-02-14 15:47 | zesstra | Note Added: 0001728 | |
| 2010-02-14 15:47 | zesstra | Status | new => feedback |
| 2010-03-03 17:38 | Coogan | Note Added: 0001753 | |
| 2010-03-04 14:18 | zesstra | Note Added: 0001758 | |
| 2010-03-08 16:34 | Coogan | Note Added: 0001771 | |
| 2010-03-09 02:49 | zesstra | Note Added: 0001773 | |
| 2010-03-14 09:03 | zesstra | Relationship added | has duplicate 0000681 |
| 2010-11-19 09:36 | zesstra | Additional Information Updated | |
| 2010-11-19 10:02 | zesstra | Note Added: 0001919 | |
| 2010-11-19 10:02 | zesstra | Status | feedback => new |
| 2021-04-16 21:00 | zesstra | Assigned To | => zesstra |
| 2021-04-16 21:00 | zesstra | Status | new => closed |
| 2021-04-16 21:00 | zesstra | Resolution | open => fixed |
| 2021-04-16 21:00 | zesstra | Note Added: 0002605 |
