Because I always forget, here’s a reminder to myself on how to use
git format-patch and
git send-email from the command line.
The following process applies to many other mailing-list based projects as well, with local differences in helper scripts.
The following example is for contributing to the [Buildroot Project], but the process is much the same for other mailing list-based projects.
Make your changes on an up-to-date branch from Buildroot master
$ git checkout -b package/foo $ git fetch --all --tags $ git rebase origin/master
Use logical commits; upgrade package as one, changing/extending behavior as another, etc.
Use commit messages to record why changes are made. First line is a summary referencing the sub-system, followed by an empty line and the message body, and concluded by your sign-off:
package/foo: bump version to v1.2.3 Signed-off-by: Your Name <email@example.com>
Verify formatting of package files; .in, .mk, etc.
$ ./utils/check-package package/foo/*
If you change or add a new package, verify you don’t introduce any recursive dependencies, or other nasty surprises. Remember, the build systems includes all
.mkfiles into one big Makefile, so any changes you make are seen by all other packages.
$ make menuconfig # complains if you have recursive deps. $ make <pkg>-rebuild # check output of build
Test your package/change with a set of cross-compilation toolchains. The
.configfile is a menuconfig snippet enabling the package to test:
$ ./utils/test-pkg -c foo.config -p foo
Output goes in
~/br-test-pkg/, check all logs. Some toolchains can help you track down issues with your package you won’t see elsewhere.
Format your patches, with the optional
--cover-letter, very useful to explain a series of patches:
$ git format-patch --cover-letter -M -n -s -o mail origin/master
Remember to edit the cover letter — it serves as an introduction and explains the reasoning behind your changes. Focus on the why, not the how, the patches have separate commit messages
Figure out DEVELOPERS to Cc in your correspondence to the mailing list:
$ ./utils/get-developers mail/* git send-email --to firstname.lastname@example.org --cc email@example.com
At the very least, the following should be output:
git send-email --to firstname.lastname@example.org
mail/*to send. You and others in Signed-off-by, Reviewed-by: are Cc:ed by default
$ git send-email --to email@example.com --cc firstname.lastname@example.org mail/*
You are offered one last chance to proofread the contents (remember to check the email headers!) before you send.
Note: if you haven’t set up your
~/.gitconfigyet for sending email, please see https://git-scm.com/docs/git-send-email or my blog post https://troglobit.com/post/2022-01-24-gmail-and-git-send-email/ for details.