How-to: git messages

Однажды в жизни начинающего мейнтейнера возникает момент, когда нужно добавить что-то в основную часть системы (к примеру, в ядро). И ты, такой радостный и счастливый, присылаешь свой патч кому-нибудь из старших, а он возьми да и спроси: "А что это, и зачем оно нужно?" В этот момент тебе и ответить-то нечего, тебе твои изменения кажутся вполне очевидными и полезными, а старший просто не видит "всей глубины твоих глубин"...

Вполне возможно, что так оно и есть - человек не в полной мере владеет вопросом (не в контексте того, чем ты был занят), и ему нужно получить больше информации, чтобы составить более-менее полную картину того, что твориться у тебя в голове. Также возможно (если тот, к кому ты обратился - спец по твоему вопросу) то, что человек тебя проверяет, как бы спрашивает тебя: "А ты сам понимаешь, какие изменения внесут твой патч?"

Для того, чтобы таких вопросов у старших не возникало, нужно сразу грамотно составить письмо, из которого принимающему будет понятно, какие изменения ты предлагаешь, и правильно оформить патч.

Само собой разумеется, что изменения должны быть проверены и протестированы, иначе из-за невнимательности эти изменения могут вылиться в проблему, причину которой придётся искать не один день

Итак, начнём с формирования патча. 1. Вносим свои изменения. 2. Закрепляем свои изменения, внятно описав суть своих изменений в теле коммита:

git commit -a --signoff

где signoff - твоя подпись.

Пример оформления коммита (пример реальный):

Enabling support of sound chip in Steam Deck

Details of device: https://www.steamdeck.com/en/tech

Details of audio module ("Hardware notes" > "Audio"):
https://open-sd.gitlab.io/opensd-docs/opensd-docs/latest/hardware_notes/audio.html

This patch enabling:

 - support of Rembrandt Radeon High Definition
   Audio Controller used in Steam Deck handheld
   (https://linux-hardware.org/?id=pci:1002-1640-1e44-1776);

Changes tested on original hardware, kernel un-def 6.3.7

Signed-off-by: Artyom Bystrov <arbars@altlinux.org>

Да, навыки английского языка тут будут как минимум не лишними. На крайний случай можно воспользоваться словарём и автопереводчиком. Теперь формируем патч:

git format-patch --no-stat -1 HEAD

На выходе мы должны получить файл-патч с текстом коммита типа такого:

From 92cfb848fbbcdea316101910888e17e70c2657ef Mon Sep 17 00:00:00 2001
From: Artyom Bystrov <arbars@altlinux.org>
Date: Wed, 14 Jun 2023 02:09:51 +0300
Subject: [PATCH] Enabling support of sound chip in Steam Deck

Details of device: https://www.steamdeck.com/en/tech

Details of audio module ("Hardware notes" > "Audio"):
https://open-sd.gitlab.io/opensd-docs/opensd-docs/latest/hardware_notes/audio.html

This patch enabling:

 - support of Rembrandt Radeon High Definition
   Audio Controller used in Steam Deck handheld
   (https://linux-hardware.org/?id=pci:1002-1640-1e44-1776);

Changes tested on original hardware, kernel un-def 6.3.7

Signed-off-by: Artyom Bystrov <arbars@altlinux.org>

После текста коммита, как правило, идёт сам патч.

После того, как мы сформировали наш патч, стоит его показать паре людей, разбирающихся в вопросе - они могут подсказать, что поправить, а что трогать не стоит. После проверки и тестирования патч можно отправить старшему мейнтейнеру.