thomvaill · TheGuit · Sep 3, 2021 · Sep 3, 2021
diff --git a/packages/init/assets/README.md → packages/init/assets/en/README.md b/packages/init/assets/README.md → packages/init/assets/en/README.md
diff --git a/packages/init/assets/index.md → packages/init/assets/en/index.md b/packages/init/assets/index.md → packages/init/assets/en/index.md
diff --git a/packages/init/assets/template.md → packages/init/assets/en/template.md b/packages/init/assets/template.md → packages/init/assets/en/template.md
diff --git a/...sets/use-log4brains-to-manage-the-adrs.md → ...s/en/use-log4brains-to-manage-the-adrs.md b/...sets/use-log4brains-to-manage-the-adrs.md → ...s/en/use-log4brains-to-manage-the-adrs.md
diff --git a/...arkdown-architectural-decision-records.md → ...arkdown-architectural-decision-records.md b/...arkdown-architectural-decision-records.md → ...arkdown-architectural-decision-records.md
diff --git a/packages/init/assets/fr/README.md b/packages/init/assets/fr/README.md
@@ -0,0 +1,35 @@
+# Architecture Decision Records
+
+ADRs are automatically published to our Log4brains architecture knowledge base:
+
+🔗 **<http://INSERT-YOUR-LOG4BRAINS-URL>**
+
+Please use this link to browse them.
+
+## Development
+
+If not already done, install Log4brains:
+
+```bash
+npm install -g log4brains
+```
+
+To preview the knowledge base locally, run:
+
+```bash
+log4brains preview
+```
+
+In preview mode, the Hot Reload feature is enabled: any change you make to a markdown file is applied live in the UI.
+
+To create a new ADR interactively, run:
+
+```bash
+log4brains adr new
+```
+
+## More information
+
+- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/master#readme)
+- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them)
+- [ADR GitHub organization](https://adr.github.io/)
diff --git a/packages/init/assets/fr/index.md b/packages/init/assets/fr/index.md
@@ -0,0 +1,36 @@
+<!-- This file is the homepage of your Log4brains knowledge base. You are free to edit it as you want -->
+
+# Architecture knowledge base
+
+Welcome 👋 to the architecture knowledge base of {PROJECT_NAME}.
+You will find here all the Architecture Decision Records (ADR) of the project.
+
+## Definition and purpose
+
+> An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant.
+> An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitutes its decision log.
+
+An ADR is immutable: only its status can change (i.e., become deprecated or superseded). That way, you can become familiar with the whole project history just by reading its decision log in chronological order.
+Moreover, maintaining this documentation aims at:
+
+- 🚀 Improving and speeding up the onboarding of a new team member
+- 🔭 Avoiding blind acceptance/reversal of a past decision (cf [Michael Nygard's famous article on ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html))
+- 🤝 Formalizing the decision process of the team
+
+## Usage
+
+This website is automatically updated after a change on the `master` branch of the project's Git repository.
+In fact, the developers manage this documentation directly with markdown files located next to their code, so it is more convenient for them to keep it up-to-date.
+You can browse the ADRs by using the left menu or the search bar.
+
+The typical workflow of an ADR is the following:
+
+![ADR workflow](/l4b-static/adr-workflow.png)
+
+The decision process is entirely collaborative and backed by pull requests.
+
+## More information
+
+- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/master#readme)
+- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them)
+- [ADR GitHub organization](https://adr.github.io/)
diff --git a/packages/init/assets/fr/template.md b/packages/init/assets/fr/template.md
@@ -0,0 +1,73 @@
+# [titre court de la décision prise]
+
+- Status: [draft | proposed | rejected | accepted | deprecated | … | superseded by [xxx](yyyymmdd-xxx.md)] <!-- optionnel -->
+- Décideurs: [liste de toutes les ayant pris part à cette décision] <!-- optionnel -->
+- Date: [YYYY-MM-DD quand la décision a été mis à jour la dernière fois] <!-- optional. To customize the ordering without relying on Git creation dates and filenames -->
+- Tags: [liste de tags séparé par des vigules ou des espaces] <!-- optionnel -->
+
+Ticket de fonctionnalités : [description | URL redmine] <!-- optionnel -->
+
+## Contexte et énoncé du problème
+
+[Décrivez le contexte et l'énoncé du problème, par exemple, sous une forme libre en utilisant deux à trois phrases. Vous pouvez exprimer le problème sous la forme d'une question.]
+
+## Facteurs de décision <!-- optionnel -->
+
+- [facteur 1, e.g., une contrainte, un doute, …]
+- [facteur 2, e.g., une contrainte, un doute, …]
+- … <!-- le nombre de facteurs peut varier -->
+
+## Options envisagées
+
+- [option 1]
+- [option 2]
+- [option 3]
+- … <!-- le nombre d'options peut varier -->
+
+## Résultat de la décision
+
+Option choisie: "[option 1]", parce que [justification. ex. seule option, qui permet de résoudre l'intégralité du problème | qui répond aux exigences | … | est la plus performante (voir plus bas)].
+
+### Impacts positifs <!-- optionnel -->
+
+- [ex. ameliore la qualité, suivi de l'impact nécessaire, …]
+- …
+
+### Impacts négatifs <!-- optionnel -->
+
+- [ex. dégrade la qualité, suivi de l'impact nécessaire, …]
+- …
+
+## Avantages et inconvénients des options <!-- optionnel -->
+
+### [option 1]
+
+[exemple | description | liens vers des sources pour plus d'informations | …] <!-- optionnel -->
+
+- Positif, parce que [argument a]
+- Positif, parce que [argument b]
+- Négatif, parce que [argument c]
+- … <!-- le nombre de pour et contre peut varier -->
+
+### [option 2]
+
+[exemple | description | liens vers des sources pour plus d'informations | …] <!-- optionnel -->
+
+- Positif, parce que [argument a]
+- Positif, parce que [argument b]
+- Négatif, parce que [argument c]
+- … <!-- le nombre de pour et contre peut varier -->
+
+### [option 3]
+
+[exemple | description | liens vers des sources pour plus d'informations | …] <!-- optionnel -->
+
+- Positif, parce que [argument a]
+- Positif, parce que [argument b]
+- Négatif, parce que [argument c]
+- … <!-- le nombre de pour et contre peut varier -->
+
+## Liens <!-- optionnel -->
+
+- [Texte du lien](lien) <!-- example: Précisé par [xxx](yyyymmdd-xxx.md) -->
+- … <!-- le nombre de lien peut varier -->
diff --git a/packages/init/assets/fr/use-log4brains-to-manage-the-adrs.md b/packages/init/assets/fr/use-log4brains-to-manage-the-adrs.md
@@ -0,0 +1,22 @@
+# Use Log4brains to manage the ADRs
+
+- Status: accepted
+- Date: {DATE_YESTERDAY}
+- Tags: dev-tools, doc
+
+## Context and Problem Statement
+
+We want to record architectural decisions made in this project.
+Which tool(s) should we use to manage these records?
+
+## Considered Options
+
+- [Log4brains](https://github.com/thomvaill/log4brains): architecture knowledge base (command-line + static site generator)
+- [ADR Tools](https://github.com/npryce/adr-tools): command-line to create ADRs
+- [ADR Tools Python](https://bitbucket.org/tinkerer_/adr-tools-python/src/master/): command-line to create ADRs
+- [adr-viewer](https://github.com/mrwilson/adr-viewer): static site generator
+- [adr-log](https://adr.github.io/adr-log/): command-line to create a TOC of ADRs
+
+## Decision Outcome
+
+Chosen option: "Log4brains", because it includes the features of all the other tools, and even more.
diff --git a/packages/init/assets/fr/use-markdown-architectural-decision-records.md b/packages/init/assets/fr/use-markdown-architectural-decision-records.md
@@ -0,0 +1,42 @@
+# Use Markdown Architectural Decision Records
+
+- Status: accepted
+- Date: {DATE_YESTERDAY}
+- Tags: doc
+
+## Context and Problem Statement
+
+We want to record architectural decisions made in this project.
+Which format and structure should these records follow?
+
+## Considered Options
+
+- [MADR](https://adr.github.io/madr/) 2.1.2 with Log4brains patch
+- [MADR](https://adr.github.io/madr/) 2.1.2 – The original Markdown Architectural Decision Records
+- [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
+- [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
+- Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+- Formless – No conventions for file format and structure
+
+## Decision Outcome
+
+Chosen option: "MADR 2.1.2 with Log4brains patch", because
+
+- Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+- The MADR format is lean and fits our development style.
+- The MADR structure is comprehensible and facilitates usage & maintenance.
+- The MADR project is vivid.
+- Version 2.1.2 is the latest one available when starting to document ADRs.
+- The Log4brains patch adds more features, like tags.
+
+The "Log4brains patch" performs the following modifications to the original template:
+
+- Change the ADR filenames format (`NNN-adr-name` becomes `YYYYMMDD-adr-name`), to avoid conflicts during Git merges.
+- Add a `draft` status, to enable collaborative writing.
+- Add a `Tags` field.
+
+## Links
+
+- Relates to [Use Log4brains to manage the ADRs]({LOG4BRAINS_ADR_SLUG}.md)
diff --git a/packages/init/src/commands/InitCommand.ts b/packages/init/src/commands/InitCommand.ts
@@ -32,6 +32,7 @@ type L4bYmlConfig = {
   project: {
     name: string;
     tz: string;
+    lang: string;
     adrFolder: string;
     packages?: L4bYmlPackageConfig[];
   };
@@ -143,6 +144,25 @@ export class InitCommand {
           ]
         );
 
+    // Project type
+    const lang = noInteraction
+      ? "en"
+      : await this.console.askListQuestion(
+          "Which language do you want to use to generate base file?",
+          [
+            {
+              name: "English",
+              value: "en",
+              short: "English"
+            },
+            {
+              name: "Français",
+              value: "fr",
+              short: "Français"
+            }
+          ]
+        );
+
     // Main ADR folder location
     let adrFolder = this.guessMainAdrFolderPath(cwd);
     if (adrFolder) {
@@ -220,6 +240,7 @@ export class InitCommand {
       project: {
         name,
         tz: moment.tz.guess(),
+        lang: lang,
         adrFolder: forceUnixPath(adrFolder),
         packages
       }
@@ -262,13 +283,14 @@ export class InitCommand {
   private async copyFileIfAbsent(
     cwd: string,
     adrFolder: string,
+    lang: string,
     filename: string,
     contentCb?: (content: string) => string
   ): Promise<void> {
     const outPath = path.join(cwd, adrFolder, filename);
     if (!fs.existsSync(outPath)) {
       let content = await fsP.readFile(
-        path.join(assetsPath, filename),
+        path.join(assetsPath, lang, filename),
         "utf-8"
       );
       if (contentCb) {
@@ -355,11 +377,12 @@ export class InitCommand {
 
     // Copy template, index and README if not already created
     this.console.updateSpinner("Copying template files...");
-    await this.copyFileIfAbsent(cwd, adrFolder, "template.md");
-    await this.copyFileIfAbsent(cwd, adrFolder, "index.md", (content) =>
+    const { lang } = config.project;
+    await this.copyFileIfAbsent(cwd, adrFolder, lang, "template.md");
+    await this.copyFileIfAbsent(cwd, adrFolder, lang, "index.md", (content) =>
       content.replace(/{PROJECT_NAME}/g, config.project.name)
     );
-    await this.copyFileIfAbsent(cwd, adrFolder, "README.md");
+    await this.copyFileIfAbsent(cwd, adrFolder, lang, "README.md");
 
     // List existing ADRs
     this.console.updateSpinner("Creating your first ADR...");