| 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]> |