Pré-requisitos

É preciso instalar algumas dependências para conseguir contribuir:

Debian:

sudo apt update

sudo apt install \
  git \
  git-email \
  perl \
  make \
  python3

sudo apt install \
  python3-pip \
  python3-venv

Fedora:

sudo dnf install \
  git \
  git-email \
  perl \
  make \
  python3

sudo dnf install \
  python3-pip

Verifique:

git --version
git send-email --help
perl --version
python3 --version

Primeiro passo: preparar o ambiente

Verificar instalação:

git send-email --help

Configure a sua identidade:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Configurando SMTP:

git config --global sendemail.smtpserver smtp.gmail.com
git config --global sendemail.smtpserverport 587
git config --global sendemail.smtpencryption tls
git config --global sendemail.smtpuser seuemail@gmail.com

Pode-se adicionar:

git config --global sendemail.assume8bitEncoding UTF-8

Isso evitará que todas as vezes seja perguntado sobre o encoding em patches com acento, etc.

Verifique:

cat ~/.gitconfig

Você deve ter algo assim:

[user]
    email = seuemail@gmail.com
    name = seu nome
[sendemail]
    smtpServer = smtp.gmail.com
    smtpServerPort = 587
    smtpEncryption = tls
    smtpUser = seuemail@gmail.com

Essa parte é muito importante, pois é por meio do email que iremos enviar os nossos patches.

Gerando senha de app (Gmail)

Para autenticar no Gmail, uma opção simples é utilizar uma senha de app. Para gerá-la, a conta Google deve estar com a verificação em duas etapas ativada. OAuth2 também pode ser utilizado.

support.google.com/mail/answer/185833

A senha de app será utilizada pelo git send-email na autenticação SMTP quando solicitada.

Clonando

Com a configuração acima realizada, podemos realizar o clone do kernel para começar a tradução:

git clone \
  --branch docs-next \
  --single-branch \
  git://git.lwn.net/linux.git \
  linux-docs

O --single-branch limita o clone à branch docs-next, evitando buscar as demais branches do repositório.

cd linux-docs/

git switch -c nomeDaSuaBranch

Após criar sua branch de trabalho, edite apenas os arquivos necessários para a contribuição, por exemplo:

Documentation/translations/pt_BR/process/index.rst
Documentation/translations/pt_BR/process/volatile-considered-harmful.rst

Pós clone

Crie um ambiente virtual Python na raiz do kernel (usado apenas para gerar a documentação em HTML com Sphinx):

python3 -m venv .venv-sphinx
source .venv-sphinx/bin/activate
python -m pip install --upgrade pip

Instalar dependências faltantes:

pip install -r Documentation/sphinx/requirements.txt
pip install ply

Pós tradução

Revise as alterações realizadas:

git diff

Revise se há problemas como espaço em branco:

git diff --check

O comando git diff --check não deve retornar nenhuma mensagem.

Adicione somente os arquivos modificados que fazem parte do patch:

git add \
  Documentation/translations/pt_BR/process/index.rst \
  Documentation/translations/pt_BR/process/volatile-considered-harmful.rst

Evite usar git add .

Revisar conteúdo em staging:

git diff --cached
git diff --cached --check

Criar commit:

git commit -s

Revisar:

git show HEAD
git show --check HEAD

O summary deve ser curto e descritivo, com aproximadamente 70–75 caracteres no máximo. O corpo da mensagem deve ser quebrado em aproximadamente 75 colunas.

docs: translations: pt_BR: translate volatile-considered-harmful.rst

Translate volatile-considered-harmful.rst into Brazilian Portuguese and
add it to the pt_BR process documentation index.

Assisted-by: LLM
Signed-off-by: Seu Nome <seu-email@example.com>

Essa primeira linha será o subject do email.

Para validar ou corrigir a mensagem:

git commit --amend

Verificando:

git log -1 --format=full

Testando a documentação

make htmldocs

Opcionalmente:

make pdfdocs

Criando patch

rm -rf /tmp/volatile-patch
mkdir -p /tmp/volatile-patch

git format-patch -1 HEAD -o /tmp/volatile-patch

Isso criaria algo assim:

/tmp/volatile-patch/0001-docs-translations-pt_BR-translate-volatile-considere.patch

Lendo seu patch (antes de enviar):

cat /tmp/volatile-patch/0001-*.patch

# ou
git format-patch -1 HEAD --stdout | less

Rode o script sobre o patch que será enviado:

./scripts/checkpatch.pl --strict \
  /tmp/volatile-patch/0001-*.patch

Se preparando para envio do patch

Descobrindo os destinatários:

./scripts/get_maintainer.pl \
  /tmp/volatile-patch/0001-*.patch

Exemplo:

Daniel Pereira (maintainer:PORTUGUESE (BRAZILIAN) TRANSLATION)
Jonathan Corbet (maintainer:DOCUMENTATION)
Shuah Khan (reviewer:DOCUMENTATION)
Randy Dunlap (reviewer:DOCUMENTATION)
linux-doc@vger.kernel.org (open list)
linux-kernel@vger.kernel.org (open list)

O script pode retornar mais pessoas do que as que é preciso; para isso, priorize o envio para:
1. mantenedor específico;
2. mantenedores do subsistema;
3. reviewers indicados;
4. mailing lists relevantes.

