diff --git a/packages/init/assets/README.md b/packages/init/assets/en/README.md similarity index 100% rename from packages/init/assets/README.md rename to packages/init/assets/en/README.md diff --git a/packages/init/assets/index.md b/packages/init/assets/en/index.md similarity index 100% rename from packages/init/assets/index.md rename to packages/init/assets/en/index.md diff --git a/packages/init/assets/template.md b/packages/init/assets/en/template.md similarity index 100% rename from packages/init/assets/template.md rename to packages/init/assets/en/template.md diff --git a/packages/init/assets/use-log4brains-to-manage-the-adrs.md b/packages/init/assets/en/use-log4brains-to-manage-the-adrs.md similarity index 100% rename from packages/init/assets/use-log4brains-to-manage-the-adrs.md rename to packages/init/assets/en/use-log4brains-to-manage-the-adrs.md diff --git a/packages/init/assets/use-markdown-architectural-decision-records.md b/packages/init/assets/en/use-markdown-architectural-decision-records.md similarity index 100% rename from packages/init/assets/use-markdown-architectural-decision-records.md rename to packages/init/assets/en/use-markdown-architectural-decision-records.md diff --git a/packages/init/assets/fr/README.md b/packages/init/assets/fr/README.md new file mode 100644 index 00000000..74bccd30 --- /dev/null +++ b/packages/init/assets/fr/README.md @@ -0,0 +1,35 @@ +# Architecture Decision Records + +ADRs are automatically published to our Log4brains architecture knowledge base: + +🔗 **** + +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 new file mode 100644 index 00000000..7b5e225f --- /dev/null +++ b/packages/init/assets/fr/index.md @@ -0,0 +1,36 @@ + + +# 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 new file mode 100644 index 00000000..cad64910 --- /dev/null +++ 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)] +- Décideurs: [liste de toutes les ayant pris part à cette décision] +- Date: [YYYY-MM-DD quand la décision a été mis à jour la dernière fois] +- Tags: [liste de tags séparé par des vigules ou des espaces] + +Ticket de fonctionnalités : [description | URL redmine] + +## 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 + +- [facteur 1, e.g., une contrainte, un doute, …] +- [facteur 2, e.g., une contrainte, un doute, …] +- … + +## Options envisagées + +- [option 1] +- [option 2] +- [option 3] +- … + +## 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 + +- [ex. ameliore la qualité, suivi de l'impact nécessaire, …] +- … + +### Impacts négatifs + +- [ex. dégrade la qualité, suivi de l'impact nécessaire, …] +- … + +## Avantages et inconvénients des options + +### [option 1] + +[exemple | description | liens vers des sources pour plus d'informations | …] + +- Positif, parce que [argument a] +- Positif, parce que [argument b] +- Négatif, parce que [argument c] +- … + +### [option 2] + +[exemple | description | liens vers des sources pour plus d'informations | …] + +- Positif, parce que [argument a] +- Positif, parce que [argument b] +- Négatif, parce que [argument c] +- … + +### [option 3] + +[exemple | description | liens vers des sources pour plus d'informations | …] + +- Positif, parce que [argument a] +- Positif, parce que [argument b] +- Négatif, parce que [argument c] +- … + +## Liens + +- [Texte du lien](lien) +- … \ No newline at end of file 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 new file mode 100644 index 00000000..36b42d3d --- /dev/null +++ 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 new file mode 100644 index 00000000..a9ac6237 --- /dev/null +++ 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 +- 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 index 0a2c5c44..c208cfe1 100644 --- 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 { 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...");