* [PATCH 0/4] docs: pt_BR: process: Add remaining core process translations
@ 2026-09-09 12:48 Daniel Pereira
2026-09-09 12:48 ` [PATCH 1/4] docs: pt_BR: translate coding-style.rst Daniel Pereira
` (4 more replies)
0 siblings, 5 replies; 6+ messages in thread
From: Daniel Pereira @ 2026-09-09 12:48 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
This patch series introduces new Portuguese (pt_BR) translations for core kernel process documentation files.
Changes included in this series:
- New translations for coding-style.rst, kernel-enforcement-statement.rst, maintainer-tip.rst, and submitting-patches.rst.
- Meticulous alignment of all section underlines in coding-style.rst to match the title lengths precisely, preventing Sphinx compilation warnings.
- Thorough localization of internal cross-references across these documents. We applied the `pt_BR_` prefix to anchors such as `pt_BR_describe_changes`, `pt_BR_backtraces`, `pt_BR_resend_reminders`, `pt_BR_split_changes`, `pt_BR_the_canonical_patch_format`, `pt_BR_interleaved_replies`, and `pt_BR_maintainer-tip-coding-style`. This prevents "duplicate label" warnings during global Sphinx builds.
- Cleaned up orphan labels (`tagging_people` and `explicit_in_reply_to`) that were completely unused internally to streamline the documentation.
- Improved readability of translated technical terms (e.g., using "comentários no fim da linha" instead of literal "comentários de cauda").
The entire series has been validated with checkpatch.pl and successfully passes `make htmldocs` without syntax errors or broken internal cross-references.
Daniel Pereira (4):
docs: pt_BR: translate coding-style.rst
docs: pt_BR: translate kernel-enforcement-statement.rst
docs: pt_BR: translate maintainer-tip.rst
docs: pt_BR: translate submitting-patches.rst
.../translations/pt_BR/process/2.Process.rst | 2 +-
.../pt_BR/process/coding-style.rst | 1318 +++++++++++++++++
.../translations/pt_BR/process/index.rst | 4 +
.../process/kernel-enforcement-statement.rst | 163 ++
.../pt_BR/process/maintainer-kvm-x86.rst | 6 +-
.../pt_BR/process/maintainer-tip.rst | 847 +++++++++++
.../pt_BR/process/submitting-patches.rst | 961 ++++++++++++
7 files changed, 3297 insertions(+), 4 deletions(-)
create mode 100644 Documentation/translations/pt_BR/process/coding-style.rst
create mode 100644 Documentation/translations/pt_BR/process/kernel-enforcement-statement.rst
create mode 100644 Documentation/translations/pt_BR/process/maintainer-tip.rst
create mode 100644 Documentation/translations/pt_BR/process/submitting-patches.rst
--
2.47.3
^ permalink raw reply [flat|nested] 6+ messages in thread
* [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
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ 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] 6+ 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
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ 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] 6+ 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
2026-09-15 19:13 ` [PATCH 0/4] docs: pt_BR: process: Add remaining core process translations Jonathan Corbet
4 siblings, 0 replies; 6+ 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] 6+ 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
2026-09-15 19:13 ` [PATCH 0/4] docs: pt_BR: process: Add remaining core process translations Jonathan Corbet
4 siblings, 0 replies; 6+ 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] 6+ messages in thread
* Re: [PATCH 0/4] docs: pt_BR: process: Add remaining core process translations
2026-09-09 12:48 [PATCH 0/4] docs: pt_BR: process: Add remaining core process translations Daniel Pereira
` (3 preceding siblings ...)
2026-09-09 12:48 ` [PATCH 4/4] docs: pt_BR: translate submitting-patches.rst Daniel Pereira
@ 2026-09-15 19:13 ` Jonathan Corbet
4 siblings, 0 replies; 6+ messages in thread
From: Jonathan Corbet @ 2026-09-15 19:13 UTC (permalink / raw)
To: Daniel Pereira; +Cc: linux-doc, Daniel Pereira
Daniel Pereira <danielmaraboo@gmail.com> writes:
> This patch series introduces new Portuguese (pt_BR) translations for core kernel process documentation files.
>
> Changes included in this series:
> - New translations for coding-style.rst, kernel-enforcement-statement.rst, maintainer-tip.rst, and submitting-patches.rst.
> - Meticulous alignment of all section underlines in coding-style.rst to match the title lengths precisely, preventing Sphinx compilation warnings.
> - Thorough localization of internal cross-references across these documents. We applied the `pt_BR_` prefix to anchors such as `pt_BR_describe_changes`, `pt_BR_backtraces`, `pt_BR_resend_reminders`, `pt_BR_split_changes`, `pt_BR_the_canonical_patch_format`, `pt_BR_interleaved_replies`, and `pt_BR_maintainer-tip-coding-style`. This prevents "duplicate label" warnings during global Sphinx builds.
> - Cleaned up orphan labels (`tagging_people` and `explicit_in_reply_to`) that were completely unused internally to streamline the documentation.
> - Improved readability of translated technical terms (e.g., using "comentários no fim da linha" instead of literal "comentários de cauda").
>
> The entire series has been validated with checkpatch.pl and successfully passes `make htmldocs` without syntax errors or broken internal cross-references.
For future reference, please try to keep the cover-letter text within 80
columns as well.
> Daniel Pereira (4):
> docs: pt_BR: translate coding-style.rst
> docs: pt_BR: translate kernel-enforcement-statement.rst
> docs: pt_BR: translate maintainer-tip.rst
> docs: pt_BR: translate submitting-patches.rst
>
> .../translations/pt_BR/process/2.Process.rst | 2 +-
> .../pt_BR/process/coding-style.rst | 1318 +++++++++++++++++
> .../translations/pt_BR/process/index.rst | 4 +
> .../process/kernel-enforcement-statement.rst | 163 ++
> .../pt_BR/process/maintainer-kvm-x86.rst | 6 +-
> .../pt_BR/process/maintainer-tip.rst | 847 +++++++++++
> .../pt_BR/process/submitting-patches.rst | 961 ++++++++++++
> 7 files changed, 3297 insertions(+), 4 deletions(-)
> create mode 100644 Documentation/translations/pt_BR/process/coding-style.rst
> create mode 100644 Documentation/translations/pt_BR/process/kernel-enforcement-statement.rst
> create mode 100644 Documentation/translations/pt_BR/process/maintainer-tip.rst
> create mode 100644 Documentation/translations/pt_BR/process/submitting-patches.rst
Series applied, thanks.
jon
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2026-09-15 19:13 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
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 ` [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
2026-09-15 19:13 ` [PATCH 0/4] docs: pt_BR: process: Add remaining core process translations Jonathan Corbet
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.