Advocacy for patches
Written 2023-01-01
Updated 2023-01-02 (fixed typo)
This is an [opinion] article. Opinions expressed are mine. Please do not interpret this article as truth or fact. Occasionally, I may express opinion as fact accidentally. Please forgive me. I am not a source of authority.
Introduction
In this blog post, I advocate for the use of patches (.patch files) for contributing things to projects.
What are patches?
diff(1), git-diff(1), git-format-patch(1) generate patches. They can be applied to files with patch(1) and/or git-apply(1). These files are easy to distribute and embed in text.
Patches are {editor,version control} agnostic
No special tools are needed to view a patch file in its intended form: only a text editor, web browser, or anything that can display text in a readable form. Here is a patch:
--- a/test.c 2023-01-01 21:55:48.113470274 +0800
+++ b/test.c 2023-01-01 21:56:15.623824727 +0800
@@ -3,5 +3,5 @@
int
main(void)
{
- printf("hello, world\n");
+ puts("hello, world\n");
}
(Generated with diff -up a/test.c b/test.c.)
The - marks a deletion while + marks an addition.
As you can see, it is readable even when confined in a web browser without any
sort of syntax highlighting.
Applying it is trivial: simply patch -p0 <patchfile, and you have
your new file. Amazing!
Even if the contributor decides to download an archive of a repository instead of fetching it with git(1) or some other tool, they can still contribute. No one is left out. Many editors including Emacs also have built-in tools to handle diff files.
Patches are transparent
A patch shows exactly what it does. It is guaranteed that it does not do anything more, and thus is perfect for RFC posts, since code reviewers/etc can reply to the thread quoting exactly what they are referring to, using the tools they already have (an email client).
Patches are easier to distribute
Patches are nothing but a text file, meaning they can be embedded in a wiki (although not a very good idea, unless they are signed in some way), stored in a textual archive (mailing lists?), and require little effort to handle. They can also be distributed easily through web servers.
On the other hand, pull requests require:
- something serving git (or whatever version control framework is used)
- pulling the repository outside of the original pull request message
- (optional but very useful) getting a diff manually of the two repositories for easier reading
Conclusion
Patches are (in my opinion) a great way to distribute contributions to software, due to their accessibility, ease of distribution, and transparency.
(This site also looks a bit like a diff, with the red and green :)