ChangeLog and NEWS file (Re: [31640] trunk/base)
So, I'm now putting the 1.6.0 release together finally, but I have a few comments I'd like to make to this list. First and foremost, take a look at my r31640 commit, quoted below: On Nov 30, 2007, at 11:32 PM, jmpp@macports.org wrote:
Revision 31640 Author jmpp@macports.org Date 2007-11-30 19:32:13 -0800 (Fri, 30 Nov 2007) Log Message
The ChangeLog was orignally meant to be a user-parsable file listing only major changes to base, so that we could use it in our release process to advertise our new goodies. Unfortunately, lately it has turned into a litle bit of a file tracking commits to base, with a little bit of user level information and a lot of gaps in between to do either one right, bleh!
Therefore add a real user-parsable NEWS file in which new features and bug fixes for each release will be advertised, starting with the contents of 1.6.0
Here's hoping that from now on the ChangeLog will turn into a file that truly tracks commits to base, with proper revision numbers for each entry and ticket numbers in case of bug fixes, after being spared from having to remain user-parsable.
---snip (you can find the newly added NEWS file in base/NEWS)--- From now on I would like to request that, as noted in this commit log, any change made to base is recorded in the ChangeLog, with precise revision(s) information and Trac ticket number(s) if you're fixing a bug(s). The best way to accomplish this is to simply incorporate this bit in your commit right away, so that you don't have to come back to the ChangeLog who-knows how long after when you might have forgotten the details. I (or anyone else coordinating releases) will handle the NEWS file at release time, after discussing what part of the changes should be advertised for user consumption, so don't worry about that. So, in short, don't be shy to add to the ChangeLog an entry for your every single commit to base, but please be thorough when you do. Thanks! Secondly, about the NEWS file, there's this commit about which I didn't exactly know what to say: http://trac.macports.org/projects/macports/changeset/30216 Markus, are those Portfile level options that Portfile writers will be able to use? No...? What then? Thirdly, one other thing I didn't add to the NEWS file is our support for /etc/paths.d/ and /etc/manpaths.d/ config options, as I haven't been able to keep up with that thread. I'll amend as soon as I get a chance. Some other things might come up, but my mind is on five things right now and I'm forgetting. Please do alert me to anything about 1.6.0 I might be missing, thanks! Regards,... -jmpp
Is there any reason the ChangeLog can not be automatically generated from the SVN commit messages?
On Dec 1, 2007, at 4:53 AM, Randall Wood wrote:
Is there any reason the ChangeLog can not be automatically generated from the SVN commit messages?
First off, an entry in the ChangeLog does not need to fully mirror its corresponding commit log. If the latter is small, like a one liner comment, then it surely could, that wouldn't be a bad thing; but in the other case, when a commit log is a detailed explanation of what was fixed and how (as commit logs should really be), then duplicating all that information in the ChangeLog would be completely overkill, in my opinion. That's the reason why I'm requesting entries in the ChangeLog be made full with svn revision and ticket number (if any) references, so that they can be regarded as "summaries that point interested parties to further information", short of telling them "run 'svn log' on base and spend hours in there to become acquainted with what has changed and how" (sounds live I've been there...? ;-). But that put aside, do you have any suggestions for auto-generation of the ChangeLog off of the commit log? The only thing that comes to mind is a post-commit hook of some kind that prepends the log of particular revisions to the ChangeLog and then in turn commits that change, which in my opinion is also unnecessarily overkill (you would have to handle infinite loops and other corner cases). The only other thing I can think of is... manually making an entry for your commit ;-) Regards,... -jmpp
On Dec 2, 2007, at 1:28 PM, Juan Manuel Palacios wrote:
On Dec 1, 2007, at 4:53 AM, Randall Wood wrote:
Is there any reason the ChangeLog can not be automatically generated from the SVN commit messages?
First off, an entry in the ChangeLog does not need to fully mirror its corresponding commit log. If the latter is small, like a one liner comment, then it surely could, that wouldn't be a bad thing; but in the other case, when a commit log is a detailed explanation of what was fixed and how (as commit logs should really be), then duplicating all that information in the ChangeLog would be completely overkill, in my opinion. That's the reason why I'm requesting entries in the ChangeLog be made full with svn revision and ticket number (if any) references, so that they can be regarded as "summaries that point interested parties to further information", short of telling them "run 'svn log' on base and spend hours in there to become acquainted with what has changed and how" (sounds live I've been there...? ;-).
But that put aside, do you have any suggestions for auto-generation of the ChangeLog off of the commit log? The only thing that comes to mind is a post-commit hook of some kind that prepends the log of particular revisions to the ChangeLog and then in turn commits that change, which in my opinion is also unnecessarily overkill (you would have to handle infinite loops and other corner cases). The only other thing I can think of is... manually making an entry for your commit ;-)
Regards,...
-jmpp
One thing I forgot to say is that it's also perfectly acceptable to group a number of related commits in a single entry on the ChangeLog, provided the full list svn revisions (and, again, ticket number(s) if applicable) is included with it. Regards,... -jmpp
participants (2)
-
Juan Manuel Palacios
-
Randall Wood