The Perfect Patch

Dokument został przetłumaczony za zgodą Andrew Mortona. Jeżeli znajdziesz błąd w tłumaczeniu, to możesz go poprawić. Jeżeli masz własne spostrzeżenia na temat omawianego tutaj zagadnienia, to po prostu zrób przypis na dole strony.

Wersja oryginalna znajduje się tutaj: http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt

Doskonała łatka.
gro.ldso|mpka#gro.ldso|mpka
Zaktualizowany 12 Sty 2006

Najnowsza wersja tego dokumentu może być znaleziona tutaj: http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt

Proszę również przeczytać http://linux.yyz.us/patch-format.html

1: Doręczanie

==

a) Łatki mogą być doręczane tylko i wyłącznie za pomocą e-maili. Pobieranie ich z serwerów nie należy do przyjemności.

b) Jedna łatka na jednego e-maila z listą zmian w treści listu.

2: Temat

==

a) Temat e-maila powinien treściwie opisywać łatkę zawartą w liście. Tematem nie powinna być nazwa pliku. Nie używaj tego samego tematu do wszystkich łatek w serii.

Pamiętaj, że Temat: Twojego listu staje się globalnie unikatowym identyfikatorem łatki. Propaguje się na wiele sposobów w systemie kontroli wersji kernela. Tytuł: może być później używany podczas dyskusji developerów w odniesieniu do łatki. Ludzie będą googlować w poszukiwaniu łatki o Tytule:, żeby przeczytać dyskusje odnoszące się do niej.

b) Podczas wysyłania serii łatek, każda z nich powinna być kolejno ponumerowana w Temacie:

c) Byłoby miło, gdyby w Temacie: było wspomniane którego podsystemu to dotyczy. Zobacz przykład poniżej.

d) Przykładowy Temat:

[patch 2/5] ext2: improve scalability of bitmap searching

e) Zauważ, że skrypty odbierające łatki używane przez niektórych ludzi wyrzucają z Tematu: tekst umieszczony w nawiasach []. Powinieneś więc umieszczać tam informacje, które nie mają długoterminowego związku z tematem łatki. Należy w to włączać słowo “patch” i numer łatki. Identyfikator podsystemu (“ext2:”) powinien znaleźć się poza nawiasami.

3: Zaznaczenie autorstwa (kto popełnił tą łatkę)

==

Jeżeli ktoś inny napisał łatkę, powinno być to zaznaczone, żeby było wiadomo, kogo za nią chwalić (i winić).
Aby to zakomunikować, dodaj na samym początku e-maila linię:

From: John Doe <moc.reverehw|eodj#moc.reverehw|eodj>

Wtedy program zapamięta to i jdoe w git dostanie linijkę “Author”.

4: Lista zmian

==

a) Pamiętaj, że Temat: i lista zmian które dostarczasz, zostaną zapisane na stałe. Inni developerzy mogą chcieć przeczytać i zrozumieć twoją łatkę i listę zmian w odległej przyszłości.

Lista zmian powinna opisywać łatkę bardzo dokładnie:

- dlaczego jądro wymaga łatania

- ogólne zamiary *FIXME* the overall design approach in the patch *FIXME*

- detale dotyczące implementacji

- rezultaty testów

b) Nie musisz wspominać, że łatka aplikuje się na * ("applies to 2.6.8-rc1"). To nie jest interesująca informacja – jeżeli łatka jest na jądro z kernel.org jest oczywiste, że się aplikuje i prawdopodobnie może zostać włączona do późniejszej wersji jądra niż ta, na którą ją napisałeś.

c) Nie opisuj łatek w stylu “ta łatka robi…” lub “tu jest łatka, która…”. Nie ma sensu mówić nam, że to jest łatka, jeśli jest ona w SCM – _wiemy_, że to jest łatka!

d) Przy opisywaniu zmian nie odnoś się do wcześniejszych łatek. Nie jest zbyt użyteczne posiadanie skończonej listy zmian w której można przeczytać “OK, to naprawia błędy o których wczoraj wspominałeś“. Każda wersja łatki powinna zawierać ujednoliconą listę zmian. To sugeruje, że potrzebujesz systemu zarządzania łatkami, który utrzymuje listy zmian. (Patrz niżej)

