From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from pigeon.gentoo.org ([208.92.234.80] helo=lists.gentoo.org)
	by finch.gentoo.org with esmtp (Exim 4.60)
	(envelope-from <gentoo-dev+bounces-40574-garchives=archives.gentoo.org@lists.gentoo.org>)
	id 1NyyIG-0005vk-3b
	for garchives@archives.gentoo.org; Tue, 06 Apr 2010 02:13:32 +0000
Received: from pigeon.gentoo.org (localhost [127.0.0.1])
	by pigeon.gentoo.org (Postfix) with SMTP id EB481E09A1;
	Tue,  6 Apr 2010 02:13:25 +0000 (UTC)
Received: from mail-pv0-f181.google.com (mail-pv0-f181.google.com [74.125.83.181])
	by pigeon.gentoo.org (Postfix) with ESMTP id 881D9E0990
	for <gentoo-dev@lists.gentoo.org>; Tue,  6 Apr 2010 02:13:03 +0000 (UTC)
Received: by pvg16 with SMTP id 16so1934797pvg.40
        for <gentoo-dev@lists.gentoo.org>; Mon, 05 Apr 2010 19:13:03 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=gamma;
        h=domainkey-signature:mime-version:sender:received:date
         :x-google-sender-auth:received:message-id:subject:from:to
         :content-type;
        bh=ON7SWbdUc13ZXJcCGRXfoB+aob1L1/WEoKe8J3L7x+Y=;
        b=rJ67HPhLy5kz2BqvQnVh9ax5+WbjCkM76h0Xxu+LpHQ/imuI0F0j8ooJBTCHQiHFfp
         CXhxHwFdFdb5cNS3TgjDcSwd9raLboDTcIlKZkZD3bAV/Gpo1jnolQwsOYUsnQDKSpML
         WkQCt15Gmva2z0IMEtT2w0GlEH7iKenb/i6P4=
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:sender:date:x-google-sender-auth:message-id:subject
         :from:to:content-type;
        b=X3Xnzu2VN/X63crPFfBiNByEWFsUTsrt34a/h9uVY7Q7ypLuWE9bQ+bEyfm0UlGZFZ
         FhoxQHbupwXSjTSKm1ROkJU77R0iY/DS7mZAGKcRguAKlrSWcFH/FtC6UP5Rtk7YY/Wu
         XBEmXpEbgAnn2FuMPkK1qg0aXbo5Rwa8J8FiU=
Precedence: bulk
List-Post: <mailto:gentoo-dev@lists.gentoo.org>
List-Help: <mailto:gentoo-dev+help@lists.gentoo.org>
List-Unsubscribe: <mailto:gentoo-dev+unsubscribe@lists.gentoo.org>
List-Subscribe: <mailto:gentoo-dev+subscribe@lists.gentoo.org>
List-Id: Gentoo Linux mail <gentoo-dev.gentoo.org>
X-BeenThere: gentoo-dev@lists.gentoo.org
Reply-to: gentoo-dev@lists.gentoo.org
MIME-Version: 1.0
Sender: nirbheek.chauhan@gmail.com
Received: by 10.140.191.19 with HTTP; Mon, 5 Apr 2010 19:13:02 -0700 (PDT)
Date: Tue, 6 Apr 2010 07:43:02 +0530
X-Google-Sender-Auth: b59c4447163c0fce
Received: by 10.141.101.21 with SMTP id d21mr3952923rvm.95.1270519983009; Mon, 
	05 Apr 2010 19:13:03 -0700 (PDT)
Message-ID: <y2h8b4c83ad1004051913je48d03eat3af5f26b7500428f@mail.gmail.com>
Subject: [gentoo-dev] [git migration] The problem of ChangeLog generation
From: Nirbheek Chauhan <nirbheek@gentoo.org>
To: Gentoo Dev <gentoo-dev@lists.gentoo.org>
Content-Type: text/plain; charset=UTF-8
X-Archives-Salt: 2c4f6fb8-e66e-4d78-bf43-2fdb348acf60
X-Archives-Hash: 5384c440a0d2fd016a4f85a0fdb1c234

One of the few remaining problems to be solved for the migration to
git for our gentoo-x86/ and gentoo/ trees (besides other
projects/overlays) is the problem of how to handle ChangeLogs.

====
Gist:
====
* It makes zero sense to manually manage ChangeLogs in git[1]
  - Irritating conflicts while merging branches or remote master
    + Similar argument for having only distfile manifests; but I digress...
  - Duplication of effort and information
  - Saves space for local checkouts
* Proposed is to generate ChangeLogs from git commits on the rsync
server side when metadata generation is done
  - Scripts to do this already exist[1]


Now, there are obviously problems with this. Some of them are
documented below alongwith their proposed solutions. If people foresee
other problems with this; they are requested to comment. They are also
welcome to comment if they have a better solution to the problems
listed below.

Also, please try to keep this thread on-topic.


========
Problems:
========
* Messages in ChangeLog are not always the same as the commit messages
(~1% are different)
* Some people place additional information in the commit message which
is intended only for developer use
  - Most of the difference in ChangeLog/commit messages comes from this
* Trivial changes are often not documented in ChangeLogs
  - This is upto the developer's personal preference
  - Some folks do this because of the extra time it takes
    + This use-case becomes irrelevant due to automatic generation of ChangeLog

========
Solutions:
========
* Do not re-generate the existing ChangeLog; rather make the ChangeLog
generation script smart enough to only append
  - Solves the "messages not same" problem for existing commits
* Use a separator in the commit message like "== \n" to denote that
everything after this is dev-only information and should be skipped
from the user ChangeLog
  - Solves the problem for people who like to add extra dev-only info
in the CVS commit message
* Ignore commits with "[$tag][trivial]" in the tag[2] from being added
to ChangeLog
  - Keeps the wishes of the developer and does not pollute ChangeLog
with such info


1. http://live.gnome.org/Git/ChangeLog
2. http://live.gnome.org/Git/CommitMessages
-- 
~Nirbheek Chauhan

Gentoo GNOME+Mozilla Team