Host translations in gitbook, using monorepo approach (InnerSourceCommons#578)

spier · rmarting · commit 6728ecaa3299 · 2024-02-29T10:52:36.000+01:00
* Remove the main gitbook yaml file. Need to be sure that config is picked up from subfolders.
* Change config of the en book
* Change config of the ja book
* Change config of the zh book
* Generate the TOCs for all books in a GHA matrix build
* Change commit messsage in book.yaml workflow run to make clear which file was changed and why
* Improve documentation
diff --git a/.gitbook.yaml b/.gitbook.yaml
diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml
@@ -3,13 +3,19 @@ name: Gitbook Generation
 on:
   push:
     branches:
-      - "main"
-      - "book-*"
+      - main
+  pull_request:
+    branches:
+      - main
 
 jobs:
   gitbook-generation:
     runs-on: ubuntu-latest
 
+    strategy:
+      matrix:
+        language: [en, ja, zh]
+
     steps:
     - uses: actions/checkout@v3
       with:
@@ -21,22 +27,13 @@ jobs:
         working-directory: 'book/scripts/'
         bundler-cache: true
 
-    - name: Determine book language
-      run: |
-        [[ "$GITHUB_REF_NAME" =~ ^book-.*$ ]] && book_language=${GITHUB_REF_NAME:5:2} || book_language="en"
-        echo "BOOK_LANGUAGE=$book_language" >> $GITHUB_ENV
-
     - name: Generate ToC
       run: |
         cd book/scripts/
-        ruby generate_toc.rb $BOOK_LANGUAGE 
-        echo "Generated book for: $BOOK_LANGUAGE" >> $GITHUB_STEP_SUMMARY
-
-    - name: Copy .gitbook.yml to root
-      run: |
-        cp book/$BOOK_LANGUAGE/.gitbook.yaml .
+        ruby generate_toc.rb ${{ matrix.language }} 
+        echo "Generated book for: ${{ matrix.language }}" >> $GITHUB_STEP_SUMMARY
 
-    - name: Commit updated files for the book
+    - name: Commit updated toc.md for the book
       uses: stefanzweifel/git-auto-commit-action@v4
       with:
-        commit_message: Writing updated files for the book
+        commit_message: Writing updated toc.md for the ${{ matrix.language }} book
diff --git a/book/README.md b/book/README.md
@@ -20,9 +20,9 @@ We use the [gitbook.com](https://www.gitbook.com) service to host our book.
 
 The `/book` folder contains generator scripts and extra content required to create the gitbook.
 
-- `.github/workflows/book.yml` - A GitHub Action that triggers scripts to generate the book.
-- `/book/scripts/generate_toc.rb` - Generates the table of contents (ToC) for the book. It takes patterns of maturity **Structured** and **Validated**, extracts title and patlet, and injects this info into `/book/en/toc_template.md`. The output is written to `/book/en/toc.md`. The ToC is what you see on the left-hand-side menu in the gitbook.
-- `/book/en/.gitbook.yaml` - Holds basic configuration for the gitbook service. This file is copied to the root of the repo, if the English book is generated.
+- `.github/workflows/book.yml` - A GitHub Action that triggers `generate_toc.rb`.
+- `/book/scripts/generate_toc.rb` - Generates the table of contents (ToC) for the book. It takes patterns of maturity **Structured** and **Validated**, extracts title and patlet, and injects this info into `/book/en/toc_template.md`. The output is written to `/book/en/toc.md`. The ToC is what you see in the menu on the left in the gitbook.
+- `/book/en/.gitbook.yaml` - Holds basic configuration for the gitbook service.
 - `/book/en/introduction.md` - The introduction to our book. This is what the reader sees first when they open the book. *Note:* The current content is based on [README.md](../README.md).
 - `/book/en/contribute.md` - Explains how to contribute to this book.
 - `/book/en/explore-patterns.md` - Shows the mind map of all patterns. Allows readers to link to the mind map directly.
@@ -42,10 +42,13 @@ For more on the translation process see [these translation instructions](../tran
 
 The book is generated in multiple languages.
 
-Depending on which **branch** a change is merged into, a different book is generated:
+gitbook takes care of the markdown to HTML rendering for us.
+To do so, we need to provide a full list of all patterns that should be dipslayed in the book.
 
-* changes merged to `main` branch: triggers the book generation for the **English** book.
-* changes merged to `book-<YOUR_LANGUAGE>`[^1] branch: triggers the book generation for the book in the given language e.g. `book-jp` for the **Japanese** book.
+As the list of patterns grows over time, we generate the list automatically using `/book/scripts/generate_toc.rb`.
+The script is triggered by the [.github/workflows/book.yml](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/.github/workflows/book.yml) workflow, which contains a hard-coded list of all languages for which we need to generate `toc.md` files.
+
+If a new language is added, you need to modify [this line](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/monorepo-test/.github/workflows/book.yml#L17) in `.github/workflows/book.yml` and add the 2-letter language code of the language that you are adding.
 
 ## Objectives of the book
 
diff --git a/book/en/.gitbook.yaml b/book/en/.gitbook.yaml
@@ -1,5 +1,5 @@
 root : ./
 
 structure:
-  readme: book/en/introduction.md
-  summary: book/en/toc.md
+  readme: introduction.md
+  summary: toc.md
diff --git a/book/en/introduction.md b/book/en/introduction.md
@@ -3,8 +3,8 @@
 ![InnerSource Patterns book](innersource-patterns-book-cover.jpg)
 
 {% hint style="info" %}
-You are reading an early release of the InnerSource Patterns book and may still find broken links, spelling mistakes, or other errors.
-Please help us to fix them to produce the best book possible :). Learn how to [contribute to this book](contribute.md).
+You can help us to create the best possible book about InnerSource Patterns :).
+Learn how to [contribute to this book](contribute.md).
 {% endhint %}
 
 Welcome to the **InnerSource Patterns Book**.
diff --git a/book/ja/.gitbook.yaml b/book/ja/.gitbook.yaml
@@ -1,6 +1,6 @@
 root : ./
 
 structure:
-  readme: book/ja/introduction.md
-  summary: book/ja/toc.md
+  readme: introduction.md
+  summary: toc.md
   
diff --git a/book/ja/toc.md b/book/ja/toc.md
@@ -39,6 +39,7 @@ Instead edit toc_template.md
 * [基本原則ガイダンスの文書化](../../translation/ja/patterns/document-your-guiding-principles.md) - 「オープンソースのベストプラクティスを組織内に適用する」という通常のインナーソースの説明は、オープンソースのバックグラウンドがない人々にはうまく機能しません。 解決策として、インナーソースの最も重要な原則を文書化し広く公開しましょう。
 * [実験として始める](../../translation/ja/patterns/start-as-experiment.md) - インナーソースイニシアチブを期間限定の実験として開始し、インナーソースに慣れていないマネージャーがイニシアチブを承認およびサポートしやすくします。
 * [成熟度モデル](../../translation/ja/patterns/maturity-model.md) - チームはインナーソースを採用し始めました。このプラクティスは、複数の部門に広がっています。しかし、インナーソースプロジェクトを構成する概念への理解は様々です。解決策は、チームがセルフチェックを経て、まだ気づいていないパターンやプラクティスを発見できるよう、成熟度モデルを提供することです。
+* [持続可能な成長のためのエクステンション](../../translation/ja/patterns/extensions-for-sustainable-growth.md) - インナーソースプロジェクトは多くのコントリビューションを受けており、メンテナンスが難しくなっています。メンテナは、プロジェクトのコア部分から離れた拡張機構を提供することで、最小のコストとメンテナンスオーバーヘッドでプロジェクトの能力をスケールアップすることを可能にします。
 * [正式なコミュニティリーダー](../../translation/ja/patterns/dedicated-community-leader.md) - インナーソースの取り組みを成功させるために、コミュニケーションとテクニカルの両方のスキルを持つ人をコミュニティのリーダーとして選ぶ。
 
 ## 付録<a id="appendix"></a>
diff --git a/book/zh/.gitbook.yaml b/book/zh/.gitbook.yaml
@@ -1,5 +1,5 @@
 root : ./
 
 structure:
-  readme: book/zh/introduction.md
-  summary: book/zh/toc.md
+  readme: introduction.md
+  summary: toc.md
diff --git a/translation/README.md b/translation/README.md
@@ -22,20 +22,20 @@ Please note that this document contains recommendations, aimed at removing barri
 - Please make your changes to the respective `.md` file.
 - Once you are ready, send us a Pull Request.
 
-### Translating a new InnerSource Patterns
+### Adding a new InnerSource Pattern to an Existing Translation
 
 - Copy the pattern that you want to translate from `/patterns/2-structured/<file>.md` to `/translation/<YOUR_LANGUAGE>/patterns/<file>.md`.[^1] Make sure to keep the file name the same.
 - Then start your translation in that new file.
 - Once you are ready, send us a Pull Request.
 
-### Starting the Translation of a New Language
+### Starting the Translation of an Entirely New Language
 
 That is awesome! We welcome your passion. When implementing InnerSource practices in your region, there can be language barriers. There is great value in getting people in your organization to understand InnerSource in their own language.
 
 Before starting a new translation please talk to us in Slack (in the `#innersource-patterns` channel). Alternatively open an issue on this GitHub repo to start an async conversation about your translation project.
 
-The translation should begin by creating a `book-<YOUR_LANGUAGE>` branch to work on.[^1]
-e.g. `book-jp` is used for the Japanese translation.
+The translation should begin by creating a new `translation-<YOUR_LANGUAGE>` branch to work on.[^1]
+e.g. `translation-de` would be used for the German translation.
 
 There are a few things you should prepare before starting a translation project.
 
@@ -56,7 +56,8 @@ In particular, for special terms, such as "Trusted Committer", please review not
 The patterns books is published in multiple languages, including English, Japanese and Chinese (as of August/2023).
 Find the full list of available languages in the [patterns books](https://patterns.innersourcecommons.org/).
 
-Trusted Committers in this repository will also be onboarded during the translation process.
+When publishing an entirely new language to our book, we also like to add at least one of the translators as a Trusted Committer to the project.
+They will then get notified on any fixes/additions to the translation in the future, and can greatly help us by providing reviews.
 
 When you complete a translation under `/translation/<YOUR_LANGUAGE>/`, a GitHub Actions pipeline will run to generate the output for publication in the gitbook. The process is described in detail in [/book/README.md](/book/README.md).
 
