Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: pt_BR: add netdev and maintainer handbook translations
Add the Brazilian Portuguese translation for the netdev subsystem
process and update the maintainer handbook to include it.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260312122425.19577-1-danielmaraboo@gmail.com>
authored by
Daniel Pereira
and committed by
Jonathan Corbet
c991b7ef
97b5266d
+607
-1
+1
Documentation/translations/pt_BR/index.rst
+1
Documentation/translations/pt_BR/index.rst
+10
-1
Documentation/translations/pt_BR/process/maintainer-handbooks.rst
+10
-1
Documentation/translations/pt_BR/process/maintainer-handbooks.rst
···
5
5
6
6
O propósito deste documento é fornecer informações específicas de
7
7
subsistemas que são suplementares ao manual geral do processo de
8
-
desenvolvimento :ref:`Documentation/process <development_process_main>`.
8
+
desenvolvimento.
9
+
10
+
Conteúdos:
11
+
12
+
.. toctree::
13
+
:numbered:
14
+
:maxdepth: 2
15
+
16
+
maintainer-netdev
17
+
+596
Documentation/translations/pt_BR/process/maintainer-netdev.rst
+596
Documentation/translations/pt_BR/process/maintainer-netdev.rst
···
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 <joe@barn.org>
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/123themessageid@barn.org/
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/456getstheclicks@barn.org/
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: stable@vger.kernel.org``, 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 security@kernel.org 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).