* [PATCH 1/4] docs: pt_BR: translate coding-style.rst
2026-09-09 12:48 [PATCH 0/4] docs: pt_BR: process: Add remaining core process translations Daniel Pereira
@ 2026-09-09 12:48 ` Daniel Pereira
2026-09-09 12:48 ` [PATCH 2/4] docs: pt_BR: translate kernel-enforcement-statement.rst Daniel Pereira
` (2 subsequent siblings)
3 siblings, 0 replies; 5+ messages in thread
From: Daniel Pereira @ 2026-09-09 12:48 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
Translate Documentation/process/coding-style.rst into Brazilian
Portuguese and add it to the pt_BR process documentation index.
This document provides the coding style guidelines for Linux kernel
developers, ensuring consistency and readability across the codebase.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
.../pt_BR/process/coding-style.rst | 1318 +++++++++++++++++
.../translations/pt_BR/process/index.rst | 1 +
2 files changed, 1319 insertions(+)
create mode 100644 Documentation/translations/pt_BR/process/coding-style.rst
diff --git a/Documentation/translations/pt_BR/process/coding-style.rst b/Documentation/translations/pt_BR/process/coding-style.rst
new file mode 100644
index 000000000..26dcd1246
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/coding-style.rst
@@ -0,0 +1,1318 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Estilo de codificação do kernel Linux
+=====================================
+
+Este é um breve documento descrevendo o estilo de codificação preferido
+para o kernel Linux. O estilo de codificação é muito pessoal, e eu não
+**forçarei** minhas opiniões a ninguém, mas isso é o que vale para tudo
+que eu tenha que manter, e eu preferiria isso para a maioria das outras
+coisas também. Por favor, considere pelo menos os pontos aqui apresentados.
+
+Primeiramente, eu sugiro imprimir uma cópia dos padrões de codificação do GNU,
+e NÃO lê-la. Queime-as, é um grande gesto simbólico.
+
+De qualquer forma, aqui vai:
+
+
+1) Indentação
+-------------
+
+As tabulações têm 8 caracteres, e portanto as indentações também têm 8
+caracteres. Há movimentos heréticos que tentam fazer com que as indentações
+tenham 4 (ou até 2!) caracteres de profundidade, e isso é semelhante a
+tentar definir o valor de PI como 3.
+
+Justificativa: A ideia central da indentação é definir claramente onde um
+bloco de controle começa e termina. Especialmente quando você esteve olhando
+para a tela por 20 horas seguidas, você vai achar muito mais fácil ver como
+a indentação funciona se ela for mais ampla.
+
+Agora, algumas pessoas afirmarão que ter indentações de 8 caracteres faz
+o código se deslocar demais para a direita e dificultam a leitura em um
+terminal de 80 caracteres. A resposta é que, se você precisar de mais de 3
+níveis de indentação, você já está em apuros de qualquer forma, e deve
+corrigir seu programa.
+
+Em resumo, indentações de 8 caracteres deixam as coisas mais fáceis de ler, e
+têm o benefício adicional de avisar quando você está aninhando suas funções
+em excesso. Atenda a esse aviso.
+
+A maneira preferida de aliviar vários níveis de indentação em uma instrução
+``switch`` é alinhar o ``switch`` e seus rótulos subordinados ``case`` na
+mesma coluna, em vez de indentar duplamente os rótulos ``case``. Por exemplo:
+
+.. code-block:: c
+
+ switch (suffix) {
+ case 'G':
+ case 'g':
+ mem <<= 30;
+ break;
+ case 'M':
+ case 'm':
+ mem <<= 20;
+ break;
+ case 'K':
+ case 'k':
+ mem <<= 10;
+ fallthrough;
+ default:
+ break;
+ }
+
+Não coloque múltiplas instruções em uma única linha, a menos que você tenha
+algo para esconder:
+
+.. code-block:: c
+
+ if (condition) do_this;
+ do_something_everytime;
+
+Não use vírgulas para evitar usar chaves:
+
+.. code-block:: c
+
+ if (condition)
+ do_this(), do_that();
+
+Sempre use chaves para múltiplas instruções:
+
+.. code-block:: c
+
+ if (condition) {
+ do_this();
+ do_that();
+ }
+
+Também não coloque múltiplas atribuições em uma única linha. O estilo de
+codificação do kernel é extremamente simples. Evite expressões complicadas.
+
+
+Fora de comentários, documentação e, exceto em Kconfig, espaços nunca são
+usados para indentação, e o exemplo acima foi deliberadamente quebrado.
+
+Obtenha um editor decente e não deixe espaços em branco no final das linhas.
+
+
+2) Quebrando linhas longas e strings
+------------------------------------
+
+O estilo de codificação trata principalmente da legibilidade e da
+manutenibilidade usando ferramentas comumente disponíveis.
+
+O limite preferido para o comprimento de uma única linha é de 80 colunas.
+
+Instruções com mais de 80 colunas devem ser quebradas em partes sensatas,
+a menos que exceder 80 colunas aumente significativamente a legibilidade e
+não esconda informações.
+
+Os descendentes são sempre substancialmente mais curtos do que o pai e são
+colocados substancialmente à direita. Um estilo muito usado é alinhar os
+descendentes ao parêntese de abertura de uma função.
+
+Essas mesmas regras são aplicadas aos cabeçalhos de função com uma lista de
+argumentos longa.
+
+No entanto, nunca quebre strings visíveis ao usuário, como mensagens
+``printk``, porque isso prejudica a capacidade de fazer ``grep`` nelas.
+
+
+3) Posicionamento de chaves e espaços
+-------------------------------------
+
+A outra questão que sempre surge no estilo em C é o posicionamento das
+chaves. Ao contrário do tamanho da indentação, há poucos motivos técnicos
+para escolher uma estratégia de posicionamento em vez de outra, mas a forma
+preferida, como nos mostraram os profetas Kernighan e Ritchie, é colocar a
+chave de abertura no final da linha e a chave de fechamento no início, assim:
+
+.. code-block:: c
+
+ if (x is true) {
+ we do y
+ }
+
+Isso se aplica a todos os blocos de instruções que não sejam funções (if,
+switch, for, while, do). Por exemplo:
+
+.. code-block:: c
+
+ switch (action) {
+ case KOBJ_ADD:
+ return "add";
+ case KOBJ_REMOVE:
+ return "remove";
+ case KOBJ_CHANGE:
+ return "change";
+ default:
+ return NULL;
+ }
+
+No entanto, há um caso especial: as funções, que têm a chave de abertura no
+início da linha seguinte, assim:
+
+.. code-block:: c
+
+ int function(int x)
+ {
+ body of function
+ }
+
+Pessoas heréticas por todo o mundo afirmaram que essa inconsistência é ...
+bem ... inconsistente, mas todas as pessoas de bom senso sabem que (a) K&R
+estão **corretos** e (b) K&R estão certos. Além disso, as funções são
+especiais de qualquer forma (você não pode aninhá-las em C).
+
+Observe que a chave de fechamento fica vazia em uma linha própria, **exceto**
+nos casos em que ela é seguida por uma continuação da mesma instrução, ou
+seja, um ``while`` em um do-statement ou um ``else`` em um if-statement, como
+neste exemplo:
+
+.. code-block:: c
+
+ do {
+ body of do-loop
+ } while (condition);
+
+e
+
+.. code-block:: c
+
+ if (x == y) {
+ ..
+ } else if (x > y) {
+ ...
+ } else {
+ ....
+ }
+
+Justificativa: K&R.
+
+Além disso, observe que esse posicionamento de chaves também minimiza o
+número de linhas vazias (ou quase vazias), sem qualquer perda de
+legibilidade. Assim, como o suprimento de linhas novas na sua tela não é um
+recurso renovável (pense em telas de terminal de 25 linhas), você tem mais
+linhas vazias para colocar comentários.
+
+Não use chaves desnecessariamente quando uma única instrução basta.
+
+.. code-block:: c
+
+ if (condition)
+ action();
+
+e
+
+.. code-block:: c
+
+ if (condition)
+ do_this();
+ else
+ do_that();
+
+Isso não se aplica se apenas um ramo de uma instrução condicional for uma
+única instrução; nesse último caso, use chaves em ambos os ramos:
+
+.. code-block:: c
+
+ if (condition) {
+ do_this();
+ do_that();
+ } else {
+ otherwise();
+ }
+
+Além disso, use chaves quando um laço contiver mais de uma instrução simples:
+
+.. code-block:: c
+
+ while (condition) {
+ if (test)
+ do_something();
+ }
+
+3.1) Espaços
+************
+
+O estilo do kernel Linux para o uso de espaços depende (em grande parte) do
+uso de função versus palavra-chave. Use um espaço após (a maioria das)
+palavras-chave. As exceções notáveis são ``sizeof``, ``typeof``, ``alignof`` e
+``__attribute__``, que parecem um pouco com funções (e geralmente são usadas
+com parênteses no Linux, embora não sejam obrigatórias na linguagem, como em:
+``sizeof info`` depois que ``struct fileinfo info;`` é declarado).
+
+Então use um espaço após estas palavras-chave::
+
+ if, switch, case, for, do, while
+
+mas não com ``sizeof``, ``typeof``, ``alignof`` ou ``__attribute__``. Por
+exemplo,
+
+.. code-block:: c
+
+
+ s = sizeof(struct file);
+
+Não adicione espaços ao redor (dentro) de expressões entre parênteses. Este
+exemplo é **ruim**:
+
+.. code-block:: c
+
+
+ s = sizeof( struct file );
+
+Ao declarar dados de ponteiro ou uma função que retorna um tipo de ponteiro, o
+uso preferido de ``*`` fica adjacente ao nome dos dados ou ao nome da função e
+não adjacente ao nome do tipo. Exemplos:
+
+.. code-block:: c
+
+
+ char *linux_banner;
+ unsigned long long memparse(char *ptr, char **retptr);
+ char *match_strdup(substring_t *s);
+
+Use um espaço em volta (de cada lado) da maioria dos operadores binários e
+ternários, como qualquer um destes::
+
+ = + - < > * / % | & ^ <= >= == != ? :
+
+mas sem espaço após operadores unários::
+
+ & * + - ~ ! sizeof typeof alignof __attribute__ defined
+
+sem espaço antes dos operadores unários pós-fixados de incremento e
+decremento::
+
+ ++ --
+
+sem espaço após os operadores unários prefixados de incremento e
+decremento::
+
+ ++ --
+
+e sem espaço ao redor dos operadores de membro de estrutura ``.`` e ``->``.
+
+Não deixe espaços em branco no final das linhas. Alguns editores com
+indentação ``inteligente`` inserem espaços no início das novas linhas conforme
+apropriado, para que você possa começar a digitar a próxima linha de código
+imediatamente. No entanto, alguns desses editores não removem o espaço em
+branco se você acabar não colocando uma linha de código ali, como quando deixa
+uma linha em branco. Como resultado, você termina com linhas contendo espaço
+em branco no final.
+
+O Git avisará você sobre patches que introduzem espaço em branco no final e
+pode remover esse espaço automaticamente para você; entretanto, se você
+aplicar uma série de patches, isso pode fazer com que patches posteriores da
+série falhem ao alterar suas linhas de contexto.
+
+
+4) Nomeação
+-----------
+
+C é uma linguagem espartana, e suas convenções de nomenclatura devem seguir o
+mesmo caminho. Ao contrário dos programadores em Modula-2 e Pascal, os
+programadores em C não usam nomes bonitinhos como ThisVariableIsATemporaryCounter.
+Um programador em C chamaria essa variável de ``tmp``, o que é muito mais fácil
+de escrever e não é menos fácil de entender.
+
+ENTRETANTO, embora nomes em camelCase sejam desencorajados, nomes descritivos
+para variáveis globais são essenciais. Chamar uma função global de ``foo`` é
+um crime.
+
+Variáveis GLOBAIS (a serem usadas somente se você **realmente** precisar) devem
+ter nomes descritivos, assim como as funções globais. Se você tiver uma função
+que conta o número de usuários ativos, você deve chamá-la de
+``count_active_users()`` ou algo parecido; você **não** deve chamá-la de
+``cntusr()``.
+
+Codificar o tipo de uma função no nome (a chamada notação Húngara) é absurdo -
+o compilador conhece os tipos de qualquer forma e pode verificar isso, e isso
+só confunde o programador.
+
+Nomes de variáveis locais devem ser curtos e diretos. Se você tiver algum
+contador inteiro aleatório de loop, provavelmente deve ser chamado de ``i``.
+Chamá-lo de ``loop_counter`` é improdutivo, se não houver chance de ser mal
+interpretado. Da mesma forma, ``tmp`` pode ser praticamente qualquer tipo de
+variável usada para manter um valor temporário.
+
+Se você tem medo de misturar os nomes de variáveis locais, você tem outro
+problema, chamado síndrome de desequilíbrio de hormônio de crescimento da
+função. Veja o capítulo 6 (Funções).
+
+Para nomes de símbolos e documentação, evite introduzir o uso novo de
+'master / slave' (ou 'slave' independente de 'master') e 'blacklist /
+whitelist'.
+
+Substituições recomendadas para 'master / slave' são:
+ '{primary,main} / {secondary,replica,subordinate}'
+ '{initiator,requester} / {target,responder}'
+ '{controller,host} / {device,worker,proxy}'
+ 'leader / follower'
+ 'director / performer'
+
+Substituições recomendadas para 'blacklist/whitelist' são:
+ 'denylist / allowlist'
+ 'blocklist / passlist'
+
+Exceções para introduzir novos usos são manter uma ABI/API do espaço do
+usuário, ou ao atualizar código para um hardware ou especificação de
+protocolo existente (a partir de 2020) que exija esses termos. Para novas
+especificações, traduza o uso da terminologia na especificação para o padrão
+de codificação do kernel quando possível.
+
+5) Tipos definidos (typedefs)
+-----------------------------
+
+Por favor, não use coisas como ``vps_t``.
+É um **erro** usar ``typedef`` para estruturas e ponteiros. Quando você vê
+
+.. code-block:: c
+
+
+ vps_t a;
+
+no código-fonte, o que isso significa?
+Em contraste, se diz
+
+.. code-block:: c
+
+ struct virtual_container *a;
+
+você consegue dizer o que ``a`` é.
+
+Muitas pessoas pensam que ``typedef``s ``ajudam na legibilidade``. Não é bem
+assim. Eles são úteis apenas para:
+
+ (a) objetos totalmente opacos (onde o ``typedef`` é usado ativamente para
+ **ocultar** o que o objeto é).
+
+ Exemplo: ``pte_t`` etc. Objetos opacos que você só pode acessar usando
+ as funções de acesso apropriadas.
+
+ .. note::
+
+ Opacidade e ``funções de acesso`` não são boas em si mesmas.
+ A razão pela qual as temos para coisas como ``pte_t`` etc. é que
+ realmente existe absolutamente **zero** informação acessível de forma portátil
+ ali.
+
+ (b) tipos inteiros claros, em que a abstração **ajuda** a evitar confusão
+ sobre se é ``int`` ou ``long``.
+
+ ``u8/u16/u32`` são typedefs perfeitamente aceitáveis, embora se
+ encaixem melhor na categoria (d) do que aqui.
+
+ .. note::
+
+ Novamente - precisa haver uma **razão** para isso. Se algo é
+ ``unsigned long``, não há motivo para fazer
+
+ typedef unsigned long myflags_t;
+
+ mas se houver uma razão clara para que em certas circunstâncias possa
+ ser ``unsigned int`` e em outras configurações possa ser ``unsigned
+ long``, então, claro, use um ``typedef``.
+
+ (c) quando você usa ``sparse`` para criar literalmente um **novo** tipo para
+ verificação de tipos.
+
+ (d) novos tipos idênticos aos tipos padrão do C99, em certas
+ circunstâncias excepcionais.
+
+ Embora levasse apenas um curto período para os olhos e o cérebro se
+ acostumarem aos tipos padrão como ``uint32_t``, algumas pessoas ainda
+ se opõem ao seu uso.
+
+ Portanto, os tipos específicos do Linux ``u8/u16/u32/u64`` e seus
+ equivalentes assinados, que são idênticos aos tipos padrão, são
+ permitidos -- embora não sejam obrigatórios em código novo seu.
+
+ Ao editar código existente que já usa um ou outro conjunto de tipos, você
+ deve seguir as escolhas existentes nesse código.
+
+ (e) tipos seguros para uso em espaço do usuário.
+
+ Em certas estruturas visíveis ao espaço do usuário, não podemos exigir
+ tipos C99 nem usar a forma ``u32`` acima. Portanto, usamos ``__u32`` e
+ tipos semelhantes em todas as estruturas compartilhadas com o espaço do
+ usuário.
+
+Pode haver outros casos também, mas a regra básica deve ser: NUNCA use um
+``typedef`` a menos que você consiga encaixar claramente em uma dessas regras.
+
+Em geral, um ponteiro, ou uma estrutura com elementos que podem ser acessados
+diretamente, **nunca** deve ser um ``typedef``.
+
+
+6) Funções
+----------
+
+As funções devem ser curtas e diretas, e fazer apenas uma coisa. Elas devem
+caber em uma ou duas telas de texto (o tamanho de tela ISO/ANSI é 80x24,
+como todos sabem), e fazer uma coisa e fazê-la bem.
+
+O comprimento máximo de uma função é inversamente proporcional à complexidade
+e ao nível de indentação dessa função. Então, se você tiver uma função
+conceitualmente simples que seja apenas uma longa (mas simples) instrução
+``switch``, em que você precisa fazer várias pequenas coisas para muitos casos
+diferentes, é aceitável ter uma função mais longa.
+
+No entanto, se você tiver uma função complexa e suspeitar que um estudante
+do primeiro ano do ensino médio, menos talentoso, talvez nem entenda do que
+se trata a função, você deve obedecer aos limites máximos ainda mais de
+perto. Use funções auxiliares com nomes descritivos (você pode pedir ao
+compilador para incorporá-las em linha se achar que é crítico para o
+desempenho, e provavelmente ele fará um trabalho melhor do que você faria).
+
+Outra medida da função é o número de variáveis locais. Elas não devem exceder
+5-10, ou algo está errado. Reflita sobre a função e divida em partes menores.
+Um cérebro humano geralmente consegue rastrear facilmente cerca de 7 coisas
+diferentes; qualquer quantidade acima disso o confunde. Você sabe que é
+brilhante, mas talvez queira entender o que fez daqui a 2 semanas.
+
+Nos arquivos de código-fonte, separe as funções com uma linha em branco. Se a
+função for exportada, a macro **EXPORT** para ela deve seguir imediatamente
+depois da linha da chave de fechamento da função. Por exemplo:
+
+.. code-block:: c
+
+ int system_is_up(void)
+ {
+ return system_state == SYSTEM_RUNNING;
+ }
+ EXPORT_SYMBOL(system_is_up);
+
+6.1) Protótipos de função
+*************************
+
+Nos protótipos de função, inclua nomes de parâmetros junto com seus tipos de
+dados. Embora isso não seja obrigatório pela linguagem C, é preferido no Linux
+porque é uma maneira simples de adicionar informações valiosas para o leitor.
+
+Não use a palavra-chave ``extern`` em declarações de função, pois isso torna
+as linhas mais longas e não é estritamente necessário.
+
+Ao escrever protótipos de função, por favor mantenha a `ordem dos elementos
+regular <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_.
+Por exemplo, usando este exemplo de declaração de função::
+
+ __init void * __must_check action(enum magic value, size_t size, u8 count,
+ char *fmt, ...) __printf(4, 5) __malloc;
+
+A ordem preferida dos elementos para um protótipo de função é:
+
+- classe de armazenamento (abaixo, ``static __always_inline``, observando que
+ ``__always_inline`` é tecnicamente um atributo, mas é tratado como ``inline``)
+- atributos de classe de armazenamento (aqui, ``__init`` -- ou seja,
+ declarações de seção, mas também coisas como ``__cold``)
+- tipo de retorno (aqui, ``void *``)
+- atributos do tipo de retorno (aqui, ``__must_check``)
+- nome da função (aqui, ``action``)
+- parâmetros da função (aqui, ``(enum magic value, size_t size, u8 count,
+ char *fmt, ...)``, observando que os nomes dos parâmetros devem sempre ser
+ incluídos)
+- atributos dos parâmetros da função (aqui, ``__printf(4, 5)``)
+- atributos de comportamento da função (aqui, ``__malloc``)
+
+Observe que, para uma **definição** de função (ou seja, o corpo real da
+função), o compilador não permite atributos de parâmetro da função depois dos
+parâmetros da função. Nesses casos, eles devem vir depois dos atributos da
+classe de armazenamento (por exemplo, observe a posição alterada de
+``__printf(4, 5)`` abaixo, em comparação com o exemplo de **declaração**
+acima)::
+
+ static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value,
+ size_t size, u8 count, char *fmt, ...) __malloc
+ {
+ ...
+ }
+
+7) Saída centralizada de funções
+--------------------------------
+
+Embora seja depreciado por algumas pessoas, o equivalente da instrução
+``goto`` é usado com frequência pelos compiladores na forma da instrução de
+salto incondicional.
+
+A instrução ``goto`` é útil quando uma função sai de vários pontos e é
+necessária alguma tarefa comum, como limpeza. Se não for necessária nenhuma
+limpeza, basta retornar diretamente.
+
+Escolha nomes de rótulos que indiquem o que o ``goto`` faz ou por que ele
+existe. Um exemplo de nome bom poderia ser ``out_free_buffer:`` se o goto
+liberar ``buffer``. Evite usar nomes do GW-BASIC como ``err1:`` e ``err2:``,
+porque você teria que renumerá-los se adicionasse ou removesse caminhos de
+saída, e isso também torna a correção mais difícil de verificar.
+
+A justificativa para usar gotos é:
+
+- instruções incondicionais são mais fáceis de entender e seguir
+- o aninhamento é reduzido
+- erros por não atualizar pontos de saída individuais ao fazer
+ modificações são evitados
+- economiza o trabalho do compilador de otimizar e remover código redundante ;)
+
+.. code-block:: c
+
+ int fun(int a)
+ {
+ int result = 0;
+ char *buffer;
+
+ buffer = kmalloc(SIZE, GFP_KERNEL);
+ if (!buffer)
+ return -ENOMEM;
+
+ if (condition1) {
+ while (loop1) {
+ ...
+ }
+ result = 1;
+ goto out_free_buffer;
+ }
+ ...
+ out_free_buffer:
+ kfree(buffer);
+ return result;
+ }
+
+Um tipo comum de bug do qual você deve estar ciente é o ``one err bugs``
+(o "bug de um erro"), que se parece com isto:
+
+.. code-block:: c
+
+ err:
+ kfree(foo->bar);
+ kfree(foo);
+ return ret;
+
+O problema neste código é que, em alguns caminhos de saída, ``foo`` é NULL.
+Normalmente, a correção é dividir em dois rótulos de erro
+``err_free_bar:`` e ``err_free_foo:``:
+
+.. code-block:: c
+
+ err_free_bar:
+ kfree(foo->bar);
+ err_free_foo:
+ kfree(foo);
+ return ret;
+
+Idealmente, você deve simular erros para testar todos os caminhos de saída.
+
+
+8) Comentários
+--------------
+
+Comentários são bons, mas também há o perigo de comentar demais. NUNCA tente
+explicar COMO o seu código funciona em um comentário: é muito melhor escrever
+o código de forma que o **funcionamento** seja óbvio, e é um desperdício de
+tempo explicar código mal escrito.
+
+Em geral, você quer que seus comentários digam O QUE o seu código faz, não
+COMO. Também tente evitar colocar comentários dentro do corpo de uma função:
+se a função for tão complexa que você precisa comentar partes separadas dela,
+provavelmente você deveria voltar ao capítulo 6 por um tempo. Você pode fazer
+pequenos comentários para notar ou avisar sobre algo particularmente esperto
+(ou feio), mas tente evitar excesso. Em vez disso, coloque os comentários no
+início da função, dizendo às pessoas o que ela faz e, possivelmente, POR QUE
+ela faz isso.
+
+Ao comentar as funções da API do kernel, por favor use o formato kernel-doc.
+Veja os arquivos em :ref:`Documentation/doc-guide/ <doc_guide>` e
+``tools/docs/kernel-doc`` para detalhes. Observe que o perigo de comentar em
+excesso se aplica aos comentários kernel-doc da mesma forma. Não adicione
+kernel-doc genérico que apenas repete o que já é óbvio pela assinatura da
+função.
+
+O estilo preferido para comentários longos (em várias linhas) é:
+
+.. code-block:: c
+
+ /*
+ * Este é o estilo preferido para comentários em várias linhas
+ * no código-fonte do kernel Linux.
+ * Por favor, use-o de forma consistente.
+ *
+ * Descrição: uma coluna de asteriscos à esquerda,
+ * com linhas de início e fim quase vazias.
+ */
+
+Também é importante comentar dados, sejam tipos básicos ou tipos derivados.
+Para isso, use apenas uma declaração de dado por linha (sem vírgulas para
+múltiplas declarações de dados). Isso deixa espaço para um pequeno comentário
+em cada item explicando seu uso.
+
+
+9) Você fez uma bagunça
+-----------------------
+
+Tudo bem, todos fazemos isso. Você provavelmente foi informado por seu
+auxiliar de longa data em Unix que o ``GNU emacs`` formata automaticamente os
+arquivos-fonte em C para você, e você percebeu que ele realmente faz isso, mas as
+configurações padrão que ele usa são menos do que desejáveis (na verdade,
+elas são piores do que digitação aleatória - um número infinito de macacos
+digitando no GNU emacs nunca faria um bom programa).
+
+Então, você pode ou se livrar do GNU emacs, ou mudar para usar valores mais
+sãos. Para fazer isso, você pode colocar o seguinte no seu arquivo .emacs:
+
+.. code-block:: elisp
+
+ (defun c-lineup-arglist-tabs-only (ignored)
+ "Line up argument lists by tabs, not spaces"
+ (let* ((anchor (c-langelem-pos c-syntactic-element))
+ (column (c-langelem-2nd-pos c-syntactic-element))
+ (offset (- (1+ column) anchor))
+ (steps (floor offset c-basic-offset)))
+ (* (max steps 1)
+ c-basic-offset)))
+
+ (dir-locals-set-class-variables
+ 'linux-kernel
+ '((c-mode . (
+ (c-basic-offset . 8)
+ (c-label-minimum-indentation . 0)
+ (c-offsets-alist . (
+ (arglist-close . c-lineup-arglist-tabs-only)
+ (arglist-cont-nonempty .
+ (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
+ (arglist-intro . +)
+ (brace-list-intro . +)
+ (c . c-lineup-C-comments)
+ (case-label . 0)
+ (comment-intro . c-lineup-comment)
+ (cpp-define-intro . +)
+ (cpp-macro . -1000)
+ (cpp-macro-cont . +)
+ (defun-block-intro . +)
+ (else-clause . 0)
+ (func-decl-cont . +)
+ (inclass . +)
+ (inher-cont . c-lineup-multi-inher)
+ (knr-argdecl-intro . 0)
+ (label . -1000)
+ (statement . 0)
+ (statement-block-intro . +)
+ (statement-case-intro . +)
+ (statement-cont . +)
+ (substatement . +)
+ ))
+ (indent-tabs-mode . t)
+ (show-trailing-whitespace . t)
+ ))))
+
+ (dir-locals-set-directory-class
+ (expand-file-name "~/src/linux-trees")
+ 'linux-kernel)
+
+Isso fará o emacs funcionar melhor com o estilo de codificação do kernel para
+arquivos C abaixo de ``~/src/linux-trees``.
+
+Mas, mesmo que você falhe em fazer o emacs formatar de maneira sensata, nem
+tudo está perdido: use ``indent``.
+
+Agora, novamente, o GNU indent tem as mesmas configurações sem cérebro do GNU
+emacs, e é por isso que você precisa dar a ele algumas opções de linha de
+comando. No entanto, isso não é tão ruim, porque até os criadores do GNU
+indent reconhecem a autoridade do K&R (as pessoas do GNU não são más, apenas
+estão gravemente equivocadas nessa questão), então você apenas dá ao indent as
+opções ``-kr -i8`` (que significa ``K&R, indentações de 8 caracteres``), ou
+usa ``scripts/Lindent``, que indenta no estilo mais recente.
+
+``indent`` tem muitas opções, e especialmente quando se trata de reformatação
+de comentários, você pode querer dar uma olhada na página de manual. Mas
+lembre-se: ``indent`` não é uma solução para programação ruim.
+
+Observe que você também pode usar a ferramenta ``clang-format`` para ajudá-lo
+com essas regras, para reformatar rapidamente partes do seu código
+automaticamente e revisar arquivos completos para detectar erros de estilo de
+codificação, erros de digitação e possíveis melhorias. Também é útil para
+ordenar ``#includes``, alinhar variáveis/macros, reorganizar texto e outras
+tarefas semelhantes. Consulte o arquivo
+:ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
+para obter mais detalhes.
+
+Algumas configurações básicas do editor, como indentação e finais de linha,
+serão definidas automaticamente se você estiver usando um editor compatível com
+o EditorConfig. Consulte o site oficial do EditorConfig para obter mais
+informação: https://editorconfig.org/
+
+10) Arquivos de configuração Kconfig
+------------------------------------
+
+Para todos os arquivos de configuração Kconfig* em toda a árvore de origem,
+a indentação é um pouco diferente. Linhas sob uma definição ``config`` são
+indentadas com uma tabulação, enquanto o texto de ajuda é indentado com mais
+dois espaços. Exemplo::
+
+ config AUDIT
+ bool "Auditing support"
+ depends on NET
+ help
+ Enable auditing infrastructure that can be used with another
+ kernel subsystem, such as SELinux (which requires this for
+ logging of avc messages output). Does not do system-call
+ auditing without CONFIG_AUDITSYSCALL.
+
+Recursos seriamente perigosos (como suporte de gravação para certos sistemas
+de arquivos) devem anunciar isso de forma proeminente na string do prompt::
+
+ config ADFS_FS_RW
+ bool "ADFS write support (DANGEROUS)"
+ depends on ADFS_FS
+ ...
+
+Para documentação completa sobre os arquivos de configuração, consulte o
+arquivo Documentation/kbuild/kconfig-language.rst.
+
+
+11) Estruturas de dados
+-----------------------
+
+Estruturas de dados que tenham visibilidade fora do ambiente monothread em que
+são criadas e destruídas devem ter contadores de referência. No kernel, coleta
+de lixo não existe (e fora do kernel, a coleta de lixo é lenta e
+ineficiente), o que significa que você absolutamente **precisa** contar todas
+as referências de uso.
+
+Contagem de referência significa que você pode evitar bloqueios e permite que
+múltiplos usuários tenham acesso à estrutura de dados em paralelo - sem se
+preocupar com a estrutura desaparecendo debaixo deles do nada apenas porque
+eles dormiram ou fizeram outra coisa por um tempo.
+
+Observe que bloqueio **não** substitui contagem de referência. O bloqueio é
+usado para manter estruturas de dados coerentes, enquanto a contagem de
+referência é uma técnica de gerenciamento de memória. Normalmente, ambos são
+necessários, e não devem ser confundidos entre si.
+
+Muitas estruturas de dados podem, de fato, ter dois níveis de contagem de
+referência, quando existem usuários de diferentes ``classes``. A contagem da
+subclasse conta o número de usuários da subclasse e decrementa a contagem
+global apenas uma vez quando a contagem da subclasse chega a zero.
+
+Exemplos desse tipo de ``multi-level-reference-counting`` podem ser encontrados
+em gerenciamento de memória (``struct mm_struct``: mm_users e mm_count) e em
+código de sistema de arquivos (``struct super_block``: s_count e s_active).
+
+Lembre-se: se outra thread puder encontrar sua estrutura de dados, e você não
+tiver contagem de referência nela, quase certamente há um bug.
+
+
+12) Macros, enums e RTL
+-----------------------
+
+Nomes de macros que definem constantes e rótulos em enums são maiúsculos.
+
+.. code-block:: c
+
+ #define CONSTANT 0x12345
+
+Enums são preferidos quando várias constantes relacionadas são definidas.
+
+Nomes de macro em maiúsculas são apreciados, mas macros que se parecem com
+funções podem ser nomeadas em minúsculas.
+
+Em geral, funções inline são preferíveis a macros que se parecem com funções.
+
+Macros com múltiplas instruções devem ser envoltas em um bloco do-while:
+
+.. code-block:: c
+
+ #define macrofun(a, b, c) \
+ do { \
+ if (a == 5) \
+ do_this(b, c); \
+ } while (0)
+
+Macros do tipo função com parâmetros não usados devem ser substituídas por
+funções estáticas inline para evitar o problema de variáveis não usadas:
+
+.. code-block:: c
+
+ static inline void fun(struct foo *foo)
+ {
+ }
+
+Devido a práticas históricas, muitos arquivos ainda empregam a abordagem
+"cast para (void)" para avaliar parâmetros. No entanto, esse método não é
+aconselhável.
+Funções inline resolvem o problema de "expressão com efeitos colaterais
+avaliada mais de uma vez", contornam problemas de variáveis não usadas e, por
+algum motivo, geralmente são mais bem documentadas do que macros.
+
+.. code-block:: c
+
+ /*
+ * Evite fazer isto sempre que possível e prefira funções estáticas
+ * inline
+ */
+ #define macrofun(foo) do { (void) (foo); } while (0)
+
+Coisas a evitar ao usar macros:
+
+1) macros que afetam o fluxo de controle:
+
+.. code-block:: c
+
+ #define FOO(x) \
+ do { \
+ if (blah(x) < 0) \
+ return -EBUGGERED; \
+ } while (0)
+
+é uma ideia **muito** ruim. Ela parece uma chamada de função, mas sai da
+função ``calling``; não quebre os parsers internos de quem lerá o código.
+
+2) macros que dependem de ter uma variável local com um nome mágico:
+
+.. code-block:: c
+
+ #define FOO(val) bar(index, val)
+
+pode parecer uma boa coisa, mas é confuso pra caramba para quem lê o código e
+é propenso a quebrar com mudanças aparentemente inocentes.
+
+3) macros com argumentos usados como l-values: FOO(x) = y; vai te morder se
+alguém, por exemplo, transformar FOO em uma função inline.
+
+4) esquecer da precedência: macros que definem constantes usando expressões
+devem colocar a expressão entre parênteses. Cuidado com problemas semelhantes
+com macros que usam parâmetros.
+
+.. code-block:: c
+
+ #define CONSTANT 0x4000
+ #define CONSTEXP (CONSTANT | 3)
+
+5) colisões de namespace ao definir variáveis locais em macros que se
+parecem com funções:
+
+.. code-block:: c
+
+ #define FOO(x) \
+ ({ \
+ typeof(x) ret; \
+ ret = calc_ret(x); \
+ (ret); \
+ })
+
+``ret`` é um nome comum para uma variável local - ``__foo_ret`` tem menos
+chance de colidir com uma variável existente.
+
+O manual do cpp trata de macros de forma exaustiva. O manual interno do gcc
+também cobre o RTL, que é usado frequentemente com linguagem de montagem no
+kernel.
+
+
+13) Imprimindo mensagens do kernel
+----------------------------------
+
+Desenvolvedores do kernel gostam de ser vistos como letrados. Preste atenção à
+ortografia das mensagens do kernel para causar uma boa impressão. Não use
+contrações incorretas como ``dont``; use ``do not`` ou ``don't`` em vez
+disso. Faça as mensagens concisas, claras e inequívocas.
+
+Mensagens do kernel não precisam terminar com ponto.
+
+Imprimir números entre parênteses (%d) não agrega valor e deve ser evitado.
+
+Há vários macros de diagnóstico do modelo de driver em <linux/dev_printk.h>
+que você deve usar para garantir que as mensagens sejam correspondidas ao
+dispositivo e driver corretos e sejam marcadas com o nível certo: ``dev_err()``,
+``dev_warn()``, ``dev_info()`` e assim por diante. Para mensagens que não
+estão associadas a um device específico, <linux/printk.h> define
+``pr_notice()``, ``pr_info()``, ``pr_warn()``, ``pr_err()`` etc. Quando os
+drivers funcionam corretamente, eles ficam silenciosos, então prefira usar
+``dev_dbg``/``pr_debug`` a menos que algo esteja errado.
+
+Encontrar boas mensagens de depuração pode ser um desafio; e, uma vez que
+você tenha essas mensagens, elas podem ajudar bastante para solução de
+problemas remota. No entanto, a impressão de mensagens de depuração é tratada
+diferentemente da impressão de outras mensagens não de depuração. Enquanto as
+outras funções ``pr_XXX()`` imprimem incondicionalmente, ``pr_debug()`` não;
+ela é compilada fora por padrão, a menos que ``DEBUG`` seja definido ou
+``CONFIG_DYNAMIC_DEBUG`` esteja configurado. Isso também vale para
+``dev_dbg()``, e uma convenção relacionada usa ``VERBOSE_DEBUG`` para adicionar
+mensagens ``dev_vdbg()`` às já habilitadas por ``DEBUG``.
+
+Muitos subsistemas têm opções de depuração do Kconfig para ativar ``-DDEBUG``
+no Makefile correspondente; em outros casos, arquivos específicos fazem
+``#define DEBUG``. E quando uma mensagem de depuração deve ser impressa
+incondicionalmente, por exemplo, se ela já estiver dentro de uma seção
+``#ifdef`` relacionada à depuração, pode-se usar ``printk(KERN_DEBUG ...)``.
+
+
+14) Alocando memória
+--------------------
+
+O kernel fornece os seguintes alocadores de memória de uso geral:
+``kmalloc()``, ``kzalloc()``, ``kmalloc_objs()``, ``kzalloc_objs()``,
+``vmalloc()`` e ``vzalloc()``. Consulte a documentação da API para obter mais
+informações sobre eles. :ref:`Documentation/core-api/memory-allocation.rst
+<memory_allocation>`
+
+A forma preferida de passar o tamanho de uma estrutura é a seguinte:
+
+.. code-block:: c
+
+ p = kmalloc_obj(*p, ...);
+
+A forma alternativa em que o nome da estrutura é escrito explicitamente piora a
+legibilidade e cria oportunidade para um bug quando o tipo da variável ponteiro
+é alterado, mas o ``sizeof`` correspondente passado para um alocador de memória
+não é.
+
+Casting do valor de retorno, que é um ponteiro ``void``, é redundante. A
+conversão de ponteiro ``void`` para qualquer outro tipo de ponteiro é garantida
+pela linguagem de programação C.
+
+A forma preferida para alocar um array é a seguinte:
+
+.. code-block:: c
+
+ p = kmalloc_objs(*p, n, ...);
+
+A forma preferida para alocar um array zerado é a seguinte:
+
+.. code-block:: c
+
+ p = kzalloc_objs(*p, n, ...);
+
+As duas formas verificam estouro no tamanho de alocação ``n * sizeof(...)`` e
+retornam ``NULL`` se isso ocorrer.
+
+Essas funções genéricas de alocação emitem um dump de pilha em caso de falha
+quando usadas sem ``__GFP_NOWARN``, então não há utilidade em emitir uma
+mensagem de falha adicional quando ``NULL`` é retornado.
+
+15) A doença do inline
+----------------------
+
+Parece haver uma percepção errônea comum de que o gcc tem uma opção mágica de
+aceleração chamada ``inline``. Embora o uso de ``inline`` possa ser apropriado
+(por exemplo, como uma forma de substituir macros; veja o Capítulo 12), muitas
+vezes não é. O uso abundante da palavra-chave ``inline`` leva a um kernel
+muito maior, o que, por sua vez, torna o sistema mais lento como um todo, por
+causa de uma maior ocupação de i-cache para a CPU e simplesmente porque há menos
+memória disponível para o ``pagecache``. Pense nisso: uma falha no pagecache
+causa um seek no disco, que facilmente leva 5 milissegundos. Há MUITOS ciclos
+de CPU que podem entrar nesses 5 milissegundos.
+
+Uma regra prática razoável é não colocar ``inline`` em funções com mais de 3
+linhas de código. Uma exceção a essa regra são os casos em que um parâmetro é
+conhecido como uma constante em tempo de compilação, e como resultado dessa
+constância você *sabe* que o compilador será capaz de otimizar grande parte da
+sua função em tempo de compilação. Para um bom exemplo desse caso posterior,
+veja a função inline ``kmalloc()``.
+
+Muitas pessoas argumentam que adicionar ``inline`` a funções ``static`` usadas
+apenas uma vez é sempre uma vantagem, porque não há custo de espaço. Embora
+isso seja tecnicamente correto, o gcc é capaz de fazer esse inline
+automaticamente sem ajuda, e a questão de manutenção de remover o ``inline``
+quando um segundo usuário aparece supera o valor potencial da dica que diz ao
+gcc para fazer algo que ele faria de qualquer forma.
+
+
+16) Valores e nomes de retorno de função
+----------------------------------------
+
+Funções podem retornar valores de vários tipos, e um dos mais comuns é um valor
+que indica se a função teve sucesso ou falhou. Esse valor pode ser representado
+como um inteiro de código de erro (-Exxx = falha, 0 = sucesso) ou como um
+booleano ``succeeded`` (0 = falha, diferente de zero = sucesso).
+
+Misturar esses dois tipos de representação é uma fonte fértil de bugs difíceis
+de encontrar. Se a linguagem C incluísse uma distinção forte entre inteiros e
+booleanos, o compilador encontraria esses erros para nós... mas não inclui. Para
+ajudar a evitar esses bugs, siga sempre esta convenção::
+
+ Se o nome de uma função for uma ação ou um comando imperativo,
+ a função deve retornar um inteiro de código de erro. Se o nome
+ for um predicado, a função deve retornar um booleano de "sucesso".
+
+Por exemplo, ``add work`` é um comando, e a função ``add_work()`` retorna 0
+para sucesso ou -EBUSY para falha. Da mesma forma, ``PCI device present`` é um
+predicado, e a função ``pci_dev_present()`` retorna 1 se encontrar um device
+correspondente ou 0 se não encontrar.
+
+Todas as funções ``EXPORT`` devem respeitar esta convenção, e assim também
+devem todas as funções públicas. Funções privadas (``static``) não precisam,
+mas é recomendável que o façam.
+
+Funções cujo valor de retorno é o resultado real de um cálculo, em vez de uma
+indicação de se o cálculo teve sucesso, não estão sujeitas a essa regra.
+Normalmente, elas indicam falha retornando algum resultado fora do intervalo.
+Exemplos típicos seriam funções que retornam ponteiros; elas usam ``NULL`` ou o
+mecanismo ``ERR_PTR`` para informar falha.
+
+
+17) Usando bool
+---------------
+
+O tipo ``bool`` do kernel Linux é um alias do tipo C99 ``_Bool``. Valores
+``bool`` só podem avaliar para 0 ou 1, e conversão implícita ou explícita para
+``bool`` converte automaticamente o valor para verdadeiro ou falso. Ao usar
+tipos ``bool``, a construção ``!!`` não é necessária, o que elimina uma classe
+de bugs.
+
+Ao trabalhar com valores ``bool``, as definições ``true`` e ``false`` devem ser
+usadas em vez de 1 e 0.
+
+Tipos de retorno de função ``bool`` e variáveis locais na pilha são sempre
+válidos quando apropriados. O uso de ``bool`` é encorajado para melhorar a
+legibilidade e muitas vezes é uma opção melhor do que ``int`` para armazenar
+valores booleanos.
+
+Não use ``bool`` se o layout da linha de cache ou o tamanho do valor importar,
+porque seu tamanho e alinhamento variam conforme a arquitetura compilada.
+Estruturas otimizadas para alinhamento e tamanho não devem usar ``bool``.
+
+Se uma estrutura tiver muitos valores verdadeiro/falso, considere consolidá-los
+em um ``bitfield`` com membros de 1 bit, ou usar um tipo de largura fixa
+apropriado, como ``u8``.
+
+Da mesma forma, para argumentos de função, muitos valores verdadeiro/falso podem
+ser consolidados em um único argumento de sinalizadores bit a bit, e
+``flags`` muitas vezes pode ser uma alternativa mais legível se os pontos de
+chamada tiverem constantes verdadeiras/falsas "nuas".
+
+Caso contrário, o uso limitado de ``bool`` em estruturas e argumentos pode
+melhorar a legibilidade.
+
+18) Não reinventando as macros do kernel
+----------------------------------------
+
+Existem muitos arquivos de cabeçalho em ``include/linux/`` que contêm várias
+macros que você deve usar em vez de escrever explicitamente alguma variante
+delas. Por exemplo, se você precisa calcular o comprimento de um array, aproveite
+a macro
+
+.. code-block:: c
+
+ #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
+
+que é definida em ``array_size.h``.
+
+Da mesma forma, se você precisar calcular o tamanho de um membro de alguma
+estrutura, use
+
+.. code-block:: c
+
+ #define sizeof_field(t, f) (sizeof(((t*)0)->f))
+
+que é definida em ``stddef.h``.
+
+Também existem macros ``min()`` e ``max()`` definidas em ``minmax.h`` que fazem
+verificação estrita de tipos se você precisar delas. Sinta-se à vontade para
+explorar os arquivos de cabeçalho para ver o que já está definido e não deve
+ser reproduzido no seu código.
+
+
+19) Modelines do editor e outros restos
+---------------------------------------
+
+Alguns editores podem interpretar informações de configuração embutidas em
+arquivos de origem, indicadas por marcadores especiais. Por exemplo, o emacs
+interpreta linhas marcadas assim:
+
+.. code-block:: c
+
+ -*- mode: c -*-
+
+Ou assim:
+
+.. code-block:: c
+
+ /*
+ Local Variables:
+ compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
+ End:
+ */
+
+O Vim interpreta marcadores que parecem com isto:
+
+.. code-block:: c
+
+ /* vim:set sw=8 noet */
+
+Não inclua nenhum desses em arquivos de origem. As pessoas têm suas próprias
+configurações pessoais de editor, e seus arquivos de origem não devem
+substituí-las. Isso inclui marcadores para indentação e configuração de modo.
+As pessoas podem usar seu próprio modo personalizado, ou podem ter algum outro
+método mágico para fazer a indentação funcionar corretamente.
+
+
+20) Montagem inline
+-------------------
+
+Em código específico de arquitetura, pode ser necessário usar montagem inline
+para interagir com a funcionalidade da CPU ou da plataforma. Não hesite em
+fazê-lo quando necessário. No entanto, não use montagem inline de forma
+gratuita quando o C puder fazer o trabalho. Você pode e deve mexer em hardware
+em C quando possível.
+
+Considere escrever funções auxiliares simples que encapsulem partes comuns de
+montagem inline, em vez de escrevê-las repetidamente com pequenas variações.
+Lembre-se de que a montagem inline pode usar parâmetros C.
+
+Funções grandes e não triviais de montagem devem ir para arquivos ``.S``, com
+protótipos C correspondentes definidos em arquivos de cabeçalho C. Os
+protótipos C para funções de montagem devem usar ``asmlinkage``.
+
+Você pode precisar marcar sua instrução ``asm`` como ``volatile`` para impedir
+que o GCC a remova se o GCC não perceber efeitos colaterais. No entanto, você
+nem sempre precisa fazer isso, e fazê-lo desnecessariamente pode limitar a
+otimização.
+
+Ao escrever uma única instrução de montagem inline contendo várias instruções,
+coloque cada instrução em uma linha separada em uma string separada e termine
+cada string, exceto a última, com ``\n\t`` para indentar corretamente a
+próxima instrução na saída de montagem:
+
+.. code-block:: c
+
+ asm ("magic %reg1, #42\n\t"
+ "more_magic %reg2, %reg3"
+ : /* outputs */ : /* inputs */ : /* clobbers */);
+
+
+21) Compilação condicional
+--------------------------
+
+Sempre que possível, não use condicionais do pré-processador (#if, #ifdef) em
+arquivos ``.c``; isso torna o código mais difícil de ler e a lógica mais difícil
+de seguir. Em vez disso, use esses condicionais em um arquivo de cabeçalho que
+defina funções para uso nesses arquivos ``.c``, fornecendo versões de stub sem
+efeito no caso ``#else``, e então chame essas funções incondicionalmente nos
+arquivos ``.c``. O compilador evitará gerar qualquer código para as chamadas de
+stub, produzindo resultados idênticos, mas a lógica permanecerá fácil de
+seguir.
+
+Prefira compilar funções inteiras fora do código, em vez de partes de funções
+ou partes de expressões. Em vez de colocar um ``ifdef`` em uma expressão,
+extraia parte ou toda a expressão para uma função auxiliar separada e aplique a
+condicional a essa função.
+
+Se você tiver uma função ou variável que pode potencialmente ficar sem uso em
+uma configuração específica, e o compilador avisaria sobre a definição ficar sem
+uso, marque a definição como ``__maybe_unused`` em vez de envolvê-la em uma
+condicional do pré-processador. (No entanto, se uma função ou variável
+*sempre* ficar sem uso, elimine-a.)
+
+Dentro do código, quando possível, use a macro ``IS_ENABLED`` para converter um
+símbolo Kconfig em uma expressão booleana C e usá-la em uma condicional C
+normal:
+
+.. code-block:: c
+
+ if (IS_ENABLED(CONFIG_SOMETHING)) {
+ ...
+ }
+
+O compilador reduzirá a condicional a um valor constante e incluirá ou
+excluirá o bloco de código assim como com um ``#ifdef``, então isso não
+adicionará nenhum custo de runtime. No entanto, essa abordagem ainda permite
+que o compilador C veja o código dentro do bloco e verifique sua correção
+(sintaxe, tipos, referências de símbolo etc.). Portanto, você ainda precisa usar
+um ``#ifdef`` se o código dentro do bloco referenciar símbolos que não existirão
+se a condição não for atendida.
+
+No final de qualquer bloco ``#if`` ou ``#ifdef`` não trivial (mais de algumas
+linhas), coloque um comentário após o ``#endif`` na mesma linha, indicando a
+expressão condicional usada. Por exemplo:
+
+.. code-block:: c
+
+ #ifdef CONFIG_SOMETHING
+ ...
+ #endif /* CONFIG_SOMETHING */
+
+
+22) Não derrube o kernel
+------------------------
+
+Em geral, a decisão de derrubar o kernel pertence ao usuário, e não ao
+desenvolvedor do kernel.
+
+Evite ``panic()``
+*****************
+
+``panic()`` deve ser usado com cuidado e principalmente apenas durante a inicialização
+do sistema. ``panic()`` é, por exemplo, aceitável ao ficar sem memória durante
+a inicialização e não ser possível continuar.
+
+Use ``WARN()`` em vez de ``BUG()``
+**********************************
+
+Não adicione novo código que use nenhuma das variantes de ``BUG()``, como
+``BUG()``, ``BUG_ON()`` ou ``VM_BUG_ON()``. Em vez disso, use uma variante de
+``WARN*()``, preferencialmente ``WARN_ON_ONCE()``, e possivelmente com código de
+recuperação. O código de recuperação não é obrigatório se não houver uma
+maneira razoável de pelo menos recuperar parcialmente.
+
+"Sou preguiçoso para tratar erros" não é uma desculpa para usar ``BUG()``.
+Corrupções internas graves sem como continuar ainda podem usar ``BUG()``, mas
+precisam de uma boa justificativa.
+
+Use ``WARN_ON_ONCE()`` em vez de ``WARN()`` ou ``WARN_ON()``
+************************************************************
+
+``WARN_ON_ONCE()`` geralmente é preferido em relação a ``WARN()`` ou
+``WARN_ON()``, porque é comum que uma dada condição de aviso, se ocorrer,
+ocorra várias vezes. Isso pode encher e sobrescrever o log do kernel e até
+diminuir o sistema o suficiente para que o registro excessivo vire um problema
+adicional.
+
+Não emita ``WARN`` levianamente
+*******************************
+
+``WARN*()`` foi concebido para situações inesperadas, em que "isso nunca devia
+acontecer". Macros ``WARN*()`` não devem ser usadas para nada que se espere que
+aconteça durante a operação normal. Esses não são asserts de pré- ou pós-
+condição, por exemplo. Novamente: ``WARN*()`` não deve ser usado para uma
+condição que se espera que seja acionada facilmente, por exemplo, por ações do
+espaço do usuário. ``pr_warn_once()`` é uma alternativa possível, se você
+precisar notificar o usuário sobre um problema.
+
+Não se preocupe com usuários de ``panic_on_warn``
+*************************************************
+
+Mais algumas palavras sobre ``panic_on_warn``: lembre-se de que
+``panic_on_warn`` é uma opção disponível do kernel, e muitos usuários a
+habilitam. É por isso que existe um texto "Não emita WARN levianamente" acima.
+Entretanto, a existência de usuários de ``panic_on_warn`` não é uma razão válida
+para evitar o uso judicioso de ``WARN*()``. Isso ocorre porque quem habilita
+``panic_on_warn`` explicitamente pediu ao kernel para travar se um ``WARN*()``
+for disparado, e esses usuários devem estar preparados para lidar com as
+consequências de um sistema que tem uma chance um pouco maior de travar.
+
+Use ``BUILD_BUG_ON()`` para assertivas em tempo de compilação
+*************************************************************
+
+O uso de ``BUILD_BUG_ON()`` é aceitável e encorajado, porque é uma assertiva
+em tempo de compilação que não tem efeito em tempo de execução.
+
+Apêndice I) Referências
+-----------------------
+
+The C Programming Language, Second Edition
+by Brian W. Kernighan and Dennis M. Ritchie.
+Prentice Hall, Inc., 1988.
+ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
+
+The Practice of Programming
+by Brian W. Kernighan and Rob Pike.
+Addison-Wesley, Inc., 1999.
+ISBN 0-201-61586-X.
+
+Manuais GNU - onde em conformidade com K&R e este texto - para cpp, gcc,
+gcc internals e indent, todos disponíveis em https://www.gnu.org/manual/
+
+WG14 é o grupo de trabalho de padronização internacional para a linguagem de
+programação C, URL: http://www.open-std.org/JTC1/SC22/WG14/
+
+Kernel CodingStyle, by greg@kroah.com at OLS 2002:
+http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
diff --git a/Documentation/translations/pt_BR/process/index.rst b/Documentation/translations/pt_BR/process/index.rst
index 7841eca6b..38150e566 100644
--- a/Documentation/translations/pt_BR/process/index.rst
+++ b/Documentation/translations/pt_BR/process/index.rst
@@ -38,6 +38,7 @@ devem estar familiarizados.
:maxdepth: 1
Requisitos mínimos <changes>
+ Estilo de codificação do kernel Linux <coding-style>
Informações sobre clientes de email para Linux <email-clients>
Como aplicar patches <applying-patches>
Backporting e resolução de conflitos <backporting>
--
2.47.3
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 2/4] docs: pt_BR: translate kernel-enforcement-statement.rst
2026-09-09 12:48 [PATCH 0/4] docs: pt_BR: process: Add remaining core process translations Daniel Pereira
2026-09-09 12:48 ` [PATCH 1/4] docs: pt_BR: translate coding-style.rst Daniel Pereira
@ 2026-09-09 12:48 ` Daniel Pereira
2026-09-09 12:48 ` [PATCH 3/4] docs: pt_BR: translate maintainer-tip.rst Daniel Pereira
2026-09-09 12:48 ` [PATCH 4/4] docs: pt_BR: translate submitting-patches.rst Daniel Pereira
3 siblings, 0 replies; 5+ messages in thread
From: Daniel Pereira @ 2026-09-09 12:48 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
Translate Documentation/process/kernel-enforcement-statement.rst into
Brazilian Portuguese and add it to the pt_BR process documentation index.
This document outlines the Linux kernel developers' statement regarding
how the license for the software is enforced and compliance expectations.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
.../translations/pt_BR/process/index.rst | 1 +
.../process/kernel-enforcement-statement.rst | 163 ++++++++++++++++++
2 files changed, 164 insertions(+)
create mode 100644 Documentation/translations/pt_BR/process/kernel-enforcement-statement.rst
diff --git a/Documentation/translations/pt_BR/process/index.rst b/Documentation/translations/pt_BR/process/index.rst
index 38150e566..63282b053 100644
--- a/Documentation/translations/pt_BR/process/index.rst
+++ b/Documentation/translations/pt_BR/process/index.rst
@@ -59,6 +59,7 @@ Estas são as regras pelas quais tentamos viver na comunidade do kernel
Código de Conduta de Compromisso do Colaborador <code-of-conduct>
Interpretação do Código de Conduta do Kernel Linux <code-of-conduct-interpretation>
Modelos de Maturidade para Contribuição no Kernel Linux <contribution-maturity-model.rst>
+ Declaração de Aplicação do Kernel Linux <kernel-enforcement-statement>
Declaração sobre Drivers do Kernel <kernel-driver-statement>
Estilo de gerenciamento do kernel Linux <management-style>
Assistentes de código <coding-assistants>
diff --git a/Documentation/translations/pt_BR/process/kernel-enforcement-statement.rst b/Documentation/translations/pt_BR/process/kernel-enforcement-statement.rst
new file mode 100644
index 000000000..3833c433c
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/kernel-enforcement-statement.rst
@@ -0,0 +1,163 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Declaração de Aplicação do Kernel Linux
+---------------------------------------
+
+Como desenvolvedores do kernel Linux, temos um grande interesse em como nosso
+software é usado e como a licença do nosso software é aplicada. A conformidade
+com as obrigações de compartilhamento recíproco da GPL-2.0 é crítica para a
+sustentabilidade a longo prazo do nosso software e da nossa comunidade.
+
+Embora exista o direito de aplicar os interesses de direitos autorais separados nas
+contribuições feitas à nossa comunidade, compartilhamos o interesse em garantir
+que ações de aplicação individuais sejam conduzidas de uma maneira que beneficie
+nossa comunidade e não tenham um impacto negativo não intencional na saúde e no
+crescimento do nosso ecossistema de software. A fim de deter ações de aplicação
+inúteis, concordamos que é do melhor interesse da nossa comunidade de
+desenvolvimento assumir o seguinte compromisso com os usuários do kernel Linux,
+em nosso nome e em nome de quaisquer sucessores dos nossos interesses de
+direitos autorais:
+
+ Não obstante as disposições de rescisão da GPL-2.0, concordamos que
+ é do melhor interesse da nossa comunidade de desenvolvimento adotar as
+ seguintes disposições da GPL-3.0 como permissões adicionais sob nossa
+ licença com relação a qualquer reivindicação não defensiva de direitos sob a
+ licença.
+
+ No entanto, se você cessar toda violação desta Licença, sua licença
+ de um detentor de direitos autorais específico será restabelecida (a)
+ provisoriamente, a menos e até que o detentor de direitos autorais encerre
+ explícita e definitivamente sua licença, e (b) permanentemente, se o
+ detentor de direitos autorais não notificar você sobre a violação por
+ algum meio razoável antes de 60 dias após a cessação.
+
+ Além disso, sua licença de um detentor de direitos autorais específico é
+ restabelecida permanentemente se o detentor de direitos autorais
+ notificá-lo da violação por algum meio razoável, se esta for a primeira
+ vez que você recebe um aviso de violação desta Licença (para qualquer
+ trabalho) daquele detentor de direitos autorais, e você sanar a violação
+ antes de 30 dias após o recebimento do aviso.
+
+Nossa intenção ao fornecer essas garantias é incentivar um maior uso do
+software. Queremos que empresas e indivíduos usem, modifiquem e distribuam
+este software. Queremos trabalhar com os usuários de forma aberta e transparente
+para eliminar qualquer incerteza sobre nossas expectativas em relação à
+conformidade ou aplicação que possa limitar a adoção do nosso software. Vemos
+a ação judicial como um último recurso, a ser iniciada apenas quando outros
+esforços da comunidade falharem em resolver o problema.
+
+Por fim, uma vez que um problema de não conformidade seja resolvido, esperamos
+que o usuário se sinta bem-vindo para se juntar a nós em nossos esforços neste
+projeto. Trabalhando juntos, seremos mais fortes.
+
+Exceto onde indicado abaixo, falamos apenas por nós mesmos, e não por qualquer
+empresa para a qual possamos trabalhar hoje, no passado ou no futuro.
+
+ - Bjorn Andersson (Linaro)
+ - Andrea Arcangeli
+ - Neil Armstrong
+ - Jens Axboe
+ - Pablo Neira Ayuso
+ - Khalid Aziz
+ - Ralf Baechle
+ - Felipe Balbi
+ - Arnd Bergmann
+ - Ard Biesheuvel
+ - Tim Bird
+ - Paolo Bonzini
+ - Christian Borntraeger
+ - Mark Brown (Linaro)
+ - Paul Burton
+ - Javier Martinez Canillas
+ - Rob Clark
+ - Kees Cook (Google)
+ - Jonathan Corbet
+ - Dennis Dalessandro
+ - Vivien Didelot (Savoir-faire Linux)
+ - Hans de Goede
+ - Mel Gorman (SUSE)
+ - Sven Eckelmann
+ - Alex Elder (Linaro)
+ - Fabio Estevam
+ - Larry Finger
+ - Bhumika Goyal
+ - Andy Gross
+ - Juergen Gross
+ - Shawn Guo
+ - Ulf Hansson
+ - Stephen Hemminger (Microsoft)
+ - Tejun Heo
+ - Rob Herring
+ - Masami Hiramatsu
+ - Michal Hocko
+ - Simon Horman
+ - Johan Hovold (Hovold Consulting AB)
+ - Christophe JAILLET
+ - Olof Johansson
+ - Lee Jones (Linaro)
+ - Heiner Kallweit
+ - Srinivas Kandagatla
+ - Jan Kara
+ - Shuah Khan (Samsung)
+ - David Kershner
+ - Jaegeuk Kim
+ - Namhyung Kim
+ - Colin Ian King
+ - Jeff Kirsher
+ - Greg Kroah-Hartman (Linux Foundation)
+ - Christian König
+ - Vinod Koul
+ - Krzysztof Kozlowski
+ - Viresh Kumar
+ - Aneesh Kumar K.V
+ - Julia Lawall
+ - Doug Ledford
+ - Chuck Lever (Oracle)
+ - Daniel Lezcano
+ - Shaohua Li
+ - Xin Long
+ - Tony Luck
+ - Catalin Marinas (Arm Ltd)
+ - Mike Marshall
+ - Chris Mason
+ - Paul E. McKenney
+ - Arnaldo Carvalho de Melo
+ - David S. Miller
+ - Ingo Molnar
+ - Kuninori Morimoto
+ - Trond Myklebust
+ - Martin K. Petersen (Oracle)
+ - Borislav Petkov
+ - Jiri Pirko
+ - Josh Poimboeuf
+ - Sebastian Reichel (Collabora)
+ - Guenter Roeck
+ - Joerg Roedel
+ - Leon Romanovsky
+ - Steven Rostedt (VMware)
+ - Frank Rowand
+ - Ivan Safonov
+ - Anna Schumaker
+ - Jes Sorensen
+ - K.Y. Srinivasan
+ - David Sterba (SUSE)
+ - Heiko Stuebner
+ - Jiri Kosina (SUSE)
+ - Willy Tarreau
+ - Dmitry Torokhov
+ - Linus Torvalds
+ - Thierry Reding
+ - Rik van Riel
+ - Luis R. Rodriguez
+ - Geert Uytterhoeven (Glider bvba)
+ - Eduardo Valentin (Amazon.com)
+ - Daniel Vetter
+ - Linus Walleij
+ - Richard Weinberger
+ - Dan Williams
+ - Rafael J. Wysocki
+ - Arvind Yadav
+ - Masahiro Yamada
+ - Wei Yongjun
+ - Lv Zheng
+ - Marc Zyngier (Arm Ltd)
--
2.47.3
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 3/4] docs: pt_BR: translate maintainer-tip.rst
2026-09-09 12:48 [PATCH 0/4] docs: pt_BR: process: Add remaining core process translations Daniel Pereira
2026-09-09 12:48 ` [PATCH 1/4] docs: pt_BR: translate coding-style.rst Daniel Pereira
2026-09-09 12:48 ` [PATCH 2/4] docs: pt_BR: translate kernel-enforcement-statement.rst Daniel Pereira
@ 2026-09-09 12:48 ` Daniel Pereira
2026-09-09 12:48 ` [PATCH 4/4] docs: pt_BR: translate submitting-patches.rst Daniel Pereira
3 siblings, 0 replies; 5+ messages in thread
From: Daniel Pereira @ 2026-09-09 12:48 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
Translate Documentation/process/maintainer-tip.rst into Brazilian
Portuguese and add it to the pt_BR process documentation index.
This document serves as the handbook for the tip tree, providing subsystem
specific information supplementary to the general development process.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
.../translations/pt_BR/process/index.rst | 1 +
.../pt_BR/process/maintainer-tip.rst | 847 ++++++++++++++++++
2 files changed, 848 insertions(+)
create mode 100644 Documentation/translations/pt_BR/process/maintainer-tip.rst
diff --git a/Documentation/translations/pt_BR/process/index.rst b/Documentation/translations/pt_BR/process/index.rst
index 63282b053..e011b55a1 100644
--- a/Documentation/translations/pt_BR/process/index.rst
+++ b/Documentation/translations/pt_BR/process/index.rst
@@ -63,6 +63,7 @@ Estas são as regras pelas quais tentamos viver na comunidade do kernel
Declaração sobre Drivers do Kernel <kernel-driver-statement>
Estilo de gerenciamento do kernel Linux <management-style>
Assistentes de código <coding-assistants>
+ O manual da árvore tip <maintainer-tip>
Conclave (Continuidade do projeto) <conclave>
Lidando com bugs
diff --git a/Documentation/translations/pt_BR/process/maintainer-tip.rst b/Documentation/translations/pt_BR/process/maintainer-tip.rst
new file mode 100644
index 000000000..e583bad42
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/maintainer-tip.rst
@@ -0,0 +1,847 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+O manual da árvore tip
+======================
+
+O que é a árvore tip?
+---------------------
+
+A árvore tip é uma coleção de vários subsistemas e áreas de
+desenvolvimento. A árvore tip é tanto uma árvore de desenvolvimento direto quanto uma
+árvore de agregação para várias árvores de sub-mantenedores. A URL gitweb da árvore tip
+é: https://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git
+
+A árvore tip contém os seguintes subsistemas:
+
+ - **Arquitetura x86**
+
+ O desenvolvimento da arquitetura x86 ocorre na árvore tip, exceto
+ pelas partes específicas do KVM e XEN no x86, que são mantidas nos
+ subsistemas correspondentes e roteadas diretamente para a mainline a partir
+ dali. Ainda é uma boa prática enviar Cc para os mantenedores x86 nos
+ patches do KVM e XEN específicos para x86.
+
+ Alguns subsistemas x86 têm seus próprios mantenedores além dos
+ mantenedores gerais do x86. Por favor, envie Cc para os mantenedores gerais do x86 em
+ patches que toquem em arquivos em arch/x86, mesmo quando não forem indicados
+ pelo arquivo MAINTAINER.
+
+ Note que ``x86@kernel.org`` não é uma lista de discussão. É meramente um
+ alias de e-mail que distribui mensagens para a equipe de mantenedores de nível superior
+ do x86. Por favor, sempre envie Cc para a lista de discussão do Linux Kernel (LKML)
+ ``linux-kernel@vger.kernel.org``, caso contrário, seu e-mail acabará apenas nas
+ caixas de entrada privadas dos mantenedores.
+
+ - **Scheduler**
+
+ O desenvolvimento do scheduler ocorre na árvore -tip, na
+ branch sched/core - com ocasionais árvores de subtópicos para
+ conjuntos de patches em progresso.
+
+ - **Locking e atomics**
+
+ O desenvolvimento de locking (incluindo atomics e outras primitivas de
+ sincronização que estão conectadas ao locking) ocorre na árvore -tip,
+ na branch locking/core - com ocasionais árvores de subtópicos
+ para conjuntos de patches em progresso.
+
+ - **Subsistema genérico de interrupções e drivers de chip de interrupção**:
+
+ - o desenvolvimento do núcleo de interrupções ocorre na branch irq/core
+
+ - o desenvolvimento do driver de chip de interrupção também ocorre na branch
+ irq/core, mas os patches geralmente são aplicados em uma árvore de mantenedor
+ separada e depois agregados na irq/core
+
+ - **Tempo, timers, timekeeping, NOHZ e drivers de chip relacionados**:
+
+ - o desenvolvimento do timekeeping, núcleo clocksource, NTP e alarmtimer
+ ocorre na branch timers/core, mas os patches geralmente são aplicados em
+ uma árvore de mantenedor separada e depois agregados na timers/core
+
+ - o desenvolvimento do driver clocksource/event ocorre na branch
+ timers/core, mas os patches são em sua maioria aplicados em uma árvore de mantenedor
+ separada e depois agregados na timers/core
+
+ - **Núcleo de contadores de desempenho, suporte a arquitetura e ferramentas**:
+
+ - o desenvolvimento do núcleo perf e suporte a arquitetura ocorre na
+ branch perf/core
+
+ - o desenvolvimento de ferramentas perf ocorre na árvore do mantenedor
+ de ferramentas perf e é agregado à árvore tip.
+
+ - **Núcleo de hotplug de CPU**
+
+ - **Núcleo RAS**
+
+ Em sua maioria, os patches RAS específicos para x86 são coletados na branch
+ ras/core da árvore tip.
+
+ - **Núcleo EFI**
+
+ Desenvolvimento EFI na árvore git efi. Os patches coletados são
+ agregados na branch efi/core da árvore tip.
+
+ - **RCU**
+
+ O desenvolvimento do RCU ocorre na árvore linux-rcu. As mudanças resultantes
+ são agregadas na branch core/rcu da árvore tip.
+
+ - **Vários componentes de código do núcleo**:
+
+ - debugobjects
+
+ - objtool
+
+ - partes e peças aleatórias
+
+
+Notas de submissão de patch
+---------------------------
+
+Selecionando a árvore/branch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Em geral, o desenvolvimento contra o head da branch master da árvore tip é
+adequado, mas para os subsistemas que são mantidos separadamente, possuem sua
+própria árvore git e são apenas agregados na árvore tip, o desenvolvimento deve
+ocorrer contra a árvore ou branch do subsistema relevante.
+
+Correções de bugs que visam a mainline devem sempre ser aplicáveis contra a
+árvore do kernel mainline. Potenciais conflitos contra mudanças que já estão
+na fila da árvore tip são resolvidos pelos mantenedores.
+
+Assunto do patch
+^^^^^^^^^^^^^^^^
+
+O formato preferido da árvore tip para prefixos de assunto do patch é
+'subsys/component:', ex. 'x86/apic:', 'x86/mm/fault:', 'sched/fair:',
+'genirq/core:'. Por favor, não use nomes de arquivos ou caminhos de arquivos completos como
+prefixo. 'git log path/to/file' deve lhe dar uma dica razoável na maioria
+dos casos.
+
+A descrição condensada do patch na linha de assunto deve começar com uma
+letra maiúscula e deve ser escrita em tom imperativo.
+
+
+Changelog
+^^^^^^^^^
+
+As regras gerais sobre changelogs no :ref:`Guia de submissão de patches
+<pt_BR_describe_changes>`, se aplicam.
+
+Os mantenedores da árvore tip valorizam seguir essas regras, especialmente no
+pedido para escrever changelogs no modo imperativo e não personificando
+o código ou sua execução. Isso não é apenas um capricho dos
+mantenedores. Changelogs escritos em palavras abstratas são mais precisos e
+tendem a ser menos confusos do que aqueles escritos em forma de romances.
+
+Também é útil estruturar o changelog em vários parágrafos e não
+juntar tudo em um só. Uma boa estrutura é explicar
+o contexto, o problema e a solução em parágrafos separados e nesta
+ordem.
+
+Exemplos para ilustração:
+
+ Exemplo 1::
+
+ x86/intel_rdt/mbm: Corrigir o manipulador de overflow do MBM durante hot cpu
+
+ Quando uma CPU está morrendo, cancelamos o worker e agendamos um novo worker em uma
+ CPU diferente no mesmo domínio. Mas se o timer já está prestes a
+ expirar (digamos 0.99s) então essencialmente dobramos o intervalo.
+
+ Modificamos o tratamento de hot cpu para cancelar o trabalho atrasado na cpu
+ que está morrendo e executar o worker imediatamente em uma cpu diferente no mesmo domínio. Não
+ fazemos o flush do worker porque o worker de overflow do MBM reagenda o
+ worker na mesma CPU e escaneia a domain->cpu_mask para obter o ponteiro
+ do domínio.
+
+ Versão melhorada::
+
+ x86/intel_rdt/mbm: Corrigir o manipulador de overflow do MBM durante hotplug de CPU
+
+ Quando uma CPU está morrendo, o worker de overflow é cancelado e reagendado em uma
+ CPU diferente no mesmo domínio. Mas se o timer já estiver prestes a
+ expirar isso essencialmente dobra o intervalo, o que pode resultar em um overflow
+ não detectado.
+
+ Cancele o worker de overflow e reagende-o imediatamente em uma CPU diferente
+ no mesmo domínio. O trabalho também poderia sofrer um flush, mas isso iria
+ reagendá-lo na mesma CPU.
+
+ Exemplo 2::
+
+ time: POSIX CPU timers: Garantir que a variável seja inicializada
+
+ Se cpu_timer_sample_group retornar -EINVAL, ela não terá escrito em
+ *sample. Checar o valor de retorno de cpu_timer_sample_group previne o
+ uso potencial de um valor não inicializado de now no bloco seguinte.
+ Dado um clock_idx inválido, o código anterior poderia caso contrário sobrescrever
+ *oldval de maneira indefinida. Isso agora é prevenido. Também exploramos
+ o curto-circuito do && para amostrar o timer apenas se o resultado for
+ realmente usado para atualizar *oldval.
+
+ Versão melhorada::
+
+ posix-cpu-timers: Tornar set_process_cpu_timer() mais robusto
+
+ Como o valor de retorno de cpu_timer_sample_group() não é checado,
+ compiladores e checadores estáticos podem legitimamente avisar sobre um uso potencial
+ da variável não inicializada 'now'. Isso não é um problema de tempo de execução pois todos
+ os locais de chamada passam ids de clock válidos.
+
+ Além disso, cpu_timer_sample_group() é invocado incondicionalmente mesmo quando o
+ resultado não é usado porque *oldval é NULL.
+
+ Torne a invocação condicional e cheque o valor de retorno.
+
+ Exemplo 3::
+
+ A entidade também pode ser usada para outros propósitos.
+
+ Vamos renomeá-la para ser mais genérica.
+
+ Versão melhorada::
+
+ A entidade também pode ser usada para outros propósitos.
+
+ Renomeie para ser mais genérica.
+
+
+Para cenários complexos, especialmente condições de corrida (race conditions) e problemas
+de ordenação de memória, é valioso descrever o cenário com uma tabela que mostra
+o paralelismo e a ordem temporal dos eventos. Aqui está um exemplo::
+
+ CPU0 CPU1
+ free_irq(X) interrupt X
+ spin_lock(desc->lock)
+ wake irq thread()
+ spin_unlock(desc->lock)
+ spin_lock(desc->lock)
+ remove action()
+ shutdown_irq()
+ release_resources() thread_handler()
+ spin_unlock(desc->lock) access released resources.
+ ^^^^^^^^^^^^^^^^^^^^^^^^^
+ synchronize_irq()
+
+O Lockdep fornece uma saída útil semelhante para descrever um possível cenário
+de deadlock::
+
+ CPU0 CPU1
+ rtmutex_lock(&rcu->rt_mutex)
+ spin_lock(&rcu->rt_mutex.wait_lock)
+ local_irq_disable()
+ spin_lock(&timer->it_lock)
+ spin_lock(&rcu->mutex.wait_lock)
+ --> Interrupt
+ spin_lock(&timer->it_lock)
+
+Referências a funções em changelogs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Quando uma função é mencionada no changelog, seja no corpo do texto ou na
+linha de assunto, por favor use o formato 'nome_da_funcao()'. Omitir os
+parênteses após o nome da função pode ser ambíguo::
+
+ Subject: subsys/component: Make reservation_count static
+
+ reservation_count is only used in reservation_stats. Make it static.
+
+A variante com parênteses é mais precisa::
+
+ Subject: subsys/component: Make reservation_count() static
+
+ reservation_count() is only called from reservation_stats(). Make it
+ static.
+
+
+Backtraces em changelogs
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Veja :ref:`pt_BR_backtraces`.
+
+Ordenação das tags de commit
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Para ter uma visão uniforme das tags de commit, os mantenedores da tip usam o
+seguinte esquema de ordenação de tags:
+
+ - Fixes: 12+char-SHA1 ("sub/sys: Original subject line")
+
+ Uma tag Fixes deve ser adicionada mesmo para alterações que não precisam ser
+ portadas de volta (backported) para kernels estáveis, ou seja, quando abordar um
+ problema recém-introduzido que afeta apenas a árvore tip ou o head atual da linha principal (mainline). Estas tags
+ são úteis para identificar o commit original e são muito mais valiosas
+ do que mencionar de forma proeminente o commit que introduziu um problema no
+ próprio texto do changelog, porque elas podem ser automaticamente
+ extraídas.
+
+ O exemplo a seguir ilustra a diferença::
+
+ Commit
+
+ abcdef012345678 ("x86/xxx: Replace foo with bar")
+
+ deixou uma instância não utilizada da variável foo. Remova-a.
+
+ Signed-off-by: J.Dev <j.dev@mail>
+
+ Por favor, diga em vez disso::
+
+ A recente substituição de foo por bar deixou uma instância não utilizada da
+ variável foo. Remova-a.
+
+ Fixes: abcdef012345678 ("x86/xxx: Replace foo with bar")
+ Signed-off-by: J.Dev <j.dev@mail>
+
+ O último coloca as informações sobre o patch em foco e
+ as complementa com a referência ao commit que introduziu o problema,
+ em vez de colocar o foco no commit original em primeiro lugar.
+
+ - Reported-by: ``Reporter <reporter@mail>``
+
+ - Closes: ``URL or Message-ID of the bug report this is fixing``
+
+ - Originally-by: ``Original author <original-author@mail>``
+
+ - Suggested-by: ``Suggester <suggester@mail>``
+
+ - Co-developed-by: ``Co-author <co-author@mail>``
+
+ Signed-off-by: ``Co-author <co-author@mail>``
+
+ Note que Co-developed-by e Signed-off-by do(s) co-autor(es) devem
+ vir em pares.
+
+ - Signed-off-by: ``Author <author@mail>``
+
+ O primeiro Signed-off-by (SOB) após o último par Co-developed-by/SOB é o
+ SOB do autor, ou seja, a pessoa marcada como autora pelo git.
+
+ - Signed-off-by: ``Patch handler <handler@mail>``
+
+ SOBs após o SOB do autor são de pessoas que lidam e transportam
+ o patch, mas não estiveram envolvidas no desenvolvimento. As cadeias de SOB devem
+ refletir a rota **real** que um patch tomou conforme foi propagado para nós,
+ com a primeira entrada de SOB sinalizando a autoria principal de um único
+ autor. Acks devem ser dados como linhas Acked-by e aprovações de revisão
+ como linhas Reviewed-by.
+
+ Se o manipulador fez modificações no patch ou no changelog, então
+ isso deve ser mencionado **após** o texto do changelog e **acima**
+ de todas as tags de commit no seguinte formato::
+
+ ... o texto do changelog termina.
+
+ [ handler: Substituiu foo por bar e atualizou o changelog ]
+
+ First-tag: .....
+
+ Observe as duas novas linhas vazias que separam o texto do changelog e as
+ tags de commit daquele aviso.
+
+ Se um patch for enviado para a lista de discussão por um manipulador, então o autor tem
+ que ser notado na primeira linha do changelog com::
+
+ From: Author <author@mail>
+
+ O texto do changelog começa aqui....
+
+ assim a autoria é preservada. A linha 'From:' tem que ser seguida
+ por uma nova linha vazia. Se essa linha 'From:' estiver faltando, então o patch
+ seria atribuído à pessoa que o enviou (transportou, manipulou).
+ A linha 'From:' é automaticamente removida quando o patch é aplicado
+ e não aparece no changelog final do git. Ela meramente afeta
+ a informação de autoria do commit resultante do Git.
+
+ - Tested-by: ``Tester <tester@mail>``
+
+ - Reviewed-by: ``Reviewer <reviewer@mail>``
+
+ - Acked-by: ``Acker <acker@mail>``
+
+ - Cc: ``cc-ed-person <person@mail>``
+
+ Se o patch deve ser portado para stable, então por favor adicione uma tag '``Cc:
+ stable@vger.kernel.org``', mas não coloque em Cc o stable ao enviar o seu
+ e-mail.
+
+ - Link: ``https://link/to/information``
+
+ Para se referir a um e-mail postado nas listas de discussão do kernel, por favor
+ use o URL de redirecionamento lore.kernel.org::
+
+ Link: https://lore.kernel.org/email-message-id@here
+
+ Esta URL deve ser usada ao se referir a tópicos de lista de discussão relevantes,
+ conjuntos de patches relacionados, ou outras threads de discussão notáveis.
+ Uma maneira conveniente de associar os trailers ``Link:`` com a mensagem de commit
+ é usar a notação de colchetes semelhante ao markdown, por exemplo::
+
+ A similar approach was attempted before as part of a different
+ effort [1], but the initial implementation caused too many
+ regressions [2], so it was backed out and reimplemented.
+
+ Link: https://lore.kernel.org/some-msgid@here # [1]
+ Link: https://bugzilla.example.org/bug/12345 # [2]
+
+ Você também pode usar os trailers ``Link:`` para indicar a origem do
+ patch ao aplicá-lo em sua árvore git. Neste caso, por favor use o
+ domínio dedicado ``patch.msgid.link`` em vez de ``lore.kernel.org``.
+ Esta prática torna possível que as ferramentas automatizadas identifiquem
+ qual link usar para recuperar o envio do patch original. Por
+ exemplo::
+
+ Link: https://patch.msgid.link/patch-source-message-id@here
+
+Por favor não use tags combinadas, ex. ``Reported-and-tested-by``, pois
+elas apenas complicam a extração automatizada de tags.
+
+
+Links para documentação
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Fornecer links para a documentação no changelog é uma grande ajuda para depuração e
+análise posteriores. Infelizmente, os URLs costumam quebrar muito rapidamente
+porque as empresas reestruturam seus sites frequentemente. Exceções não 'voláteis'
+incluem o Intel SDM e o AMD APM.
+
+Portanto, para documentos 'voláteis', por favor crie uma entrada no bugzilla do kernel
+https://bugzilla.kernel.org e anexe uma cópia desses documentos
+à entrada do bugzilla. Finalmente, forneça o URL da entrada do bugzilla no
+changelog.
+
+Reenvio de patch ou lembretes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Veja :ref:`pt_BR_resend_reminders`.
+
+Janela de merge
+^^^^^^^^^^^^^^^
+
+Por favor, não espere que os patches sejam revisados ou mesclados pelos mantenedores da árvore tip
+em torno ou durante a janela de merge. As árvores ficam fechadas
+para todos, exceto correções urgentes, durante esse tempo. Elas reabrem assim que a janela de merge
+fecha e um novo kernel -rc1 é lançado.
+
+Grandes séries devem ser enviadas em estado mesclável (mergeable state) *pelo* *menos* uma semana
+antes da janela de merge abrir. Exceções são feitas para correções de bugs e
+*às vezes* para pequenos drivers independentes para novos hardwares ou patches minimamente
+invasivos para ativação de hardware.
+
+Durante a janela de merge, os mantenedores se concentram em seguir as
+alterações upstream, corrigir problemas resultantes da janela de merge, coletar correções de bugs, e
+se permitir um respiro. Por favor, respeite isso.
+
+Os chamados branches _urgent_ serão mesclados na linha principal (mainline) durante a
+fase de estabilização de cada versão.
+
+
+Git
+^^^
+
+Os mantenedores da árvore tip aceitam pull requests do git de mantenedores que fornecem
+alterações de subsistema para agregação na árvore tip.
+
+Pull requests para novos envios de patches normalmente não são aceitos e não
+substituem o envio adequado de patch para a lista de discussão. O principal motivo para
+isso é que o fluxo de trabalho de revisão é baseado em e-mail.
+
+Se você enviar uma série maior de patches, é útil fornecer um branch git
+em um repositório privado que permita que pessoas interessadas façam pull da
+série facilmente para testes. A maneira usual de oferecer isso é uma URL do git na carta de apresentação (cover letter)
+da série de patches.
+
+Testes
+^^^^^^
+
+O código deve ser testado antes de ser enviado para os mantenedores da árvore tip. Qualquer coisa
+além de alterações menores deve ser construída, inicializada e testada com
+opções abrangentes (e pesadas) de depuração do kernel ativadas.
+
+Essas opções de depuração podem ser encontradas em kernel/configs/x86_debug.config
+e podem ser adicionadas a uma configuração de kernel existente executando:
+
+ make x86_debug.config
+
+Algumas dessas opções são específicas do x86 e podem ser deixadas de fora ao testar
+em outras arquiteturas.
+
+.. _pt_BR_maintainer-tip-coding-style:
+
+Notas de estilo de código
+-------------------------
+
+Estilo de comentário
+^^^^^^^^^^^^^^^^^^^^
+
+Frases em comentários começam com uma letra maiúscula.
+
+Comentários de linha única::
+
+ /* Este é um comentário de linha única */
+
+Comentários de várias linhas::
+
+ /*
+ * This is a properly formatted
+ * multi-line comment.
+ *
+ * Larger multi-line comments should be split into paragraphs.
+ */
+
+Sem comentários no fim da linha (veja abaixo):
+
+ Por favor, abstenha-se de usar comentários no fim da linha. Comentários no fim da linha atrapalham o
+ fluxo de leitura em quase todos os contextos, mas especialmente em código::
+
+ if (somecondition_is_true) /* Não coloque um comentário aqui */
+ dostuff(); /* Nem aqui */
+
+ seed = MAGIC_CONSTANT; /* Nem aqui */
+
+ Use comentários independentes em vez disso::
+
+ /* Esta condição não é óbvia sem um comentário */
+ if (somecondition_is_true) {
+ /* Isso realmente precisa ser documentado */
+ dostuff();
+ }
+
+ /* Esta inicialização mágica precisa de um comentário. Talvez não? */
+ seed = MAGIC_CONSTANT;
+
+ Use o estilo C++, comentários no fim da linha ao documentar structs em headers para
+ alcançar um layout mais compacto e melhor legibilidade::
+
+ // eax
+ u32 x2apic_shift : 5, // Número de bits para deslocar o ID APIC para a direita
+ // para o ID de topologia no próximo nível
+ : 27; // Reservado
+ // ebx
+ u32 num_processors : 16, // Número de processadores no nível atual
+ : 16; // Reservado
+
+ versus::
+
+ /* eax */
+ /*
+ * Número de bits para deslocar o ID APIC para a direita para o ID de topologia
+ * no próximo nível
+ */
+ u32 x2apic_shift : 5,
+ /* Reservado */
+ : 27;
+
+ /* ebx */
+ /* Número de processadores no nível atual */
+ u32 num_processors : 16,
+ /* Reservado */
+ : 16;
+
+Comente as coisas importantes:
+
+ Comentários devem ser adicionados onde a operação não é óbvia. Documentar
+ o óbvio é apenas uma distração::
+
+ /* Decrementa o refcount e verifica por zero */
+ if (refcount_dec_and_test(&p->refcnt)) {
+ do;
+ lots;
+ of;
+ magic;
+ things;
+ }
+
+ Em vez disso, os comentários devem explicar os detalhes não óbvios e documentar
+ as restrições::
+
+ if (refcount_dec_and_test(&p->refcnt)) {
+ /*
+ * Explicação muito boa de por que as coisas mágicas abaixo
+ * precisam ser feitas, restrições de ordenação e locking,
+ * etc..
+ */
+ do;
+ lots;
+ of;
+ magic;
+ /* Precisa ser a última operação porque ... */
+ things;
+ }
+
+Comentários de documentação de função:
+
+ Para documentar funções e seus argumentos por favor use o formato kernel-doc
+ e não comentários de formato livre::
+
+ /**
+ * magic_function - Faz muitas coisas mágicas
+ * @magic: Ponteiro para os dados mágicos nos quais operar
+ * @offset: Deslocamento no array de dados de @magic
+ *
+ * Explicação profunda das coisas misteriosas feitas com @magic junto
+ * com a documentação dos valores de retorno.
+ *
+ * Note que os descritores de argumento acima estão dispostos
+ * de forma tabular.
+ */
+
+ Isto se aplica especialmente a funções visíveis globalmente e funções
+ inline em arquivos de cabeçalho públicos. Pode ser um exagero usar o formato
+ kernel-doc para cada função (estática) que precisa de uma pequena explicação. O
+ uso de nomes de funções descritivos frequentemente substitui esses pequenos comentários.
+ Aplique o bom senso como sempre.
+
+
+Documentando requisitos de locking
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ Documentar requisitos de locking é uma coisa boa, mas comentários não
+ são necessariamente a melhor escolha. Em vez de escrever::
+
+ /* Caller must hold foo->lock */
+ void func(struct foo *foo)
+ {
+ ...
+ }
+
+ Por favor, use::
+
+ void func(struct foo *foo)
+ {
+ lockdep_assert_held(&foo->lock);
+ ...
+ }
+
+ Em kernels PROVE_LOCKING, lockdep_assert_held() emite um aviso
+ se o chamador não detém o lock. Comentários não podem fazer isso.
+
+Regras de chaves
+^^^^^^^^^^^^^^^^
+
+Chaves devem ser omitidas apenas se a instrução que se segue a 'if', 'for',
+'while' etc. for verdadeiramente uma única linha::
+
+ if (foo)
+ do_something();
+
+O seguinte não é considerado uma instrução de linha única mesmo
+que o C não exija chaves::
+
+ for (i = 0; i < end; i++)
+ if (foo[i])
+ do_something(foo[i]);
+
+Adicionar chaves ao redor do loop externo melhora o fluxo de leitura::
+
+ for (i = 0; i < end; i++) {
+ if (foo[i])
+ do_something(foo[i]);
+ }
+
+
+Declarações de variáveis
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ordem preferida das declarações de variáveis no início de uma
+função é a ordem de árvore de abeto invertida (reverse fir tree order)::
+
+ struct long_struct_name *descriptive_name;
+ unsigned long foo, bar;
+ unsigned int tmp;
+ int ret;
+
+O que está acima é mais rápido de analisar do que a ordem invertida::
+
+ int ret;
+ unsigned int tmp;
+ unsigned long foo, bar;
+ struct long_struct_name *descriptive_name;
+
+E ainda mais do que uma ordem aleatória::
+
+ unsigned long foo, bar;
+ int ret;
+ struct long_struct_name *descriptive_name;
+ unsigned int tmp;
+
+Também por favor tente agregar variáveis do mesmo tipo em uma única
+linha. Não há sentido em desperdiçar espaço na tela::
+
+ unsigned long a;
+ unsigned long b;
+ unsigned long c;
+ unsigned long d;
+
+É realmente suficiente fazer::
+
+ unsigned long a, b, c, d;
+
+Por favor, evite também introduzir divisões de linha em declarações de variáveis::
+
+ struct long_struct_name *descriptive_name = container_of(bar,
+ struct long_struct_name,
+ member);
+ struct foobar foo;
+
+É muito melhor mover a inicialização para uma linha separada após as
+declarações::
+
+ struct long_struct_name *descriptive_name;
+ struct foobar foo;
+
+ descriptive_name = container_of(bar, struct long_struct_name, member);
+
+
+Tipos de variáveis
+^^^^^^^^^^^^^^^^^^
+
+Por favor use os tipos u8, u16, u32, u64 adequados para variáveis que são destinadas
+a descrever hardware ou são usadas como argumentos para funções que acessam
+hardware. Estes tipos definem claramente a largura em bits e evitam
+truncamento, expansão e confusão entre 32/64 bits.
+
+u64 também é recomendado em código que se tornaria ambíguo para kernels
+de 32 bits quando 'unsigned long' fosse usado em vez disso. Embora em tais
+situações 'unsigned long long' pudesse ser usado também, u64 é mais curto
+e também mostra claramente que a operação requer uma largura de 64 bits
+independente da CPU alvo.
+
+Por favor use 'unsigned int' em vez de 'unsigned'.
+
+
+Constantes
+^^^^^^^^^^
+
+Por favor, não use números (hexa)decimais literais em código ou inicializadores.
+Ou use defines adequados que tenham nomes descritivos ou considere usar
+um enum.
+
+
+Declarações e inicializadores de struct
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As declarações de struct devem alinhar os nomes dos membros da struct de forma
+tabular::
+
+ struct bar_order {
+ unsigned int guest_id;
+ int ordered_item;
+ struct menu *menu;
+ };
+
+Por favor, evite documentar os membros da struct dentro da declaração, pois
+isso frequentemente resulta em comentários formatados de maneira estranha e os membros da struct
+ficam ofuscados::
+
+ struct bar_order {
+ unsigned int guest_id; /* ID único do convidado */
+ int ordered_item;
+ /* Ponteiro para uma instância de menu que contém todas as bebidas */
+ struct menu *menu;
+ };
+
+Em vez disso, por favor considere usar o formato kernel-doc em um comentário precedendo
+a declaração da struct, que é mais fácil de ler e tem a vantagem adicional
+de incluir a informação na documentação do kernel, por exemplo, da
+seguinte forma::
+
+
+ /**
+ * struct bar_order - Descrição de um pedido de bar
+ * @guest_id: ID único do convidado
+ * @ordered_item: O número do item do menu
+ * @menu: Ponteiro para o menu do qual o item
+ * foi pedido
+ *
+ * Informação suplementar para usar a struct.
+ *
+ * Note que os descritores dos membros da struct acima estão dispostos
+ * de forma tabular.
+ */
+ struct bar_order {
+ unsigned int guest_id;
+ int ordered_item;
+ struct menu *menu;
+ };
+
+Inicializadores de struct estáticos devem usar inicializadores C99 e também devem ser
+alinhados de forma tabular::
+
+ static struct foo statfoo = {
+ .a = 0,
+ .plain_integer = CONSTANT_DEFINE_OR_ENUM,
+ .bar = &statbar,
+ };
+
+Note que embora a sintaxe C99 permita a omissão da vírgula final,
+nós recomendamos o uso de uma vírgula na última linha porque isso torna
+o reordenamento e a adição de novas linhas mais fáceis, e também torna tais
+patches futuros ligeiramente mais fáceis de ler.
+
+Quebras de linha
+^^^^^^^^^^^^^^^^
+
+Restringir o comprimento da linha a 80 caracteres torna código profundamente indentado difícil de
+ler. Considere dividir o código em funções auxiliares para evitar quebra de
+linha excessiva.
+
+A regra de 80 caracteres não é uma regra estrita, então por favor use bom senso ao
+quebrar linhas. Especialmente strings de formato nunca devem ser divididas.
+
+Ao dividir declarações de funções ou chamadas de funções, então por favor alinhe
+o primeiro argumento na segunda linha com o primeiro argumento na primeira
+linha::
+
+ static int long_function_name(struct foobar *barfoo, unsigned int id,
+ unsigned int offset)
+ {
+
+ if (!id) {
+ ret = longer_function_name(barfoo, DEFAULT_BARFOO_ID,
+ offset);
+ ...
+
+Namespaces
+^^^^^^^^^^
+
+Namespaces de funções/variáveis melhoram a legibilidade e permitem
+grepping fácil. Estes namespaces são prefixos de string para nomes
+de funções e variáveis visíveis globalmente, incluindo inlines. Estes prefixos devem
+combinar o subsistema e o nome do componente como 'x86_comp\_',
+'sched\_', 'irq\_', e 'mutex\_'.
+
+Isso também inclui funções estáticas de escopo de arquivo que são imediatamente colocadas
+em templates de driver visíveis globalmente - é útil que esses símbolos
+também carreguem um bom prefixo, para legibilidade do backtrace.
+
+Prefixos de namespace podem ser omitidos para funções e variáveis
+estáticas locais. Funções verdadeiramente locais, chamadas apenas por outras funções locais,
+podem ter nomes descritivos mais curtos - nossa preocupação principal é a facilidade de grepping
+e a legibilidade do backtrace.
+
+Por favor note que os prefixos 'xxx_vendor\_' e 'vendor_xxx\_' não são
+úteis para funções estáticas em arquivos específicos de fornecedores. Afinal,
+já está claro que o código é específico do fornecedor. Além disso, nomes
+de fornecedores devem ser apenas para funcionalidades verdadeiramente específicas de fornecedores.
+
+Como sempre, aplique o bom senso e vise a consistência e a legibilidade.
+
+
+Notificações de commit
+----------------------
+
+A árvore tip é monitorada por um bot por novos commits. O bot envia um email
+para cada novo commit para uma lista de discussão dedicada
+(``linux-tip-commits@vger.kernel.org``) e coloca em Cc todas as pessoas que são
+mencionadas em uma das tags de commit. Ele usa o ID da mensagem de email da
+tag Link no final da lista de tags para definir o cabeçalho de email In-Reply-To para que
+a mensagem seja encadeada corretamente com o email de submissão do patch.
+
+Os mantenedores e submantenedores tip tentam responder ao remetente
+ao fazer o merge de um patch, mas às vezes eles esquecem ou isso não se encaixa no
+fluxo de trabalho do momento. Embora a mensagem do bot seja puramente mecânica, ela
+também implica em um 'Obrigado! Aplicado.'.
--
2.47.3
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 4/4] docs: pt_BR: translate submitting-patches.rst
2026-09-09 12:48 [PATCH 0/4] docs: pt_BR: process: Add remaining core process translations Daniel Pereira
` (2 preceding siblings ...)
2026-09-09 12:48 ` [PATCH 3/4] docs: pt_BR: translate maintainer-tip.rst Daniel Pereira
@ 2026-09-09 12:48 ` Daniel Pereira
3 siblings, 0 replies; 5+ messages in thread
From: Daniel Pereira @ 2026-09-09 12:48 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
Translate Documentation/process/submitting-patches.rst into Brazilian
Portuguese and add it to the pt_BR process documentation index.
This document contains guidelines and essential instructions for
developers submitting code and patches to the Linux kernel.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
.../translations/pt_BR/process/2.Process.rst | 2 +-
.../translations/pt_BR/process/index.rst | 1 +
.../pt_BR/process/maintainer-kvm-x86.rst | 6 +-
.../pt_BR/process/submitting-patches.rst | 961 ++++++++++++++++++
4 files changed, 966 insertions(+), 4 deletions(-)
create mode 100644 Documentation/translations/pt_BR/process/submitting-patches.rst
diff --git a/Documentation/translations/pt_BR/process/2.Process.rst b/Documentation/translations/pt_BR/process/2.Process.rst
index 03e288d46..0019b7404 100644
--- a/Documentation/translations/pt_BR/process/2.Process.rst
+++ b/Documentation/translations/pt_BR/process/2.Process.rst
@@ -455,7 +455,7 @@ Existem algumas dicas que podem ajudar na sobrevivência na lista linux-kernel:
- Use respostas intercaladas, o que torna sua resposta mais fácil
de ler. (ou seja, evite o "top-posting" — a prática de colocar sua resposta
acima do texto citado ao qual você está respondendo). Para mais detalhes, veja
- :ref:`Documentation/process/submitting-patches.rst <interleaved_replies>`.
+ :ref:`Documentation/process/submitting-patches.rst <pt_BR_interleaved_replies>`.
- Pergunte na lista de discussão correta. A lista linux-kernel pode até ser o
ponto de encontro geral, mas não é o melhor lugar para encontrar desenvolvedores
diff --git a/Documentation/translations/pt_BR/process/index.rst b/Documentation/translations/pt_BR/process/index.rst
index e011b55a1..2c63d82bf 100644
--- a/Documentation/translations/pt_BR/process/index.rst
+++ b/Documentation/translations/pt_BR/process/index.rst
@@ -26,6 +26,7 @@ sua entrada na comunidade do kernel.
Como começar <howto>
Guia do Processo de Desenvolvimento <development-process>
+ Enviando patches: o guia essencial para colocar o seu código no kernel <submitting-patches>
Lista de verificação para submissão de patches do kernel Linux <submit-checklist>
Ferramentas e guias técnicos para desenvolvedores do kernel
diff --git a/Documentation/translations/pt_BR/process/maintainer-kvm-x86.rst b/Documentation/translations/pt_BR/process/maintainer-kvm-x86.rst
index 6480ff08b..d9fd272fb 100644
--- a/Documentation/translations/pt_BR/process/maintainer-kvm-x86.rst
+++ b/Documentation/translations/pt_BR/process/maintainer-kvm-x86.rst
@@ -122,7 +122,7 @@ Quando se trata de estilo, nomenclatura, padrões, etc., a consistência é a
prioridade número um no KVM x86. Se tudo mais falhar, siga o que já existe.
Com algumas ressalvas listadas abaixo, siga o estilo de codificação preferido
-dos mantenedores da árvore "tip" (:ref:`maintainer-tip-coding-style`), já que
+dos mantenedores da árvore "tip" (:ref:`pt_BR_maintainer-tip-coding-style`), já que
patches/séries frequentemente tocam tanto arquivos do KVM quanto arquivos x86
não-KVM, ou seja, atraem a atenção de mantenedores do KVM *e* da árvore "tip".
@@ -206,7 +206,7 @@ Novos tópicos surgem ocasionalmente, mas, por favor, inicie uma discussão na
lista se desejar propor a introdução de um novo tópico; ou seja, não aja por
conta própria.
-Veja :ref:`the_canonical_patch_format` para mais informações, com uma ressalva:
+Veja :ref:`pt_BR_the_canonical_patch_format` para mais informações, com uma ressalva:
não trate o limite de 70-75 caracteres como um limite absoluto e rígido. Em
vez disso, use 75 caracteres como um limite firme, mas não rígido, e use 80
caracteres como um limite intransponível. Ou seja, permita que o shortlog
@@ -218,7 +218,7 @@ Changelog
O mais importante: escreva os changelogs usando o modo imperativo e evite o uso
de pronomes.
-Veja :ref:`describe_changes` para mais informações, com uma ressalva: comece com
+Veja :ref:`pt_BR_describe_changes` para mais informações, com uma ressalva: comece com
uma breve descrição das mudanças reais e, em seguida, apresente o contexto e o
histórico. Note! Esta ordem entra em conflito direto com a abordagem preferida
da árvore "tip"! Por favor, siga o estilo preferido da árvore "tip" ao enviar
diff --git a/Documentation/translations/pt_BR/process/submitting-patches.rst b/Documentation/translations/pt_BR/process/submitting-patches.rst
new file mode 100644
index 000000000..8cf1aae52
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/submitting-patches.rst
@@ -0,0 +1,961 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Enviando patches: o guia essencial para colocar o seu código no kernel
+======================================================================
+
+Para uma pessoa ou empresa que deseja enviar uma mudança para o
+kernel Linux, o processo pode, por vezes, ser intimidador se você não
+estiver familiarizado com "o sistema". Este texto é uma coleção de sugestões
+que podem aumentar muito as chances de sua mudança ser aceita.
+
+Este documento contém um grande número de sugestões em um formato relativamente
+conciso. Para informações detalhadas sobre como funciona o processo de
+desenvolvimento do kernel, consulte Documentation/process/development-process.rst.
+Além disso, leia Documentation/process/submit-checklist.rst
+para uma lista de itens a serem verificados antes de enviar o código.
+Para patches de binding de device tree, leia
+Documentation/devicetree/bindings/submitting-patches.rst.
+
+Esta documentação assume que você está usando o ``git`` para preparar seus
+patches. Se você não está familiarizado com o ``git``, é muito recomendado que
+você aprenda a usá-lo, ele tornará a sua vida como um desenvolvedor do kernel e,
+em geral, muito mais fácil.
+
+Alguns subsistemas e árvores de mantenedores possuem informações adicionais
+sobre seus fluxos de trabalho e expectativas, consulte
+Documentation/process/maintainer-handbooks.rst.
+
+Obtenha uma árvore de código-fonte atual
+----------------------------------------
+
+Se você não tiver um repositório com o código-fonte atual do kernel em mãos,
+use o ``git`` para obter um. Você vai querer começar com o repositório mainline,
+que pode ser obtido com::
+
+ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+
+Note, no entanto, que você pode não querer desenvolver diretamente na
+árvore mainline. A maioria dos mantenedores de subsistemas mantém suas
+próprias árvores e desejam ver os patches preparados em relação a essas árvores.
+Consulte a entrada **T:** do subsistema no arquivo MAINTAINERS para encontrar
+essa árvore, ou simplesmente pergunte ao mantenedor se a árvore não estiver
+listada lá.
+
+.. _pt_BR_describe_changes:
+
+Descreva as suas mudanças
+-------------------------
+
+Descreva o seu problema. Seja o seu patch uma correção de bug de uma linha ou
+5000 linhas de um novo recurso, deve haver um problema subjacente que o motivou
+a fazer esse trabalho. Convença o revisor de que existe um problema que vale a
+pena corrigir e que faz sentido que ele leia além do primeiro parágrafo.
+
+Descreva o impacto visível ao usuário. Travamentos e bloqueios diretos são
+bastante convincentes, mas nem todos os bugs são tão evidentes. Mesmo que o
+problema tenha sido identificado durante a revisão do código, descreva o impacto
+que você acredita que ele pode ter sobre os usuários. Tenha em mente que a
+maioria das instalações Linux executa kernels de árvores estáveis secundárias
+ou árvores específicas de fornecedores/produtos que selecionam apenas patches
+específicos do upstream, então inclua qualquer coisa que possa ajudar a
+direcionar sua mudança downstream: circunstâncias provocadoras, trechos do
+dmesg, descrições do travamento, regressões de desempenho, picos de latência,
+bloqueios, etc.
+
+Quantifique as otimizações e compensações. Se você afirma haver melhorias no
+desempenho, consumo de memória, uso da pilha ou tamanho do binário, inclua
+números que as comprovem. Mas também descreva custos que não são óbvios.
+Otimizações geralmente não são gratuitas, sendo trocas entre CPU, memória e
+legibilidade; ou, quando se trata de heurísticas, entre diferentes cargas de
+trabalho. Descreva as desvantagens esperadas da sua otimização para que o
+revisor possa pesar os custos contra os benefícios.
+
+Uma vez estabelecido o problema, descreva o que você está efetivamente fazendo
+sobre ele, com detalhes técnicos. É importante descrever a mudança em inglês
+claro para o revisor verificar que o código está se comportando como
+você pretendia.
+
+O mantenedor agradecerá se você escrever a descrição do seu patch em uma forma
+que possa ser facilmente inserida no sistema de gerenciamento de código-fonte do
+Linux, o ``git``, como uma "mensagem de commit". Veja
+:ref:`pt_BR_the_canonical_patch_format`.
+
+Resolva apenas um problema por patch. Se a sua descrição começar a ficar longa,
+isso é um sinal de que você provavelmente precisa dividir o seu patch.
+Consulte :ref:`pt_BR_split_changes`.
+
+Quando você enviar ou reenviar um patch ou uma série de patches, inclua a
+descrição completa do patch e a justificativa para ele. Não diga apenas
+que esta é a versão N do patch (ou série). Não espere que o mantenedor
+do subsistema consulte versões anteriores do patch ou URLs de referência
+para encontrar a descrição do patch e colocá-la no patch.
+Ou seja, o patch (ou a série) e sua descrição devem ser autossuficientes.
+Isso beneficia tanto os mantenedores quanto os revisores. Alguns revisores
+provavelmente nem chegaram a receber as versões anteriores do patch.
+
+Descreva suas alterações no modo imperativo, por exemplo, "faça xyzzy executar
+frotz" em vez de "[Este patch] faz xyzzy executar frotz" ou "[Eu] mudei xyzzy
+para executar frotz", como se você estivesse dando ordens à base de código para
+mudar o seu comportamento.
+
+Se você quiser se referir a um commit específico, não se refira apenas ao
+ID SHA-1 do commit. Por favor, inclua também o resumo de uma linha do
+commit, para tornar mais fácil para os revisores saberem sobre o que se trata.
+Exemplo::
+
+ Commit e21d2170f36602ae2708 ("video: remove unnecessary
+ platform_set_drvdata()") removed the unnecessary
+ platform_set_drvdata(), but left the variable "dev" unused,
+ delete it.
+
+Você também deve ter a certeza de usar pelo menos os primeiros doze caracteres do
+ID SHA-1. O repositório do kernel possui um número *muito* grande de objetos, o que torna as
+colisões com IDs mais curtos uma possibilidade real. Tenha em mente que, mesmo que
+não haja colisão com o seu ID de seis caracteres agora, essa condição pode
+mudar daqui a cinco anos.
+
+Se discussões relacionadas ou qualquer outra informação de contexto por trás da mudança
+puderem ser encontradas na web, adicione tags 'Link:' apontando para isso. Se o patch é o
+resultado de algumas discussões anteriores na lista de e-mails ou algo documentado na
+web, aponte para ele.
+
+Ao criar links para arquivos de listas de e-mails, de preferência use o serviço
+de arquivo de mensagens lore.kernel.org. Para criar a URL do link, use o
+conteúdo do cabeçalho ``Message-ID`` da mensagem, sem os colchetes angulares
+circundantes. Por exemplo::
+
+ Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI
+
+Por favor, verifique o link para se certificar de que ele está realmente
+funcionando e aponta para a mensagem relevante.
+
+No entanto, tente tornar a sua explicação compreensível sem recursos
+externos. Além de fornecer um URL para um arquivo da lista de e-mails ou bug,
+resuma os pontos relevantes da discussão que levaram ao patch conforme enviado.
+
+Caso o seu patch corrija um bug, use a tag 'Closes:' com um URL que referencie o
+relato nos arquivos da lista de e-mails ou em um rastreador público de bugs. Por exemplo::
+
+ Closes: https://example.com/issues/1234
+
+Alguns rastreadores de bugs têm a capacidade de fechar os problemas
+automaticamente quando um commit com tal tag é aplicado. Alguns bots que monitoram as listas de
+e-mails também podem rastrear tais tags e tomar certas ações. Rastreadores de bugs
+privados e URLs inválidos são proibidos.
+
+Se o seu patch corrige um bug em um commit específico, por exemplo, você encontrou um problema usando
+``git bisect``, por favor, use a tag 'Fixes:' com pelo menos os primeiros 12
+caracteres do ID SHA-1 e o resumo de uma linha. Não divida a tag em
+várias linhas, as tags estão isentas da regra de "quebra de linha nas 75 colunas" para
+simplificar os scripts de parsing. Por exemplo::
+
+ Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
+
+As seguintes configurações do ``git config`` podem ser usadas para adicionar um formato aprimorado para
+exibir o estilo acima nos comandos ``git log`` ou ``git show``::
+
+ [core]
+ abbrev = 12
+ [pretty]
+ fixes = Fixes: %h (\"%s\")
+
+Um exemplo de chamada::
+
+ $ git log -1 --pretty=fixes 54a4f0239f2e
+ Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
+
+.. _pt_BR_split_changes:
+
+Separe as suas mudanças
+-----------------------
+
+Separe cada **mudança lógica** em um patch separado.
+
+Por exemplo, se as suas alterações incluírem tanto correções de bugs quanto melhorias
+de desempenho para um único driver, separe essas alterações em dois
+ou mais patches. Se as suas alterações incluírem uma atualização de API e um novo
+driver que utiliza essa nova API, separe-os em dois patches.
+
+Por outro lado, se você fizer uma única alteração em vários arquivos,
+agrupe essas alterações em um único patch. Assim, uma única mudança
+lógica está contida em um único patch.
+
+O ponto a lembrar é que cada patch deve fazer uma mudança facilmente compreendida
+que possa ser verificada pelos revisores. Cada patch deve ser justificável
+por seus próprios méritos.
+
+Se um patch depender de outro patch para que uma mudança seja
+completa, não tem problema. Simplesmente note **"this patch depends on patch X"**
+na descrição do seu patch.
+
+Ao dividir a sua mudança em uma série de patches, tome um cuidado especial para
+garantir que o kernel compile e seja executado adequadamente após cada patch da
+série. Desenvolvedores que usam o ``git bisect`` para rastrear um problema podem acabar
+dividindo a sua série de patches em qualquer ponto; eles não ficarão gratos se você
+introduzir bugs no meio do processo.
+
+Se você não conseguir condensar o seu conjunto de patches em um conjunto menor
+de patches, então publique, digamos, apenas uns 15 de cada vez e aguarde pela
+revisão e integração.
+
+
+
+Verifique o estilo das suas mudanças
+------------------------------------
+
+Verifique o seu patch quanto a violações básicas de estilo, cujos detalhes podem ser
+encontrados em Documentation/process/coding-style.rst.
+Não fazer isso simplesmente desperdiça
+o tempo dos revisores e fará com que o seu patch seja rejeitado, provavelmente
+sem sequer ser lido.
+
+Uma exceção significativa é quando se move código de um arquivo para
+outro -- neste caso você não deve modificar o código movido no
+mesmo patch que o move. Isso delineia claramente o ato de
+mover o código e as suas alterações. Isso ajuda muito a revisão das
+diferenças reais e permite que as ferramentas rastreiem melhor o histórico do
+próprio código.
+
+Verifique os seus patches com o verificador de estilo de patch antes de os submeter
+(scripts/checkpatch.pl). Note, porém, que o verificador de estilo deve ser
+visto como um guia, e não como um substituto para o julgamento humano. Se o seu
+código parecer melhor com uma violação, provavelmente é melhor deixá-lo como está.
+
+O verificador emite relatórios em três níveis:
+ - ERROR: coisas que muito provavelmente estão erradas
+ - WARNING: coisas que requerem uma revisão cuidadosa
+ - CHECK: coisas que requerem reflexão
+
+Você deve ser capaz de justificar todas as violações que permanecerem no seu
+patch.
+
+Selecione os destinatários do seu patch
+---------------------------------------
+
+Você deve sempre copiar o(s) mantenedor(es) e a(s) lista(s) do subsistema
+apropriado(s) em qualquer patch para o código que eles mantêm; dê uma
+olhada no arquivo MAINTAINERS e no histórico de revisão do código-fonte
+para ver quem são esses mantenedores. O script scripts/get_maintainer.pl
+pode ser muito útil nesta etapa (passe os caminhos para seus patches
+como argumentos para scripts/get_maintainer.pl). Se você não conseguir
+encontrar um mantenedor para o subsistema em que está trabalhando,
+Andrew Morton (akpm@linux-foundation.org) serve como um mantenedor de
+último recurso.
+
+linux-kernel@vger.kernel.org deve ser usado por padrão para todos os
+patches, mas o volume dessa lista fez com que vários desenvolvedores a
+ignorassem. Por favor, não envie spam para listas e pessoas não
+relacionadas.
+
+Muitas listas relacionadas ao kernel estão hospedadas em kernel.org;
+você pode encontrar uma lista delas em https://subspace.kernel.org.
+Existem listas relacionadas ao kernel hospedadas em outros lugares
+também, no entanto.
+
+Linus Torvalds é o árbitro final de todas as mudanças aceitas no
+kernel do Linux. Seu endereço de e-mail é <torvalds@linux-foundation.org>.
+Ele recebe muitos e-mails e, neste momento, muito poucos patches passam
+por Linus diretamente, então, normalmente, você deve fazer o seu melhor
+para -evitar- enviar e-mails para ele.
+
+Se você tiver um patch que corrija um bug de segurança explorável,
+envie esse patch para security@kernel.org. Para bugs severos, um
+curto embargo pode ser considerado para permitir que os distribuidores
+disponibilizem o patch aos usuários; em tais casos, obviamente, o
+patch não deve ser enviado a nenhuma lista pública. Veja também
+Documentation/process/security-bugs.rst.
+
+Patches que corrigem um bug severo em um kernel já lançado devem ser
+direcionados aos mantenedores stable (estáveis), colocando uma linha como esta::
+
+ Cc: stable@vger.kernel.org
+
+na área de sign-off do seu patch (note, NÃO como um destinatário de e-mail).
+Você também deve ler Documentation/process/stable-kernel-rules.rst
+além deste documento.
+
+Se as alterações afetarem as interfaces userland-kernel,
+por favor, envie ao mantenedor das MAN-PAGES (como listado no arquivo MAINTAINERS)
+um patch para as páginas de manual, ou pelo menos uma notificação da alteração,
+para que alguma informação chegue às páginas de manual. Mudanças na API
+do espaço de usuário também devem ser copiadas para linux-api@vger.kernel.org.
+
+
+Sem MIME, sem links, sem compressão, sem anexos. Apenas texto puro
+------------------------------------------------------------------
+
+Linus e outros desenvolvedores do kernel precisam ser capazes de ler e
+comentar as mudanças que você está enviando. É importante que um
+desenvolvedor do kernel seja capaz de "citar" suas mudanças, usando
+ferramentas de e-mail padrão, para que eles possam comentar em partes
+específicas do seu código.
+
+Por esse motivo, todos os patches devem ser enviados por e-mail "inline". A
+maneira mais fácil de fazer isso é com ``git send-email``, que é
+fortemente recomendado. Um tutorial interativo para ``git send-email``
+está disponível em https://git-send-email.io.
+
+Se você optar por não usar ``git send-email``:
+
+.. warning::
+
+ Tenha cuidado com a quebra de linha do seu editor corrompendo seu patch,
+ se você optar por recortar e colar o seu patch.
+
+Não anexe o patch como um anexo MIME, comprimido ou não.
+Muitos aplicativos populares de e-mail nem sempre transmitirão um
+anexo MIME como texto puro, tornando impossível comentar o seu
+código. Um anexo MIME também leva um pouco mais de tempo para Linus
+processar, diminuindo a probabilidade da sua alteração anexada em MIME
+ser aceita.
+
+Exceção: Se o seu cliente de e-mail estiver danificando os patches,
+alguém pode pedir que você os reenvie usando MIME.
+
+Veja Documentation/process/email-clients.rst para dicas sobre como
+configurar seu cliente de e-mail para que ele envie seus patches intocados.
+
+Responda aos comentários de revisão
+-----------------------------------
+
+Seu patch quase certamente receberá comentários dos revisores sobre maneiras
+pelas quais o patch pode ser melhorado, na forma de uma resposta ao seu
+e-mail. Você deve responder a esses comentários; ignorar revisores é uma
+boa maneira de ser ignorado em troca. Você pode simplesmente responder aos
+e-mails deles para responder aos seus comentários. Comentários de revisão
+ou perguntas que não levam a uma alteração no código devem quase certamente
+resultar em um comentário ou entrada no changelog para que o próximo
+revisor entenda melhor o que está acontecendo.
+
+Certifique-se de dizer aos revisores quais alterações você está fazendo e
+de agradecê-los pelo tempo dedicado. A revisão de código é um processo
+cansativo e demorado, e os revisores às vezes ficam mal-humorados. Mesmo
+nesse caso, no entanto, responda educadamente e resolva os problemas que
+eles apontaram. Ao enviar uma próxima versão, adicione um ``changelog do patch``
+à carta de apresentação (cover letter) ou aos patches individuais,
+explicando a diferença em relação ao envio anterior (veja
+:ref:`pt_BR_the_canonical_patch_format`).
+Notifique as pessoas que comentaram no seu patch sobre as novas versões
+adicionando-as à lista de CC dos patches.
+
+Veja Documentation/process/email-clients.rst para recomendações sobre
+clientes de e-mail e etiqueta de listas de discussão.
+
+.. _pt_BR_interleaved_replies:
+
+Use respostas intercaladas e aparadas em discussões por e-mail
+--------------------------------------------------------------
+O top-posting (responder no topo) é fortemente desencorajado em
+discussões de desenvolvimento do kernel do Linux. Respostas
+intercaladas (ou "inline") tornam as conversas muito mais fáceis de
+acompanhar. Para mais detalhes, veja:
+https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
+
+Como é frequentemente citado na lista de discussão::
+
+ A: http://en.wikipedia.org/wiki/Top_post
+ Q: Onde encontro informações sobre essa coisa chamada top-posting?
+ A: Porque bagunça a ordem em que as pessoas normalmente leem o texto.
+ Q: Por que o top-posting é algo tão ruim?
+ A: Top-posting.
+ Q: Qual é a coisa mais irritante no e-mail?
+
+Da mesma forma, por favor, apare (corte) todas as citações
+desnecessárias que não são relevantes para a sua resposta. Isso torna
+as respostas mais fáceis de encontrar, e economiza tempo e espaço. Para
+mais detalhes, veja: http://daringfireball.net/2007/07/on_top ::
+
+ A: Não.
+ Q: Devo incluir citações após minha resposta?
+
+.. _pt_BR_resend_reminders:
+
+Não desanime - nem fique impaciente
+-----------------------------------
+
+Depois de ter enviado a sua alteração, seja paciente e espere. Os
+revisores são pessoas ocupadas e podem não chegar ao seu patch
+imediatamente.
+
+Era uma vez, patches costumavam desaparecer no vazio sem comentários,
+mas o processo de desenvolvimento funciona de forma mais suave do que
+isso agora. Você deve receber comentários dentro de algumas semanas
+(normalmente 2-3); se isso não acontecer, certifique-se de que você
+enviou seus patches para o lugar certo. Espere por no mínimo uma
+semana antes de reenviar ou dar um "ping" nos revisores -
+possivelmente mais tempo durante períodos ocupados, como as janelas
+de mesclagem (merge windows).
+
+Também não há problema em reenviar o patch ou a série de patches após
+algumas semanas com a palavra "RESEND" adicionada à linha de Assunto::
+
+ [PATCH Vx RESEND] sub/sys: Resumo condensado do patch
+
+Não adicione "RESEND" quando você estiver enviando uma versão
+modificada do seu patch ou série de patches - "RESEND" se aplica
+apenas ao reenvio de um patch ou série de patches que não foram
+modificados de forma alguma em relação ao envio anterior.
+
+
+Inclua PATCH no Assunto
+-----------------------
+
+Devido ao alto tráfego de e-mails para Linus e para a linux-kernel, é
+uma convenção comum prefixar a sua linha de Assunto com [PATCH]. Isso
+permite que Linus e outros desenvolvedores do kernel distingam
+mais facilmente os patches de outras discussões por e-mail.
+
+O ``git send-email`` fará isso por você automaticamente.
+
+
+Assine seu trabalho - o Certificado de Origem do Desenvolvedor
+--------------------------------------------------------------
+
+Para melhorar o rastreamento de quem fez o que, especialmente com patches
+que podem percolar até o seu local de descanso final no kernel através de
+várias camadas de mantenedores, nós introduzimos um procedimento de
+"sign-off" nos patches que estão sendo enviados por e-mail.
+
+O sign-off é uma linha simples no final da explicação do patch, que
+certifica que você o escreveu ou que de outra forma tem o direito de
+repassá-lo como um patch de código aberto. As regras são bem simples:
+se você pode certificar o seguinte::
+
+ Certificado de Origem do Desenvolvedor 1.1
+
+ Ao fazer uma contribuição para este projeto, eu certifico que:
+
+ (a) A contribuição foi criada no todo ou em parte por mim e eu
+ tenho o direito de enviá-la sob a licença de código aberto
+ indicada no arquivo; ou
+
+ (b) A contribuição baseia-se em trabalho anterior que, até onde eu
+ sei, é coberto por uma licença de código aberto apropriada
+ e eu tenho o direito, sob essa licença, de enviar esse
+ trabalho com modificações, tenham sido criadas no todo ou
+ em parte por mim, sob a mesma licença de código aberto (a menos que eu
+ tenha permissão para enviar sob uma licença diferente), conforme
+ indicado no arquivo; ou
+
+ (c) A contribuição foi fornecida diretamente a mim por alguma outra
+ pessoa que certificou (a), (b) ou (c) e eu não a modifiquei.
+
+ (d) Eu entendo e concordo que este projeto e a contribuição
+ são públicos e que um registro da contribuição (incluindo todas
+ as informações pessoais que eu envio com ela, incluindo meu
+ sign-off) é mantido indefinidamente e pode ser redistribuído de forma
+ consistente com este projeto ou com a(s) licença(s) de código
+ aberto envolvida(s).
+
+então você apenas adiciona uma linha dizendo::
+
+ Signed-off-by: Random J Developer <random@developer.example.org>
+
+usando uma identidade conhecida (desculpe, sem contribuições anônimas.)
+Isso será feito para você automaticamente se você usar o ``git commit -s``.
+As reversões também devem incluir "Signed-off-by". O ``git revert -s``
+faz isso por você.
+
+Algumas pessoas também colocam tags extras no final. Elas serão
+apenas ignoradas por enquanto, mas você pode fazer isso para marcar
+procedimentos internos da empresa ou apenas para apontar algum
+detalhe especial sobre o sign-off.
+
+Quaisquer outros SoBs (Signed-off-by:'s) seguindo o SoB do autor
+são de pessoas que manusearam e transportaram o patch, mas não
+estiveram envolvidas no seu desenvolvimento. As cadeias de SoB devem
+refletir a rota **real** que um patch percorreu à medida que foi
+propagado aos mantenedores e, finalmente, para Linus, com a primeira
+entrada de SoB sinalizando a autoria principal de um único autor.
+
+
+Quando usar Acked-by:, Cc: e Co-developed-by:
+---------------------------------------------
+
+A tag Signed-off-by: indica que o signatário esteve envolvido no
+desenvolvimento do patch, ou que ele/ela estava no caminho de
+entrega do patch.
+
+Se uma pessoa não esteve diretamente envolvida na preparação ou manuseio de um
+patch, mas deseja manifestar e registrar sua aprovação, ela pode
+pedir para ter uma linha Acked-by: adicionada ao changelog do patch.
+
+Acked-by: destina-se a ser usado por aqueles responsáveis ou envolvidos com o
+código afetado de uma forma ou de outra. Mais comumente, o mantenedor quando esse
+mantenedor não contribuiu nem encaminhou o patch.
+
+Acked-by: também pode ser usado por outras partes interessadas, como pessoas com conhecimento de
+domínio (por exemplo, o autor original do código sendo modificado), revisores
+do lado do espaço de usuário para um patch uAPI do kernel ou usuários-chave de um recurso. Opcionalmente,
+nestes casos, pode ser útil adicionar um "# Sufixo" para esclarecer seu significado::
+
+ Acked-by: The Stakeholder <stakeholder@example.org> # As primary user
+
+Acked-by: não é tão formal quanto Signed-off-by:. É um registro de que o avaliador
+pelo menos revisou o patch e indicou aceitação. Por isso, os responsáveis pela fusão de
+patches às vezes converterão manualmente um "sim, parece bom para mim" de um avaliador
+em um Acked-by: (mas note que geralmente é melhor pedir um
+ack explícito).
+
+Acked-by: também é menos formal do que Reviewed-by:. Por exemplo, mantenedores podem
+usá-lo para sinalizar que estão de acordo com a inclusão de um patch, mas podem não tê-lo
+revisado tão minuciosamente como se um Reviewed-by: fosse fornecido. Da mesma forma, um
+usuário-chave pode não ter realizado uma revisão técnica do patch, mas ainda assim estar
+satisfeito com a abordagem geral, o recurso ou a interface voltada para o usuário.
+
+Acked-by: não indica necessariamente o reconhecimento de todo o patch.
+Por exemplo, se um patch afeta vários subsistemas e tem um Acked-by: de
+um mantenedor de subsistema, isso geralmente indica o reconhecimento apenas
+da parte que afeta o código desse mantenedor. O bom senso deve ser usado aqui.
+Em caso de dúvida, as pessoas devem consultar a discussão original nos arquivos da
+lista de discussão. Um "# Sufixo" também pode ser usado neste caso para esclarecer.
+
+Se uma pessoa teve a oportunidade de comentar em um patch, mas não
+forneceu tais comentários, você pode opcionalmente adicionar uma tag ``Cc:`` ao patch.
+Esta tag documenta que partes potencialmente interessadas foram incluídas na
+discussão. Note que esta é uma de apenas três tags que você pode usar
+sem a permissão explícita da pessoa nomeada (veja 'Marcar pessoas requer
+permissão' abaixo para detalhes).
+
+Co-developed-by: afirma que o patch foi co-criado por múltiplos desenvolvedores;
+é usado para dar atribuição a coautores (além do autor
+atribuído pela tag From:) quando várias pessoas trabalham em um único patch. Como
+Co-developed-by: denota autoria, cada Co-developed-by: deve ser imediatamente
+seguido por um Signed-off-by: do coautor associado. O procedimento padrão de assinatura
+se aplica, ou seja, a ordem das tags Signed-off-by: deve refletir a
+história cronológica do patch na medida do possível, independentemente se
+o autor for atribuído via From: ou Co-developed-by:. Notavelmente, o último
+Signed-off-by: deve ser sempre o do desenvolvedor que está enviando o patch.
+
+Note que a tag From: é opcional quando o autor no From: também é a pessoa (e
+e-mail) listada na linha From: do cabeçalho do e-mail.
+
+Exemplo de um patch enviado pelo autor do From:::
+
+ <changelog>
+
+ Co-developed-by: First Co-Author <first@coauthor.example.org>
+ Signed-off-by: First Co-Author <first@coauthor.example.org>
+ Co-developed-by: Second Co-Author <second@coauthor.example.org>
+ Signed-off-by: Second Co-Author <second@coauthor.example.org>
+ Signed-off-by: From Author <from@author.example.org>
+
+Exemplo de um patch enviado por um autor do Co-developed-by:::
+
+ From: From Author <from@author.example.org>
+
+ <changelog>
+
+ Co-developed-by: Random Co-Author <random@coauthor.example.org>
+ Signed-off-by: Random Co-Author <random@coauthor.example.org>
+ Signed-off-by: From Author <from@author.example.org>
+ Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
+ Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
+
+
+Usando Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
+---------------------------------------------------------------------
+
+A tag Reported-by dá crédito às pessoas que encontram bugs e os relatam e
+espera-se que isso as inspire a nos ajudar novamente no futuro. A tag destina-se a
+bugs; por favor, não a use para dar crédito a solicitações de recursos. A tag deve ser
+seguida por uma tag Closes: apontando para o relato, a menos que o relato não
+esteja disponível na web. A tag Link: pode ser usada em vez de Closes: se o patch
+corrigir uma parte do(s) problema(s) sendo relatado(s). Note que a tag Reported-by é
+uma de apenas três tags que você pode usar sem a permissão explícita da
+pessoa nomeada (veja 'Marcar pessoas requer permissão' abaixo para detalhes).
+
+Uma tag Tested-by: indica que o patch foi testado com sucesso (em
+algum ambiente) pela pessoa nomeada. Esta tag informa aos mantenedores que
+algum teste foi realizado, fornece um meio para localizar testadores para
+patches futuros e garante crédito para os testadores.
+
+Reviewed-by:, por sua vez, indica que o patch foi revisado e considerado
+aceitável de acordo com a Declaração do Revisor::
+
+ Declaração de supervisão do revisor
+
+ Ao oferecer minha tag Reviewed-by:, eu declaro que:
+
+ (a) Eu realizei uma revisão técnica deste patch para
+ avaliar sua adequação e prontidão para inclusão no
+ kernel mainline.
+
+ (b) Quaisquer problemas, preocupações ou perguntas relacionadas ao patch
+ foram comunicadas de volta ao remetente. Eu estou satisfeito
+ com a resposta do remetente aos meus comentários.
+
+ (c) Embora possa haver coisas que poderiam ser melhoradas com este
+ envio, eu acredito que é, neste momento, (1) uma
+ modificação que vale a pena para o kernel, e (2) livre de problemas
+ conhecidos que argumentariam contra sua inclusão.
+
+ (d) Embora eu tenha revisado o patch e acredite que seja sólido, eu
+ não faço (a menos que explicitamente declarado em outro lugar)
+ garantias de que alcançará seu propósito
+ declarado ou funcionará adequadamente em qualquer situação.
+
+Uma tag Reviewed-by é uma declaração de opinião de que o patch é uma
+modificação apropriada do kernel sem nenhum problema técnico sério
+restante. Qualquer revisor interessado (que tenha feito o trabalho e seja uma
+pessoa com identidade conhecida) pode oferecer uma tag Reviewed-by para um patch. Esta tag
+serve para dar crédito aos revisores e para informar os mantenedores do grau de
+revisão que foi feito no patch. Tags Reviewed-by:, quando fornecidas por
+revisores conhecidos por entender a área de assunto e realizar revisões completas,
+normalmente aumentarão a probabilidade de seu patch entrar no kernel.
+
+Ambas as tags Tested-by e Reviewed-by, uma vez recebidas na lista de discussão do testador
+ou revisor, devem ser adicionadas pelo autor aos patches aplicáveis ao enviar as
+próximas versões. No entanto, se o patch mudou substancialmente na versão
+seguinte, essas tags podem não ser mais aplicáveis e, portanto, devem ser removidas.
+Normalmente, a remoção das tags Acked-by, Tested-by ou Reviewed-by de alguém deve ser
+mencionada no changelog do patch com uma explicação (após o separador '---').
+
+Uma tag Suggested-by: indica que a ideia do patch foi sugerida pela pessoa
+nomeada e garante crédito à pessoa pela ideia: se creditarmos diligentemente
+nossos relatores de ideias, eles serão, com sorte, inspirados a nos ajudar novamente no
+futuro. Note que esta é uma de apenas três tags que você pode usar sem
+permissão explícita da pessoa nomeada (veja 'Marcar pessoas requer
+permissão' abaixo para detalhes).
+
+Uma tag Fixes: indica que o patch corrige um bug em um commit anterior. Ela
+é usada para facilitar a determinação de onde um problema se originou, o que pode ajudar
+na revisão da correção de um bug. Esta tag também auxilia a equipe do kernel estável a determinar
+quais versões do kernel estável devem receber sua correção. Este é o método preferido
+para indicar um bug corrigido pelo patch. Veja :ref:`pt_BR_describe_changes`
+para mais detalhes.
+
+Nota: Anexar uma tag Fixes: não subverte o processo de regras do kernel
+estável, nem o requisito de enviar em Cc: para stable@vger.kernel.org em todos os patches
+candidatos estáveis. Para mais informações, por favor, leia
+Documentation/process/stable-kernel-rules.rst.
+
+Por fim, embora fornecer tags seja bem-vindo e tipicamente muito apreciado, por favor
+note que os signatários (ou seja, remetentes e mantenedores) podem usar sua discrição ao
+aplicar as tags oferecidas.
+
+
+Marcar pessoas requer permissão
+-------------------------------
+
+Tenha cuidado ao adicionar as tags mencionadas acima aos seus patches, pois todas
+exceto Cc:, Reported-by: e Suggested-by: precisam de permissão explícita da
+pessoa nomeada. Para essas três, a permissão implícita é suficiente se a pessoa
+contribuiu para o kernel Linux usando esse nome e endereço de e-mail de acordo
+com os arquivos do lore ou o histórico de commits -- e no caso de Reported-by:
+e Suggested-by: tenha feito o relato ou sugestão em público. Note que o
+bugzilla.kernel.org é um local público nesse sentido, mas os endereços de e-mail
+usados lá são privados; portanto, não os exponha em tags, a menos que a pessoa
+os tenha usado em contribuições anteriores.
+
+Usando Assisted-by:
+-------------------
+
+Se você usou qualquer tipo de ferramenta avançada de codificação na criação do seu patch,
+você precisa reconhecer esse uso adicionando uma tag Assisted-by. A falha em
+fazer isso pode impedir a aceitação do seu trabalho. Por favor, veja
+Documentation/process/coding-assistants.rst para detalhes sobre o
+reconhecimento de assistentes de codificação.
+
+
+.. _pt_BR_the_canonical_patch_format:
+
+O formato canônico do patch
+---------------------------
+
+Esta seção descreve como o próprio patch deve ser formatado. Note
+que, se você tiver seus patches armazenados em um repositório ``git``, a formatação
+adequada do patch pode ser obtida com ``git format-patch``. As ferramentas não podem criar
+o texto necessário, no entanto, portanto, leia as instruções abaixo de qualquer maneira.
+
+Linha de Assunto
+^^^^^^^^^^^^^^^^
+
+A linha de assunto canônica do patch é::
+
+ Assunto: [PATCH 001/123] subsistema: frase de resumo
+
+O corpo canônico da mensagem do patch contém o seguinte:
+
+ - Uma linha ``from`` especificando o autor do patch, seguida por uma linha
+ vazia (necessário apenas se a pessoa enviando o patch não for o autor).
+
+ - O corpo da explicação, com quebra de linha em 75 colunas, que será
+ copiado para o changelog permanente para descrever este patch.
+
+ - Uma linha vazia.
+
+ - As linhas ``Signed-off-by:``, descritas acima, que também
+ irão para o changelog.
+
+ - Uma linha de marcador contendo simplesmente ``---``.
+
+ - Quaisquer comentários adicionais não adequados para o changelog.
+
+ - O próprio patch (saída do ``diff``).
+
+O formato da linha de Assunto torna muito fácil classificar os e-mails
+alfabeticamente pela linha de assunto - praticamente qualquer leitor de e-mail
+suportará isso - pois, como o número de sequência é preenchido com zeros,
+a classificação numérica e alfabética é a mesma.
+
+O ``subsystem`` no Assunto do e-mail deve identificar qual
+área ou subsistema do kernel está recebendo o patch.
+
+A ``frase de resumo`` no Assunto do e-mail deve descrever de forma concisa
+o patch que esse e-mail contém. A ``frase de resumo`` não deve ser um nome de arquivo.
+Não use a mesma ``frase de resumo`` para cada patch em uma série de patches inteira (onde uma ``série
+de patches`` é uma sequência ordenada de múltiplos patches relacionados).
+
+Tenha em mente que a ``frase de resumo`` do seu e-mail se torna um
+identificador globalmente único para aquele patch. Ela se propaga por todo o caminho
+até o changelog do ``git``. A ``frase de resumo`` pode ser usada posteriormente em
+discussões de desenvolvedores que se referem ao patch. As pessoas vão querer
+pesquisar no Google pela ``frase de resumo`` para ler a discussão sobre esse
+patch. Também será a única coisa que as pessoas poderão ver rapidamente
+quando, dois ou três meses depois, estiverem passando por talvez
+milhares de patches usando ferramentas como ``gitk`` ou ``git log
+--oneline``.
+
+Por essas razões, o ``resumo`` não deve ter mais de 70-75
+caracteres, e deve descrever tanto o que o patch altera, quanto
+por que o patch pode ser necessário. É um desafio ser
+sucinto e descritivo, mas é isso que um resumo bem escrito
+deve fazer.
+
+A ``frase de resumo`` pode ser prefixada por tags delimitadas por colchetes
+retos: "Assunto: [PATCH <tag>...] <frase de resumo>". As tags não
+são consideradas parte da frase de resumo, mas descrevem como o patch
+deve ser tratado. Tags comuns podem incluir um descritor de versão se
+as múltiplas versões do patch tiverem sido enviadas em resposta a
+comentários (ou seja, "v1, v2, v3"), ou "RFC" para indicar um pedido de
+comentários.
+
+Se houver quatro patches em uma série de patches, os patches individuais podem
+ser numerados assim: 1/4, 2/4, 3/4, 4/4. Isso garante que os desenvolvedores
+entendam a ordem na qual os patches devem ser aplicados e que
+eles tenham revisado ou aplicado todos os patches na série de patches.
+
+Aqui estão alguns bons exemplos de Assuntos::
+
+ Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
+ Subject: [PATCH v2 01/27] x86: fix eflags tracking
+ Subject: [PATCH v2] sub/sys: Condensed patch summary
+ Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary
+
+Linha From
+^^^^^^^^^^
+
+A linha ``from`` deve ser a primeira linha no corpo da mensagem,
+e tem a forma:
+
+ From: Patch Author <author@example.com>
+
+A linha ``from`` especifica quem será creditado como o autor do
+patch no changelog permanente. Se a linha ``from`` estiver faltando,
+então a linha ``From:`` do cabeçalho do e-mail será usada para determinar
+o autor do patch no changelog.
+
+O autor pode indicar sua afiliação ou o patrocinador do trabalho
+adicionando o nome de uma organização às linhas ``from`` e ``SoB``,
+por exemplo:
+
+ From: Patch Author (Company) <author@example.com>
+
+Corpo da Explicação
+^^^^^^^^^^^^^^^^^^^
+
+O corpo da explicação será commitado no changelog
+permanente da fonte, então deve fazer sentido para um leitor competente que já
+esqueceu há muito tempo os detalhes imediatos da discussão que podem ter levado a
+este patch. Incluir sintomas da falha que o patch aborda
+(mensagens de log do kernel, mensagens oops, etc.) é especialmente útil para
+pessoas que possam estar pesquisando nas mensagens de commit procurando pelo patch
+aplicável. O texto deve ser escrito com detalhes suficientes para que, quando lido
+semanas, meses ou até anos depois, possa dar ao leitor os detalhes
+necessários para compreender o raciocínio do **por que** o patch foi criado.
+
+Se um patch corrige uma falha de compilação, pode não ser necessário incluir
+_todas_ as falhas de compilação; apenas o suficiente para que seja provável que
+alguém pesquisando pelo patch possa encontrá-lo. Como na ``frase de resumo``,
+é importante ser tanto sucinto quanto descritivo.
+
+.. _pt_BR_backtraces:
+
+Backtraces em mensagens de commit
+"""""""""""""""""""""""""""""""""
+
+Backtraces ajudam a documentar a cadeia de chamadas que leva a um problema. No entanto,
+nem todos os backtraces são úteis. Por exemplo, as cadeias de chamadas iniciais de boot são
+únicas e óbvias. Copiar a saída dmesg completa verbatim, no entanto,
+adiciona informações que distraem, como timestamps, listas de módulos, dumps de
+registradores e pilhas.
+
+Portanto, os backtraces mais úteis devem destilar as informações
+relevantes do dump, o que facilita o foco no problema
+real. Aqui está um exemplo de um backtrace bem aparado::
+
+ unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
+ at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
+ Call Trace:
+ mba_wrmsr
+ update_domains
+ rdtgroup_mkdir
+
+Comentários
+^^^^^^^^^^^
+
+A linha marcadora ``---`` serve ao propósito essencial de marcar para
+as ferramentas de manipulação de patches onde a mensagem do changelog termina.
+
+Um bom uso para os comentários adicionais após o marcador ``---`` é
+para um ``diffstat``, para mostrar quais arquivos mudaram, e o número de
+linhas inseridas e excluídas por arquivo. Um ``diffstat`` é especialmente útil
+em patches maiores. Se você for incluir um ``diffstat`` após o
+marcador ``---``, por favor, use as opções do ``diffstat`` ``-p 1 -w 70`` para que
+os nomes dos arquivos sejam listados a partir do topo da árvore de código-fonte do kernel e não
+usem muito espaço horizontal (cabem facilmente em 80 colunas, talvez com algum
+recuo). (o ``git`` gera diffstats apropriados por padrão.)
+
+Outros comentários relevantes apenas para o momento ou para o mantenedor, não
+adequados para o changelog permanente, também devem ir aqui. Um bom
+exemplo de tais comentários podem ser ``changelogs do patch`` que descrevem
+o que mudou entre as versões v1 e v2 do patch.
+
+Por favor, coloque esta informação **após** a linha ``---`` que separa
+o changelog do restante do patch. A informação da versão não
+faz parte do changelog que é commitado na árvore git. É
+informação adicional para os revisores. Se for colocada acima das
+tags de commit, precisará de interação manual para removê-la. Se estiver abaixo
+da linha separadora, ela é automaticamente removida ao aplicar o
+patch. Se disponíveis, adicionar links para as versões anteriores do patch (por exemplo,
+link do arquivo lore.kernel.org) é recomendado para ajudar os revisores::
+
+ <commit message>
+ ...
+ Signed-off-by: Author <author@mail>
+ ---
+ V2 -> V3: Removed redundant helper function
+ V1 -> V2: Cleaned up coding style and addressed review comments
+
+ v2: https://lore.kernel.org/bar
+ v1: https://lore.kernel.org/foo
+
+ path/to/file | 5+++--
+ ...
+
+Veja mais detalhes sobre o formato de patch adequado nas seguintes
+referências.
+
+
+Cabeçalhos In-Reply-To explícitos
+---------------------------------
+
+Pode ser útil adicionar manualmente cabeçalhos In-Reply-To: a um patch
+(por exemplo, ao usar ``git send-email``) para associar o patch com
+discussões relevantes anteriores, por exemplo, para vincular uma correção de bug ao e-mail com
+o relatório do bug. No entanto, para uma série de múltiplos patches, geralmente é
+melhor evitar usar In-Reply-To: para vincular a versões mais antigas da
+série. Desta forma, múltiplas versões do patch não se tornam uma
+floresta incontrolável de referências nos clientes de e-mail. Se um link for
+útil, você pode usar o redirecionador https://lore.kernel.org/ (por exemplo, no
+texto do e-mail de capa) para vincular a uma versão anterior da série de patches.
+
+
+Informações sobre a árvore base
+-------------------------------
+
+Quando outros desenvolvedores recebem seus patches e iniciam o processo de revisão,
+é absolutamente necessário que eles saibam qual é o commit/branch
+base no qual seu trabalho se aplica, considerando a enorme quantidade de
+árvores de mantenedores presentes hoje em dia. Note novamente a entrada **T:** no
+arquivo MAINTAINERS explicado acima.
+
+Isso é ainda mais importante para processos automatizados de CI que tentam
+executar uma série de testes a fim de estabelecer a qualidade da sua
+submissão antes que o mantenedor inicie a revisão.
+
+Se você estiver usando ``git format-patch`` para gerar seus patches, você pode
+incluir automaticamente as informações da árvore base em sua submissão ao
+usar a flag ``--base``. A maneira mais fácil e conveniente de usar
+esta opção é com branches de tópicos (topical branches)::
+
+ $ git checkout -t -b my-topical-branch master
+ Branch 'my-topical-branch' set up to track local branch 'master'.
+ Switched to a new branch 'my-topical-branch'
+
+ [perform your edits and commits]
+
+ $ git format-patch --base=auto --cover-letter -o outgoing/ master
+ outgoing/0000-cover-letter.patch
+ outgoing/0001-First-Commit.patch
+ outgoing/...
+
+Quando você abrir ``outgoing/0000-cover-letter.patch`` para edição, você
+notará que ele terá o trailer ``base-commit:`` bem no
+final, o qual fornece ao revisor e às ferramentas de CI informações suficientes
+para realizar o ``git am`` adequadamente sem se preocupar com conflitos::
+
+ $ git checkout -b patch-review [base-commit-id]
+ Switched to a new branch 'patch-review'
+ $ git am patches.mbox
+ Applying: First Commit
+ Applying: ...
+
+Por favor, veja ``man git-format-patch`` para mais informações sobre esta
+opção.
+
+.. note::
+
+ A funcionalidade ``--base`` foi introduzida no git versão 2.9.0.
+
+Se você não estiver usando git para formatar seus patches, você ainda pode incluir
+o mesmo trailer ``base-commit`` para indicar o hash do commit da árvore
+na qual seu trabalho se baseia. Você deve adicioná-lo na cover
+letter (carta de apresentação) ou no primeiro patch da série e ele deve ser colocado
+abaixo da linha ``---`` ou bem no final de todo o outro
+conteúdo, logo antes da sua assinatura de e-mail.
+
+Certifique-se de que o commit base está em uma árvore oficial de mantenedor/mainline
+e não em alguma árvore interna acessível apenas por você - caso contrário seria
+inútil.
+
+Ferramentas
+-----------
+
+Muitos dos aspectos técnicos deste processo podem ser automatizados usando
+b4, documentado em <https://b4.docs.kernel.org/en/latest/>. Isso pode
+ajudar com coisas como rastreamento de dependências, execução do checkpatch e
+com a formatação e o envio de e-mails.
+
+Referências
+-----------
+
+Andrew Morton, "The perfect patch" (tpp).
+ <https://www.ozlabs.org/~akpm/stuff/tpp.txt>
+
+Jeff Garzik, "Linux kernel patch submission format".
+ <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
+
+Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
+ <http://www.kroah.com/log/linux/maintainer.html>
+
+ <http://www.kroah.com/log/linux/maintainer-02.html>
+
+ <http://www.kroah.com/log/linux/maintainer-03.html>
+
+ <http://www.kroah.com/log/linux/maintainer-04.html>
+
+ <http://www.kroah.com/log/linux/maintainer-05.html>
+
+ <http://www.kroah.com/log/linux/maintainer-06.html>
+
+Kernel Documentation/process/coding-style.rst
+
+Linus Torvalds's mail on the canonical patch format:
+ <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
+
+Andi Kleen, "On submitting kernel patches"
+ Some strategies to get difficult or controversial changes in.
+
+ http://halobates.de/on-submitting-patches.pdf
--
2.47.3
^ permalink raw reply related [flat|nested] 5+ messages in thread