| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
===================================== |
| 4 |
Subsistema de Rede do Linux (netdev) |
| 5 |
===================================== |
| 6 |
|
| 7 |
tl;dr |
| 8 |
----- |
| 9 |
|
| 10 |
- **Direcione seu patch para uma árvore** – use ``[PATCH net]``para correções |
| 11 |
ou ``[PATCH net-next]`` para novas funcionalidades. |
| 12 |
- **Tag Fixes** – para correções, a tag ``Fixes:`` é obrigatória, |
| 13 |
independentemente da árvore de destino. |
| 14 |
- **Tamanho da série** – não envie séries grandes (> 15 patches);divida-as em |
| 15 |
partes menores. |
| 16 |
- **Intervalo de envio** – não reenvie seus patches dentro de um período de 24 |
| 17 |
horas. |
| 18 |
- **Reverse xmas tree** – organize as declarações de variáveis locais da mais |
| 19 |
longa para a mais curta. |
| 20 |
|
| 21 |
netdev |
| 22 |
------ |
| 23 |
A **netdev** é a lista de discussão para todos os assuntos do Linux relacionados |
| 24 |
a rede. Isso inclui qualquer item encontrado em ``net/`` (ex: código principal |
| 25 |
como IPv6) e em ``drivers/net`` (ex: drivers específicos de hardware) na árvore |
| 26 |
de diretórios do Linux. |
| 27 |
|
| 28 |
Note que alguns subsistemas (ex: drivers de rede sem fio/wireless), que possuem |
| 29 |
um alto volume de tráfego, possuem suas próprias listas de discussão e árvores |
| 30 |
específicas. |
| 31 |
|
| 32 |
Como muitas outras listas de discussão do Linux, a lista netdev é hospedada no |
| 33 |
`kernel.org <https://www.kernel.org/>`_, com arquivos disponíveis em |
| 34 |
https://lore.kernel.org/netdev/. |
| 35 |
|
| 36 |
À exceção dos subsistemas mencionados anteriormente, todo o desenvolvimento de |
| 37 |
rede do Linux (ex: RFCs, revisões, comentários, etc.) ocorre na **netdev**. |
| 38 |
|
| 39 |
Ciclo de Desenvolvimento |
| 40 |
------------------------ |
| 41 |
|
| 42 |
Aqui está um pouco de informação contextual sobre a cadência de desenvolvimento |
| 43 |
do Linux. Cada nova versão (release) inicia-se com uma "janela de mesclagem" |
| 44 |
(*merge window*) de duas semanas, onde os mantenedores principais enviam suas |
| 45 |
novas implementações para o Linus para incorporação na árvore principal |
| 46 |
(*mainline tree*). |
| 47 |
|
| 48 |
Após as duas semanas, a janela de mesclagem é fechada e a versão é |
| 49 |
nomeada/etiquetada como ``-rc1``. Nenhuma funcionalidade nova é incorporada à |
| 50 |
árvore principal após isso -- espera-se apenas correções (*fixes*) para o |
| 51 |
conteúdo da rc1. |
| 52 |
|
| 53 |
Após cerca de uma semana coletando correções para a rc1, a rc2 é lançada. Isso |
| 54 |
se repete semanalmente até a rc7 (tipicamente; às vezes rc6 se o ritmo estiver |
| 55 |
calmo, ou rc8 se houver muita instabilidade); uma semana após a última vX.Y-rcN |
| 56 |
ser concluída, a versão oficial vX.Y é lançada. |
| 57 |
|
| 58 |
Para descobrir em que ponto do ciclo estamos agora - carregue a página da |
| 59 |
mainline (Linus) aqui: |
| 60 |
|
| 61 |
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git |
| 62 |
|
| 63 |
e observe o topo da seção de "tags". Se for rc1, estamos no início do ciclo |
| 64 |
de desenvolvimento. Se a rc7 foi marcada há uma semana, então um lançamento |
| 65 |
é provavelmente iminente. Se a tag mais recente for uma tag de lançamento |
| 66 |
final (sem o sufixo ``-rcN``) - muito provavelmente estamos em uma janela de |
| 67 |
mesclagem (*merge window*) e o ``net-next`` está fechado. |
| 68 |
|
| 69 |
Árvores git e fluxo de patches |
| 70 |
------------------------------ |
| 71 |
|
| 72 |
Existem duas árvores de rede (repositórios git) em jogo. Ambas são coordenadas |
| 73 |
por David Miller, o mantenedor principal de rede. Há a árvore ``net``e a árvore |
| 74 |
``net-next``. Como você provavelmente pode adivinhar pelos nomes, a árvore |
| 75 |
``net`` é para correções de código existente já na árvore mainline de Linus, e a |
| 76 |
``net-next`` é para onde o novo código vai para o lançamento futuro. |
| 77 |
Você pode encontrar as árvores aqui: |
| 78 |
|
| 79 |
- https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git |
| 80 |
- https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git |
| 81 |
|
| 82 |
Relacionando isso ao desenvolvimento do kernel: no início da janela de mesclagem |
| 83 |
(*merge window*) de 2 semanas, a árvore ``net-next`` será fechada, sem novas |
| 84 |
mudanças ou funcionalidades. O conteúdo novo acumulado nas últimas 10 semanas |
| 85 |
será passado para a mainline/Linus via um *pull request* para a vX.Y ao mesmo |
| 86 |
tempo, a árvore ``net`` começará a acumular correções para este conteúdo enviado |
| 87 |
relacionado à vX.Y. |
| 88 |
|
| 89 |
Um anúncio indicando quando a ``net-next`` foi fechada é geralmente enviado para |
| 90 |
a netdev, mas sabendo o que foi dito acima, você pode prever isso com |
| 91 |
antecedência. |
| 92 |
|
| 93 |
.. warning:: |
| 94 |
|
| 95 |
Não envie novo conteúdo para a ``net-next`` para a netdev durante o período |
| 96 |
em que a árvore ``net-next`` estiver fechada. |
| 97 |
|
| 98 |
Patches RFC enviados apenas para revisão são obviamente bem-vindos a qualquer |
| 99 |
momento (use ``--subject-prefix='RFC net-next'`` com ``git format-patch``). |
| 100 |
|
| 101 |
Pouco depois das duas semanas terem passado (e a vX.Y-rc1 ser lançada), a árvore |
| 102 |
para a ``net-next`` reabre para coletar conteúdo para o próximo lançamento |
| 103 |
(vX.Y+1). |
| 104 |
|
| 105 |
Se você não estiver inscrito na netdev e/ou simplesmente não tiver certeza se a |
| 106 |
``net-next`` já reabriu, basta verificar o link do repositório git da |
| 107 |
``net-next`` acima para quaisquer novos *commits* relacionados à rede. Você |
| 108 |
também pode verificar o seguinte site para o status atual: |
| 109 |
|
| 110 |
https://netdev.bots.linux.dev/net-next.html |
| 111 |
|
| 112 |
A árvore ``net`` continua a coletar correções para o conteúdo da vX.Y e é |
| 113 |
enviada de volta para Linus em intervalos regulares (~semanais). Isso significa |
| 114 |
que o foco da ``net`` é a estabilização e correções de bugs. |
| 115 |
|
| 116 |
Finalmente, a vX.Y é lançada e todo o ciclo recomeça. |
| 117 |
|
| 118 |
Revisão de patches da netdev |
| 119 |
---------------------------- |
| 120 |
|
| 121 |
Status do patch |
| 122 |
~~~~~~~~~~~~~~~ |
| 123 |
|
| 124 |
O status de um patch pode ser verificado olhando a fila principal do patchwork |
| 125 |
para a netdev: |
| 126 |
|
| 127 |
https://patchwork.kernel.org/project/netdevbpf/list/ |
| 128 |
|
| 129 |
O campo "State" informará exatamente onde as coisas estão com o seu patch: |
| 130 |
|
| 131 |
================= ============================================================ |
| 132 |
Estado do patch Descrição |
| 133 |
================= ============================================================ |
| 134 |
New, Under review revisão pendente, o patch está na fila do mantenedor |
| 135 |
para revisão; os dois estados são usados alternadamente |
| 136 |
(dependendo do co-mantenedor exato que estiver lidando |
| 137 |
com o patchwork no momento) |
| 138 |
Accepted o patch foi aplicado à árvore de rede apropriada, |
| 139 |
isso é geralmente definido de forma automática pelo pw-bot |
| 140 |
Needs ACK aguardando um "ack" de um especialista da área |
| 141 |
ou testes |
| 142 |
Changes requested o patch não passou na revisão, espera-se uma nova |
| 143 |
revisão com mudanças apropriadas no código e na mensagem |
| 144 |
de commit |
| 145 |
Rejected o patch foi rejeitado e não se espera uma nova |
| 146 |
revisão |
| 147 |
Not applicable espera-se que o patch seja aplicado fora do |
| 148 |
subsistema de rede |
| 149 |
Awaiting upstream o patch deve ser revisado e tratado pelo sub-mantenedor |
| 150 |
apropriado, que o enviará para as árvores de rede; |
| 151 |
patches definidos como ``Awaiting upstream`` no patchwork |
| 152 |
da netdev geralmente permanecerão neste estado, |
| 153 |
independentemente de o sub-mantenedor ter solicitado |
| 154 |
mudanças, aceito ou rejeitado o patch |
| 155 |
Deferred o patch precisa ser reenviado mais tarde, geralmente |
| 156 |
devido a alguma dependência ou porque foi enviado para |
| 157 |
uma árvore fechada |
| 158 |
Superseded uma nova versão do patch foi enviada, geralmente |
| 159 |
definido pelo pw-bot |
| 160 |
RFC não deve ser aplicado, geralmente não está na |
| 161 |
fila de revisão do mantenedor; o pw-bot pode definir |
| 162 |
patches para este estado automaticamente com base nas |
| 163 |
tags do assunto |
| 164 |
================= ============================================================ |
| 165 |
|
| 166 |
Os patches são indexados pelo cabeçalho ``Message-ID`` dos e-mails que os |
| 167 |
transportaram; portanto, se você tiver problemas para encontrar seu patch, |
| 168 |
anexe o valor do ``Message-ID`` à URL acima. |
| 169 |
|
| 170 |
Atualizando o status do patch |
| 171 |
----------------------------- |
| 172 |
|
| 173 |
Colaboradores e revisores não têm permissões para atualizar o estado do patch |
| 174 |
diretamente no patchwork. O Patchwork não expõe muitas informações sobre o |
| 175 |
histórico do estado dos patches; portanto, ter várias pessoas atualizando o |
| 176 |
estado leva a confusões. |
| 177 |
|
| 178 |
Em vez de delegar permissões do patchwork, a netdev usa um robô de e-mail |
| 179 |
simples (bot) que procura por comandos/linhas especiais dentro dos e-mails |
| 180 |
enviados para a lista de discussão. Por exemplo, para marcar uma série como |
| 181 |
Mudanças Solicitadas (*Changes Requested*), é necessário enviar a seguinte |
| 182 |
linha em qualquer lugar na thread do e-mail:: |
| 183 |
|
| 184 |
pw-bot: changes-requested |
| 185 |
|
| 186 |
Como resultado, o bot definirá toda a série como Mudanças Solicitadas. Isso |
| 187 |
pode ser útil quando o autor descobre um bug em sua própria série e deseja |
| 188 |
evitar que ela seja aplicada. |
| 189 |
|
| 190 |
O uso do bot é totalmente opcional; em caso de dúvida, ignore completamente a |
| 191 |
existência dele. Os mantenedores classificarão e atualizarão o estado dos |
| 192 |
patches por conta própria. Nenhum e-mail deve ser enviado à lista com o |
| 193 |
propósito principal de se comunicar com o bot; os comandos do bot devem ser |
| 194 |
vistos como metadados. |
| 195 |
|
| 196 |
O uso do bot é restrito aos autores dos patches (o cabeçalho ``From:`` no envio |
| 197 |
do patch e no comando deve coincidir!), mantenedores do código modificado de |
| 198 |
acordo com o arquivo MAINTAINERS (novamente, o ``From:`` deve coincidir |
| 199 |
com a entrada no MAINTAINERS) e alguns revisores seniores. |
| 200 |
|
| 201 |
O bot registra sua atividade aqui: |
| 202 |
|
| 203 |
https://netdev.bots.linux.dev/pw-bot.html |
| 204 |
|
| 205 |
Prazos de revisão |
| 206 |
~~~~~~~~~~~~~~~~~ |
| 207 |
|
| 208 |
De modo geral, os patches são triados rapidamente (em menos de 48h). Mas |
| 209 |
seja paciente; se o seu patch estiver ativo no patchwork (ou seja, listado |
| 210 |
na lista de patches do projeto), as chances de ele ter sido esquecido são |
| 211 |
próximas de zero. |
| 212 |
|
| 213 |
O alto volume de desenvolvimento na netdev faz com que os revisores encerrem |
| 214 |
discussões de forma relativamente rápida. É muito improvável que novos |
| 215 |
comentários e respostas cheguem após uma semana de silêncio. Se um |
| 216 |
patch não estiver mais ativo no patchwork e a thread ficar inativa por mais de |
| 217 |
uma semana - esclareça os próximos passos e/ou envie a próxima versão. |
| 218 |
|
| 219 |
Especificamente para envios de RFC, se ninguém responder em uma semana ou os |
| 220 |
revisores perderam o envio ou não têm opiniões fortes a respeito. Se o código |
| 221 |
estiver pronto, reenvie como um PATCH. |
| 222 |
|
| 223 |
E-mails dizendo apenas "ping" ou "bump" são considerados rudes. Se você não |
| 224 |
conseguir identificar o status do patch pelo patchwork ou onde a discussão |
| 225 |
parou - descreva sua melhor suposição e pergunte se ela está correta. Por |
| 226 |
exemplo:: |
| 227 |
|
| 228 |
Não entendo quais são os próximos passos. A Pessoa X parece estar descontente |
| 229 |
com A; devo fazer B e enviar novamente os patches? |
| 230 |
|
| 231 |
.. _Solicitações de mudanças: |
| 232 |
|
| 233 |
Mudanças solicitadas |
| 234 |
~~~~~~~~~~~~~~~~~~~~ |
| 235 |
|
| 236 |
Patches marcados como ``Changes Requested`` precisam ser revisados. A nova |
| 237 |
versão deve vir com um registro de alterações (changelog), |
| 238 |
preferencialmente incluindo links para as postagens anteriores, por exemplo:: |
| 239 |
|
| 240 |
[PATCH net-next v3] net: faz as vacas dizerem "muuu" |
| 241 |
|
| 242 |
Mesmo os usuários que não bebem leite apreciam ouvir as vacas dizendo |
| 243 |
"muuu". |
| 244 |
|
| 245 |
A quantidade de mugidos dependerá da taxa de pacotes, portanto, deve |
| 246 |
corresponder muito bem ao ciclo diurno. |
| 247 |
|
| 248 |
Signed-off-by: Joe Defarmer <[email protected]> |
| 249 |
--- |
| 250 |
v3: |
| 251 |
- adicionada uma nota sobre a flutuação do mugido conforme a hora |
| 252 |
do dia na |
| 253 |
mensagem de commit |
| 254 |
v2: https://lore.kernel.org/netdev/[email protected]/ |
| 255 |
- corrigido argumento ausente na kernel doc para netif_is_bovine() |
| 256 |
- corrigido vazamento de memória (memory leak) em |
| 257 |
netdev_register_cow() |
| 258 |
v1: https://lore.kernel.org/netdev/[email protected]/ |
| 259 |
|
| 260 |
A mensagem de commit deve ser revisada para responder a quaisquer perguntas que |
| 261 |
os revisores tenham feito em discussões anteriores. Ocasionalmente, a |
| 262 |
atualização da mensagem de commit será a única mudança na nova versão. |
| 263 |
|
| 264 |
Reenvios parciais |
| 265 |
~~~~~~~~~~~~~~~~~ |
| 266 |
|
| 267 |
Por favor, sempre reenvie a série completa de patches e certifique-se de |
| 268 |
numerar seus patches de forma que fique claro que este é o conjunto mais |
| 269 |
recente e completo de patches que pode ser aplicado. Não tente reenviar apenas |
| 270 |
os patches que foram alterados. |
| 271 |
|
| 272 |
Lidando com patches aplicados incorretamente |
| 273 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 274 |
|
| 275 |
Ocasionalmente, uma série de patches é aplicada antes de receber feedback |
| 276 |
crítico, ou a versão errada de uma série é aplicada. |
| 277 |
|
| 278 |
Não é possível fazer o patch desaparecer uma vez que ele foi enviado (pushed); |
| 279 |
o histórico de commits nas árvores netdev é imutável. Por favor, envie versões |
| 280 |
incrementais sobre o que foi mesclado para corrigir os patches da maneira que |
| 281 |
eles ficariam se a sua série de patches mais recente fosse mesclada. |
| 282 |
|
| 283 |
Em casos onde uma reversão completa (revert) é necessária, a reversão deve ser |
| 284 |
enviada como um patch para a lista com uma mensagem de commit explicando os |
| 285 |
problemas técnicos com o commit revertido. Reversões devem ser usadas como |
| 286 |
último recurso, quando a mudança original está completamente errada; correções |
| 287 |
incrementais são preferidas. |
| 288 |
|
| 289 |
Árvore estável |
| 290 |
~~~~~~~~~~~~~~ |
| 291 |
|
| 292 |
Embora antigamente as submissões para a netdev não devessem carregar tags |
| 293 |
explícitas ``CC: [email protected]``, esse não é mais o caso hoje em dia. |
| 294 |
Por favor, siga as regras padrão de estabilidade em |
| 295 |
``Documentation/process/stable-kernel-rules.rst``, e certifique-se de incluir as |
| 296 |
tags Fixes apropriadas! |
| 297 |
|
| 298 |
Correções de segurança |
| 299 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 300 |
|
| 301 |
Não envie e-mails diretamente para os mantenedores da netdev se você acha que |
| 302 |
descobriu um bug que possa ter possíveis implicações de segurança. O atual |
| 303 |
mantenedor da netdev tem solicitado consistentemente que as pessoas usem as |
| 304 |
listas de discussão e não entrem em contato diretamente. Se você não estiver |
| 305 |
de acordo com isso, considere enviar um e-mail para [email protected] ou |
| 306 |
ler sobre http://oss-security.openwall.org/wiki/mailing-lists/distros como |
| 307 |
possíveis mecanismos alternativos. |
| 308 |
|
| 309 |
Envio conjunto de mudanças em componentes de espaço do usuário |
| 310 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 311 |
|
| 312 |
O código de espaço do usuário (*user space*) que exercita funcionalidades do |
| 313 |
kernel deve ser enviado juntamente com os patches do kernel. Isso dá aos |
| 314 |
revisores a chance de ver como qualquer nova interface é usada e quão |
| 315 |
bem ela funciona. |
| 316 |
|
| 317 |
Quando as ferramentas de espaço do usuário residem no próprio repositório do |
| 318 |
kernel, todas as alterações devem geralmente vir em uma única série. Se a série |
| 319 |
se tornar muito grande ou se o projeto de espaço do usuário não for revisado na |
| 320 |
netdev, inclua um link para um repositório público onde os patches de espaço do |
| 321 |
usuário possam ser vistos. |
| 322 |
|
| 323 |
No caso de ferramentas de espaço do usuário residirem em um repositório |
| 324 |
separado, mas serem revisadas na netdev (por exemplo, patches para ferramentas |
| 325 |
``iproute2``), os patches do kernel e do espaço do usuário devem formar séries |
| 326 |
(threads) separadas quando postados na lista de discussão, por exemplo:: |
| 327 |
|
| 328 |
[PATCH net-next 0/3] net: carta de apresentação de alguma funcionalidade |
| 329 |
└─ [PATCH net-next 1/3] net: preparação para alguma funcionalidade |
| 330 |
└─ [PATCH net-next 2/3] net: implementação de alguma funcionalidade |
| 331 |
└─ [PATCH net-next 3/3] selftest: net: alguma funcionalidade |
| 332 |
|
| 333 |
[PATCH iproute2-next] ip: adiciona suporte para alguma funcionalidade |
| 334 |
|
| 335 |
A postagem em uma única thread é desencorajada porque confunde o patchwork |
| 336 |
(a partir da versão 2.2.2 do patchwork). |
| 337 |
|
| 338 |
Envio conjunto de selftests |
| 339 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 340 |
|
| 341 |
Os selftests devem fazer parte da mesma série que as mudanças de código. |
| 342 |
Especificamente para correções, tanto a mudança de código quanto o teste |
| 343 |
relacionado devem ir para a mesma árvore (os testes podem não ter uma tag |
| 344 |
Fixes, o que é esperado). Misturar mudanças de código e mudanças de teste em |
| 345 |
um único commit é desencorajado. |
| 346 |
|
| 347 |
Preparando as mudanças |
| 348 |
---------------------- |
| 349 |
|
| 350 |
Atenção aos detalhes é importante. Releia seu próprio trabalho como se você |
| 351 |
fosse o revisor. Você pode começar usando o ``checkpatch.pl``, talvez até com |
| 352 |
a flag ``--strict``. Mas não seja robótico e irracional ao fazer isso. Se sua |
| 353 |
mudança for uma correção de bug, certifique-se de que seu log de commit indique |
| 354 |
o sintoma visível para o usuário final, a razão subjacente de por que isso |
| 355 |
acontece e, se necessário, explique por que a correção proposta é a melhor |
| 356 |
maneira de resolver as coisas. Não corrompa espaços em branco e, como é comum, |
| 357 |
não use recuos incorretos em argumentos de função que abrangem várias linhas. |
| 358 |
Se for o seu primeiro patch, envie-o para si mesmo por e-mail para que você |
| 359 |
possa testar a aplicação em uma árvore sem patches para confirmar que a |
| 360 |
infraestrutura não o danificou. |
| 361 |
|
| 362 |
Finalmente, volte e leia ``Documentation/process/submitting-patches.rst`` |
| 363 |
para ter certeza de que não está repetindo algum erro comum documentado lá. |
| 364 |
|
| 365 |
Indicando a árvore de destino |
| 366 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 367 |
|
| 368 |
Para ajudar os mantenedores e os bots de CI, você deve marcar explicitamente |
| 369 |
qual árvore seu patch tem como alvo. Supondo que você use git, utilize a flag |
| 370 |
de prefixo:: |
| 371 |
|
| 372 |
git format-patch --subject-prefix='PATCH net-next' inicio..fim |
| 373 |
|
| 374 |
Use ``net`` em vez de ``net-next`` (sempre em letras minúsculas) no comando |
| 375 |
acima para conteúdos de correção de bugs da árvore ``net``. |
| 376 |
|
| 377 |
Dividindo o trabalho em patches |
| 378 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 379 |
|
| 380 |
Coloque-se no lugar do revisor. Cada patch é lido separadamente e, portanto, |
| 381 |
deve constituir um passo compreensível em direção ao seu objetivo declarado. |
| 382 |
|
| 383 |
Evite enviar séries com mais de 15 patches. Séries maiores levam mais tempo |
| 384 |
para serem revisadas, pois os revisores adiarão a análise até encontrarem um |
| 385 |
grande bloco de tempo disponível. Uma série pequena pode ser revisada em pouco |
| 386 |
tempo, então os mantenedores simplesmente a revisam de imediato. Como resultado, |
| 387 |
uma sequência de séries menores é mesclada mais rapidamente e com melhor |
| 388 |
cobertura de revisão. Reenviar séries grandes também aumenta o tráfego na lista |
| 389 |
de discussão. |
| 390 |
|
| 391 |
Limitar patches pendentes na lista de discussão |
| 392 |
----------------------------------------------- |
| 393 |
|
| 394 |
Evite ter mais de 15 patches, em todas as séries, pendentes de revisão na lista |
| 395 |
de discussão para uma única árvore. Em outras palavras, um máximo de 15 patches |
| 396 |
sob revisão na ``net`` e um máximo de 15 patches sob revisão na ``net-next``. |
| 397 |
|
| 398 |
Este limite tem o objetivo de focar o esforço do desenvolvedor nos testes dos |
| 399 |
patches antes da revisão upstream, auxiliando a qualidade das submissões |
| 400 |
upstream e aliviando a carga sobre os revisores. |
| 401 |
|
| 402 |
Ordenação de variáveis locais ("árvore invertida", "RCS") |
| 403 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 404 |
|
| 405 |
A netdev tem uma convenção para ordenar variáveis locais em funções. Ordene as |
| 406 |
linhas de declaração de variáveis da mais longa para a mais curta, por exemplo:: |
| 407 |
|
| 408 |
struct scatterlist *sg; |
| 409 |
struct sk_buff *skb; |
| 410 |
int err, i; |
| 411 |
|
| 412 |
Se houver dependências entre as variáveis que impeçam a ordenação, mova a |
| 413 |
inicialização para fora da linha de declaração. |
| 414 |
|
| 415 |
Precedência de formatação |
| 416 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 417 |
|
| 418 |
Ao trabalhar em código existente que utiliza formatação não padrão, faça com |
| 419 |
que seu código siga as diretrizes mais recentes, para que, eventualmente, |
| 420 |
todo o código no domínio da netdev esteja no formato preferido. |
| 421 |
|
| 422 |
Uso de construções gerenciadas por dispositivo e cleanup.h |
| 423 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 424 |
|
| 425 |
Historicamente, a netdev permanece cética em relação às promessas de todas as |
| 426 |
APIs de "auto-limpeza" (auto-cleanup), incluindo até mesmo os auxiliares |
| 427 |
``devm_``. Eles não são o estilo preferido de implementação, apenas um estilo |
| 428 |
aceitável. |
| 429 |
|
| 430 |
O uso de ``guard()`` é desencorajado em qualquer função com mais de 20 linhas; |
| 431 |
``scoped_guard()`` é considerado mais legível. O uso de lock/unlock normal |
| 432 |
ainda é (levemente) preferido. |
| 433 |
|
| 434 |
Construções de limpeza de baixo nível (como ``__free()``) podem ser usadas ao |
| 435 |
construir APIs e auxiliares, especialmente iteradores com escopo. No entanto, o |
| 436 |
uso direto de ``__free()`` dentro do núcleo de rede (networking core) e drivers |
| 437 |
é desencorajado. Orientações semelhantes se aplicam à declaração de variáveis |
| 438 |
no meio da função. |
| 439 |
|
| 440 |
Patches de limpeza (Clean-up patches) |
| 441 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 442 |
|
| 443 |
A netdev desencoraja patches que realizam limpezas simples que não estejam no |
| 444 |
contexto de outro trabalho. Por exemplo: |
| 445 |
|
| 446 |
* Tratar avisos do ``checkpatch.pl`` e outros avisos triviais de estilo de |
| 447 |
codificação |
| 448 |
* Tratar problemas de Ordenação de variáveis locais |
| 449 |
* Conversões para APIs gerenciadas por dispositivo (auxiliares ``devm_``) |
| 450 |
|
| 451 |
Isso ocorre porque se considera que a agitação (*churn*) que tais mudanças |
| 452 |
produzem tem um custo maior do que o valor de tais limpezas. |
| 453 |
|
| 454 |
Por outro lado, correções de ortografia e gramática não são desencorajadas. |
| 455 |
|
| 456 |
Reenviando após a revisão |
| 457 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 458 |
|
| 459 |
Aguarde pelo menos 24 horas entre as postagens. Isso garantirá que revisores de |
| 460 |
todas as localizações geográficas tenham a chance de se manifestar. Não espere |
| 461 |
muito tempo (semanas) entre as postagens, pois isso tornará mais difícil para |
| 462 |
os revisores lembrarem de todo o contexto. |
| 463 |
|
| 464 |
Certifique-se de tratar todo o feedback em sua nova postagem. Não envie uma |
| 465 |
nova versão do código se a discussão sobre a versão anterior ainda estiver em |
| 466 |
andamento, a menos que seja instruído diretamente por um revisor. |
| 467 |
|
| 468 |
A nova versão dos patches deve ser postada como uma thread separada, não como |
| 469 |
uma resposta à postagem anterior. O registro de alterações (changelog) deve |
| 470 |
incluir um link para a postagem anterior (veja :ref:`Solicitações |
| 471 |
de mudanças`). |
| 472 |
|
| 473 |
Testes |
| 474 |
------ |
| 475 |
|
| 476 |
Nível de teste esperado |
| 477 |
~~~~~~~~~~~~~~~~~~~~~~~ |
| 478 |
|
| 479 |
No mínimo, suas alterações devem passar por uma compilação ``allyesconfig`` e |
| 480 |
uma ``allmodconfig`` com ``W=1`` definido, sem novos avisos ou falhas. |
| 481 |
|
| 482 |
O ideal é que você tenha feito testes em tempo de execução específicos para sua |
| 483 |
alteração, e que a série de patches contenha um conjunto de selftests do kernel |
| 484 |
para ``tools/testing/selftests/net`` ou usando o framework KUnit. |
| 485 |
|
| 486 |
Espera-se que você teste suas alterações no topo da árvore de rede relevante |
| 487 |
(``net`` ou ``net-next``) e não, por exemplo, em uma árvore estável ou na |
| 488 |
``linux-next``. |
| 489 |
|
| 490 |
Verificações do patchwork |
| 491 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 492 |
|
| 493 |
As verificações (*checks*) no patchwork são, em sua maioria, wrappers simples |
| 494 |
em torno de scripts existentes do kernel; as fontes estão disponíveis em: |
| 495 |
|
| 496 |
https://github.com/linux-netdev/nipa/tree/master/tests |
| 497 |
|
| 498 |
**Não** envie seus patches apenas para executá-los nas verificações. Você deve |
| 499 |
garantir que seus patches estejam prontos, testando-os localmente antes de |
| 500 |
postar na lista de discussão. A instância do bot de build do patchwork fica |
| 501 |
sobrecarregada com muita facilidade e a netdev@vger realmente não precisa de |
| 502 |
mais tráfego se pudermos evitar. |
| 503 |
|
| 504 |
netdevsim |
| 505 |
~~~~~~~~~ |
| 506 |
|
| 507 |
O ``netdevsim`` é um driver de teste que pode ser usado para exercitar APIs de |
| 508 |
configuração de driver sem a necessidade de hardware compatível. Mock-ups e |
| 509 |
testes baseados no ``netdevsim`` são fortemente encorajados ao adicionar novas |
| 510 |
APIs, mas o ``netdevsim`` em si **não** é considerado um caso de uso/usuário. |
| 511 |
Você também deve implementar as novas APIs em um driver real. |
| 512 |
|
| 513 |
Não damos garantias de que o ``netdevsim`` mudará no futuro de uma forma que |
| 514 |
quebraria o que normalmente seria considerado uAPI. O ``netdevsim`` é reservado |
| 515 |
apenas para uso por testes upstream, portanto, quaisquer novos recursos do |
| 516 |
``netdevsim`` devem ser acompanhados de selftests em ``tools/testing/selftests/``. |
| 517 |
|
| 518 |
Status de suporte para drivers |
| 519 |
------------------------------ |
| 520 |
|
| 521 |
.. note: |
| 522 |
|
| 523 |
Os requisitos a seguir aplicam-se apenas a drivers de NIC Ethernet. |
| 524 |
|
| 525 |
A netdev define requisitos adicionais para drivers que desejam adquirir o status |
| 526 |
``Supported`` (Suportado) no arquivo MAINTAINERS. Drivers ``Supported`` devem |
| 527 |
executar todos os testes de driver upstream e relatar os resultados duas vezes |
| 528 |
por dia. Drivers que não cumprirem este requisito devem usar o status |
| 529 |
``Maintained`` (Mantido). Atualmente, não há diferença na forma como os drivers |
| 530 |
``Supported`` e ``Maintained`` são tratados no upstream. |
| 531 |
|
| 532 |
As regras exatas que um driver deve seguir para adquirir o status ``Supported``: |
| 533 |
|
| 534 |
1. Deve executar todos os testes sob os alvos ``drivers/net`` e |
| 535 |
``drivers/net/hw`` dos selftests do Linux. A execução e o relato |
| 536 |
de testes privados / internos também são bem-vindos, mas os testes |
| 537 |
upstream são obrigatórios. |
| 538 |
|
| 539 |
2. A frequência mínima de execução é uma vez a cada 12 horas. Deve |
| 540 |
testar o branch designado a partir do feed de branches selecionado. |
| 541 |
Observe que os branches são construídos automaticamente e estão |
| 542 |
expostos à postagem intencional de patches maliciosos; portanto, |
| 543 |
os sistemas de teste devem ser isolados. |
| 544 |
|
| 545 |
3. Drivers que suportam múltiplas gerações de dispositivos devem |
| 546 |
testar pelo menos um dispositivo de cada geração. Um manifesto do |
| 547 |
ambiente de teste (*testbed manifest* - formato exato a definir) |
| 548 |
deve descrever os modelos de dispositivos testados. |
| 549 |
|
| 550 |
4. Os testes devem ser executados de forma confiável; se múltiplos |
| 551 |
branches forem ignorados ou se os testes falharem devido a problemas |
| 552 |
no ambiente de execução, o status ``Supported`` será retirado. |
| 553 |
|
| 554 |
5. Falhas nos testes devido a bugs no driver ou no próprio teste, |
| 555 |
ou falta de suporte para a funcionalidade que o teste visa, *não* |
| 556 |
são motivo para a perda do status ``Supported``. |
| 557 |
|
| 558 |
O CI da netdev manterá uma página oficial de dispositivos suportados, listando |
| 559 |
seus resultados de testes recentes. |
| 560 |
|
| 561 |
O mantenedor do driver pode providenciar para que outra pessoa execute o teste; |
| 562 |
não há exigência de que a pessoa listada como mantenedora (ou seu empregador) |
| 563 |
seja responsável pela execução dos testes. Colaborações entre |
| 564 |
fornecedores, hospedagem de CI no GitHub (GH CI), outros repositórios sob o |
| 565 |
linux-netdev, etc., são muito bem-vindas. |
| 566 |
|
| 567 |
Veja https://github.com/linux-netdev/nipa/wiki para mais informações sobre o CI |
| 568 |
da netdev. Sinta-se à vontade para entrar em contato com os mantenedores ou com |
| 569 |
a lista para quaisquer dúvidas. |
| 570 |
|
| 571 |
Orientações para revisores |
| 572 |
-------------------------- |
| 573 |
|
| 574 |
Revisar patches de outras pessoas na lista é altamente incentivado, |
| 575 |
independentemente do nível de experiência. Para orientações gerais e dicas |
| 576 |
úteis, consulte `revisão de tópicos avançados de desenvolvimento`. |
| 577 |
|
| 578 |
É seguro assumir que os mantenedores da netdev conhecem a comunidade e o nível |
| 579 |
de experiência dos revisores. Os revisores não devem se preocupar com o fato de |
| 580 |
seus comentários impedirem ou desviarem o fluxo de patches. Revisores menos |
| 581 |
experientes são fortemente incentivados a fazer uma revisão mais aprofundada das |
| 582 |
submissões e não focar exclusivamente em questões triviais ou subjetivas, como |
| 583 |
formatação de código, tags, etc. |
| 584 |
|
| 585 |
Depoimentos / feedback |
| 586 |
---------------------- |
| 587 |
|
| 588 |
Algumas empresas utilizam o feedback de colegas em revisões de desempenho de |
| 589 |
funcionários. Sinta-se à vontade para solicitar feedback dos mantenedores da |
| 590 |
netdev, especialmente se você dedica uma quantidade significativa de tempo |
| 591 |
revisando código e se esforça além do esperado para melhorar a infraestrutura |
| 592 |
compartilhada. |
| 593 |
|
| 594 |
O feedback deve ser solicitado por você, o colaborador, e será sempre |
| 595 |
compartilhado com você (mesmo que você solicite que ele seja enviado ao seu |
| 596 |
gerente). |