Skip to contentSkip to conversation

docs: pt_BR: Reorganize index.rst to avoid merge conflicts

PATCH In review Daniel Pereira 2 participants 3 messages Jul 27 – Aug 3

Subsystems (2)
lore
Share & tools
lore

Daniel Pereira

author maintainer
#0 lore raw

PATCH 1/1 docs: pt_BR: Reorganize index.rst to avoid merge conflicts

The main index.rst file for the pt_BR translation was grouping all translated documents directly in its toctree. Because many contributors are submitting translations simultaneously to the same file, it has become a bottleneck, causing frequent merge conflicts.

To solve this issue and improve maintainability, this patch refactors the structure to follow the pattern used by the base English documentation. Specifically, a new index.rst was created inside the process/ directory to handle all future contributions and document additions targeting that specific directory.

The root index.rst now simply references process/index.rst. This modular organization keeps the main tree clean and significantly reduces patch collisions.

---
 Documentation/translations/pt_BR/index.rst    | 28 +--------------
 .../translations/pt_BR/process/index.rst      | 34 +++++++++++++++++++
 2 files changed, 35 insertions(+), 27 deletions(-)
 create mode 100644 Documentation/translations/pt_BR/process/index.rst
Documentation/translations/pt_BR/index.rst +1 -27
index 232d18f7c..e868544d1 100644
@@ -1,7 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-
-
 =========================================
 Documentação do Kernel Linux em Português
 =========================================
@@ -22,8 +20,6 @@ na reorganização da documentação de forma mais coerente. Melhorias na
 documentação são sempre bem-vindas; se você deseja ajudar, inscreva-se na lista
 de discussão linux-doc em vger.kernel.org.
 
-
-
 Avisos
 ======
 
@@ -66,26 +62,4 @@ kernel e sobre como ver seu trabalho integrado.
 .. toctree::
    :maxdepth: 1
 
-   Introdução <process/1.Intro>
-   Guia do Processo de Desenvolvimento <process/development-process>
-   Como aplicar patches <process/applying-patches>
-   Backporting e resolução de conflitos <process/backporting>
-   Como não Deixar as ioctls malfeitas <process/botching-up-ioctls>
-   Index de documentos do Kernel <process/kernel-docs>
-   Regras de licenciamento <process/license-rules>
-   Como começar <process/howto>
-   Requisitos mínimos <process/changes>
-   Conclave (Continuidade do projeto) <process/conclave>
-   Modelos de Maturidade para Contribuição no Kernel Linux <process/contribution-maturity-model.rst>
-   Manuais dos mantenedores <process/maintainer-handbooks>
-   Processo do subsistema de rede (netdev) <process/maintainer-netdev>
-   Processo do subsistema SoC <process/maintainer-soc>
-   Conformidade de DTS para SoC <process/maintainer-soc-clean-dts>
-   Processo do subsistema KVM x86 <process/maintainer-kvm-x86>
-   Adicionando uma nova chamada de Sistema <process/adding-syscalls>
-   Declaração sobre Drivers do Kernel <process/kernel-driver-statement>
-   Lista de verificação para submissão de patches do kernel Linux <process/submit-checklist>
-   Interpretação do Código de Conduta do Kernel Linux <process/code-of-conduct-interpretation>
-   Código de Conduta de Compromisso do Colaborador <process/code-of-conduct>
-   Interfaces, recursos de linguagem, atributos e convenções obsoletos <process/deprecated>
-
+   Todos os documentos do processo de desenvolvimento <process/index>
Documentation/translations/pt_BR/process/index.rst new file +34 -0
new file mode 100644
index 000000000..b3518fe72
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================================
+Trabalhando com a comunidade de desenvolvimento
+================================================
+
+As guias fundamentais para a interação com a comunidade de desenvolvimento do
+kernel e sobre como ver seu trabalho integrado.
+
+.. toctree::
+   :maxdepth: 1
+
+   Introdução <1.Intro>
+   Guia do Processo de Desenvolvimento <development-process>
+   Como aplicar patches <applying-patches>
+   Backporting e resolução de conflitos <backporting>
+   Como não Deixar as ioctls malfeitas <botching-up-ioctls>
+   Index de documentos do Kernel <kernel-docs>
+   Regras de licenciamento <license-rules>
+   Como começar <howto>
+   Requisitos mínimos <changes>
+   Conclave (Continuidade do projeto) <conclave>
+   Modelos de Maturidade para Contribuição no Kernel Linux <contribution-maturity-model>
+   Manuais dos mantenedores <maintainer-handbooks>
+   Processo do subsistema de rede (netdev) <maintainer-netdev>
+   Processo do subsistema SoC <maintainer-soc>
+   Conformidade de DTS para SoC <maintainer-soc-clean-dts>
+   Processo do subsistema KVM x86 <maintainer-kvm-x86>
+   Adicionando uma nova chamada de Sistema <adding-syscalls>
+   Declaração sobre Drivers do Kernel <kernel-driver-statement>
+   Lista de verificação para submissão de patches do kernel Linux <submit-checklist>
+   Interpretação do Código de Conduta do Kernel Linux <code-of-conduct-interpretation>
+   Código de Conduta de Compromisso do Colaborador <code-of-conduct>
+   Interfaces, recursos de linguagem, atributos e convenções obsoletos <deprecated>
Signature · 1 line
2.52.0
maintainer
#1 lore raw
Quoted 15 lines · Daniel Pereira

The main index.rst file for the pt_BR translation was grouping all translated documents directly in its toctree. Because many contributors are submitting translations simultaneously to the same file, it has become a bottleneck, causing frequent merge conflicts.

To solve this issue and improve maintainability, this patch refactors the structure to follow the pattern used by the base English documentation. Specifically, a new index.rst was created inside the process/ directory to handle all future contributions and document additions targeting that specific directory.

The root index.rst now simply references process/index.rst. This modular organization keeps the main tree clean and significantly reduces patch collisions.

Quoted 6 lines
---
 Documentation/translations/pt_BR/index.rst    | 28 +--------------
 .../translations/pt_BR/process/index.rst      | 34 +++++++++++++++++++
 2 files changed, 35 insertions(+), 27 deletions(-)
 create mode 100644 Documentation/translations/pt_BR/process/index.rst

This is a step in the right direction but... having everybody just append TOC entries to a different file will not change the overall situation. It would be far better to translate Documentation/process/index.rst, with its subsection structure, to avoid that "everybody appends and conflicts" behavior.

This patch, of course, also conflicts badly with the various other translations that you have acked.

Here is my suggestion: I'll apply the outstanding Portuguese translation patches today, then say "no more" for 7.3. You can then create a new index.rst that is current with all of the done translations; we can apply that either before or after the merge window. Everybody doing translation patches can then work against that new index.rst file and, hopefully, life will get smoother.

Does that work for you?

Thanks,

jon

author maintainer
#2 lore raw

Em seg., 3 de ago. de 2026 às 15:29, Jonathan Corbet <[email protected]> escreveu:

Quoted 11 lines

Here is my suggestion: I'll apply the outstanding Portuguese translation patches today, then say "no more" for 7.3. You can then create a new index.rst that is current with all of the done translations; we can apply that either before or after the merge window. Everybody doing translation patches can then work against that new index.rst file and, hopefully, life will get smoother.

Does that work for you?

Hi Jon,

You are absolutely right. I agree that just moving the entries won't solve the long-term conflict issues.

Please discard this patch. I will wait for you to apply the outstanding translation patches, and once those are in, I will prepare a new index.rst structure as you suggested.

Thanks for the guidance,

Daniel