• Immutable Page
  • Info
  • Attachments

Diff for "HowToWriteAChangelog"

Differences between revisions 3 and 4

Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
When creating a patch for submission to the Linux kernel there are specific guidlines you should follow. This page will attempt to outline them. This [https://chris.beams.io/posts/git-commit/ blog post] on writing git changelog messages is quite informative, although not kernel specific and not everything is relevant, for example, there is a tendency among kernel developers to not capitalize text in the subject line. When creating a patch for submission to the Linux kernel there are specific guidlines you should follow.
Line 19: Line 19:
The subject should use imperative mood. For an explanation of imperative mood see the blog post linked above. The subject should use imperative mood. For an explanation of imperative mood see the kernel documentation (Describe your changes, linked below).
Line 25: Line 25:
How to write the body of a changelog is addressed in the kernel tree documentation. Specifically in submitting-patches.rst Section 2 [https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes Describe your changes]. How to write the body of a changelog is addressed in the kernel tree documentation. Specifically Section 2 of [https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes Describe your changes].

When creating a patch for submission to the Linux kernel there are specific guidlines you should follow.

Subject

The subject line of your commit should be prefixed with the subsystem:

staging: ks7010: remove local variable foo

You can get some hint on which prefix to use by checking the commit history of a specific file:

git log --pretty=oneline --abbrev-commit path/to/file

There may be multiple prefixes used previously, you may need to check other files in the subsystem to see the preferred style.

Subject lines not longer than approximately 50 characters ease later development.

The subject should use imperative mood. For an explanation of imperative mood see the kernel documentation (Describe your changes, linked below).

Body

You may like to wrap text in the body of the changelog at approximately 72 characters.

How to write the body of a changelog is addressed in the kernel tree documentation. Specifically Section 2 of Describe your changes.

While there are plenty of examples of how not to do this on LKML it will greatly help with getting your patches merged if you take time to thoroughly and correctly write the changelog. This also helps reviewers and maintainers review your patches. It also helps future developers if they view your patches while bug hunting.

Writing clean, bug free, code includes writing descriptive and technically correct changelog messages. The process of writing changelog messages has the added advantage of greatly improving ones written skills and ones knowledge of the kernel, the C programming language, and programming technique in general.

See also first kernel patch, git tips and patch tips and tricks.

Tell others about this page:

last edited 2017-04-18 02:59:17 by Tobin Harding