diff options
| -rw-r--r-- | ChangeLog | 7 | ||||
| -rw-r--r-- | doc/gnulib.texi | 3 | ||||
| -rw-r--r-- | doc/vcs-to-changelog.texi | 52 |
3 files changed, 62 insertions, 0 deletions
@@ -1,5 +1,12 @@ 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. * build-aux/vcs_to_changelog.py: New commandline option -q. 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 <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 |