From: Siddhesh Poyarekar <siddhesh@gotplt.org>
To: bug-gnulib@gnu.org
Cc: Siddhesh Poyarekar <siddhesh@gotplt.org>
Subject: [PATCH] vcs-to-changelog: Add manual documentation
Date: Thu, 16 Jan 2020 13:33:00 +0530 [thread overview]
Message-ID: <20200116080300.67462-1-siddhesh@gotplt.org> (raw)
* 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
@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 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 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
--
2.24.1
next reply other threads:[~2020-01-16 9:08 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-01-16 8:03 Siddhesh Poyarekar [this message]
2020-01-16 20:35 ` [PATCH] vcs-to-changelog: Add manual documentation Bruno Haible
2020-01-17 3:38 ` Siddhesh Poyarekar
2020-01-18 18:33 ` Bruno Haible
2020-01-19 4:37 ` Siddhesh Poyarekar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://lists.gnu.org/mailman/listinfo/bug-gnulib
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200116080300.67462-1-siddhesh@gotplt.org \
--to=siddhesh@gotplt.org \
--cc=bug-gnulib@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).