ChangeLog for Developers
When editing the ChangeLog, there is an extremely particular format that must be followed. This format can be figured out just by reading a few pages of the last edits to the file. However, here are some specific rules and examples.
Entries/What to mention
Each commit to the tree typically mandates an entry to the ChangeLog describing the major/important changes of the commit. If any source code has been added or changed, it must have an entry in the ChangeLog. Build/resource files need only be mentioned if the changes are drastic or otherwise important. If you are changing a build file (like Makefile.am or *.mdp) just because you added a source file, it is acceptable and preferred to leave the file out of the list in the ChangeLog entry.
Any svn property changes do not need to be mentioned. For instance, changing an svn:ignore property does not warrant a ChangeLog entry.
Entry Header
All entries to the ChangeLog must start with the date, name, and email address of the person committing. If you have provided a ChangeLog with a patch and you will not actually be committing it, this line will be changed by the person committing. Attribution will be moved to a note under date line. This date/name/email line is for the person committing.
Specifically, the date must be of the form YYYY-MM-DD, then two spaces must follow it, followed by the full name of the person committing, followed by two spaces, and then the email address of the person committing, surrounded by < and >. For example:
2025-02-26 Aaron Bockover <aaron-bockover's-email>
Entry File List
Following the entry header as outlined above, there must be a single blank line. What then follows is a list of files that have been added/changed/removed. This list must be formed in a very specific manner.
The list is always indented with one TAB character. Using spaces to indent the list is not acceptable. To note a file in the list, use the * character followed by a single space, followed immediately by a colon (:) and then begin describing changes to the file.
* src/Libraries/Lastfm/Lastfm/AudioscrobblerConnection.cs: Provide support for user agent when sending requests to Audioscrobbler servers. Can be passed via ctor or by setting the UserAgent property. Also marked ctor as internal.
Note that if the length of the line that contains a file name is over 80 characters, the changes to that file must be described on the following line. Each line is indented with a tab character and should line up with the bullet (*) denoting the filename line. All lines must be wrapped the same way.
If there are multiple files that are described by the same change message, they can be ground together. Begin describing the changes on the last file in the group according the rules above.
* src/Extensions/Banshee.Lastfm/Banshee.Lastfm.Radio/LastfmSource.cs: * src/Extensions/Banshee.Lastfm/Banshee.Lastfm.Audioscrobbler/AudioscrobblerService.cs: * src/Libraries/Lastfm/Lastfm/LastfmCore.cs: Use LastfmCore as a singleton to access Last.fm classes.
There must be a blank line between two groups of file entries.
* src/Core/Banshee.ThickClient/Banshee.Gui/ViewActions.cs: Added Ctrl+E keyboard shortcut for equalizer window. * src/Core/Banshee.ThickClient/Banshee.Gui/GlobalActions.cs: Added Stock.Preferences icon for Preferences menu item.
A complete example
2025-02-21 Scott Peterson <scott-peterson's-email> * src/Core/Banshee.ThickClient/Banshee.Gui/SourceActions.cs: Changed it so that the "Sort Children" option appears only if there are two or more children of a source: a list of one is always sorted :) 2025-02-21 Gabriel Burt <gabriel-burt's-email> * src/Libraries/Hyena/Hyena.Query/DateQueryValue.cs: Make the regex static. * src/Libraries/Lastfm/Lastfm.Data/DataEntryCollection.cs: * src/Libraries/Lastfm/Lastfm.Data/DataEntry.cs: Enforce the Root as being a XmlElement, and if it doesn't have a child element of the requied name, see if it has an attribute.
Some automation
While each entry to the ChangeLog must strictly follow the format described above, there is a nice tool called prepare-changelog (http://banshee-project.org/files/prepare-changelog) that can save you a lot of time when constructing the entry, and it also follows the proper formatting guidelines for constructing the entry header and file list.
To use it, first add the following lines to your ~/.bashrc:
export CHANGE_LOG_NAME="Your Full Name" export CHANGE_LOG_EMAIL_ADDRESS="user@host"
And then copy prepare-changelog (http://banshee-project.org/files/prepare-changelog) to a directory in your PATH (like ~/bin if you have configured this also in your ~/.bashrc). Ensure you make prepare-changelog executable.
To add ~/bin to your PATH add the following line to your ~/.bashrc. Ensure of course you have created the ~/bin directory first.
export PATH=~/bin${PATH+:$PATH}
To make ~/bin/prepare-changelog executable, run the following command:
$ chmod +x ~/bin/prepare-changelog
Once you have configured everything, to create the ChangeLog entry, just run prepare-changelog at the top level directory in Banshee, where the actual ChangeLog file belongs.
Syntax Warnings
If you use vim to edit the ChangeLog file, it will highlight improper spacing in the ChangeLog. Not only will this help you avoid improper ChangeLog formatting, Aaron uses vim to edit and review the ChangeLog, so he will certainly see your mistakes!
