고급 주제: Git tree와 patch review

정기적인 kernel 개발 참여를 위한 고급 주제

개발 절차의 기본을 익힌 뒤 정기적으로 Linux kernel 개발에 참여하려는 developer에게 도움이 되는 Git tree 관리와 patch review 주제를 다룬다.

기본 개발 절차를 익힌 뒤에는 patch series를 넘어 Git tree를 안전하게 운영하고 다른 사람의 patch를 검토하는 역할로 범위를 넓힐 수 있습니다. 이 문서는 정기 contributor와 maintainer로 성장할 때 필요한 두 영역을 연결합니다.

.. include:: ../disclaimer-ita.rst

:Original: :ref:`Documentation/process/7.AdvancedTopics.rst <development_advancedtopics>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

.. _it_development_advancedtopics:

Argomenti avanzati
==================

A questo punto, si spera, dovreste avere un'idea su come funziona il processo
di sviluppo.  Ma rimane comunque molto da imparare!  Questo capitolo copre
alcuni argomenti che potrebbero essere utili per gli sviluppatori che stanno
per diventare parte integrante del processo di sviluppo del kernel.

분산 version control과 공개 Git server

Kernel의 분산 version control 사용은 Linus가 proprietary BitKeeper를 시험한 2002년 초에 시작되었다. BitKeeper 자체는 논란이 있었지만 분산 version 관리 방식은 kernel 개발을 즉시 가속했다. 이후 여러 free 대안이 등장했고 kernel project는 Git을 표준 도구로 선택했다.

Patch 수가 늘어날수록 Git은 developer의 작업을 크게 단순화하지만 강력한 만큼 위험과 거친 부분도 있다. 이 문서는 Git 사용법 자체보다 Git이 kernel 개발 절차에 어떻게 들어가는지 설명한다.

• Git 공식 사이트https://git-scm.com/
• Git user manualhttps://www.kernel.org/pub/software/scm/git/docs/user-manual.html

다른 사람이 사용할 patch를 Git으로 제공하기 전에 mainline repository 복제, revision history 탐색, commit, branch를 확실히 익혀야 한다. Rebase 같은 history rewriting 도구와 ref, remote branch, index, fast-forward merge, push, pull, detached HEAD 같은 용어도 이해해야 한다.

처음에는 email 제출용 patch를 Git으로 생성하는 연습이 좋다. 다른 사람이 pull할 tree를 공개하려면 Internet에서 접근할 Git server가 필요하다. git-daemon으로 직접 구성하거나 public hosting을 사용할 수 있다. Established developer는 kernel.org account를 얻을 수 있지만 쉽지는 않으며 https://kernel.org/faq/를 참고한다.

Linux는 BitKeeper 경험을 거쳐 Git을 source 관리 표준으로 선택했습니다. Patch 수가 늘수록 branch와 history 도구가 작업을 단순화하지만, mainline repository 복제, revision 탐색, commit, `rebase`, ref, remote branch, index, fast-forward, push·pull과 detached HEAD 개념을 먼저 익혀야 합니다.

Email 제출용 patch를 Git으로 생성하는 연습부터 시작한 뒤 다른 사람이 pull할 수 있는 공개 server를 준비합니다. Internet에 노출된 `git-daemon`, Github 같은 public hosting 또는 자격을 갖춘 개발자의 kernel.org account를 사용할 수 있으며 공개 전에 접근성과 실제 pull 가능 여부를 확인합니다.

Gestire le modifiche con git
-----------------------------

L'uso di un sistema distribuito per il controllo delle versioni del kernel
ebbe iniziò nel 2002 quando Linux iniziò a provare il programma proprietario
BitKeeper.  Nonostante l'uso di BitKeeper fosse opinabile, di certo il suo
approccio alla gestione dei sorgenti non lo era.  Un sistema distribuito per
il controllo delle versioni accelerò immediatamente lo sviluppo del kernel.
Oggigiorno, ci sono diverse alternative libere a BitKeeper.  Per il meglio o il
peggio, il progetto del kernel ha deciso di usare git per gestire i sorgenti.

Gestire le modifiche con git può rendere la vita dello sviluppatore molto
più facile, specialmente quando il volume delle modifiche cresce.
Git ha anche i suoi lati taglienti che possono essere pericolosi; è uno
strumento giovane e potente che è ancora in fase di civilizzazione da parte
dei suoi sviluppatori.  Questo documento non ha lo scopo di insegnare l'uso
di git ai suoi lettori; ci sarebbe materiale a sufficienza per un lungo
documento al riguardo.  Invece, qui ci concentriamo in particolare su come
git è parte del processo di sviluppo del kernel.  Gli sviluppatori che
desiderassero diventare agili con git troveranno più informazioni ai
seguenti indirizzi:

	https://git-scm.com/

	https://www.kernel.org/pub/software/scm/git/docs/user-manual.html

e su varie guide che potrete trovare su internet.

La prima cosa da fare prima di usarlo per produrre patch che saranno
disponibili ad altri, è quella di leggere i siti qui sopra e di acquisire una
base solida su come funziona git.  Uno sviluppatore che sappia usare git
dovrebbe essere capace di ottenere una copia del repositorio principale,
esplorare la storia della revisione, registrare le modifiche, usare i rami,
eccetera.  Una certa comprensione degli strumenti git per riscrivere la storia
(come ``rebase``) è altrettanto utile.  Git ha i propri concetti e la propria
terminologia; un nuovo utente dovrebbe conoscere *refs*, *remote branch*,
*index*, *fast-forward merge*, *push* e *pull*, *detached head*, eccetera.
Il tutto potrebbe essere un po' intimidatorio visto da fuori, ma con un po'
di studio i concetti non saranno così difficili da capire.

Utilizzare git per produrre patch da sottomettere via email può essere
un buon esercizio da fare mentre si sta prendendo confidenza con lo strumento.

Quando sarete in grado di creare rami git che siano guardabili da altri,
vi servirà, ovviamente, un server dal quale sia possibile attingere le vostre
modifiche.  Se avete un server accessibile da Internet, configurarlo per
eseguire git-daemon è relativamente semplice .  Altrimenti, iniziano a
svilupparsi piattaforme che offrono spazi pubblici, e gratuiti (Github,
per esempio).  Gli sviluppatori permanenti possono ottenere un account
su kernel.org, ma non è proprio facile da ottenere; per maggiori informazioni
consultate la pagina web https://kernel.org/faq/.

topic branch와 공개 history의 불변성

일반적인 Git workflow는 개발 line마다 독립적인 topic branch를 많이 사용한다. Git branch는 비용이 작으므로 적극적으로 활용한다.

다른 사람에게 pull을 요청할 public branch에서 직접 개발해서는 안 된다. Public branch는 신중하게 만들고 development branch의 patch가 완전하고 제출 가능한 상태가 된 뒤에만 merge한다.

Git은 bisection을 깨는 patch나 명백한 bug를 고치거나 history에서 제거하고, 수개월 개발한 patch series를 최신 mainline 위에서 작성한 것처럼 다시 구성하며, branch 사이에 변경을 옮길 수 있다. 신중한 history revision은 깨끗한 patch set을 만드는 데 유용하다.

하지만 history를 다시 쓰면 시험한 tree가 새로운 미시험 tree로 바뀐다. 다른 developer가 이미 pull한 history를 바꾸면 공통 history view가 사라져 협업이 매우 어려워진다. 따라서 외부에 공개한 history는 원칙적으로 immutable하게 취급한다.

Public server에 push한 변경은 다시 쓰지 않는다. Git은 fast-forward가 아닌 push를 기본적으로 거부해 이 규칙을 돕는다. linux-next conflict를 피하려고 changeset을 tree 사이에 옮기는 예외가 있을 수 있지만 드물어야 한다. 개발은 rewrite 가능한 private branch에서 하고 충분히 성숙한 뒤 public branch로 옮긴다.

개발 line마다 private topic branch를 만들고 bisection을 깨는 commit, 명백한 bug와 series 순서를 `rebase` 등으로 정리합니다. 다른 사람이 pull할 public branch에는 완성되고 제출 가능한 patch만 옮깁니다.

한 번 공개한 history를 다시 쓰면 이미 pull한 개발자의 공통 ancestry가 깨지고 검증된 tree도 새로운 미검증 tree가 됩니다. non-fast-forward push가 기술적으로 가능하더라도 `linux-next` 충돌 조정 같은 드문 예외가 아니면 공개 history는 immutable하게 유지합니다.

In git è normale avere a che fare con tanti rami.  Ogni linea di sviluppo
può essere separata in "rami per argomenti" e gestiti indipendentemente.
In git i rami sono facilissimi, per cui non c'è motivo per non usarli
in libertà.  In ogni caso, non dovreste sviluppare su alcun ramo dal
quale altri potrebbero attingere.  I rami disponibili pubblicamente dovrebbero
essere creati con attenzione; integrate patch dai rami di sviluppo
solo quando sono complete e pronte ad essere consegnate - non prima.

Git offre alcuni strumenti che vi permettono di riscrivere la storia del
vostro sviluppo.  Una modifica errata (diciamo, una che rompe la bisezione,
oppure che ha un qualche tipo di baco evidente) può essere corretta sul posto
o fatta sparire completamente dalla storia.  Una serie di patch può essere
riscritta come se fosse stata scritta in cima al ramo principale di oggi,
anche se ci avete lavorato per mesi.  Le modifiche possono essere spostate
in modo trasparente da un ramo ad un altro.  E così via.  Un uso giudizioso
di git per revisionare la storia può aiutare nella creazione di una serie
di patch pulite e con meno problemi.

Un uso eccessivo può portare ad altri tipi di problemi, tuttavia, oltre
alla semplice ossessione per la creazione di una storia del progetto che sia
perfetta.  Riscrivere la storia riscriverà le patch contenute in quella
storia, trasformando un kernel verificato (si spera) in uno da verificare.
Ma, oltre a questo, gli sviluppatori non possono collaborare se non condividono
la stessa vista sulla storia del progetto; se riscrivete la storia dalla quale
altri sviluppatori hanno attinto per i loro repositori, renderete la loro vita
molto più difficile.  Quindi tenete conto di questa semplice regola generale:
la storia che avete esposto ad altri, generalmente, dovrebbe essere vista come
immutabile.

Dunque, una volta che il vostro insieme di patch è stato reso disponibile
pubblicamente non dovrebbe essere più sovrascritto.  Git tenterà di imporre
questa regola, e si rifiuterà di pubblicare nuove patch che non risultino
essere dirette discendenti di quelle pubblicate in precedenza (in altre parole,
patch che non condividono la stessa storia).  È possibile ignorare questo
controllo, e ci saranno momenti in cui sarà davvero necessario riscrivere
un ramo già pubblicato.  Un esempio è linux-next dove le patch vengono
spostate da un ramo all'altro al fine di evitare conflitti.  Ma questo tipo
d'azione dovrebbe essere un'eccezione.  Questo è uno dei motivi per cui lo
sviluppo dovrebbe avvenire in rami privati (che possono essere sovrascritti
quando lo si ritiene necessario) e reso pubblico solo quando è in uno stato
avanzato.

공개 tree의 merge와 rerere

Base tree가 발전할 때 private branch는 rebase로 따라갈 수 있지만 공개한 tree에는 rebase를 사용할 수 없고 full merge를 해야 한다. Merge 자체는 필요하지만 너무 자주 하면 history가 불필요하게 복잡해진다.

Mainline -rc release 같은 특정 지점에서 드물게 merge하는 방식을 권한다. 불안한 변경은 private branch에서 test merge할 수 있고 Git rerere는 이전 merge conflict 해결법을 기억해 같은 작업의 반복을 줄인다.

Private branch는 base를 따라 rebase할 수 있지만 공개 tree는 full merge로 갱신해야 합니다. Merge가 너무 잦으면 history가 복잡해지므로 mainline `-rc` 같은 명확한 release 지점에서 드물게 수행하고 실제 pull 요청 전 private branch에서 test merge합니다.

Git `rerere`는 이전 merge conflict 해결을 기억해 같은 충돌을 다시 해결하는 비용을 줄입니다. 다만 자동 재사용 결과도 반드시 검토하고 build와 test를 다시 수행해야 합니다.

Man mano che il ramo principale (o altri rami su cui avete basato le
modifiche) avanza, diventa allettante l'idea di integrare tutte le patch
per rimanere sempre aggiornati.  Per un ramo privato, il *rebase* può essere
un modo semplice per rimanere aggiornati, ma questa non è un'opzione nel
momento in cui il vostro ramo è stato esposto al mondo intero.
*Merge* occasionali possono essere considerati di buon senso, ma quando
diventano troppo frequenti confondono inutilmente la storia.  La tecnica
suggerita in questi casi è quella di fare *merge* raramente, e più in generale
solo nei momenti di rilascio (per esempio gli -rc del ramo principale).
Se siete nervosi circa alcune patch in particolare, potete sempre fare
dei *merge* di test in un ramo privato.  In queste situazioni git "rerere"
può essere utile; questo strumento si ricorda come i conflitti di *merge*
furono risolti in passato cosicché non dovrete fare lo stesso lavoro due volte.

review를 거친 tree와 pull request의 신뢰

Repository 사이에서 patch를 대량 이동하면 review를 피한 부적절한 변경이 mainline에 섞이기 쉽다. Unreviewed patch나 topic과 무관한 patch가 든 Git tree를 공개하면 앞으로 tree가 pull될 가능성까지 떨어질 수 있다.

Linus의 설명을 옮기면 다음과 같다. Patch를 직접 보낼 수는 있지만 Git tree를 pull하려면 상대가 무엇을 하는지 알고 있으며 모든 변경을 일일이 다시 검사하지 않아도 될 만큼 신뢰할 수 있어야 한다. 출처는 https://lwn.net/Articles/224135/ 이다.

Branch의 모든 patch는 topic에 밀접하게 맞아야 한다. Driver fix branch가 core memory management를 바꾸어서는 안 된다. Git tree로 review 절차를 우회하지 말고 관련 list에 tree 요약을 주기적으로 게시하며 적절한 시점에 linux-next 포함을 요청한다.

다른 사람이 tree 포함을 요청하며 patch를 보내기 시작하면 maintainer도 patch를 검토해야 한다. Git am이 authorship 보존을 돕지만 third party를 거쳐 전달된 patch에는 올바른 저자를 표시하기 위해 From: line을 직접 추가해야 할 수 있다.

Pull을 요청할 때는 tree 위치, pull할 branch, pull로 생기는 변경을 모두 제공한다. git request-pull은 kernel developer가 기대하는 형식으로 요청을 만들고 변경을 public server에 push했는지도 검사한다.

Git tree는 review를 우회하는 통로가 아닙니다. Branch의 patch는 한 topic에 밀접해야 하고 관련 mailing list에 summary를 게시하며 적절한 시점에 `linux-next` 포함을 요청합니다. 무검토·무관 patch가 섞이면 future pull request에 대한 신뢰도 손상됩니다.

다른 사람의 patch를 tree에 받을 때는 실제 review와 authorship을 보존합니다. Third-party relay로 `From:`이 사라졌다면 바로잡고, pull 요청에는 repository URL, 정확한 branch와 결과 변경을 적으며 `git request-pull`로 형식과 public push 여부를 확인합니다.

Una delle lamentele più grosse e ricorrenti sull'uso di strumenti come git
è il grande movimento di patch da un repositorio all'altro che rende
facile l'integrazione nel ramo principale di modifiche mediocri, il tutto
sotto il naso dei revisori.  Gli sviluppatori del kernel tendono ad essere
scontenti quando vedono succedere queste cose; preparare un ramo git con
patch che non hanno ricevuto alcuna revisione o completamente avulse, potrebbe
influire sulla vostra capacita di proporre, in futuro, l'integrazione dei
vostri rami.  Citando Linus

::

	Potete inviarmi le vostre patch, ma per far si che io integri una
	vostra modifica da git, devo sapere che voi sappiate cosa state
	facendo, e ho bisogno di fidarmi *senza* dover passare tutte
	le modifiche manualmente una per una.

(https://lwn.net/Articles/224135/).

Per evitare queste situazioni, assicuratevi che tutte le patch in un ramo
siano strettamente correlate al tema delle modifiche; un ramo "driver fixes"
non dovrebbe fare modifiche al codice principale per la gestione della memoria.
E, più importante ancora, non usate un repositorio git per tentare di
evitare il processo di revisione.  Pubblicate un sommario di quello che il
vostro ramo contiene sulle liste di discussione più opportune, e , quando
sarà il momento, richiedete che il vostro ramo venga integrato in linux-next.

Se e quando altri inizieranno ad inviarvi patch per essere incluse nel
vostro repositorio, non dovete dimenticare di revisionarle.  Inoltre
assicuratevi di mantenerne le informazioni di paternità; al riguardo git "am"
fa del suo meglio, ma potreste dover aggiungere una riga "From:" alla patch
nel caso in cui sia arrivata per vie traverse.

Quando richiedete l'integrazione, siate certi di fornire tutte le informazioni:
dov'è il vostro repositorio, quale ramo integrare, e quali cambiamenti si
otterranno dall'integrazione.  Il comando git request-pull può essere d'aiuto;
preparerà una richiesta nel modo in cui gli altri sviluppatori se l'aspettano,
e verificherà che vi siate ricordati di pubblicare quelle patch su un
server pubblico.

patch review의 관점과 효과적인 feedback

Patch review를 advanced topic으로 분류하는 데 이견이 있을 수 있다. 다른 사람이 게시한 code를 읽는 것보다 kernel programming을 잘 배우는 방법은 드물고 reviewer는 늘 부족하므로 초보 developer도 review로 큰 기여를 할 수 있다.

경험 많은 developer의 공개 code에 질문하는 일은 부담스러울 수 있지만 어떤 code도 개선될 수 있다. Review comment는 비난보다 질문으로 표현하는 것이 좋다. '여기 locking은 틀렸다'보다 '이 path에서는 lock이 어떻게 release되는가?'가 더 효과적이다.

몇 차례 대화 뒤 논의가 교착되면 다른 reviewer나 maintainer에게 의견을 요청한다. 동의하는 사람은 요청받기 전까지 조용히 있는 경우가 많고 여러 사람의 의견은 훨씬 큰 무게를 갖는다.

Developer마다 coding style, trailing whitespace, 변경 자체의 타당성, locking, stack 사용량, security, code 중복, documentation, 성능, userspace ABI 등 서로 다른 관점에서 검토한다. 더 나은 code가 kernel에 들어가게 한다면 모든 종류의 review가 가치 있다.

Reviewed-by 같은 특정 tag를 반드시 사용할 필요는 없다. Tag를 주더라도 '이 제출의 A, B, C 측면을 살펴보았고 문제가 없어 보인다'처럼 plain English로 검토 범위를 설명하는 것이 더 유익하다.

어떤 형태로든 review message나 reply가 있어야 maintainer가 review 사실을 알 수 있다. Patch review는 문제 지적에 치우쳐 부정적인 과정이 되기 쉬우므로 가끔은 잘한 점도 말하며 특히 초보 contributor에게 긍정적 feedback을 제공한다.

Patch review는 초보자도 시작할 수 있는 중요한 기여입니다. 경험 많은 author의 code라도 개선될 수 있으며 단정적인 비난보다 `이 path에서 lock은 어떻게 해제됩니까?`처럼 확인 가능한 질문으로 의견을 표현하는 편이 생산적입니다.

교착되면 maintainer와 다른 reviewer에게 명시적으로 의견을 요청합니다. Style, trailing whitespace, locking, stack 사용, security, 중복, documentation, performance와 user-space ABI 등 서로 다른 관점의 review가 모두 품질 향상에 기여합니다.

`Reviewed-by:` tag만 남기기보다 실제로 살펴본 A, B, C 범위를 reply에 설명해야 maintainer가 review 깊이를 판단할 수 있습니다. 문제 지적에만 머물지 말고 잘된 부분도 언급하며 특히 newcomer에게 긍정적인 feedback을 제공합니다.

.. _development_advancedtopics_reviews_it:

Revisionare le patch
--------------------

Alcuni lettori potrebbero avere obiezioni sulla presenza di questa sezione
negli "argomenti avanzati" sulla base che anche gli sviluppatori principianti
dovrebbero revisionare le patch.  É certamente vero che non c'è modo
migliore di imparare come programmare per il kernel che guardare il codice
pubblicato dagli altri.  In aggiunta, i revisori sono sempre troppo pochi;
guardando il codice potete apportare un significativo contributo all'intero
processo.

Revisionare il codice potrebbe risultare intimidatorio, specialmente per i
nuovi arrivati che potrebbero sentirsi un po' nervosi nel questionare
il codice - in pubblico - pubblicato da sviluppatori più esperti.  Perfino
il codice scritto dagli sviluppatori più esperti può essere migliorato.
Forse il suggerimento migliore per i revisori (tutti) è questo: formulate
i commenti come domande e non come critiche.  Chiedere "Come viene rilasciato
il *lock* in questo percorso?" funziona sempre molto meglio che
"qui la sincronizzazione è sbagliata".

In caso di disaccordi, può essere utile chiedere una terza opinione. Se dopo
pochi scambi la discussione raggiunge un punto morto, allora chiedete ai
manutentori o altri revisori di partecipare esprimendo la loro opinione. Spesso
vige un silenzio assenso per cui gli altri revisori non intervengono se non gli
viene richiesto esplicitamente. L'opinione di più persone avrà sicuramente un
peso maggiore.

Diversi sviluppatori revisioneranno il codice con diversi punti di vista.
Alcuni potrebbero concentrarsi principalmente sullo stile del codice e se
alcune linee hanno degli spazio bianchi di troppo.  Altri si chiederanno
se accettare una modifica interamente è una cosa positiva per il kernel
o no.  E altri ancora si focalizzeranno sui problemi di sincronizzazione,
l'uso eccessivo di *stack*, problemi di sicurezza, duplicazione del codice
in altri contesti, documentazione, effetti negativi sulle prestazioni, cambi
all'ABI dello spazio utente, eccetera.  Qualunque tipo di revisione è ben
accetta e di valore, se porta ad avere un codice migliore nel kernel.

Non esistono requisiti particolarmente stringenti per l'uso di etichette come
``Reviewed-by``. Tuttavia, perché la revisione sia efficace ci si aspetta un
qualche tipo di messaggio che dica "ho verificato A, B e C nel codice che è
appena stato inviato e mi sembra tutto in ordine". Inoltre, questo permette ai
manutentori di prendere conoscenza circa una revisione avvenuta per davvero.

Per finire, la revisione delle patch può diventare un processo negativo, troppo
focalizzato sulla ricerca dei problemi. Provate a fare qualche complimento di
tanto in tanto, specialmente con i nuovi arrivati.