From 171095d3ab8ebe652b3686ddb3989051899915f0 Mon Sep 17 00:00:00 2001 From: Siddhesh Poyarekar Date: Thu, 16 Jan 2020 13:33:00 +0530 Subject: [PATCH] vcs-to-changelog: Add documentation. * doc/vcs-to-changelog.texi: New file. * doc/gnulib.texi (Build Infrastructure Modules): Add vcs-to-changelog section. --- ChangeLog | 7 ++++++ doc/gnulib.texi | 3 +++ doc/vcs-to-changelog.texi | 52 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 62 insertions(+) create mode 100644 doc/vcs-to-changelog.texi diff --git a/ChangeLog b/ChangeLog index 53e9d4ca2f..560765244e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2020-01-16 Siddhesh Poyarekar + + vcs-to-changelog: Add documentation. + * doc/vcs-to-changelog.texi: New file. + * doc/gnulib.texi (Build Infrastructure Modules): Add vcs-to-changelog + section. + 2020-01-16 Siddhesh Poyarekar vcs-to-changelog: Allow loading of custom quirks file. diff --git a/doc/gnulib.texi b/doc/gnulib.texi index c62b20d754..b673189a18 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 @include havelib.texi @@ -6777,6 +6778,8 @@ for use with GNU Automake (in particular). @include manywarnings.texi +@include vcs-to-changelog.texi + @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 0000000000..59be71858d --- /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 Texts. A +@c copy of the license is included in the section entitled ``GNU Free +@c Documentation License''. + +@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 software +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 commits to +generate the output. + +VCS To ChangeLog currently recognises changes in C source code and can traverse +commits in git. Additional source frontends and source control backends may be +added to the module. @samp{vcs-to-changelog} takes the following optional +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 following +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 expression +pattern to match and @code{sub} is the substitution. +@item @code{C_MACROS}: A list of C preprocessor macro definitions. +@end itemize -- 2.39.5