e) Dodaj linię Signed-off-by: zgodnie z Documentation/SubmittingPatches (dokumentacja jądra).

Signed-off-by: sugeruje, że jesteś autorem jakiejś części poprawki lub tworzyłeś ją kiedyś i oddałeś ją innemu developerowi do włączenia.

Jeżeli twoja rola ograniczała się do przejrzenia i przetestowania łatki, użyj Acked-by:

Czasami też używamy Cc: w łatce, aby poszczególni ludzie znali aktualny status poprawki i mieli możliwość przejrzenia jej.

f) Większość ludzi w swoich skryptach odbierających poprawki, traktuje ciąg znaków ^—- jako separator pomiędzy listą zmian a samą łatką. Możesz tego używać żeby mieć pewność, że każda informacja diffstat zostanie odrzucona kiedy łatka będzie aplikowana:

Another few #if/#ifdef cleanups, this time for the PPC architecture.
        Signed-off-by: <valdis.kletnieks@vt.edu>
        Signed-off-by: Andrew Morton <akpm@osdl.org>
        ---
         25-akpm/arch/ppc/kernel/process.c                    |    2 +-
         25-akpm/arch/ppc/platforms/85xx/mpc85xx_cds_common.c |    2 +-
         25-akpm/arch/ppc/syslib/ppc85xx_setup.c              |    4 ++--
         3 files changed, 4 insertions(+), 4 deletions(-)
        --- 25/arch/ppc/kernel/process.c
        +++ 25/arch/ppc/kernel/process.c
        @@ -667,7 +667,7 @@ void show_stack(struct task_struct *tsk,

g) Tekst nie odnoszący się do listy zmian:

Czasami chcesz włączyć do listu elektronicznego tekst, który nie powinien trafić do listy zmian w repozytorium git (np. wzmianki w stylu “to jest aktualnie w drzewie Bolebora” lub “to jest poprawiona wersja piątkowej łatki” lub cokolwiek innego).

Po prostu umieszczasz taki tekst poniżej separatora “^—-”, wtedy zostanie on automatycznie usunięty podczas umieszczania w systemie kontroli wersji.

5: Diff

==

a) Łatki powinny być formacie 'patch -p1':

--- a/kernel/sched.c
  +++ b/kernel/sched.c

b) Upewnij się, że łatka aplikuje się na najnowsze jądro - albo na drzewo git Linusa, albo na najnowszą wersje z ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/

c) Gdy chcesz dodać jakąś łatkę do -mm najlepiej jest, gdy jest ona oparta o najnowsze drzewo Linusa. Wyrzucam wszystkie poprawki odrzucane/niekompatybilne. Oczywiście są od tego odstępstwa.

d) Upewnij się, że Twoja poprawka nie wprowadza nowych białych spacji. Poniższy skrypt naprawi Twoją łatkę, wycinając z niej białe spacje.

#!/bin/sh
        strip1()
        {
                TMP=$(mktemp /tmp/XXXXXX)
                cp $1 $TMP
                sed -e '/^+/s/[         ]*$//' < $TMP > $1
                rm $TMP
        }
        for i in $*
        do
                strip1 $i
        done

6: Uogólniając

==

a) Jeżeli jest to możliwe, unikaj MIME i załączników. Upewnij się, że Twój program pocztowy nie zawija wierszy. Upewnij się, że Twój program pocztowy nie zamienia tabulacji na spacje.

Najpierw wyślij łatkę do siebie i sprawdź czy dalej można ją zaaplikować.

b) Jeżeli to wszystko zawiedzie, wtedy łatka, niechętnie bo niechętnie, może zostać wysłana w załączniku. Musisz się upewnić, że załączone poprawki mają typ mime text/plain.

Skrypty do zarządzania łatkami z http://www.zip.com.au/~akpm/linux/patches/ implementują wszystkie powyższe wytyczne.

Narzędzia do zarządzania łatkami z https://savannah.nongnu.org/projects/quilt/ również implementują wszystkie powyższe wytyczne.

Wiele przykładowych łatek można znaleźć tutaj: ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/

O ile nie zaznaczono inaczej, treść tej strony objęta jest licencją Creative Commons Attribution-Share Alike 2.5 License.