]> Savannah Git Hosting - gnulib.git/commitdiff
vcs-to-changelog: Add documentation.
authorSiddhesh Poyarekar <siddhesh@gotplt.org>
Thu, 16 Jan 2020 08:03:00 +0000 (13:33 +0530)
committerBruno Haible <bruno@clisp.org>
Thu, 16 Jan 2020 20:28:49 +0000 (21:28 +0100)
* doc/vcs-to-changelog.texi: New file.
* doc/gnulib.texi (Build Infrastructure Modules): Add
vcs-to-changelog section.

ChangeLog
doc/gnulib.texi
doc/vcs-to-changelog.texi [new file with mode: 0644]

index 53e9d4ca2fdcf400bcaa27ee940b70e2eeb6ddf3..560765244e2f8a99abcab366d8342897722575a7 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2020-01-16  Siddhesh Poyarekar  <siddhesh@gotplt.org>
+
+       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  <siddhesh@gotplt.org>
 
        vcs-to-changelog: Allow loading of custom quirks file.
index c62b20d754b3ed9813c906bf128b89ff76ac796f..b673189a18ee70cc7e4cef4608cd4ed162e8acaf 100644 (file)
@@ -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 (file)
index 0000000..59be718
--- /dev/null
@@ -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 <from_ref> <to_ref>
+@end example
+
+where @code{<from_ref>} and @code{<to_ref>} 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