от Курс за ССОК
Кръпка към изходния код (patch) се нарича текстовият файл, съдържащ разликите между оригиналния код и новия код. Имената на тези файлове, обикновено завършват на .patch или .diff. Кръпките могат да бъдат в текстов и двойчен вариант. В тази тема ще разгледаме само текстовия вариант, т.к. той се използва от всички проекти с отворен код.
Изпращайте кръпки, а не фрагменти код
Добра практика е винаги да изпращате кръпки към кода на проекта, по-които работите, вместо фрагменти код.
Кръпките имат следните предимсва:
- по-лесни за разбиране
- видими са само промените (добавени, изтрити редове код)
- по-малки по размер
- могат веднага да бъдат приложени към кода, ако бъдат одобрени
Изпращането на цели фрагменти код като нова дефиниция на функция или архивен файл с кода на проекта (в който са променени няколко файла) често води до отрицателен ефект. Това е така защото разработчиците на софтуера ще трябва сами да създадат текстовия файл с разликите, за да разберат какво се е променило.
Добре форматирано съобщение по ел. поща трябва:
- заглавието да започва с [PATCH] за улеснение на филтрите за ел. поща
- заглавието да описва възможно най-добре за какво са промените, без да е много дълго
- в текста на съобщението да са описани с няколко реда промените и най-важното от тях (пр. по сложни функции).
- Пример: https://www.redhat.com/archives/libvir-list/2008-July/msg00396.html
Пример за съобщение, което не отговаря на всички изисквания по-горе. Промените са тривиални и няма нужда от подробно описание, заглавието е достатъчно:
https://www.redhat.com/archives/anaconda-devel-list/2008-July/msg00067.html
Какво друго трябва да знаем при изпращането на кръпки
Разделяйте кръпките на по-малки файлове
Така те са по-лесни за преглед и асимилиране от останалите. Не изпращайте големи файлове, т.к. те обикновено се загубват. Разделението може да бъде по една кръпка за всеки променен файл или групирани по функционалност.
Бъдете сигурни, че софтуерът работи след промените
При някои езици трябва да се уверите, че най-малкото кода се компилира. При други е добре да изпълните програмата, за да се уверите, че вашите промени не причиняват проблем с други области на софтуера.
Прилагайте промените към послената версия на софтуера
Често, промени направени за по стара версия няма да работят с последната. Това е особено вярно при проекти, които се развиват бързо и кодът се променя драстично. В такива случай, ще се наложи да преработите кръпките към най-новата версия (т.нар. patch re-basing). Повечето проекти използват система за контрол на версиите, т.ч. нямате оправдание да не я използвате.
В случайте когато поправките са срещу по-стара версия, изрично упоменавайте това в писмата си и бъдете готови да ги преработите към най-новата версия.
Тествайте промените
Винаги тествайте промените, които правите. В случай, че не сте напишете в началото на писмото, че промените не са тествани. При големи проекти, разработчиците просто ще игнорират вашето писмо. Единственото на което можете да се надявате е да получите първоначални коментари по направените промени. Помнете, че програмистите полагат доброволен труд и ще ви изчакат да изтествате промените и да предоставите функциониращи кръпки. При малките проекти е възможно поправките ви да бъдат одобрени без тестване, но това води риск от поява на непредвидими грешки в бъдеще.
Обновете документацията и тестовете
При наличието на документация и/или автоматизирани тестове към софтуера, винаги е добра идея да ги обновите, особено в случаите на големи или важни промени. Когато документация или тестове не съществуват, не е късно да поставите началото. Дори да не сте супер програмист може да се окаже, че сте човека отговарящ за документацията, което ви поставя малко по-високо в невидимата йерархия на проекта.
Изгубени ел. писма / кръпки
Понякога се случва никои да не обърне внимание на труда ви, дори да сте обсъждали темата подробно преди това по ел. поща. Проблеми с Интернет или сървъра за ел. поща, хора отишли на почивка или просто много други задължения могат да доведат до това. Когато това се случи, изчакайте определено време (обикновено седмица-две е достатъчно), след което учтиво напомнете, че темата не е приключена. За да го направите, отговорете на собственото си писмо в пощенския списък с нещо от рода на:
Тази тема беше дискутирана преди ... и до сега нямаше възражения (или всички грешки или възражения срещу промените бяха оправени).
Моля някой друг да прегледа предложените поправки и да коментира върху тях.
Ако са достатъчно добри (отговарят на поставените условия (цели на проекта,... т.н.)), моля да бъдат приложени към изходния код.
Текста може да варира в зависимост от естеството на проекта и хората участващи в него, от по-сбит и директен до малко по-умерен. Никога не обиждайте и не критикувайте другите, за това, че не са ви обърнали внимание този път.
Пример за директно напомняне можете да видите на
https://www.redhat.com/archives/anaconda-devel-list/2008-August/msg00036.html
Пример за голяма част от изброените по-горе условия можете да видите на https://www.redhat.com/archives/anaconda-devel-list/2008-July/msg00102.html
- подробно описание на направените промени, т.к. не са тривиални
- промените са разделени функционално, т.к. половината от тях са в друг проект (независимо, че 2та проекта работят заедно, пр. използване на библиотека)
- има описание на проведените тестове - почти пълно множество от възможните варианти
- използвана е последната версия
- самите кръпки са изпратени като отговор на основното писмо, т.ч. да се получи
Основна тема
[PATCH] - кръпка 1
[PATCH] - кръпка две
Полезни команди при създаване на кръпки
Командите, които са в основата на създаване и прилагане на кръпки са diff и patch. diff се използва за създаване на текстов файл съдържащ промените между два файла/директории, а patch за прилагането на тези промени към текущия файл, за да се получи новия файл.
За примерите ще използваме файлът hello.c със следното съдържание:
#include <stdio.h>
int main(void)
{
printf("Hello World");
return 0;
}
diff
Програмата, която създадохме не отпечатва нов ред в края на текста. За да променим това правим копие на файла с
cp hello.c hello.c.orig, след което променяме printf на
printf("Hello World\n");
Разликата между двата файла получаваме с:
$ diff -u hello.c.orig hello.c
--- hello.c.orig 2008-08-31 12:00:04.000000000 +0300
+++ hello.c 2008-08-31 12:00:16.000000000 +0300
@@ -2,6 +2,6 @@
int main(void)
{
- printf("Hello World");
+ printf("Hello World\n");
return 0;
}
За да запазим разликите във файл използваме diff -u hello.c.orig hello.c > newline.patch
Винаги използвайте -u и поставяйте на първо място оригиналния файл.
При промяна на много файлове, първо направете резервно копие на директорията, след което
diff -ur myprogram-dir.orig myprogram-dir > new-feature.patch
patch
За да приложим направените промени към оригиналния файл използваме програмата patch. Поставете оригиналната версия на файловете hello.c и newline.patch в празна директория (симулирайки компютъра на друг програмист), след което
$ patch < newline.patch
patching file hello.c
След гората операция, файлът hello.c вече отпечатва нов ред в края на текста.
Можете да възстановите първоначалния вид на файла с patch -R < newline.patch
Системи за контрол на версиите на софтуера
При тези системи съществуват по-гъвкави команди, които дават възможност да се създават кръпки в различни формати и с различни опции. Най-често използваните са:
Проверете ръководството на командите и практиките на въпросния проект, за да разберете кои е най-подходящия формат за изпращане на кръпки. Това увеличава шансовете те да бъдат приети от останалите в проекта.