Normalmente:
— mantenedores diretamente responsáveis vão em To;
— reviewers e demais interessados vão em Cc;
— as mailing lists relevantes também devem ser incluídas.

Não envie para pessoas ou listas sem relação com o patch.

Testando o envio:

git send-email \
  --dry-run \
  --confirm=always \
  --to="Daniel Pereira <danielmaraboo@gmail.com>" \
  --to="Jonathan Corbet <corbet@lwn.net>" \
  --cc="Shuah Khan <skhan@linuxfoundation.org>" \
  --cc="Randy Dunlap <rdunlap@infradead.org>" \
  --cc="linux-doc@vger.kernel.org" \
  --cc="linux-kernel@vger.kernel.org" \
  --cc="Seu Nome <seu-email@example.com>" \
  /tmp/volatile-patch/0001-*.patch

No dry-run nenhum email é enviado; o que esperamos com esse teste é um retorno Result: OK. Também confira:

From:
To:
Cc:
Subject:

Pode aparecer:

The following files are 8bit, but do not declare a Content-Transfer-Encoding.

Declare which 8bit encoding to use [default: UTF-8]?

Caso sendemail.assume8bitEncoding não esteja configurado, o Git pode solicitar o encoding ao encontrar caracteres não ASCII. Nesse caso, pressione ENTER para aceitar o padrão UTF-8.

Envio real!!

git send-email \
  --confirm=always \
  --to="Daniel Pereira <danielmaraboo@gmail.com>" \
  --to="Jonathan Corbet <corbet@lwn.net>" \
  --cc="Shuah Khan <skhan@linuxfoundation.org>" \
  --cc="Randy Dunlap <rdunlap@infradead.org>" \
  --cc="linux-doc@vger.kernel.org" \
  --cc="linux-kernel@vger.kernel.org" \
  --cc="Seu Nome <seu-email@example.com>" \
  /tmp/volatile-patch/0001-*.patch

Quando aparecer:

Send this email? ([y]es|[n]o|[e]dit|[q]uit|[a]ll):

Confira:

To
Cc
Subject

Estando correto: y

Um envio bem-sucedido retorna: Result: 250

Detalhes

1. Salve o message-ID:

<20260830205912.478358-1-lucasadramalho@gmail.com>

Isso será importante para você conseguir acompanhar pela lore.kernel.org e referenciar patches antigos em V2, V3 etc. Exemplo de como o link ficaria:

https://lore.kernel.org/all/20260830205912.478358-1-lucasadramalho@gmail.com/

Importante notar que o corpo deve ser quebrado em aproximadamente 75 colunas.

---

Enviando V != 1

Não é preciso criar um novo commit para revisões simples do mesmo patch:

git add arquivo

git commit --amend

Caso alguém responda com Reviewed-by, preserve os trailers:

Assisted-by: ...
Reviewed-by: Reviewer <reviewer@example.com>
Signed-off-by: Seu Nome <seu-email@example.com>

OBS.: Se uma nova versão alterar substancialmente o patch, trailers como Reviewed-by:, Tested-by: e Acked-by: podem deixar de ser aplicáveis. Remova os trailers cuja revisão, teste ou aprovação tenha sido invalidada e mencione a remoção no changelog da nova versão.

Gerando V2

rm -rf /tmp/volatile-v2
mkdir -p /tmp/volatile-v2

git format-patch \
  -v2 \
  -1 HEAD \
  -o /tmp/volatile-v2

Adicionando changelog

vim /tmp/volatile-v2/v2-0001-*.patch

Procure por:

Signed-off-by: ...
---
 diffstat...

Adicione depois dos ---:

---
Changes in v2:
- Address review comments from Reviewer Name.
- Fix terminology in the translated text.
- Fix indentation in the process index.

v1: https://lore.kernel.org/r/MESSAGE-ID-DA-V1

O conteúdo após --- não faz parte do commit final aplicado. Isso garante que não entre no histórico de commits, poluindo-o sem necessidade.

Changelog não pertence ao commit.

---

Extras

Verificando atualização da tradução

Para verificar se a tradução está sincronizada com sua versão original:

tools/docs/checktransupdate.py \
  Documentation/translations/pt_BR/process/volatile-considered-harmful.rst

---

Checklist V1

[ ] branch criada a partir da árvore correta
[ ] alterações revisadas
[ ] git diff --check
[ ] make htmldocs
[ ] checktransupdate.py, quando aplicável
[ ] git add somente dos arquivos corretos
[ ] git diff --cached
[ ] git diff --cached --check
[ ] git commit -s
[ ] Signed-off-by presente
[ ] git show --check HEAD
[ ] git format-patch
[ ] patch revisado com less/cat
[ ] checkpatch.pl --strict
[ ] get_maintainer.pl
[ ] To e Cc revisados
[ ] git send-email --dry-run
[ ] Subject revisado
[ ] encoding UTF-8 correto
[ ] Result: OK no dry-run
[ ] envio real
[ ] Result: 250
[ ] Message-ID salvo
[ ] link do lore salvo

Checklist V != 1

[ ] review lido
[ ] alterações feitas
[ ] trailers recebidos adicionados
[ ] git commit --amend
[ ] testes repetidos
[ ] git format-patch -vN
[ ] Changes in vN adicionado após ---
[ ] Link to vN-1 adicionado
[ ] checkpatch.pl
[ ] dry-run
[ ] envio real
[ ] novo Message-ID salvo

---