From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22060 invoked from network); 23 Oct 2001 16:13:27 -0000 Received: from sunsite.dk (130.225.247.90) by ns1.primenet.com.au with SMTP; 23 Oct 2001 16:13:27 -0000 Received: (qmail 25502 invoked by alias); 23 Oct 2001 16:13:17 -0000 Mailing-List: contact zsh-workers-help@sunsite.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 16125 Received: (qmail 25471 invoked from network); 23 Oct 2001 16:13:14 -0000 From: Bart Schaefer Message-Id: <1011023161311.ZM19039@candle.brasslantern.com> Date: Tue, 23 Oct 2001 16:13:10 +0000 X-Mailer: Z-Mail (5.0.0 30July97) To: zsh-workers@sunsite.dk Subject: ChangeLog formatting? MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Should we agree on some "rules" for ChangeLog entries? Peter just made this one: * 16033: Pavel Roskin : Src/Builtins/rlimits.c: Undefine RLIMIT_RSS if it's equal to RLIMIT_VMEM to avoid duplicate case value. aczsh.m4 (zsh_LARGE_FILE_SUPPORT): Ignore output of getconf if it returns "undefined". This manages in one swoop to illustrate several things: Someone else sent the patch, but Peter committed it; the same patch made changes to different files for different reasons; and there's a specific section of one of the files to which the change applies. We're particularly inconsistent about how we credit other contributors (I'm guilty of this too). Examples: * Adapted from Stefan Dalibor, 16043: Src/utils.c: checkrmall() must not print to shout when shout's not valid. * Bart: 16038 and 16041: Src/cond.c, Src/loop.c: for caching of compiled patterns: remember that singsub() might modify the string it gets, compare with unmodified string * Norbert Koch: 15954: Doc/Zsh/arith.yo: fix inconsistency of variable name in example. * 15562, Akinori Musha: 15559, 15563: Completion/BSD/Command/_chflags, Completion/Unix/Command/_chown, Completion/Unix/Command/_sysctl: new BSD completion and fix _chown for symlinks * 15278 (Sven), 15390: Completion/Unix/Command/_mount, Completion/Unix/Type/_path_files: more Cygwin support 15278 was accidentally committed by me There are even more variants if you look at ChangeLog-3.1. However, since -3.1, we've mostly been putting the name first and the article number after it. In the case of "16038 and 16041", this doesn't work out so well; I was responsible only for 16038, but it's hard to tell that from the log entry. With respect to different reasons for different files, most of the time the files are still all listed together after the article, and the descriptions are all grouped together as well, and it's up to the reader to figure out which ones go together. I only found one previous example of breaking up the list of files: * 15060: Test/A02alias.ztst: Change expected return value to account for 15050. * 15060: Test/Y01completion.ztst, Test/Y02compmatch.ztst, Test/Y03arguments.ztst, Test/comptest: Abandon the tests during the %prep section if the zpty module can't be loaded. I can't find any examples to compare to "aczsh.m4 (zsh_LARGE_FILE_SUPPORT)". That sort of thing has always been relegated to the descriptions before. Finally, as you can see from the above, examples, we're also inconsistent about capitalization, whether there is a newline after the colon at the end of the list of file names, and at what column the lines should wrap, but those are much less significant details. Of course I probably wouldn't even be bothering to mention this if not for difflog.pl ... but as long as I'm making some kind of stab at parsing of ChangeLog entries, it'd be nice to have some limits on what the parser has to handle. Comments? -- Bart Schaefer Brass Lantern Enterprises http://www.well.com/user/barts http://www.brasslantern.com Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net