Patching of archived or unmaintained grammars

[Alhadis]

Presently, our approach to improving an unmaintained grammar module has been to fork it or replace it with one that's actively-maintained. In most cases, this solution is a no-brainer. However, there are cases when this isn't desirable or even possible:

• Users who report highlighting errors in an old, unmaintained repository may fork it, fix the issue, and then abandon their fork in the future, essentially propagating the original problem.
• There won't always be an actively-maintained grammar, especially for older and more obscure languages.
• If an author is taking a hiatus from GitHub, their grammars may appear to be unmaintained.¹ If they return after somebody's made a fork of their work to fix a particular issue, any recent upstream activity will probably be unnoticed.
• The highlighting issue may simply be a matter of portability: an author may depend on regex features that have conflicting syntaxes in Oniguruma and PCRE,² with no way of reconciling the difference without introducing new problems.

In situations like these, it might make more sense to patch the submodule³ using a locally-tracked .patch file (which could be applied prior to running the grammar-compiler). This has the advantage that it can be easily generated from a pull-request submitted to the original grammar (where the owner hasn't responded in quite some time), and the patch files can simply be deleted when or if they're finally merged upstream.

Patches could be added to vendor/patches/ with filenames of the form ocaml.tmbundle.1.patch (the name of the submodule entry under vendor/grammars, followed by an incremental counter tracking the order in which multiple patches are to be applied). It could contain either a unified diff or git-format-patch(1) output.

Example: ocaml.tmbundle.1.diff

diff --git a/Syntaxes/OCaml.plist b/Syntaxes/OCaml.plist
index c28d2ed..6fbc203 100644
--- a/Syntaxes/OCaml.plist
+++ b/Syntaxes/OCaml.plist
@@ -17,6 +17,27 @@
 	<string>OCaml</string>
 	<key>patterns</key>
 	<array>
+		<dict>
+			<key>name</key><string>string.interpolated.ocaml</string>
+			<key>begin</key><string>\\|</string>
+			<key>end</key><string>\\|</string>
+			<key>beginCaptures</key>
+			<dict>
+				<key>0</key>
+				<dict>
+					<key>name</key>
+					<string>punctuation.definition.string.begin.ocaml</string>
+				</dict>
+			</dict>
+			<key>endCaptures</key>
+			<dict>
+				<key>0</key>
+				<dict>
+					<key>name</key>
+					<string>punctuation.definition.string.end.ocaml</string>
+				</dict>
+			</dict>
+		</dict>
 		<dict>
 			<key>captures</key>
 			<dict>

Thoughts?

/cc @lildude, @Visne

Footnotes

1. Something I frequently worry about with my own grammars; I wasn't able to properly investigate SVG grammar broken Alhadis/language-etc#11 until I was at a workstation. ↩

2. For example, Oniguruma uses \g<…> for subroutine calls, while Perl/PCRE uses \k<…> instead and treats \g<…≥ as a numbered backreference to a capturing group. ↩

3. Full disclosure: this is essentially Homebrew's approach to patching formulae that I'm shamelessly ripping off I've learned works well for submodules I CBFA maintaining a fork of. ↩

[lildude]

Perfect timing. I was just thinking about such an approach when recently trawling through and updating all the current grammar issues in prep for this most recent release. All of the issues which aren't for long lines, now have upstream issues, but I'm not expecting much traction on them so this would be a perfect compromise.

I like it 👍