Debian Codegraph @

Documentation/translations/pt_BR/process/howto.rst

raw
1 .. SPDX-License-Identifier: GPL-2.0
2
3 .. _pt_process_howto:
4
5 COMO FAZER o desenvolvimento do kernel Linux
6 ============================================
7
8 Este é o documento definitivo sobre este tópico. Ele contém instruções
9 sobre como se tornar um desenvolvedor do kernel Linux e como aprender a
10 trabalhar com a comunidade de desenvolvimento do kernel Linux. Ele tenta
11 não conter nada relacionado aos aspectos técnicos da programação do kernel,
12 mas ajudará a apontar a direção certa para isso.
13
14 Se algo neste documento ficar desatualizado, por favor, envie patches para
15 o mantenedor deste arquivo, que está listado no final do documento.
16
17
18 Introdução
19 ------------
20
21 Então, você quer aprender como se tornar um desenvolvedor do kernel Linux?
22 Ou o seu gerente lhe disse: "Vá escrever um driver Linux para este
23 dispositivo". O objetivo deste documento é ensinar tudo o que você precisa
24 saber para conseguir isso, descrevendo o processo pelo qual você deve passar
25 e oferecendo dicas sobre como trabalhar com a comunidade. Ele também tentará
26 explicar algumas das razões pelas quais a comunidade trabalha da forma que
27 trabalha.
28
29 O kernel é escrito principalmente em C, com algumas partes dependentes de
30 arquitetura escritas em assembly. Um bom entendimento de C é necessário para
31 o desenvolvimento do kernel. O conhecimento de Assembly (de qualquer
32 arquitetura) não é obrigatório, a menos que você planeje fazer
33 desenvolvimento de baixo nível para essa arquitetura específica. Embora não
34 sejam um substituto para uma formação sólida em C e/ou anos de experiência,
35 os seguintes livros são bons para, no mínimo, referência:
36
37 - "The C Programming Language" por Kernighan e Ritchie [Prentice Hall]
38
39 - "Practical C Programming" por Steve Oualline [O'Reilly]
40
41 - "C: A Reference Manual" por Harbison e Steele [Prentice Hall]
42
43 O kernel é escrito usando o GNU C e a GNU toolchain. Embora ele siga o
44 padrão ISO C11, ele utiliza uma série de extensões que não estão presentes
45 no padrão. O kernel é um ambiente C independente (freestanding), sem
46 dependência da biblioteca C padrão (libc), portanto, algumas partes do
47 padrão C não são suportadas. Divisões arbitrárias de "long long" e ponto
48 flutuante não são permitidas. Às vezes, pode ser difícil entender as
49 suposições que o kernel faz sobre a toolchain e as extensões que ele utiliza
50 e, infelizmente, não existe uma referência definitiva para elas. Por favor,
51 verifique as páginas de informações do gcc (`info gcc`) para obter algumas
52 informações sobre elas.
53
54 Por favor, lembre-se de que você está tentando aprender como trabalhar com a
55 comunidade de desenvolvimento existente. É um grupo diversificado de pessoas,
56 com altos padrões de codificação, estilo e procedimento. Esses padrões foram
57 criados ao longo do tempo com base no que se descobriu funcionar melhor para
58 uma equipe tão grande e geograficamente dispersa. Tente aprender o máximo
59 possível sobre esses padrões com antecedência, pois eles estão bem
60 documentados; não espere que as pessoas se adaptem a você ou à forma de fazer
61 as coisas da sua empresa.
62
63
64 Questões Legais
65 ---------------
66
67 O código-fonte do kernel Linux é lançado sob a GPL. Por favor, veja o arquivo
68 COPYING no diretório principal da árvore de fontes. As regras de licenciamento
69 do kernel Linux e como usar os identificadores `SPDX <https://spdx.org/>`_ no
70 código-fonte estão descritas em :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
71 Se você tiver mais perguntas sobre a licença, por favor, entre em contato com
72 um advogado e não pergunte na lista de discussão do kernel Linux. As pessoas
73 nas listas de discussão não são advogados e você não deve confiar em suas
74 declarações sobre assuntos jurídicos.
75
76 Para perguntas e respostas comuns sobre a GPL, por favor, veja:
77
78 https://www.gnu.org/licenses/gpl-faq.html
79
80
81 Documentação
82 ------------
83
84 A árvore de fontes do kernel Linux possui uma vasta gama de documentos que
85 são inestimáveis para aprender como interagir com a comunidade do kernel.
86 Quando novos recursos são adicionados ao kernel, recomenda-se que novos
87 arquivos de documentação também sejam adicionados explicando como usar o
88 recurso. Quando uma mudança no kernel faz com que a interface que o kernel
89 expõe para o espaço do usuário (userspace) mude, recomenda-se que você envie
90 a informação ou um patch para as páginas de manual explicando a mudança para
91 o mantenedor das páginas de manual em [email protected], e coloque em cópia (CC)
92 a lista [email protected].
93
94 Aqui está uma lista de arquivos que estão na árvore de fontes do kernel e
95 que são de leitura obrigatória:
96
97 :ref:`Documentation/admin-guide/README.rst <readme>`
98 Este arquivo fornece um breve histórico sobre o kernel Linux e descreve
99 o que é necessário fazer para configurar e compilar o kernel. Pessoas
100 que são novas no kernel devem começar por aqui.
101
102 :doc:`changes`
103 Este arquivo fornece uma lista das versões mínimas de vários pacotes de
104 software que são necessários para compilar e executar o kernel com
105 sucesso.
106
107 :ref:`Documentation/process/coding-style.rst <codingstyle>`
108 Este documento descreve o estilo de codificação do kernel Linux e parte
109 da fundamentação por trás dele. Espera-se que todo código novo siga as
110 diretrizes deste documento. A maioria dos mantenedores apenas aceitará
111 patches se essas regras forem seguidas, e muitas pessoas apenas
112 revisarão o código se ele estiver no estilo adequado.
113
114 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
115 Este arquivo descreve em detalhes explícitos como criar e enviar
116 um patch com sucesso, incluindo (mas não limitado a):
117
118 - Conteúdo do e-mail
119 - Formato do e-mail
120 - Para quem enviá-lo
121
122 Seguir estas regras não garantirá o sucesso (já que todos os patches
123 estão sujeitos a um escrutínio de conteúdo e estilo), mas não segui-las
124 quase sempre o impedirá.
125
126 Outras excelentes descrições de como criar patches adequadamente são:
127
128 "O Patch Perfeito"
129 https://www.ozlabs.org/~akpm/stuff/tpp.txt
130
131 "Formato de Submissão de Patch do Kernel Linux"
132 https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
133
134 :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
135 Este arquivo descreve a justificativa por trás da decisão consciente de
136 não ter uma API estável dentro do kernel, incluindo pontos como:
137
138 - Camadas de adaptação (shim-layers) de subsistemas (para compatibilidade?)
139 - Portabilidade de drivers entre sistemas operacionais.
140 - Mitigação de mudanças rápidas dentro da árvore de fontes do kernel
141 (ou impedimento de mudanças rápidas).
142
143 Este documento é crucial para compreender a filosofia de desenvolvimento
144 do Linux e é muito importante para pessoas que estão migrando para o
145 Linux vindas do desenvolvimento em outros Sistemas Operacionais.
146
147 :ref:`Documentation/process/security-bugs.rst <securitybugs>`
148 Se você acredita ter encontrado um problema de segurança no kernel Linux,
149 por favor, siga os passos descritos neste documento para ajudar a
150 notificar os desenvolvedores do kernel e auxiliar na resolução do problema.
151
152 :ref:`Documentation/process/management-style.rst <managementstyle>`
153 Este documento descreve como os mantenedores do kernel Linux operam e o
154 ethos compartilhado por trás de suas metodologias. Esta é uma leitura
155 importante para qualquer pessoa nova no desenvolvimento do kernel (ou
156 para qualquer pessoa simplesmente curiosa sobre isso), pois resolve muitos
157 equívocos comuns e confusões sobre o comportamento único dos mantenedores
158 do kernel.
159
160 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
161 Este arquivo descreve as regras sobre como ocorrem os lançamentos das
162 versões estáveis (stable) do kernel e o que fazer se você desejar que
163 uma alteração seja incluída em um desses lançamentos.
164
165 :ref:`Documentation/process/kernel-docs.rst <kernel_docs>`
166 Uma lista de documentação externa que pertence ao desenvolvimento do
167 kernel. Por favor, consulte esta lista caso não encontre o que está
168 procurando dentro da documentação interna do kernel.
169
170 :ref:`Documentation/process/applying-patches.rst <applying_patches>`
171 Uma boa introdução descrevendo exatamente o que é um patch e como
172 aplicá-lo aos diferentes ramos (branches) de desenvolvimento do kernel.
173
174 O kernel também possui um grande número de documentos que podem ser
175 gerados automaticamente a partir do próprio código-fonte ou de
176 marcações ReStructuredText (ReST), como esta. Isso inclui uma
177 descrição completa da API interna do kernel e regras sobre como
178 manipular o bloqueio (locking) corretamente.
179
180 Todos esses documentos podem ser gerados em formato PDF ou HTML ao
181 executar::
182
183 make pdfdocs
184 make htmldocs
185
186 respectivamente, a partir do diretório principal do código-fonte do kernel.
187
188 Os documentos que utilizam a marcação ReST serão gerados em
189 Documentation/output. Eles também podem ser gerados nos formatos
190 LaTeX e ePub com::
191
192 make latexdocs
193 make epubdocs
194
195 Como se tornar um desenvolvedor do kernel
196 ------------------------------------------
197
198 Se você não sabe nada sobre o desenvolvimento do kernel Linux, você deve
199 consultar o projeto Linux KernelNewbies:
200
201 https://kernelnewbies.org
202
203 Ele consiste em uma lista de discussão útil onde você pode fazer quase
204 qualquer tipo de pergunta básica sobre o desenvolvimento do kernel
205 (certifique-se de pesquisar nos arquivos primeiro, antes de perguntar
206 algo que já foi respondido no passado). Ele também possui um canal de
207 IRC que você pode usar para fazer perguntas em tempo real, e muita
208 documentação útil para aprender sobre o desenvolvimento do kernel Linux.
209
210 O site possui informações básicas sobre a organização do código,
211 subsistemas e projetos atuais (tanto in-tree quanto out-of-tree).
212 Também descreve algumas informações logísticas básicas, como por exemplo,
213 como compilar um kernel e aplicar um patch.
214
215 Se você não sabe por onde começar, mas deseja procurar alguma tarefa
216 para iniciar sua integração na comunidade de desenvolvimento do kernel,
217 acesse o projeto Linux Kernel Janitor:
218
219 https://kernelnewbies.org/KernelJanitors
220
221 É um ótimo lugar para começar. Ele descreve uma lista de problemas
222 relativamente simples que precisam ser limpos e corrigidos dentro da
223 árvore de códigos-fonte do kernel Linux. Ao trabalhar com os
224 desenvolvedores responsáveis por este projeto, você aprenderá o básico
225 sobre como incluir seu patch na árvore do kernel Linux e,
226 possivelmente, será orientado sobre o que trabalhar em seguida, caso
227 ainda não tenha uma ideia.
228
229 Antes de fazer qualquer modificação real no código do kernel Linux, é
230 imperativo entender como o código em questão funciona. Para esse
231 propósito, nada é melhor do que lê-lo diretamente (a maioria das partes
232 complexas está bem comentada), talvez até com a ajuda de ferramentas
233 especializadas. Uma ferramenta particularmente recomendada é o projeto
234 Linux Cross-Reference, que é capaz de apresentar o código-fonte em um
235 formato de página web indexada e auto-referenciada. Um excelente
236 repositório atualizado do código do kernel pode ser encontrado em:
237
238 https://elixir.bootlin.com/
239
240
241 O processo de desenvolvimento
242 -----------------------------
243
244 O processo de desenvolvimento do kernel Linux consiste atualmente em algumas
245 "branches" (ramos) principais diferentes e muitos ramos de subsistemas
246 específicos. Esses diferentes ramos são:
247
248 - Árvore principal (mainline) do Linus
249 - Várias árvores estáveis com múltiplos números de versão principal
250 - Árvores específicas de subsistemas
251 - Árvore de testes de integração linux-next
252
253 Árvore principal (Mainline tree)
254 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
255
256 A árvore principal é mantida por Linus Torvalds e pode ser encontrada em
257 https://kernel.org ou no repositório. Seu processo de desenvolvimento é
258 o seguinte:
259
260 - Assim que um novo kernel é lançado, uma janela de duas semanas é aberta;
261 durante esse período, os mantenedores podem enviar grandes diffs para
262 Linus, geralmente patches que já foram incluídos na linux-next por algumas
263 semanas. A forma preferida de enviar grandes mudanças é usando o git
264 (a ferramenta de gerenciamento de código-fonte do kernel, mais informações
265 podem ser encontradas em https://git-scm.com/), mas patches simples
266 também são aceitos.
267 - Após duas semanas, um kernel -rc1 é lançado e o foco passa a ser tornar
268 o novo kernel o mais sólido possível. A maioria dos patches neste estágio
269 deve corrigir uma regressão. Bugs que sempre existiram não são regressões,
270 portanto, envie esses tipos de correções apenas se forem importantes.
271 Observe que um driver (ou sistema de arquivos) totalmente novo pode ser
272 aceito após o -rc1 porque não há risco de causar regressões com tal
273 mudança, desde que a alteração seja autocontida e não afete áreas fora do
274 código que está sendo adicionado. O git pode ser usado para enviar
275 patches para Linus após o lançamento do -rc1, mas os patches também
276 precisam ser enviados para uma lista de discussão pública para revisão.
277 - Um novo -rc é lançado sempre que Linus considerar que a árvore git atual
278 está em um estado razoavelmente estável e adequado para testes. O objetivo
279 é lançar um novo kernel -rc a cada semana.
280 - O processo continua até que o kernel seja considerado "pronto"; o
281 processo deve durar cerca de 6 semanas.
282
283 Vale a pena mencionar o que Andrew Morton escreveu na lista de discussão
284 do kernel Linux sobre os lançamentos do kernel:
285
286 *"Ninguém sabe quando um kernel será lançado, porque ele é
287 lançado de acordo com o status percebido dos bugs, não de acordo
288 com um cronograma pré-concebido."*
289
290 Várias árvores estáveis com múltiplos números de versão principal
291 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
292
293 Kernels com versões de 3 partes são kernels -stable (estáveis). Eles
294 contêm correções relativamente pequenas e críticas para problemas de
295 segurança ou regressões significativas descobertas em um determinado
296 lançamento principal da árvore mainline. Cada lançamento em uma série
297 estável principal incrementa a terceira parte do número da versão,
298 mantendo as duas primeiras partes iguais.
299
300 Este é o ramo recomendado para usuários que desejam o kernel estável
301 mais recente e não estão interessados em ajudar a testar versões de
302 desenvolvimento ou experimentais.
303
304 As árvores estáveis são mantidas pela equipe "stable"
305 <[email protected]> e são lançadas conforme a necessidade exigir.
306 O período normal de lançamento é de aproximadamente duas semanas, mas
307 pode ser mais longo se não houver problemas urgentes. Por outro lado,
308 um problema relacionado à segurança pode fazer com que um lançamento
309 ocorra quase instantaneamente.
310
311 O arquivo :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
312 na árvore do kernel documenta quais tipos de mudanças são aceitáveis para
313 a árvore -stable e como o processo de lançamento funciona.
314
315 Árvores específicas de subsistemas
316 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
317
318 Os mantenedores dos vários subsistemas do kernel — e também muitos
319 desenvolvedores de subsistemas do kernel — expõem seu estado atual de
320 desenvolvimento em repositórios de código-fonte. Dessa forma, outros
321 podem ver o que está acontecendo nas diferentes áreas do kernel. Em
322 áreas onde o desenvolvimento é rápido, um desenvolvedor pode ser
323 solicitado a basear suas submissões em tal árvore de subsistema do
324 kernel para que conflitos entre a submissão e outros trabalhos já em
325 andamento sejam evitados.
326
327 A maioria desses repositórios são árvores git, mas também existem outros
328 SCMs em uso, ou filas de patches sendo publicadas como séries quilt. Os
329 endereços desses repositórios de subsistemas estão listados no arquivo
330 MAINTAINERS. Muitos deles podem ser navegados em https://git.kernel.org/.
331
332 Antes que um patch proposto seja incluído em tal árvore de subsistema,
333 ele está sujeito a uma revisão que ocorre principalmente em listas de
334 discussão (veja a seção respectiva abaixo). Para vários subsistemas do
335 kernel, este processo de revisão é rastreado com a ferramenta patchwork.
336 O Patchwork oferece uma interface web que mostra as postagens de patches,
337 quaisquer comentários sobre um patch ou revisões feitas a ele, e os
338 mantenedores podem marcar os patches como "sob revisão", "aceitos" ou
339 "rejeitados". A maioria desses sites patchwork está listada em
340 https://patchwork.kernel.org/.
341
342 Árvore de testes de integração linux-next
343 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
344
345 Antes que as atualizações das árvores de subsistemas sejam mescladas na
346 árvore mainline, elas precisam ser testadas quanto à integração. Para
347 este propósito, existe um repositório de testes especial no qual
348 praticamente todas as árvores de subsistemas são integradas (pulled)
349 quase diariamente:
350
351 https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git
352
353 Dessa forma, a linux-next oferece uma visão resumida do que se espera
354 que entre no kernel mainline no próximo período de mesclagem (merge
355 window). Testadores aventureiros são muito bem-vindos para testar a
356 linux-next em tempo de execução.
357
358
359 Relato de Bugs
360 --------------
361
362 O arquivo 'Documentation/admin-guide/reporting-issues.rst' no diretório
363 principal de códigos-fonte do kernel descreve como relatar um possível
364 bug no kernel e detalha que tipo de informação é necessária para os
365 desenvolvedores do kernel ajudarem a rastrear o problema.
366
367 Gerenciando relatos de bugs
368 ---------------------------
369
370 Uma das melhores maneiras de colocar em prática suas habilidades de hacking
371 é corrigindo bugs relatados por outras pessoas. Você não apenas ajudará a
372 tornar o kernel mais estável, mas também aprenderá a resolver problemas do
373 mundo real, melhorará suas habilidades e outros desenvolvedores passarão a
374 notar sua presença. Corrigir bugs é uma das melhores formas de obter mérito
375 entre outros desenvolvedores, pois poucas pessoas gostam de gastar tempo
376 corrigindo bugs de terceiros.
377
378 Para trabalhar em relatos de bugs já existentes, encontre um subsistema no
379 qual você esteja interessado. Verifique no arquivo MAINTAINERS para onde
380 os bugs daquele subsistema são relatados; geralmente será uma lista de
381 discussão, raramente um rastreador de bugs (bugtracker). Pesquise nos
382 arquivos de mensagens do local indicado por relatos recentes e ajude onde
383 achar apropriado. Você também pode verificar o site
384 https://bugzilla.kernel.org para relatos de bugs; apenas alguns
385 subsistemas do kernel o utilizam ativamente para relato ou rastreamento,
386 entretanto, bugs de todo o kernel acabam sendo registrados lá.
387
388
389 Listas de discussão
390 -------------------
391
392 Como alguns dos documentos acima descrevem, a maioria dos desenvolvedores
393 do núcleo (core) do kernel participa da Linux Kernel Mailing List (LKML).
394 Detalhes sobre como se inscrever e cancelar a inscrição na lista podem
395 ser encontrados em:
396
397 https://subspace.kernel.org/subscribing.html
398
399 Existem arquivos de mensagens da lista na web em muitos lugares diferentes.
400 Use um mecanismo de busca para encontrar esses arquivos. Por exemplo:
401
402 https://lore.kernel.org/linux-kernel/
403
404 É altamente recomendável que você pesquise nos arquivos sobre o tópico que
405 deseja abordar antes de postar na lista. Muitas coisas já discutidas em
406 detalhes estão registradas apenas nos arquivos das listas de discussão.
407
408 A maioria dos subsistemas individuais do kernel também possui sua própria
409 lista de discussão separada, onde realizam seus esforços de desenvolvimento.
410 Consulte o arquivo MAINTAINERS para obter uma lista de quais são essas
411 listas para os diferentes grupos.
412
413 Muitas das listas estão hospedadas no kernel.org. Informações sobre elas
414 podem ser encontradas em:
415
416 https://subspace.kernel.org
417
418 Por favor, lembre-se de seguir bons hábitos de comportamento ao usar as
419 listas. Embora um pouco clichê, a URL a seguir possui algumas diretrizes
420 simples para interagir com a lista (ou qualquer outra lista):
421
422 https://subspace.kernel.org/etiquette.html
423
424 Se várias pessoas responderem ao seu e-mail, a lista de destinatários em
425 CC: pode se tornar bem grande. Não remova ninguém da lista CC: sem um
426 bom motivo, e não responda apenas para o endereço da lista. Acostume-se
427 a receber o e-mail duas vezes (um do remetente e outro da lista) e não
428 tente ajustar isso adicionando cabeçalhos de e-mail complexos; as pessoas
429 não gostarão disso.
430
431 Lembre-se de manter o contexto e a atribuição de suas respostas intactos;
432 mantenha as linhas do tipo "John Kernelhacker escreveu...:" no topo da
433 sua resposta e adicione seus comentários entre as seções citadas
434 individualmente, em vez de escrever tudo no topo do e-mail.
435
436 Se você adicionar patches ao seu e-mail, certifique-se de que sejam texto
437 puro legível, conforme declarado em
438 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
439 Os desenvolvedores do kernel não querem lidar com anexos ou patches
440 compactados; eles podem querer comentar linhas individuais do seu patch,
441 o que só funciona dessa forma. Certifique-se de usar um programa de
442 e-mail que não altere espaços e caracteres de tabulação (tabs). Um bom
443 primeiro teste é enviar o e-mail para si mesmo e tentar aplicar o seu
444 próprio patch. Se isso não funcionar, conserte seu programa de e-mail ou
445 troque-o até que funcione.
446
447 Acima de tudo, por favor, lembre-se de mostrar respeito aos outros
448 inscritos.
449
450
451 Trabalhando com a comunidade
452 ----------------------------
453
454 O objetivo da comunidade do kernel é fornecer o melhor kernel possível.
455 Quando você envia um patch para aceitação, ele será revisado por seus
456 méritos técnicos e apenas por eles. Então, o que você deve esperar?
457
458 - críticas
459 - comentários
460 - solicitações de mudança
461 - solicitações de justificativa
462 - silêncio
463
464 Lembre-se, isso faz parte do processo de incluir seu patch no kernel.
465 Você deve ser capaz de aceitar críticas e comentários sobre seus patches,
466 avaliá-los em nível técnico e retrabalhar seus patches ou fornecer
467 raciocínios claros e concisos sobre o porquê de certas mudanças não
468 deverem ser feitas. Se não houver respostas à sua postagem, aguarde
469 alguns dias e tente novamente; às vezes, as coisas se perdem no enorme
470 volume de mensagens.
471
472 O que você não deve fazer?
473
474 - esperar que seu patch seja aceito sem questionamentos
475 - tornar-se defensivo
476 - ignorar comentários
477 - reenviar o patch sem fazer nenhuma das alterações solicitadas
478
479 Em uma comunidade que busca a melhor solução técnica possível, sempre
480 haverá opiniões divergentes sobre o quão benéfico é um patch. Você deve
481 ser cooperativo e estar disposto a adaptar sua ideia para que ela se
482 encaixe no kernel. Ou, pelo menos, estar disposto a provar que sua ideia
483 vale a pena. Lembre-se: estar errado é aceitável, desde que você esteja
484 disposto a trabalhar em direção a uma solução correta.
485
486 É normal que as respostas ao seu primeiro patch sejam apenas uma lista
487 de uma dúzia de coisas que você deve corrigir. Isso **não** implica que
488 seu patch não será aceito e **não** é algo pessoal contra você. Simplesmente
489 corrija todos os problemas apontados em seu patch e envie-o novamente.
490
491
492 Diferenças entre a comunidade do kernel e estruturas corporativas
493 -----------------------------------------------------------------
494
495 A comunidade do kernel trabalha de forma diferente da maioria dos ambientes
496 tradicionais de desenvolvimento corporativo. Aqui está uma lista de coisas
497 que você pode tentar fazer para evitar problemas:
498
499 Boas coisas a dizer em relação às suas mudanças propostas:
500
501 - "Isto resolve múltiplos problemas."
502 - "Isto remove 2000 linhas de código."
503 - "Aqui está um patch que explica o que estou tentando descrever."
504 - "Eu testei isso em 5 arquiteturas diferentes..."
505 - "Aqui está uma série de pequenos patches que..."
506 - "Isto aumenta a performance em máquinas comuns..."
507
508 Coisas ruins que você deve evitar dizer:
509
510 - "Nós fizemos desta forma no AIX/ptx/Solaris, portanto deve ser bom..."
511 - "Eu faço isso há 20 anos, então..."
512 - "Isto é necessário para minha empresa ganhar dinheiro."
513 - "Isto é para nossa linha de produtos Enterprise."
514 - "Aqui está meu documento de design de 1000 páginas que descreve minha ideia."
515 - "Estou trabalhando nisso há 6 meses..."
516 - "Aqui está um patch de 5000 linhas que..."
517 - "Eu reescrevi toda a bagunça atual, e aqui está..."
518 - "Eu tenho um prazo (deadline), e este patch precisa ser aplicado agora."
519
520 Outra forma em que a comunidade do kernel difere da maioria dos ambientes
521 tradicionais de engenharia de software é a natureza anônima da interação.
522 Um benefício de usar e-mail e IRC como as principais formas de comunicação
523 é a ausência de discriminação baseada em gênero ou raça. O ambiente de
524 trabalho do kernel Linux aceita mulheres e minorias porque tudo o que você
525 é, é um endereço de e-mail. O aspecto internacional também ajuda a nivelar
526 o campo de jogo porque você não pode adivinhar o gênero com base no nome
527 de uma pessoa. Um homem pode se chamar Andrea e uma mulher pode se chamar
528 Pat. A maioria das mulheres que trabalharam no kernel Linux e expressaram
529 uma opinião tiveram experiências positivas.
530
531 A barreira do idioma pode causar problemas para algumas pessoas que não
532 se sentem confortáveis com o inglês. Um bom domínio do idioma pode ser
533 necessário para transmitir ideias adequadamente nas listas de discussão,
534 por isso recomenda-se que você verifique seus e-mails para garantir que
535 façam sentido em inglês antes de enviá-los.
536
537
538 Divida suas alterações
539 ----------------------
540
541 A comunidade do kernel Linux não aceita de bom grado grandes blocos de
542 código jogados de uma só vez. As mudanças precisam ser devidamente
543 introduzidas, discutidas e divididas em porções minúsculas e individuais.
544 Isso é quase o exato oposto do que as empresas costumam fazer. Sua proposta
545 também deve ser introduzida muito cedo no processo de desenvolvimento, para
546 que você possa receber feedback sobre o que está fazendo. Isso também permite
547 que a comunidade sinta que você está trabalhando com eles, e não simplesmente
548 usando-os como um depósito para sua funcionalidade. No entanto, não envie
549 50 e-mails de uma só vez para uma lista de discussão; sua série de patches
550 deve ser menor que isso quase sempre.
551
552 As razões para dividir as coisas são as seguintes:
553
554 1) Patches pequenos aumentam a probabilidade de serem aplicados, pois não
555 exigem muito tempo ou esforço para verificar sua correção. Um patch de
556 5 linhas pode ser aplicado por um mantenedor com apenas um olhar rápido.
557 No entanto, um patch de 500 linhas pode levar horas para ser revisado
558 (o tempo que leva é exponencialmente proporcional ao tamanho do patch,
559 ou algo assim).
560
561 Patches pequenos também tornam muito fácil a depuração (debug) quando
562 algo dá errado. É muito mais fácil reverter patches um por um do que
563 dissecar um patch muito grande após ele ter sido aplicado (e quebrado algo).
564
565 2) É importante não apenas enviar patches pequenos, mas também reescrever
566 e simplificar (ou simplesmente reordenar) os patches antes de submetê-los.
567
568 Aqui está uma analogia do desenvolvedor do kernel Al Viro:
569
570 *"Pense em um professor corrigindo o dever de casa de um aluno de
571 matemática. O professor não quer ver as tentativas e erros do aluno
572 antes de chegar à solução. Ele quer ver a resposta mais limpa e
573 elegante. Um bom aluno sabe disso e nunca enviaria seu trabalho
574 intermediário antes da solução final.*
575
576 *O mesmo vale para o desenvolvimento do kernel. Os mantenedores e
577 revisores não querem ver o processo de pensamento por trás da solução
578 do problema que se está resolvendo. Eles querem ver uma solução
579 simples e elegante."*
580
581 Pode ser desafiador manter o equilíbrio entre apresentar uma solução
582 elegante e trabalhar em conjunto com a comunidade discutindo seu trabalho
583 inacabado. Portanto, é bom entrar no processo cedo para obter feedback e
584 melhorar seu trabalho, mas também manter suas alterações em pequenos blocos
585 que possam ser aceitos, mesmo quando sua tarefa completa ainda não esteja
586 pronta para inclusão.
587
588 Também entenda que não é aceitável enviar patches para inclusão que estejam
589 inacabados e que serão "consertados mais tarde".
590
591
592 Justifique sua alteração
593 ------------------------
594
595 Além de dividir seus patches, é muito importante que você deixe a comunidade
596 Linux saber por que eles deveriam adicionar essa mudança. Novas
597 funcionalidades devem ser justificadas como necessárias e úteis.
598
599
600 Documente sua alteração
601 -----------------------
602
603 Ao enviar seus patches, preste atenção especial ao que você diz no texto
604 do seu e-mail. Essas informações se tornarão as informações do ChangeLog
605 para o patch e serão preservadas para que todos vejam para sempre. Elas
606 devem descrever o patch completamente, contendo:
607
608 - por que a mudança é necessária
609 - a abordagem geral de design no patch
610 - detalhes de implementação
611 - resultados de testes
612
613 Para mais detalhes sobre como tudo isso deve ser, por favor, veja a seção
614 ChangeLog do documento:
615
616 "O Patch Perfeito"
617 https://www.ozlabs.org/~akpm/stuff/tpp.txt
618
619 Todas essas coisas às vezes são muito difíceis de fazer. Pode levar anos
620 para aperfeiçoar essas práticas (se é que é possível). É um processo
621 contínuo de melhoria que exige muita paciência e determinação. Mas não
622 desista, é possível. Muitos fizeram isso antes, e cada um teve que começar
623 exatamente onde você está agora.
624
625 ----------
626
627 Agradecimentos a Paolo Ciarrocchi, que permitiu que a seção "Processo de
628 Desenvolvimento" (https://lwn.net/Articles/94386/) fosse baseada em um
629 texto que ele escreveu, e a Randy Dunlap e Gerrit Huizenga por parte da
630 lista de coisas que você deve ou não dizer. Também agradecemos a Pat Mochel,
631 Hanna Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara,
632 Josh Boyer, Kees Cook, Andrew Morton, Andi Kleen, Vadim Lobanov, Jesper Juhl,
633 Adrian Bunk, Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano,
634 Michael Kerrisk e Alex Shepard por suas revisões, comentários e contribuições.
635 Sem a ajuda deles, este documento não teria sido possível.
636
637 Mantenedor: Greg Kroah-Hartman <[email protected]>