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/
