configure создателя заплаты и куратора. Такой файл создается с помощью autoconf.
Такой подход является необдуманным и означает, что получатель будет вынужден отделять действительное содержание заплаты от большого количества шума. Данная ошибка незначительна, она не настолько важна, как некоторые из рассматриваемых далее, однако она не делает чести создателю заплаты.
19.2.1.4. Не отправляйте заплат, которые только убирают $-идентификаторы систем RCS или SCCS
Некоторые разработчики вносят специальные метки в свои исходные файлы, распространяемые с помощью системы контроля версий, когда возвращают отредактированные файлы, например, конструкции $Id$, используемые в системах RCS и CVS.
Если используется локальная система контроля версий, то изменения могут модифицировать данные метки. Это не представляет реальной опасности, поскольку когда получатель снова зарегистрирует исправленный код после применения заплаты, метки будут переназначены снова в соответствии с состоянием системы контроля версий
Данная ошибка также является незначительной, и вас простят, если более важные изменения сделаны верно, однако ее следует в любом случае избегать.
19.2.1.5. Используйте вместо формата по умолчанию (-e) форматы - с или -u
Принятый по умолчанию в-е является крайне ненадежным. Он не включает в себя контекст, поэтому утилита patch не может справиться со своей задачей, если какие-либо строки были вставлены в код главной линии проекта или удалены с момента получения создателем заплаты своей копии кода.
Получение diff-файлов, созданных с ключом -e, раздражает и наводит на мысль, что отправитель либо крайне неопытен, либо неаккуратен, либо неграмотен. Большинство подобных заплат удаляется без размышлений.
19.2.1.6. Сопровождайте заплаты документацией
Данный момент очень важен. Если заплата вносит заметные пользователям дополнения или изменяет функции программы, то
Документирование изменений хорошо демонстрирует некоторые полезные качества. Во-первых, это вежливо по отношению к человеку, которого вы пытаетесь убедить. Во-вторых, это демонстрирует ваше понимание того, что смысл внесенного изменения достаточно важен для того, чтобы объяснять его тем, кто не видит код. В-третьих, это демонстрирует заботу о людях, которые, в конце концов, будут использовать данную программу.
Хорошая документация обычно является наиболее заметным признаком, который позволяет отличить солидный вклад от быстрой и неаккуратной работы. Если созданию документации уделить необходимое время и внимание, то вскоре обнаружится, что пройдено 85% пути к принятию заплаты большинством разработчиков.
19.2.1.7. Сопровождайте заплату пояснениями
Заплата должна включать в себя пояснительную записку, объясняющую необходимость или практическую пользу заплаты с точки зрения ее создателя. Данное пояснение адресовано не пользователям программного обеспечения, а его куратору, принимающему заплату.
Записка может быть краткой, фактически некоторые из наиболее эффективных пояснительных записок, которые встречались автору, содержали в себе только одну мысль: 'См. обновления документации в данной заплате'. Однако записка должна демонстрировать правильное отношение к работе.
Правильное отношение полезно, оно демонстрирует уважение к времени куратора; подобные записки весьма конфиденциальны, но непритязательны. Правильно будет показать понимание исправляемого кода, а также то, что создатель заплаты способен разделить проблемы куратора. Также хорошо закончить упоминанием о любых осознаваемых рисках, связанных с применением заплаты. Ниже приводится несколько примеров пояснительных комментариев, которые отправляют опытные разработчики.
'Я обнаружил в коде две проблемы, X и Y. Проблему X я решил, а проблему Y даже не пытался рассматривать, поскольку не думаю, что понимаю ту часть кода, которая, как я полагаю, с ней связана.'
'Исправил ошибки по дампу, которые могут возникать, когда какой-либо foo-ввод является слишком длинным. В ходе решения проблемы я искал подобные переполнения в других местах. Возможная причина переполнения находится в файле blarg.c, где-то около строки 666. Вы уверены, что отправитель не может сгенерировать более 80 символов в течение одной передачи?'
'Вы рассматривали использование Foonly-алгоритма для решения данной проблемы? Здесь есть пример хорошей реализации — <http://www.example.com/~jsmith/foonly.html>.'
'Данная заплата решает первоочередную проблему, но я понимаю, что она неприятно усложняет распределение памяти. У меня заплата работает, однако перед распространением ее, вероятно, следует протестировать под большой нагрузкой.'
'Возможно, это — украшательство, но я в любом случае его отправляю. Может быть, вам известен более четкий способ реализации данной функции'.
19.2.1.8. Включайте в код полезные комментарии
Куратор хочет иметь полную уверенность в том, что понимает вносимые заплатой изменения, прежде чем объединить их с основным кодом. Данное правило не является неизменным. Если создатель заплаты имеет стаж хорошей работы с куратором, то куратор может только бегло просмотреть изменения перед их почти автоматическим применением. Но все, что можно сделать, чтобы помочь ему понять код и уменьшить неуверенность, увеличивает вероятность того, что заплата будет принята.
Хорошие комментарии в коде помогают куратору понять его, а плохие мешают.
Ниже приводится пример плохого комментария.
/* норман ньюби исправил этот код 13 августа 2001 года */
Данный комментарий не несет в себе никакой информации — просто помарка в центре кода
