From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-vk1-f180.google.com (mail-vk1-f180.google.com [209.85.221.180]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D286523D7D4 for ; Mon, 9 Mar 2026 03:04:34 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.180 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773025477; cv=none; b=iW9GsgdavFigjnZapRfHXs9mrzYckFe/oPZoNykf2HZ/7XEyUGoR9T8/sGwCKZGLMZlCxSseO+VcBWh5CxO9ya98O1qC2xTG3vfPYN1sjlFAdumo+vB7kWccvRHMMzJR7OGMa5RctKR2B00MmvCF51jbOnf/gVtFvZ9Q8HJ2Zok= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773025477; c=relaxed/simple; bh=U7vkUBiIm307ZsG5fo2/Dk2wY+gL6yOY6SAaftZmdA4=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type; b=unW0tTfZ0IYsufXhs05KtnpHHx+SJPoMSj5jgpy4z2LhikMiz6/tfgU2ebeTOmHFJRzYpWwNBh4wA8TT7hnEe+djta6Nztx3yu70Ld9rex4tFJmI/Ate3EZlQzyJzNrwgraxliMQPc6Pyeh/OzGmkzbta/pT+heIEThiHxevCKM= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=OW+k1ePd; arc=none smtp.client-ip=209.85.221.180 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="OW+k1ePd" Received: by mail-vk1-f180.google.com with SMTP id 71dfb90a1353d-56a8fdaddebso3778648e0c.0 for ; Sun, 08 Mar 2026 20:04:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1773025474; x=1773630274; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=dFSeSmbG7O7LoMLWyLaZk+pq+MUzcVh0MjmKZEffs5M=; b=OW+k1ePdEjgngyQjUTGOQK4sMJijLsy9438XLnJXfUAJnJch/CyszEHNVBiDXV3DJC DFDg6AKVoMITQzxO9VqWzyOMQnvyeHls7iR+7T+O3WdVbNLPh9CIZ3C6AbMnkuG+SucE q4n9Hgl1B5MeHMeBRxjTjT2JyLnbcd1Tb6H45YNhgbGfyEMZsVMs8crXdJ438PbeipMZ IfV487H6qO5cYv8Fp6uc8EesFaXZp7jraSEyS6TmV6ExAsMVxSPOntEli3E7tqsbnu6S YqcCJUo/ZrdF3/Btw1VNOoAvOweRqkiMgBrvSQsRt9OdZGhOpnB8d5qyrqFlGg9YaZtI DdIg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1773025474; x=1773630274; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=dFSeSmbG7O7LoMLWyLaZk+pq+MUzcVh0MjmKZEffs5M=; b=a3dVGd+yLCTbXIH7hzm468oazBFoVSrxdGHPFa0LGp91of+NMvwB6tAC/CZGE2nRvS 0v9pyrBK+gRYCaCMk/XGPNXUjbc8qBxjyvNI6TnAl+2XReVpYEiITqHDkO6cmLRnsMRC Ncf/6lqLcbbpzR3HFBKjJi79M0dcbNTcsFMb0nZEJq5/DMAH5U0ofkfLDzMb7Yr+HXKw dQ2DZUdlivGygExFpxnwpESBZ0QZKdtvRSl3UNaT/MTUjEqaF1At3USDNGIznKv1QFT/ bShHSGwVhkuPC2fyQjBcRZGEa+mmknfXt8hQpwaylULnO+rhn/oS1tu5EBQtvhzoIsk6 3GbA== X-Gm-Message-State: AOJu0YyEcYaQMojagNIyPRYgk8xwg13rvIktE3vG51kRsmmU1ripHAiK wOnw/2kzgjE59OLxlxkp+3/91G+l5TtkhOUs3Gd5DHLhKp6xIH9ATvk0ssoyeqCs X-Gm-Gg: ATEYQzxvSIwUVnnaLuGag+tX+lt6x9g9VZgySt/BlKNMxSTZd1dVWgr6HQphm0Tqt8U thLgS+2FVln8u4YkgyMDk2zwrfPHM3zn+8b6hF80R8vppoB2aREeSy2Q0xAVPL1jW3n7A63F/aj Sp2tGgTmhoNkMBPGPFLADK93EHDZkk0fO6VlHEMwHbQvtK1SvcazoOKWcyGxKxpfPqkit8CM/iU Ke9XBAjdaVh67kdvC75J2LfO5C0P1nkI0u2odmCfQgwuODfEdMkq6CdfUs+Fo9ajb/hG9Es8KE+ NwZXpQT8XsuLnmHxE3CFMGPkj2kldZ2QV5Ghf+Tqt8xrDE9JRzE/i8ct/lmtDmdUUptnj1h2CGr A3ZVM5cWxge2Zzrhl4ucBFTOWk1tSnpRrUgOzyc6T+pTWC3HybvS0nSop1am+z8qFjsDSiT61/T efMdHUQ/6+/lkG6ehssCkjU1yCZa+sk0x3slRJVMuXYn+i4YQ2vQe/rDxD3MvcQSIK+/KF3XOxk VE6Zg== X-Received: by 2002:a05:6102:38cc:b0:5ff:d71e:c607 with SMTP id ada2fe7eead31-5ffe5f5693cmr3359103137.13.1773025472876; Sun, 08 Mar 2026 20:04:32 -0700 (PDT) Received: from localhost.localdomain ([2804:29b8:512d:4c55:1868:543f:1aeb:fd26]) by smtp.gmail.com with ESMTPSA id a1e0cc1a2514c-94e7b35f67bsm8129581241.5.2026.03.08.20.04.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 08 Mar 2026 20:04:31 -0700 (PDT) From: Daniel Pereira To: Jonathan Corbet Cc: linux-doc@vger.kernel.org, Daniel Pereira Subject: [PATCH docs-next v2] docs: pt_BR: add netdev and maintainer handbook translations Date: Mon, 9 Mar 2026 00:04:09 -0300 Message-ID: <20260309030411.88945-1-danielmaraboo@gmail.com> X-Mailer: git-send-email 2.47.3 Precedence: bulk X-Mailing-List: linux-doc@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Translate the netdev development process and the maintainer handbooks into Brazilian Portuguese. Also, update the main pt_BR index to link these documents. Signed-off-by: Daniel Pereira --- v2: - Fixed "Title level inconsistent" error in maintainer-netdev.rst (line 233). - Corrected section header hierarchy and length to match Sphinx requirements. - Fixed formatting errors in section headers (corrected "==" markers). - Cleaned up trailing whitespaces to pass checkpatch.pl. v1: - Initial submission. --- Documentation/translations/pt_BR/index.rst | 1 + .../pt_BR/process/maintainer-handbooks.rst | 10 +- .../pt_BR/process/maintainer-netdev.rst | 788 ++++++++++++++++++ 3 files changed, 798 insertions(+), 1 deletion(-) create mode 100644 Documentation/translations/pt_BR/process/maintainer-netdev.rst diff --git a/Documentation/translations/pt_BR/index.rst b/Documentation/translations/pt_BR/index.rst index de5c005f9..8822e21cf 100644 --- a/Documentation/translations/pt_BR/index.rst +++ b/Documentation/translations/pt_BR/index.rst @@ -69,3 +69,4 @@ kernel e sobre como ver seu trabalho integrado. Como começar Requisitos mínimos Manuais dos mantenedores + Processo do subsistema de rede (netdev) diff --git a/Documentation/translations/pt_BR/process/maintainer-handbooks.rst b/Documentation/translations/pt_BR/process/maintainer-handbooks.rst index eb650bc60..2d0a029e6 100644 --- a/Documentation/translations/pt_BR/process/maintainer-handbooks.rst +++ b/Documentation/translations/pt_BR/process/maintainer-handbooks.rst @@ -5,4 +5,12 @@ Notas sobre o processo de desenvolvimento de subsistemas e mantenedores O propósito deste documento é fornecer informações específicas de subsistemas que são suplementares ao manual geral do processo de -desenvolvimento :ref:`Documentation/process `. +desenvolvimento. + +Conteúdos: + +.. toctree:: + :numbered: + :maxdepth: 2 + + maintainer-netdev \ No newline at end of file diff --git a/Documentation/translations/pt_BR/process/maintainer-netdev.rst b/Documentation/translations/pt_BR/process/maintainer-netdev.rst new file mode 100644 index 000000000..abda4fe70 --- /dev/null +++ b/Documentation/translations/pt_BR/process/maintainer-netdev.rst @@ -0,0 +1,788 @@ +.. SPDX-License-Identifier: GPL-2.0 + + +===================================== +Subsistema de Rede do Linux (netdev) +===================================== + +tl;dr +----- + +- **Direcione seu patch para uma árvore** – use ``[PATCH net]``para correções + ou ``[PATCH net-next]`` para novas funcionalidades. +- **Tag Fixes** – para correções, a tag ``Fixes:`` é obrigatória, + independentemente da árvore de destino. +- **Tamanho da série** – não envie séries grandes (> 15 patches);divida-as em + partes menores. +- **Intervalo de envio** – não reenvie seus patches dentro de um período de 24 + horas. +- **Reverse xmas tree** – organize as declarações de variáveis locais da mais + longa para a mais curta. + +netdev +------ +A **netdev** é a lista de discussão para todos os assuntos do Linux +relacionados +a rede. Isso inclui qualquer item encontrado em ``net/`` (ex: código +principal +como IPv6) e em ``drivers/net`` (ex: drivers específicos de hardware) +na árvore +de diretórios do Linux. + +Note que alguns subsistemas (ex: drivers de rede sem fio/wireless), +que possuem +um alto volume de tráfego, possuem suas próprias listas de discussão +e árvores +específicas. + +Como muitas outras listas de discussão do Linux, a lista netdev é +hospedada no +`kernel.org `_, com arquivos disponíveis em +https://lore.kernel.org/netdev/. + +À exceção dos subsistemas mencionados anteriormente, todo o +desenvolvimento de +rede do Linux (ex: RFCs, revisões, comentários, etc.) ocorre na +**netdev**. + +Ciclo de Desenvolvimento +------------------------ + +Aqui está um pouco de informação contextual sobre a cadência de +desenvolvimento +do Linux. Cada nova versão (release) inicia-se com uma "janela de +mesclagem" +(*merge window*) de duas semanas, onde os mantenedores principais +enviam suas +novas implementações para o Linus para incorporação na árvore +principal +(*mainline tree*). + +Após as duas semanas, a janela de mesclagem é fechada e a versão é +nomeada/etiquetada como ``-rc1``. Nenhuma funcionalidade nova é +incorporada à +árvore principal após isso -- espera-se apenas correções (*fixes*) +para o +conteúdo da rc1. + +Após cerca de uma semana coletando correções para a rc1, a rc2 é +lançada. Isso +se repete semanalmente até a rc7 (tipicamente; às vezes rc6 se o +ritmo estiver +calmo, ou rc8 se houver muita instabilidade); uma semana após a última +vX.Y-rcN +ser concluída, a versão oficial vX.Y é lançada. + +Para descobrir em que ponto do ciclo estamos agora - carregue a página da +mainline (Linus) aqui: + + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +e observe o topo da seção de "tags". Se for rc1, estamos no início +do ciclo +de desenvolvimento. Se a rc7 foi marcada há uma semana, então um +lançamento +é provavelmente iminente. Se a tag mais recente for uma tag de +lançamento +final (sem o sufixo ``-rcN``) - muito provavelmente estamos em uma +janela de +mesclagem (*merge window*) e o ``net-next`` está fechado. + +Árvores git e fluxo de patches +------------------------------ + +Existem duas árvores de rede (repositórios git) em jogo. Ambas são +coordenadas +por David Miller, o mantenedor principal de rede. Há a árvore ``net`` +e a +árvore ``net-next``. Como você provavelmente pode adivinhar pelos +nomes, a +árvore ``net`` é para correções de código existente já na árvore +mainline de +Linus, e a ``net-next`` é para onde o novo código vai para o lançamento +futuro. +Você pode encontrar as árvores aqui: + +- https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git +- https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git + +Relacionando isso ao desenvolvimento do kernel: no início da janela +de mesclagem +(*merge window*) de 2 semanas, a árvore ``net-next`` será fechada -- +sem novas +mudanças ou funcionalidades. O conteúdo novo acumulado nas últimas +~10 semanas +será passado para a mainline/Linus via um *pull request* para a vX.Y -- +ao mesmo +tempo, a árvore ``net`` começará a acumular correções para este +conteúdo enviado +relacionado à vX.Y. + +Um anúncio indicando quando a ``net-next`` foi fechada é geralmente +enviado para +a netdev, mas sabendo o que foi dito acima, você pode prever isso com +antecedência. + +.. warning:: + Não envie novo conteúdo para a ``net-next`` para a netdev durante + o período + em que a árvore ``net-next`` estiver fechada. + +Patches RFC enviados apenas para revisão são obviamente bem-vindos +a qualquer +momento (use ``--subject-prefix='RFC net-next'`` com ``git +format-patch``). + +Pouco depois das duas semanas terem passado (e a vX.Y-rc1 ser lançada), +a árvore +para a ``net-next`` reabre para coletar conteúdo para o próximo +lançamento +(vX.Y+1). + +Se você não estiver inscrito na netdev e/ou simplesmente não tiver +certeza se a +``net-next`` já reabriu, basta verificar o link do repositório git da +``net-next`` acima para quaisquer novos *commits* relacionados à +rede. Você +também pode verificar o seguinte site para o status atual: + + https://netdev.bots.linux.dev/net-next.html + +A árvore ``net`` continua a coletar correções para o conteúdo da +vX.Y e é +enviada de volta para Linus em intervalos regulares (~semanais). Isso +significa +que o foco da ``net`` é a estabilização e correções de bugs. + +Finalmente, a vX.Y é lançada e todo o ciclo recomeça. + +Revisão de patches da netdev +---------------------------- + +Status do patch +~~~~~~~~~~~~~~~ + +O status de um patch pode ser verificado olhando a fila principal do +patchwork +para a netdev: + + https://patchwork.kernel.org/project/netdevbpf/list/ + +O campo "State" informará exatamente onde as coisas estão com o +seu patch: + +================= ============================================================ +Estado do patch Descrição +================= ============================================================ +New, Under review revisão pendente, o patch está na fila do mantenedor + para revisão; os dois estados são usados alternadamente + (dependendo do co-mantenedor exato que estiver lidando + com o patchwork no momento) +Accepted o patch foi aplicado à árvore de rede apropriada, + isso é geralmente definido de forma automática pelo pw-bot +Needs ACK aguardando um "ack" de um especialista da área + ou testes +Changes requested o patch não passou na revisão, espera-se uma nova + revisão com mudanças apropriadas no código e na mensagem + de commit +Rejected o patch foi rejeitado e não se espera uma nova + revisão +Not applicable espera-se que o patch seja aplicado fora do + subsistema de rede +Awaiting upstream o patch deve ser revisado e tratado pelo sub-mantenedor + apropriado, que o enviará para as árvores de rede; + patches definidos como ``Awaiting upstream`` no patchwork + da netdev geralmente permanecerão neste estado, + independentemente de o sub-mantenedor ter solicitado + mudanças, aceito ou rejeitado o patch +Deferred o patch precisa ser reenviado mais tarde, geralmente + devido a alguma dependência ou porque foi enviado para + uma árvore fechada +Superseded uma nova versão do patch foi enviada, geralmente + definido pelo pw-bot +RFC não deve ser aplicado, geralmente não está na + fila de revisão do mantenedor; o pw-bot pode definir + patches para este estado automaticamente com base nas + tags do assunto +================= ============================================================ + +Os patches são indexados pelo cabeçalho ``Message-ID`` dos e-mails que os +transportaram; portanto, se você tiver problemas para encontrar seu patch, +anexe o valor do ``Message-ID`` à URL acima. + +Atualizando o status do patch +----------------------------- + +Colaboradores e revisores não têm permissões para atualizar o estado +do patch +diretamente no patchwork. O Patchwork não expõe muitas informações +sobre o +histórico do estado dos patches; portanto, ter várias pessoas +atualizando o +estado leva a confusões. + +Em vez de delegar permissões do patchwork, a netdev usa um robô +de e-mail +simples (bot) que procura por comandos/linhas especiais dentro dos e-mails +enviados para a lista de discussão. Por exemplo, para marcar uma +série como +Mudanças Solicitadas (*Changes Requested*), é necessário enviar +a seguinte +linha em qualquer lugar na thread do e-mail:: + + pw-bot: changes-requested + +Como resultado, o bot definirá toda a série como Mudanças +Solicitadas. Isso +pode ser útil quando o autor descobre um bug em sua própria série +e deseja +evitar que ela seja aplicada. + +O uso do bot é totalmente opcional; em caso de dúvida, ignore +completamente a +existência dele. Os mantenedores classificarão e atualizarão o +estado dos +patches por conta própria. Nenhum e-mail deve ser enviado à lista com o +propósito principal de se comunicar com o bot; os comandos do bot +devem ser +vistos como metadados. + +O uso do bot é restrito aos autores dos patches (o cabeçalho ``From:`` +no envio +do patch e no comando deve coincidir!), mantenedores do código +modificado de +acordo com o arquivo MAINTAINERS (novamente, o ``From:`` deve coincidir +com a +entrada no MAINTAINERS) e alguns revisores seniores. + +O bot registra sua atividade aqui: + + https://netdev.bots.linux.dev/pw-bot.html + +Prazos de revisão +~~~~~~~~~~~~~~~~~ + +De modo geral, os patches são triados rapidamente (em menos de 48h). Mas +seja +paciente; se o seu patch estiver ativo no patchwork (ou seja, listado +na lista +de patches do projeto), as chances de ele ter sido esquecido são +próximas de +zero. + +O alto volume de desenvolvimento na netdev faz com que os revisores +encerrem +discussões de forma relativamente rápida. É muito improvável que novos +comentários e respostas cheguem após uma semana de silêncio. Se um +patch não +estiver mais ativo no patchwork e a thread ficar inativa por mais de uma +semana - esclareça os próximos passos e/ou envie a próxima versão. + +Especificamente para envios de RFC, se ninguém responder em uma semana - +ou os +revisores perderam o envio ou não têm opiniões fortes a respeito. Se +o código +estiver pronto, reenvie como um PATCH. + +E-mails dizendo apenas "ping" ou "bump" são considerados rudes. Se +você não +conseguir identificar o status do patch pelo patchwork ou onde a +discussão +parou - descreva sua melhor suposição e pergunte se ela está +correta. Por +exemplo:: + + Não entendo quais são os próximos passos. A Pessoa X parece estar + descontente + com A; devo fazer B e enviar novamente os patches? + +.. _Solicitações de mudanças: + +Mudanças solicitadas +~~~~~~~~~~~~~~~~~~~~ + +Patches marcados como ``Changes Requested`` precisam +ser revisados. A nova versão deve vir com um registro de alterações +(changelog), +preferencialmente incluindo links para as postagens anteriores, por +exemplo:: + + [PATCH net-next v3] net: faz as vacas dizerem "muuu" + + Mesmo os usuários que não bebem leite apreciam ouvir as vacas dizendo + "muuu". + + A quantidade de mugidos dependerá da taxa de pacotes, portanto, deve + corresponder muito bem ao ciclo diurno. + + Signed-off-by: Joe Defarmer + --- + v3: + - adicionada uma nota sobre a flutuação do mugido conforme a hora + do dia na + mensagem de commit + v2: https://lore.kernel.org/netdev/123themessageid@barn.org/ + - corrigido argumento ausente na kernel doc para netif_is_bovine() + - corrigido vazamento de memória (memory leak) em + netdev_register_cow() + v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/ + +A mensagem de commit deve ser revisada para responder a quaisquer +perguntas que +os revisores tenham feito em discussões anteriores. Ocasionalmente, a +atualização da mensagem de commit será a única mudança na nova +versão. + +Reenvios parciais +~~~~~~~~~~~~~~~~~ + +Por favor, sempre reenvie a série completa de patches e certifique-se de +numerar seus patches de forma que fique claro que este é o conjunto mais +recente e completo de patches que pode ser aplicado. Não tente reenviar +apenas +os patches que foram alterados. + +Lidando com patches aplicados incorretamente +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ocasionalmente, uma série de patches é aplicada antes de receber +feedback +crítico, ou a versão errada de uma série é aplicada. + +Não é possível fazer o patch desaparecer uma vez que ele foi enviado +(pushed); +o histórico de commits nas árvores netdev é imutável. Por favor, +envie versões +incrementais sobre o que foi mesclado para corrigir os patches da +maneira que +eles ficariam se a sua série de patches mais recente fosse mesclada. + +Em casos onde uma reversão completa (revert) é necessária, a reversão +deve ser +enviada como um patch para a lista com uma mensagem de commit explicando +os +problemas técnicos com o commit revertido. Reversões devem ser +usadas como +último recurso, quando a mudança original está completamente errada; +correções +incrementais são preferidas. + +Árvore estável +~~~~~~~~~~~~~~ + +Embora antigamente as submissões para a netdev não devessem carregar +tags +explícitas ``CC: stable@vger.kernel.org``, esse não é mais o caso +hoje em dia. +Por favor, siga as regras padrão de estabilidade em +``Documentation/process/stable-kernel-rules.rst``, e certifique-se de +incluir as +tags Fixes apropriadas! + +Correções de segurança +~~~~~~~~~~~~~~~~~~~~~~ + +Não envie e-mails diretamente para os mantenedores da netdev se você +acha que +descobriu um bug que possa ter possíveis implicações de segurança. O +atual +mantenedor da netdev tem solicitado consistentemente que as pessoas +usem as +listas de discussão e não entrem em contato diretamente. Se você +não estiver +de acordo com isso, considere enviar um e-mail para security@kernel.org ou +ler sobre http://oss-security.openwall.org/wiki/mailing-lists/distros como +possíveis mecanismos alternativos. + +Envio conjunto de mudanças em componentes de espaço do usuário +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +O código de espaço do usuário (*user space*) que exercita +funcionalidades do +kernel deve ser enviado juntamente com os patches do kernel. Isso dá aos +revisores a chance de ver como qualquer nova interface é usada e quão +bem ela +funciona. + +Quando as ferramentas de espaço do usuário residem no próprio +repositório do +kernel, todas as alterações devem geralmente vir em uma única +série. Se a série +se tornar muito grande ou se o projeto de espaço do usuário não for +revisado na +netdev, inclua um link para um repositório público onde os patches de +espaço do +usuário possam ser vistos. + +No caso de ferramentas de espaço do usuário residirem em um repositório +separado, mas serem revisadas na netdev (por exemplo, patches para +ferramentas +``iproute2``), os patches do kernel e do espaço do usuário devem +formar séries +(threads) separadas quando postados na lista de discussão, por exemplo:: + + [PATCH net-next 0/3] net: carta de apresentação de alguma + funcionalidade + └─ [PATCH net-next 1/3] net: preparação para alguma + funcionalidade + └─ [PATCH net-next 2/3] net: implementação de alguma + funcionalidade + └─ [PATCH net-next 3/3] selftest: net: alguma funcionalidade + + [PATCH iproute2-next] ip: adiciona suporte para alguma funcionalidade + +A postagem em uma única thread é desencorajada porque confunde +o patchwork +(a partir da versão 2.2.2 do patchwork). + +Envio conjunto de selftests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Os selftests devem fazer parte da mesma série que as mudanças de +código. +Especificamente para correções, tanto a mudança de código quanto +o teste +relacionado devem ir para a mesma árvore (os testes podem não ter +uma tag +Fixes, o que é esperado). Misturar mudanças de código e mudanças de +teste em +um único commit é desencorajado. + +Preparando as mudanças +---------------------- + +Atenção aos detalhes é importante. Releia seu próprio trabalho como +se você +fosse o revisor. Você pode começar usando o ``checkpatch.pl``, talvez +até com +a flag ``--strict``. Mas não seja robótico e irracional ao fazer +isso. Se sua +mudança for uma correção de bug, certifique-se de que seu log de +commit indique +o sintoma visível para o usuário final, a razão subjacente de por +que isso +acontece e, se necessário, explique por que a correção proposta é +a melhor +maneira de resolver as coisas. Não corrompa espaços em branco e, +como é comum, +não use recuos incorretos em argumentos de função que abrangem +várias linhas. +Se for o seu primeiro patch, envie-o para si mesmo por e-mail para +que você +possa testar a aplicação em uma árvore sem patches para confirmar que a +infraestrutura não o danificou. + +Finalmente, volte e leia +``Documentation/process/submitting-patches.rst`` +para ter certeza de que não está repetindo algum erro comum documentado +lá. + +Indicando a árvore de destino +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Para ajudar os mantenedores e os bots de CI, você deve marcar +explicitamente +qual árvore seu patch tem como alvo. Supondo que você use git, utilize +a flag +de prefixo:: + + git format-patch --subject-prefix='PATCH net-next' inicio..fim + +Use ``net`` em vez de ``net-next`` (sempre em letras minúsculas) +no comando +acima para conteúdos de correção de bugs da árvore ``net``. + +Dividindo o trabalho em patches +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Coloque-se no lugar do revisor. Cada patch é lido separadamente e, +portanto, +deve constituir um passo compreensível em direção ao seu objetivo +declarado. + +Evite enviar séries com mais de 15 patches. Séries maiores levam +mais tempo +para serem revisadas, pois os revisores adiarão a análise até +encontrarem um +grande bloco de tempo disponível. Uma série pequena pode ser revisada +em pouco +tempo, então os mantenedores simplesmente a revisam de imediato. Como +resultado, +uma sequência de séries menores é mesclada mais rapidamente e com +melhor +cobertura de revisão. Reenviar séries grandes também aumenta o tráfego +na lista +de discussão. + +Limitar patches pendentes na lista de discussão +----------------------------------------------- + +Evite ter mais de 15 patches, em todas as séries, pendentes de revisão +na lista +de discussão para uma única árvore. Em outras palavras, um máximo +de 15 patches +sob revisão na ``net`` e um máximo de 15 patches sob revisão na +``net-next``. + +Este limite tem o objetivo de focar o esforço do desenvolvedor nos +testes dos +patches antes da revisão upstream, auxiliando a qualidade das submissões +upstream e aliviando a carga sobre os revisores. + + +Ordenação de variáveis locais ("árvore invertida", "RCS") +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A netdev tem uma convenção para ordenar variáveis locais em +funções. Ordene as +linhas de declaração de variáveis da mais longa para a mais curta, +por exemplo:: + + struct scatterlist *sg; + struct sk_buff *skb; + int err, i; + +Se houver dependências entre as variáveis que impeçam a ordenação, +mova a +inicialização para fora da linha de declaração. + +Precedência de formatação +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ao trabalhar em código existente que utiliza formatação não padrão, +faça com +que seu código siga as diretrizes mais recentes, para que, eventualmente, +todo +o código no domínio da netdev esteja no formato preferido. + +Uso de construções gerenciadas por dispositivo e cleanup.h +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Historicamente, a netdev permanece cética em relação às promessas +de todas as +APIs de "auto-limpeza" (auto-cleanup), incluindo até mesmo os auxiliares +``devm_``. Eles não são o estilo preferido de implementação, apenas +um estilo +aceitável. + +O uso de ``guard()`` é desencorajado em qualquer função com mais de +20 linhas; +``scoped_guard()`` é considerado mais legível. O uso de lock/unlock +normal +ainda é (levemente) preferido. + +Construções de limpeza de baixo nível (como ``__free()``) podem ser +usadas ao +construir APIs e auxiliares, especialmente iteradores com escopo. No +entanto, o +uso direto de ``__free()`` dentro do núcleo de rede (networking core) +e drivers +é desencorajado. Orientações semelhantes se aplicam à declaração +de variáveis +no meio da função. + +Patches de limpeza (Clean-up patches) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A netdev desencoraja patches que realizam limpezas simples que não +estejam no +contexto de outro trabalho. Por exemplo: + +* Tratar avisos do ``checkpatch.pl`` e outros avisos triviais de estilo de + codificação +* Tratar problemas de Ordenação de variáveis locais +* Conversões para APIs gerenciadas por dispositivo (auxiliares ``devm_``) + +Isso ocorre porque se considera que a agitação (*churn*) que tais +mudanças +produzem tem um custo maior do que o valor de tais limpezas. + +Por outro lado, correções de ortografia e gramática não são +desencorajadas. + +Reenviando após a revisão +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Aguarde pelo menos 24 horas entre as postagens. Isso garantirá que +revisores de +todas as localizações geográficas tenham a chance de se +manifestar. Não espere +muito tempo (semanas) entre as postagens, pois isso tornará mais +difícil para +os revisores lembrarem de todo o contexto. + +Certifique-se de tratar todo o feedback em sua nova postagem. Não +envie uma +nova versão do código se a discussão sobre a versão anterior ainda +estiver em +andamento, a menos que seja instruído diretamente por um revisor. + +A nova versão dos patches deve ser postada como uma thread separada, +não como +uma resposta à postagem anterior. O registro de alterações (changelog) +deve +incluir um link para a postagem anterior (veja :ref:`Solicitações +de mudanças`). + +Testes +------ + +Nível de teste esperado +~~~~~~~~~~~~~~~~~~~~~~~ + +No mínimo, suas alterações devem passar por uma compilação +``allyesconfig`` e +uma ``allmodconfig`` com ``W=1`` definido, sem novos avisos ou falhas. + +O ideal é que você tenha feito testes em tempo de execução +específicos para sua +alteração, e que a série de patches contenha um conjunto de selftests +do kernel +para ``tools/testing/selftests/net`` ou usando o framework KUnit. + +Espera-se que você teste suas alterações no topo da árvore de rede +relevante +(``net`` ou ``net-next``) e não, por exemplo, em uma árvore estável +ou na +``linux-next``. + +Verificações do patchwork +~~~~~~~~~~~~~~~~~~~~~~~~~ + +As verificações (*checks*) no patchwork são, em sua maioria, wrappers +simples +em torno de scripts existentes do kernel; as fontes estão disponíveis +em: + +https://github.com/linux-netdev/nipa/tree/master/tests + +**Não** envie seus patches apenas para executá-los nas +verificações. Você deve +garantir que seus patches estejam prontos, testando-os localmente antes de +postar na lista de discussão. A instância do bot de build do patchwork +fica +sobrecarregada com muita facilidade e a netdev@vger realmente não +precisa de +mais tráfego se pudermos evitar. + +netdevsim +~~~~~~~~~ + +O ``netdevsim`` é um driver de teste que pode ser usado para exercitar +APIs de +configuração de driver sem a necessidade de hardware +compatível. Mock-ups e +testes baseados no ``netdevsim`` são fortemente encorajados ao adicionar +novas +APIs, mas o ``netdevsim`` em si **não** é considerado um caso de +uso/usuário. +Você também deve implementar as novas APIs em um driver real. + +Não damos garantias de que o ``netdevsim`` mudará no futuro de uma +forma que +quebraria o que normalmente seria considerado uAPI. + +O ``netdevsim`` é reservado apenas para uso por testes upstream, +portanto, +quaisquer novos recursos do ``netdevsim`` devem ser acompanhados de +selftests +em ``tools/testing/selftests/``. + +Status de suporte para drivers +------------------------------ + +.. note: + +Os requisitos a seguir aplicam-se apenas a drivers de NIC Ethernet. + +A netdev define requisitos adicionais para drivers que desejam adquirir o +status ``Supported`` (Suportado) no arquivo MAINTAINERS. Drivers +``Supported`` +devem executar todos os testes de driver upstream e relatar os resultados +duas +vezes por dia. Drivers que não cumprirem este requisito devem usar +o status +``Maintained`` (Mantido). Atualmente, não há diferença na forma como os +drivers ``Supported`` e ``Maintained`` são tratados no upstream. + +As regras exatas que um driver deve seguir para adquirir o status +``Supported``: + +1. Deve executar todos os testes sob os alvos ``drivers/net`` e + ``drivers/net/hw`` dos selftests do Linux. A execução e o relato + de testes privados / internos também são bem-vindos, mas os testes + upstream são obrigatórios. + +2. A frequência mínima de execução é uma vez a cada 12 horas. Deve + testar o branch designado a partir do feed de branches selecionado. + Observe que os branches são construídos automaticamente e estão + expostos à postagem intencional de patches maliciosos; portanto, + os sistemas de teste devem ser isolados. + +3. Drivers que suportam múltiplas gerações de dispositivos devem + testar pelo menos um dispositivo de cada geração. Um manifesto do + ambiente de teste (*testbed manifest* - formato exato a definir) + deve descrever os modelos de dispositivos testados. + +4. Os testes devem ser executados de forma confiável; se múltiplos + branches forem ignorados ou se os testes falharem devido a problemas + no ambiente de execução, o status ``Supported`` será retirado. + +5. Falhas nos testes devido a bugs no driver ou no próprio teste, + ou falta de suporte para a funcionalidade que o teste visa, *não* + são motivo para a perda do status ``Supported``. + +O CI da netdev manterá uma página oficial de dispositivos suportados, +listando +seus resultados de testes recentes. + +O mantenedor do driver pode providenciar para que outra pessoa execute +o teste; +não há exigência de que a pessoa listada como mantenedora (ou seu +empregador) +seja responsável pela execução dos testes. Colaborações entre +fornecedores, +hospedagem de CI no GitHub (GH CI), outros repositórios sob o +linux-netdev, +etc., são muito bem-vindas. + +Veja https://github.com/linux-netdev/nipa/wiki para mais informações +sobre o CI +da netdev. Sinta-se à vontade para entrar em contato com os mantenedores +ou com +a lista para quaisquer dúvidas. + +Orientações para revisores +-------------------------- + +Revisar patches de outras pessoas na lista é altamente incentivado, +independentemente do nível de experiência. Para orientações gerais +e dicas +úteis, consulte `revisão de tópicos avançados de desenvolvimento`. + +É seguro assumir que os mantenedores da netdev conhecem a comunidade +e o nível +de experiência dos revisores. Os revisores não devem se preocupar com +o fato de +seus comentários impedirem ou desviarem o fluxo de patches. +Less experienced reviewers are highly encouraged to do more in-depth +review of submissions and not focus exclusively on trivial or subjective +matters like code formatting, tags etc. + +Depoimentos / feedback +---------------------- + +Algumas empresas utilizam o feedback de colegas em revisões de +desempenho de +funcionários. Sinta-se à vontade para solicitar feedback dos +mantenedores da +netdev, especialmente se você dedica uma quantidade significativa +de tempo +revisando código e se esforça além do esperado para melhorar a +infraestrutura +compartilhada. + +O feedback deve ser solicitado por você, o colaborador, e será sempre +compartilhado com você (mesmo que você solicite que ele seja enviado +ao seu +gerente). -- 2.47.3