From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS22989 209.51.188.0/24 X-Spam-Status: No, score=-4.0 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED,SPF_HELO_NONE,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id E5B301F466 for ; Thu, 16 Jan 2020 09:08:20 +0000 (UTC) Received: from localhost ([::1]:38694 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1is18V-0006mZ-FU for normalperson@yhbt.net; Thu, 16 Jan 2020 04:08:19 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:54140) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1is07j-0007Po-A7 for bug-gnulib@gnu.org; Thu, 16 Jan 2020 03:03:31 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1is07f-0005lX-G0 for bug-gnulib@gnu.org; Thu, 16 Jan 2020 03:03:27 -0500 Received: from anteater.elm.relay.mailchannels.net ([23.83.212.3]:27752) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1is07f-0005kT-0R for bug-gnulib@gnu.org; Thu, 16 Jan 2020 03:03:23 -0500 X-Sender-Id: dreamhost|x-authsender|siddhesh@gotplt.org Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id D223A214C8; Thu, 16 Jan 2020 08:03:20 +0000 (UTC) Received: from pdx1-sub0-mail-a65.g.dreamhost.com (100-96-15-240.trex.outbound.svc.cluster.local [100.96.15.240]) (Authenticated sender: dreamhost) by relay.mailchannels.net (Postfix) with ESMTPA id 40E242173B; Thu, 16 Jan 2020 08:03:20 +0000 (UTC) X-Sender-Id: dreamhost|x-authsender|siddhesh@gotplt.org Received: from pdx1-sub0-mail-a65.g.dreamhost.com ([TEMPUNAVAIL]. [64.90.62.162]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.18.5); Thu, 16 Jan 2020 08:03:20 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: dreamhost|x-authsender|siddhesh@gotplt.org X-MailChannels-Auth-Id: dreamhost X-Invention-Minister: 4d72bec74395cacc_1579161800573_2571778759 X-MC-Loop-Signature: 1579161800573:1765264542 X-MC-Ingress-Time: 1579161800572 Received: from pdx1-sub0-mail-a65.g.dreamhost.com (localhost [127.0.0.1]) by pdx1-sub0-mail-a65.g.dreamhost.com (Postfix) with ESMTP id 0FE8F84C33; Thu, 16 Jan 2020 00:03:15 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gotplt.org; h=from:to:cc :subject:date:message-id:mime-version:content-transfer-encoding; s=gotplt.org; bh=41iZmAYW2p6KbJ7IQ+rjx0gt1+w=; b=EVjMXbykcSXidw tvhdMsVEpMHyGSLwVgBoAIM+sIyuf6WKecx1aGvOaabTL/QijZJKn/UUVFiIuOlb h6sCSgg5DmsonyC+ze96oKsgRwCOlFy0eBgqwWfi19dAMeR2NToyIyvRUzYI/rbc ejnsiWMGv/k/emppPwoiWwqznjHAc= Received: from localhost.localdomain (unknown [106.220.141.18]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) (Authenticated sender: siddhesh@gotplt.org) by pdx1-sub0-mail-a65.g.dreamhost.com (Postfix) with ESMTPSA id 0976184C2E; Thu, 16 Jan 2020 00:03:11 -0800 (PST) X-DH-BACKEND: pdx1-sub0-mail-a65 From: Siddhesh Poyarekar To: bug-gnulib@gnu.org Subject: [PATCH] vcs-to-changelog: Add manual documentation Date: Thu, 16 Jan 2020 13:33:00 +0530 Message-Id: <20200116080300.67462-1-siddhesh@gotplt.org> X-Mailer: git-send-email 2.24.1 MIME-Version: 1.0 X-VR-OUT-STATUS: OK X-VR-OUT-SCORE: 0 X-VR-OUT-SPAMCAUSE: gggruggvucftvghtrhhoucdtuddrgedugedrtdeggdduudduucetufdoteggodetrfdotffvucfrrhhofhhilhgvmecuggftfghnshhusghstghrihgsvgdpffftgfetoffjqffuvfenuceurghilhhouhhtmecufedttdenucenucfjughrpefhvffufffkofgggfestdekredtredttdenucfhrhhomhepufhiugguhhgvshhhucfrohihrghrvghkrghruceoshhiugguhhgvshhhsehgohhtphhlthdrohhrgheqnecukfhppedutdeirddvvddtrddugedurddukeenucfrrghrrghmpehmohguvgepshhmthhppdhhvghloheplhhotggrlhhhohhsthdrlhhotggrlhguohhmrghinhdpihhnvghtpedutdeirddvvddtrddugedurddukedprhgvthhurhhnqdhprghthhepufhiugguhhgvshhhucfrohihrghrvghkrghruceoshhiugguhhgvshhhsehgohhtphhlthdrohhrgheqpdhmrghilhhfrhhomhepshhiugguhhgvshhhsehgohhtphhlthdrohhrghdpnhhrtghpthhtohepshhiugguhhgvshhhsehgohhtphhlthdrohhrghenucevlhhushhtvghrufhiiigvpedt Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 23.83.212.3 X-Mailman-Approved-At: Thu, 16 Jan 2020 04:08:14 -0500 X-BeenThere: bug-gnulib@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Gnulib discussion list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Siddhesh Poyarekar Errors-To: bug-gnulib-bounces+normalperson=yhbt.net@gnu.org Sender: "bug-gnulib" * doc/vcs-to-changelog.texi: New file. * doc/gnulib.texi (Build Infrastructure Modules): Add vcs-to-changelog section. --- doc/gnulib.texi | 3 +++ doc/vcs-to-changelog.texi | 52 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) create mode 100644 doc/vcs-to-changelog.texi diff --git a/doc/gnulib.texi b/doc/gnulib.texi index c62b20d75..b673189a1 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -6761,6 +6761,7 @@ for use with GNU Automake (in particular). * configmake:: * warnings:: * manywarnings:: +* VCS To ChangeLog:: @end menu =20 @include havelib.texi @@ -6777,6 +6778,8 @@ for use with GNU Automake (in particular). =20 @include manywarnings.texi =20 +@include vcs-to-changelog.texi + =20 @node Build Infrastructure Files @chapter Build Infrastructure Files diff --git a/doc/vcs-to-changelog.texi b/doc/vcs-to-changelog.texi new file mode 100644 index 000000000..060f00bd5 --- /dev/null +++ b/doc/vcs-to-changelog.texi @@ -0,0 +1,52 @@ +@node VCS To ChangeLog +@section VCS To ChangeLog + +@c Copyright (C) 2020 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.3 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, no Front-Cover Texts, and no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +@cindex VCS To ChangeLog +@findex vcs-to-changelog + +Gnulib provides the @samp{vcs-to-changelog} module to generate an output +similar to the GNU ChangeLog format from metadata of source control soft= ware +such as git. Here's an example of using @samp{vcs-to-changelog}: + +@example +build-aux/vcs_to_changelog.py +@end example + +where @code{} and @code{} refer to the range of commit= s to +generate the output. + +VCS To ChangeLog currently recognises changes in C source code and can t= raverse +commits in git. Additional source frontends and source control backends= may be +added to the module. @samp{vcs-to-changelog} takes the following optiona= l +arguments: + +@itemize +@item @code{-d}: Run the parser debugger, used for debugging +@samp{vcs-to-changelog} +@item @code{-q filename}: Load @var{filename} as the quirks file for the +project. +@end itemize + +The quirks file is a python module that must minimally implement a +@code{get_project_quirks} function that returns an object of type +@code{ProjectQuirks} or its subclass. The subclass may override the fol= lowing +members of @code{ProjectQuirks}: + +@itemize @bullet +@item @code{repo}: Specify the project repo source control. The default= value +is @code{git}. +@item @code{IGNORE_LIST}: A list of files to ignore in the changesets. +@item @code{MACRO_QUIRKS}: A list of dictionary entries with indexes as +@code{orig} and @code{sub} where @code{orig} is a Python regular express= ion +pattern to match and @code{sub} is the substitution. +@item @code{C_MACROS}: A list of C preprocessor macro definitions. +@end itemize --=20 2.24.1