[PATCH 1/7] compat/regex: add a README with a maintenance guide

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: May 4, 2017, 22:00 UTC
Message-ID: <20170504220043.25702-2-avarab@gmail.com>
In-Reply-To: <20170504220043.25702-1-avarab@gmail.com>

Add a README file to compat/regex describing how the copy of the gawk engine should be maintained.

Since gawk's regex engine was originally imported in git.git in commit d18f76dccf ("compat/regex: use the regex engine from gawk for compat", 2010-08-17) the Git project has forked the upstream code.

Most of the changes that have been made in that time have been made redundant by similar changes made upstream. Out of all the modifications made to it since then, which can be found via:

    $ git log --oneline d18f76dccf..v2.13.0-rc2 -- compat/regex/

These are the only real code changes that aren't made fully redundant by upstream patches:

    ce518bbd6c ("Fix compat/regex ANSIfication on MinGW", 2010-08-26)
    5b62e6374a ("compat/regex/regexec.c: Fix some sparse warnings", 2013-04-27)
    d099b7173d ("Fix some sparse warnings", 2013-07-18)

These look to me like they might be a non-issue due to subsequent changes, or perhaps aren't needed anymore due to compiler updates.

In addition a few style & typo changes have been made in that time:

    ce9171cd63 ("compat/regex: fix spelling and grammar in comments", 2013-04-12)
    749f763dbb ("typofix: in-code comments", 2013-07-22)
    c01499ef69 ("C: have space around && and || operators", 2013-10-16)

Some of these could still be applied, but I don't see any point in doing so. These are typo & style nits, if anyone really cares that much they should send updates to gawk.git instead of making the re-merging of code into git.git harder over such trivial issues.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 compat/regex/README | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 compat/regex/README

diff --git a/compat/regex/README b/compat/regex/README
new file mode 100644
index 0000000000..345d322d8c
--- /dev/null
+++ b/compat/regex/README
@@ -0,0 +1,21 @@
+This is the Git project's copy of the GNU awk (Gawk) regex
+engine. It's used when Git is build with e.g. NO_REGEX=NeedsStartEnd,
+or when the C library's regular expression functions are otherwise
+deficient.
+
+This is not a fork, but a source code copy. Upstream is the Gawk
+project, and the sources should be periodically updated from their
+copy, which can be done with:
+
+    for f in $(find . -name '*.[ch]' -printf "%f\n"); do wget http://git.savannah.gnu.org/cgit/gawk.git/plain/support/$f -O $f; done
+
+For ease of maintenance, and to intentionally make it inconvenient to
+diverge from upstream (since it makes it harder to re-merge) any local
+changes should be stored in the patches/ directory, which after doing
+the above can be applied as:
+
+    for p in patches/*; do patch -p3 < $p; done
+
+For any changes that aren't specific to the git.git copy please submit
+a patch to the Gawk project and/or to the GNU C library (the Gawk
+regex engine is a periodically & forked copy from glibc.git).

-- 
2.11.0