Repository: joelparkerhenderson/architecture-decision-record Branch: main Commit: a5c0ed4e8c54 Files: 453 Total size: 709.8 KB Directory structure: gitextract_2a7geaq3/ ├── CITATION.cff ├── CODE_OF_CONDUCT.md ├── LICENSE.md ├── README.md └── locales/ ├── cy/ │ ├── .locale-peer-id │ ├── nogfennau/ │ │ ├── .locale-peer-id │ │ ├── awgrymiadau-ar-gyfer-ysgrifennu-adrs-da/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── beth-yw-cofnod-penderfyniad-pensaernïaeth/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── canllawiau-i-gyflawni-penderfyniadau-cynaliadwy/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── confensiynau-enw-ffeil/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── cwestiynau-gwaith-tîm-ar-gyfer-adrau/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── cyngor-gwaith-tîm-ar-gyfer-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── meini-prawf-cynaliadwyedd-penderfynu/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── proses-cofnodion-penderfynol-pensaernïol-aws/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── sut-i-ddechrau-defnyddio-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── sut-i-ddechrau-defnyddio-adrs-gyda-git/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ └── sut-i-ddechrau-defnyddio-adrs-gydag-offer/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── templedi/ │ ├── .locale-peer-id │ ├── index.md │ ├── templed-cofnod-penderfyniad-ar-gyfer-achos-busnes/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── templed-cofnod-penderfyniad-ar-gyfer-patrwm-alecsandraidd/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── templed-cofnod-penderfyniad-gan-edgex/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── templed-cofnod-penderfyniad-gan-jeff-tyree-and-art-akerman/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── templed-cofnod-penderfyniad-gan-michael-nygard/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── templed-cofnod-penderfyniad-gan-planguage/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── templed-cofnod-penderfyniad-y-prosiect-madr/ │ ├── .locale-peer-id │ └── index.md ├── en/ │ ├── .locale-peer-id │ ├── documents/ │ │ ├── .locale-peer-id │ │ ├── aws-adr-process/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── decision-sustainability-criteria/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── file-name-conventions-for-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── fitness-functions-for-decisions-as-code/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── guidelines-to-achieve-sustainable-decisions/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── how-to-start-using-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── how-to-start-using-adrs-with-git/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── how-to-start-using-adrs-with-tools/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── suggestions-for-writing-good-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── teamwork-advice-for-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── teamwork-questions-for-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ └── what-is-an-architecture-decision-record/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── examples/ │ │ ├── .locale-peer-id │ │ ├── 4-day-work-week/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── agile-software-development/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── amazon-web-services/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── api-using-json-v-grpc/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── authentication-authorization-options/ │ │ │ └── index.md │ │ ├── browser-automation-framework-for-e2e-testing-playwright-vs-selenium/ │ │ │ └── index.md │ │ ├── chart-library-toolkit-for-data-visualization-using-typescript-and-json/ │ │ │ └── index.md │ │ ├── choosing-a-database-technology/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── continuous-integration/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── css-framework/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── docker-swarm-container-orchestration/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── environment-variable-configuration/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── go-programming-language/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── google-cloud-platform/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── high-trust-teamwork/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── index.md │ │ ├── java-programming-language/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── kubernetes-container-orchestration/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── metrics-monitors-alerts/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── microsoft-azure-cloud-infrastructure/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── microsoft-azure-devops/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── monorepo-vs-multirepo/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── mysql-database/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── postgresql-database/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── programming-code-editors/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── programming-languages/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── python-django-framework/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── python-programming-language/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── react-front-end-javascript-library/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── ruby-on-rails-framework/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── rust-programming-language/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── secrets-storage/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── snake-case-v-camelcase-for-a-rest-api/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── svelte-components/ │ │ │ └── index.md │ │ ├── svelte-front-end-javascript-library/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── sveltekit-framework/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── tailwind-css/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── timestamp-format/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── vue-front-end-javascript-library/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── web-application-framework-batteries-included-full-stack-for-a-startup-product/ │ │ │ └── index.md │ │ └── work-from-home/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── templates/ │ ├── .locale-peer-id │ ├── decision-record-template-by-arc42/ │ │ ├── LICENSE.md │ │ └── index.md │ ├── decision-record-template-by-edgex/ │ │ ├── .locale-peer-id │ │ ├── LICENSE.md │ │ └── index.md │ ├── decision-record-template-by-gareth-morgan/ │ │ ├── README.md │ │ └── index.md │ ├── decision-record-template-by-gig-cymru-nhs-wales/ │ │ └── index.md │ ├── decision-record-template-by-jeff-tyree-and-art-akerman/ │ │ ├── .locale-peer-id │ │ ├── LICENSE-WIP.md │ │ └── index.md │ ├── decision-record-template-by-michael-nygard/ │ │ ├── .locale-peer-id │ │ ├── LICENSE.md │ │ └── index.md │ ├── decision-record-template-for-alexandrian-pattern/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── decision-record-template-for-business-case/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── decision-record-template-of-the-madr-project/ │ │ ├── .locale-peer-id │ │ ├── LICENSE.md │ │ └── index.md │ ├── decision-record-template-using-planguage/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── index.md ├── es/ │ ├── .locale-peer-id │ ├── documentos/ │ │ ├── .locale-peer-id │ │ ├── consejo-de-trabajo-en-equipo-para-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── convenciones-de-nombre-de-archivo/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── criterios-de-sostenibilidad-de-decisión/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── cómo-comenzar-a-usar-adr-con-git/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── cómo-comenzar-a-usar-adr-con-herramientas/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── cómo-comenzar-a-usar-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── directrices-para-lograr-decisiones-sostenibles/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── proceso-de-registros-de-decisiones-arquitectónicas-de-aws/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── qué-es-un-registro-de-decisión-de-arquitectura/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ └── sugerencias-para-escribir-buenos-adr/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── plantillas/ │ ├── .locale-peer-id │ ├── index.md │ ├── plantilla-de-registro-de-decisión-de-edgex/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── plantilla-de-registro-de-decisión-de-jeff-tyree-y-art-akerman/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── plantilla-de-registro-de-decisión-de-michael-nygard/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── plantilla-de-registro-de-decisión-del-proyecto-madr/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── plantilla-de-registro-de-decisión-para-caso-de-negocio/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── plantilla-de-registro-de-decisión-para-el-patrón-alejandrino/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── plantilla-de-registro-de-decisión-usando-planguage/ │ ├── .locale-directory-name-en.txt │ ├── .locale-peer-id │ └── index.md ├── fr/ │ ├── .locale-peer-id │ ├── documents/ │ │ ├── .locale-peer-id │ │ ├── comment-commencer-à-utiliser-les-adr/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── comment-commencer-à-utiliser-les-adr-avec-des-outils/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── comment-commencer-à-utiliser-les-adr-avec-git/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── conseils-de-travail-déquipe-pour-les-adr/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── conventions-de-noms-de-fichiers/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── critères-de-durabilité-de-décision/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── lignes-directrices-pour-atteindre-des-décisions-durables/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── processus-des-dossiers-de-décision-architecturale-aws/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── quest-ce-quun-dossier-de-décision-darchitecture/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ └── suggestions-pour-écrire-de-bonnes-adr/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── modèles/ │ ├── .locale-peer-id │ ├── index.md │ ├── modèle-denregistrement-de-décision par jeff-tyree-et-art-akerman/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── modèle-denregistrement-de-décision pour-lanalyse-de-rentabilisation/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── modèle-denregistrement-de-décision utilisant-plangage/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── modèle-denregistrement-de-décision-du-projet-madr/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── modèle-denregistrement-de-décision-par michael-nygard/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── modèle-denregistrement-de-décision-par-edgex/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── modèle-denregistrement-de-décision-pour-le modèle-alexandrin/ │ ├── .locale-peer-id │ └── index.md ├── index.md ├── ja/ │ ├── .locale-peer-id │ ├── テンプレート/ │ │ ├── .locale-peer-id │ │ ├── EdgeX Foundryによる意思決定記録テンプレート/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── Jeff TyreeとArt Akermanによる意思決定記録テンプレート/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── Michael Nygard による意思決定記録テンプレート/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── Planguageを使用した意思決定記録テンプレート/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── index.md │ │ ├── madrプロジェクトの意思決定記録テンプレート/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── アレクサンドリアパターンの意思決定記録テンプレート/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ └── ビジネスケース用意思決定記録テンプレート/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── ドキュメント/ │ │ ├── .locale-peer-id │ │ ├── aws-adr-process/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── decision-sustainability-criteria/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── file-name-conventions-for-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── guidelines-to-achieve-sustainable-decisions/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── how-to-start-using-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── how-to-start-using-adrs-with-git/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── how-to-start-using-adrs-with-tools/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── suggestions-for-writing-good-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── teamwork-advice-for-adrs/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ └── what-is-an-architecture-decision-record/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── 翻訳注.txt ├── ko/ │ ├── .locale-peer-id │ ├── 서류/ │ │ ├── .locale-peer-id │ │ ├── adr-사용을-시작하는-방법/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── adr을-위한-팀워크-조언/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── aws-아키텍처-결정-기록-프로세스/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── git에서-adr-사용을-시작하는-방법/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── 도구를-사용하여-adr-사용을-시작하는-방법/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── 아키텍처-결정-기록이란-무엇입니까/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── 의사결정-지속가능성-기준/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── 좋은-adr-작성을-위한-제안/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ ├── 지속-가능한-결정을-달성하기-위한-지침/ │ │ │ ├── .locale-peer-id │ │ │ └── index.md │ │ └── 파일-이름-규칙/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── 템플릿/ │ ├── .locale-peer-id │ ├── index.md │ ├── madr 프로젝트의 결정 기록 템플릿/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── 결정 기록 템플릿별 edgex/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── 비즈니스 사례에 대한 의사결정 기록 템플릿/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── 알렉산드리아 패턴에 대한 결정 기록 템플릿/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── 의사 결정 기록 템플릿-by-michael-nygard/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── 의사결정 기록 템플릿 사용 p언어/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── 의사결정 기록 템플릿-by-jeff-tyree-and-art-akerman/ │ ├── .locale-peer-id │ └── index.md └── tr/ ├── .locale-peer-id ├── documents/ │ ├── .locale-peer-id │ ├── aws-adr-process/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── decision-sustainability-criteria/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── file-name-conventions-for-adrs/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── guidelines-to-achieve-sustainable-decisions/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── how-to-start-using-adrs/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── how-to-start-using-adrs-with-git/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── how-to-start-using-adrs-with-tools/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── suggestions-for-writing-good-adrs/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── teamwork-advice-for-adrs/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── teamwork-questions-for-adrs/ │ │ ├── .locale-peer-id │ │ └── index.md │ └── what-is-an-architecture-decision-record/ │ ├── .locale-peer-id │ └── index.md ├── examples/ │ ├── .locale-peer-id │ ├── 4-day-work-week/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── agile-software-development/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── amazon-web-services/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── api-using-json-v-grpc/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── authentication-authorization-options/ │ │ └── index.md │ ├── browser-automation-framework-for-e2e-testing-playwright-vs-selenium/ │ │ └── index.md │ ├── chart-library-toolkit-for-data-visualization-using-typescript-and-json/ │ │ └── index.md │ ├── choosing-a-database-technology/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── continuous-integration/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── css-framework/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── docker-swarm-container-orchestration/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── environment-variable-configuration/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── go-programming-language/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── google-cloud-platform/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── high-trust-teamwork/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── index.md │ ├── java-programming-language/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── kubernetes-container-orchestration/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── metrics-monitors-alerts/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── microsoft-azure-cloud-infrastructure/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── microsoft-azure-devops/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── monorepo-vs-multirepo/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── mysql-database/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── postgresql-database/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── programming-code-editors/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── programming-languages/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── python-django-framework/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── python-programming-language/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── react-front-end-javascript-library/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── ruby-on-rails-framework/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── rust-programming-language/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── secrets-storage/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── snake-case-v-camelcase-for-a-rest-api/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── svelte-components/ │ │ └── index.md │ ├── svelte-front-end-javascript-library/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── sveltekit-framework/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── tailwind-css/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── timestamp-format/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── vue-front-end-javascript-library/ │ │ ├── .locale-peer-id │ │ └── index.md │ ├── web-application-framework-batteries-included-full-stack-for-a-startup-product/ │ │ └── index.md │ └── work-from-home/ │ ├── .locale-peer-id │ └── index.md └── templates/ ├── .locale-peer-id ├── decision-record-template-by-arc42/ │ ├── LICENSE.md │ └── index.md ├── decision-record-template-by-edgex/ │ ├── .locale-peer-id │ ├── LICENSE.md │ └── index.md ├── decision-record-template-by-gareth-morgan/ │ ├── README.md │ └── index.md ├── decision-record-template-by-gig-cymru-nhs-wales/ │ └── index.md ├── decision-record-template-by-jeff-tyree-and-art-akerman/ │ ├── .locale-peer-id │ ├── LICENSE-WIP.md │ └── index.md ├── decision-record-template-by-michael-nygard/ │ ├── .locale-peer-id │ ├── LICENSE.md │ └── index.md ├── decision-record-template-for-alexandrian-pattern/ │ ├── .locale-peer-id │ └── index.md ├── decision-record-template-for-business-case/ │ ├── .locale-peer-id │ └── index.md ├── decision-record-template-of-the-madr-project/ │ ├── .locale-peer-id │ ├── LICENSE.md │ └── index.md ├── decision-record-template-using-planguage/ │ ├── .locale-peer-id │ └── index.md └── index.md ================================================ FILE CONTENTS ================================================ ================================================ FILE: CITATION.cff ================================================ cff-version: 1.2.0 title: Architecture decision record (ADR) message: >- If you use this work and you want to cite it, then you can use the metadata from this file. type: software authors: - given-names: Joel Parker family-names: Henderson email: joel@joelparkerhenderson.com affiliation: joelparkerhenderson.com orcid: 'https://orcid.org/0009-0000-4681-282X' identifiers: - type: url value: 'https://github.com/joelparkerhenderson/architecture-decision-record/' description: Architecture decision record (ADR) repository-code: 'https://github.com/joelparkerhenderson/architecture-decision-record/' abstract: >- Architecture decision record (ADR) license: See license file ================================================ FILE: CODE_OF_CONDUCT.md ================================================ # Contributor Covenant Code of Conduct ## Our Pledge We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. ## Our Standards Examples of behavior that contributes to a positive environment for our community include: * Demonstrating empathy and kindness toward other people * Being respectful of differing opinions, viewpoints, and experiences * Giving and gracefully accepting constructive feedback * Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience * Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: * The use of sexualized language or imagery, and sexual attention or advances of any kind * Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment * Publishing others' private information, such as a physical or email address, without their explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. ## Scope This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [INSERT CONTACT METHOD]. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. ## Enforcement Guidelines Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: ### 1. Correction **Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. **Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. ### 2. Warning **Community Impact**: A violation through a single incident or series of actions. **Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. ### 3. Temporary Ban **Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. **Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. ### 4. Permanent Ban **Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations]. [homepage]: https://www.contributor-covenant.org [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html [Mozilla CoC]: https://github.com/mozilla/diversity [FAQ]: https://www.contributor-covenant.org/faq [translations]: https://www.contributor-covenant.org/translations ================================================ FILE: LICENSE.md ================================================ # License For the work that I've personally done, such as writing the README.md file, the license is CC BY-NC-SA. https://creativecommons.org/licenses/by-nc-sa/4.0/ For the work that is included created by others, such as the original authors of the templates, please see the original works for their respective licenses, and optionally see each work's folder for a respective LICENSE.md file if available. ================================================ FILE: README.md ================================================ # Architecture decision record (ADR) An architecture decision record (ADR) is a document that captures an important architecture decision made along with its context and consequences. Contents: - [What is an architecture decision record?](#what-is-an-architecture-decision-record) - [How to start using ADRs](#how-to-start-using-adrs) - [How to start using ADRs with tools](#how-to-start-using-adrs-with-tools) - [How to start using ADRs with git](#how-to-start-using-adrs-with-git) - [File name conventions for ADRs](#file-name-conventions-for-adrs) - [Suggestions for writing good ADRs](#suggestions-for-writing-good-adrs) - [ADR example templates](#adr-example-templates) - [Teamwork advice for ADRs](#teamwork-advice-for-adrs) - [Teamwork questions for ADRs](#teamwork-questions-for-adrs) - [Next step concepts for ADRs](#next-step-concepts-for-adrs) - [Architecture diagrams \& views \& viewpoints](#architecture-diagrams--views--viewpoints) - [Fitness functions for decisions as code](#fitness-functions-for-decisions-as-code) - [Decision guardrails for pull requests](#decision-guardrails-for-pull-requests) - [For more information](#for-more-information) Templates: - [Decision record template by Jeff Tyree and Art Akerman](locales/en/templates/decision-record-template-by-jeff-tyree-and-art-akerman/) - [Decision record template by Michael Nygard](locales/en/templates/decision-record-template-by-michael-nygard/) - [Decision record template by EdgeX](locales/en/templates/decision-record-template-by-edgex/) - [Decision record template by arc42](locales/en/templates/decision-record-template-by-arc42/) - [Decision record template for Alexandrian pattern](locales/en/templates/decision-record-template-for-alexandrian-pattern/) - [Decision record template for business case](locales/en/templates/decision-record-template-for-business-case/) - [Decision record template of the MADR project](locales/en/templates/decision-record-template-of-the-madr-project/) - [Decision record template using Planguage](locales/en/templates/decision-record-template-using-planguage/) - [Decision record template by Paulo Merson](https://github.com/pmerson/ADR-template) - [Decision record template by Olaf Zimmermann](https://medium.com/olzzio/y-statements-10eb07b5a177) - [Decision record template by Gareth Morgan](locales/en/templates/decision-record-template-by-gareth-morgan/) - [Decision record template by GIG Cymru NHS Wales](locales/en/templates/decision-record-template-by-gig-cymru-nhs-wales/) - [Translations into more languages](locales/) Examples: - [CSS framework](locales/en/examples/css-framework/) - [Environment variable configuration](locales/en/examples/environment-variable-configuration/) - [Metrics, monitors, alerts](locales/en/examples/metrics-monitors-alerts/) - [Microsoft Azure DevOps](locales/en/examples/microsoft-azure-devops/) - [Monorepo vs multirepo](locales/en/examples/monorepo-vs-multirepo/) - [Programming languages](locales/en/examples/programming-languages/) - [Secrets storage](locales/en/examples/secrets-storage/) - [Timestamp format](locales/en/examples/timestamp-format/) - [Many more...](locales/en/examples/) [Translations into more languages](locales/)
## What is an architecture decision record? An **architecture decision record** (ADR) is a document that captures an important architectural decision made along with its context and consequences. An **architecture decision** (AD) is a software design choice that addresses a significant requirement. An **architecture decision log** (ADL) is the collection of all ADRs created and maintained for a particular project (or organization). An **architecturally-significant requirement** (ASR) is a requirement that has a measurable effect on a software system’s architecture. All these are within the topic of **architecture knowledge management** (AKM). The goal of this document is to provide a fast overview of ADRs, how to create them, and where to look for more information. Abbreviations: - **AD**: architecture decision - **ADL**: architecture decision log - **ADR**: architecture decision record - **AKM**: architecture knowledge management - **ASR**: architecturally-significant requirement
## How to start using ADRs To start using ADRs, talk with your teammates about these areas. Decision identification: - How urgent and how important is the AD? - Does it have to be made now, or can it wait until more is known? - Both personal and collective experience, as well as recognized design methods and practices, can assist with decision identification. - Ideally maintain a decision todo list that complements the product todo list. Decision making: - A number of decision making techniques exist, both general ones and software architecture specific ones, for instance, dialogue mapping. - Group decision making is an active research topic. Decision enactment and enforcement: - ADs are used in software design; hence they have to be communicated to, and accepted by, the stakeholders of the system that fund, develop, and operate it. - Architecturally evident coding styles and code reviews that focus on architectural concerns and decisions are two related practices. - ADs also have to be (re-)considered when modernizing a software system in software evolution. Decision sharing (optional): - Many ADs recur across projects. - Hence, experiences with past decisions, both good and bad, can be valuable reusable assets when employing an explicit knowledge management strategy. Decision documentation: - Many templates and tools for decision capturing exist. - See agile communities, e.g. M. Nygard's ADRs. - See traditional software engineering and architecture design processes, e.g. table layouts suggested by IBM UMF and by Tyree and Akerman from CapitalOne. For more: - The steps above are adopted from the Wikipedia entry on [Architectural Decision](https://en.wikipedia.org/wiki/Architectural_decision)
## How to start using ADRs with tools You can start using ADRs with tools any way you want. For example: - If you like using Google Drive and online editing, then you can create a Google Doc, or Google Sheet. - If you like use source code version control, such as git, then you can create a file for each ADR. - If you like using project planning tools, such as Atlassian Jira, then you can use the tool's planning tracker. - If you like using wikis, such as MediaWiki, then you can create an ADR wiki.
## How to start using ADRs with git If you like using git version control, then here is how we like to start using ADRs with git for a typical software project with source code. Create a directory for ADR files: ```sh $ mkdir adr ``` For each ADR, create a text file, such as `database.txt`: ```sh $ vi database.txt ``` Write anything you want in the ADR. See the templates in this repository for ideas. Commit the ADR to your git repo.
## File name conventions for ADRs If you choose to create your ADRs using typical text files, then you may want to come up with your own ADR file name convention. We prefer to use a file name convention that has a specific format. Examples: - choose-database.md - format-timestamps.md - manage-passwords.md - handle-exceptions.md Our file name convention: - The name has a present tense imperative verb phrase. This helps readability and matches our commit message format. - The name uses lowercase and dashes (same as this repo). This is a balance of readability and system usability. - The extension is markdown. This can be useful for easy formatting.
## Suggestions for writing good ADRs Characteristics of a good ADR: - Rationale: Explain the reasons for doing the particular AD. This can include the context (see below), pros and cons of various potential choices, feature comparisons, cost/benefit discussions, and more. - Specific: Each ADR should be about one AD, not multiple ADs. - Timestamps: Identify when each item in the ADR is written. This is especially important for aspects that may change over time, such as costs, schedules, scaling, and the like. - Immutable: Don't alter existing information in an ADR. Instead, amend the ADR by adding new information, or supersede the ADR by creating a new ADR. Characteristics of a good "Context" section in an ADR: - Explain your organization's situation and business priorities. - Include rationale and considerations based on social and skills makeups of your teams. - Include pros and cons that are relevant, and describe them in terms that align with your needs and goals. Characteristics of good "Consequences" section in an ADR: - Explain what follows from making the decision. This can include the effects, outcomes, outputs, follow ups, and more. - Include information about any subsequent ADRs. It's relatively common for one ADR to trigger the need for more ADRs, such as when one ADR makes a big overarching choice, which in turn creates needs for more smaller decisions. - Include any after-action review processes. It's typical for teams to review each ADR one month later, to compare the ADR information with what's happened in actual practice, in order to learn and grow. A new ADR may take the place of a previous ADR: - When an AD is made that replaces or invalidates a previous ADR, then a new ADR should be created
## ADR example templates ADR example templates that we have collected on the net: - [ADR template by Michael Nygard](locales/en/templates/decision-record-template-by-michael-nygard/) (simple and popular) - [ADR template by Jeff Tyree and Art Akerman](locales/en/templates/decision-record-template-by-jeff-tyree-and-art-akerman/) (more sophisticated) - [ADR template for Alexandrian pattern](locales/en/templates/decision-record-template-for-alexandrian-pattern/) (simple with context specifics) - [ADR template for business case](locales/en/templates/decision-record-template-for-business-case/) (more MBA-oriented, with costs, SWOT, and more opinions) - [ADR template of the Markdown Any Decision Records (MADR) project](locales/en/templates/decision-record-template-of-the-madr-project/) (both simple and elaborate version; the latter emphasizes options and their pros and cons) - [ADR template using Planguage](locales/en/templates/decision-record-template-using-planguage/) (more quality assurance oriented)
## Teamwork advice for ADRs If you're considering using decision records with your team, then here's some advice that we've learned by working with many teams. You have an opportunity to lead your teammates, by talking together about the "why", rather than mandating the "what". For example, decision records are a way for teams to think smarter and communicate better; decision records are not valuable if they're just an after-the-fact forced paperwork requirement. Some teams much prefer the name "decisions" over the abbreviation "ADRs". When some teams use the directory name "decisions", then it's as if a light bulb turns on, and the team starts putting more information into the directory, such as vendor decisions, planning decisions, scheduling decisions, etc. All of these kinds of information can use the same template. We hypothesize that people learn faster with words ("decisions") over abbreviations ("ADRs"), and people are more motivated to write work-in-progress docs when the word "record" is removed, and also some developers and some managers dislike the word "architecture". In theory, immutability is ideal. In practice, mutability has worked better for our teams. We insert the new info the existing ADR, with a date stamp, and a note that the info arrived after the decision. This kind of approach leads to a "living document" that we all can update. Typical updates are when we get information thanks to new teammates, or new offerings, or real-world results of our usages, or after-the-fact third-party changes such as vendor capabilities, pricing plans, license agreements, etc.
## Teamwork questions for ADRs ### Who can create an ADR? Consider areas such as specific people, or specific roles, or specific teams, or specific departments; also consider if there are people, or roles, or teams, or department that can commission an ADR, meaning they request one that someone else will author. Example answer: Any person in our organization who has read the architecture decision record README page can propose an ADR, meaning the person can start writing it, and share it with the team. ### What justifies raising an ADR? Consider areas such as your organization's team ways of working, your software system structure, cross-team coordination, long-term maintainability, external interfaces, who you want to benefit, and the like. Example answer: We want to create an ADR when we want future developers to understand the “why” of what we're doing. ### What justifies not raising an ADR? Consider areas such as decisions that are not about architecture, or are tiny such as minimal-risk or self-contained or single-developer, or are already fully covered elsewhere such as by standards or policies or documentation, or are temporary such as workarounds or proofs of concepts or orexperiments. Example answer: We want to skip an ADR when a decision is limited in scope and time and risk and cost, or is already covered elsewhere. ### What is the lifecycle of an ADR? Consider areas such as the creation process, research process, decisioning process, implementation process, and sunsetting process. Consider how to track the ADR lifecycle over time, such as how to move the ADR from one state to the next state, and also how to communicate this to stakeholders. Example answer: We want an ADR to have five lifecycle stages: Initiating → Researching → Evaluating → Implementing → Maintaining → Sunsetting. ### What are criteria for lifecycle steps of an ADR? Consider areas such as acceptance criteria for an ADR, meaning how do you know it's good enough to progress from one lifecycle step to the next? Is the problem clearly articulated? Have the alternatives been considered? Are trade-offs well-enough understood and documented? Is all relevant context in place? Are all relevant stakeholders involved? Has all feedback been incorporated? Example answer: We want an ADR to be voted on by stakeholders when the active team has 1) completed their research, 2) completed their evaluation, 3) published the ADR proposal to the stakeholders with a request for comments and a timebox of one week, 4) all stakeholder comments have been incorporated and addressed. ### What roles and responsibilities interact with an ADR? Consider roles such as proposer, researcher, evaluator, reviewer, approver, maintainer, and the like. Consider responsibilities such as communication with stakeholders, ensuring expectations are met, sharing on the website or intranet, and reviewing the work periodically and especially when relevant changes happen. Example answer: We want each ADR to always have a primary contact person, secondary contact person, and accountable team; these are responsible for communications, publications, maintenance, periodic review at least once per year, and eventual sunsetting as needed. ### How does governance interact with an ADR? Consider areas such as your organization's ways of working, any special compliance needs such as for legal aspects or human resource aspects, how you want to handle consensus versus conflict versus escalation. Are there areas or people or teams that can have more influence than others regarding an ADR, such as being able to approve it, or vote on it, or veto it? Example answer: The governance of an ADR is in this priority order: the CEO, the CTO, the CLO, the team that implements an ADR, the experts on the team that are most-knowledgeable about the AD. No one else has governance unless described in the ADR. ### What principles interact with an ADR? Consider areas such as your organization's ways of working that include moving quickly versus moving slowly, for decision consensus versus decision conflict, and for risk preferences versus safety preferences, public discussion versus private discussion, and the like. Example answer: We use the leadership principles of bias for action, disagree-and-commit, 70% estimates are good enough for easily-reversable easily-isolatable decisions, and public ways of working with the exception of confidential information as described in our organization's confidentiality agreement.
## Next step concepts for ADRs [Arc42](https://arc42.org/) answers two questions in a pragmatic way and can be tailored to your specific needs. What should you document/communicate about your architecture? How should you document/communicate? Arc42 includes architecture decision records plus guidance on goals, constraints, contexts, quality, risks, and more. [The C4 model](https://c4model.com/) is an easy to learn, developer friendly approach to software architecture diagramming. C4 is a set of hierarchical digrams for context, containers, components, code, plus supporting diagrams for system landscape, dynamic, and deployment.
## Architecture diagrams & views & viewpoints An architecture diagram is called an "architecture view". An "architecture view" is an instance of a "architecture viewpoint". An "architecture viewpoint" has a specific audience with specific concerns in mind. Architecture viewpoint examples, view examples, and diagram examples: - Business Capabilities - High-level Business Processes - [Value Streams](https://en.wikipedia.org/wiki/Value_stream) - Software Functions mapped to application components - [C4 Model](https://en.wikipedia.org/wiki/C4_model) Context Diagram (TO-BE / AS-IS) - [C4 Model](https://en.wikipedia.org/wiki/C4_model) Container Diagram (TO-BE / AS-IS) - [Entity-relationship Diagram](https://en.wikipedia.org/w/index.php?title=Entity_relationship_diagram) (ERD) to map data entities to application components - [Sequence Diagrams](https://en.wikipedia.org/wiki/Sequence_diagram) to describe functional flows within systems and for integrations - [Business Process Model and Notation](https://en.wikipedia.org/wiki/Business_Process_Model_and_Notation) (BPMN) diagrams to describe data flows across application components - [Business Process Model and Notation](https://en.wikipedia.org/wiki/Business_Process_Model_and_Notation) (BPMN) diagrams to describe business processes / user Scenarios - [Identity and Access Management](https://en.wikipedia.org/wiki/Identity_and_access_management) (IAM) diagrams - [Role-Based Access Control](https://en.wikipedia.org/wiki/Role-based_access_control) (RBAC) diagrams with roles per application component - [Attribute-Based Access Control](https://en.wikipedia.org/wiki/Attribute-based_access_control) (ABAC) diagrams with attributes per application component - Privacy diagrams Related diagrams: - A Use Case Diagram shows use cases to management/customers, which precedes requirements, which precedes the software architecture. - A Deployment Diagram shows the physical hardware/computers that the software components are deployed to. - A Data Flow Diagram shows how data moves through the system and is transformed. - A Sequence Diagram is used to show how protocols like HTTP work on a time axis. - An Activity Diagram depicts the workflow of activities a software system undertakes, like an NPC AI.
## Fitness functions for decisions as code Fitness functions are objective automated checks, written with programming code, that verify decisions are being maintained. - Fitness functions make decisions testable and assurable. - Fitness functions for decisions can greatly help quality assurance, regulatory processes, and governance goals. ### How fitness functions connect to decisions A decision record documents the decision, while a fitness function assures the decision. - Example decision: We use event sourcing for audit requirements. - Example fitness function: We use the continuous integration server to test that all state changes must produce events. ### Why fitness functions help decisions Objective measurements: Fitness functions pass or fail, so work is visible and clear. Continuous use: Fitness functions are your living rules, run on every commit and build. Confidence to refactor: Fitness functions automatically catch decision rule errors. Scalable governance: Fitness functions assure standards without creating bottlenecks. ### Can fitness functions use AI? Fitness functions can leverage AI LLMs for decisions by asking questions for your work, such as your plans, code, schemas, APIs, and more: ```txt IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning. IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search. This is a fitness function to evaluate if our work is using all our decisions, and is correct and accurate. - Our decisions are here: {url} - Our wor to evaluate is here: {url} Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive. ``` ### Architecture unit testing [ArchUnit](https://www.archunit.org/): check architecture rules of Java code by using any plain Java unit test framework. [ArchUnitTS](https://github.com/LukasNiessen/ArchUnitTS): check architecture rules of TypeScript code and JavaScript code by using Jest, Vitest, Jasmine, etc. ## Decision guardrails for pull requests [Decision Guardian](https://github.com/DecispherHQ/decision-guardian) automatically surfaces the right decision records at the right moment — when a developer is actively modifying the code those decisions cover. Instead of hoping developers read a docs folder before merging, the relevant context appears directly on the pull request. This works for any kind of decision record: architecture decisions, data decisions, compliance decisions, clinical and medical decisions, security decisions, and more. Works with any CI system (GitLab, Jenkins, CircleCI) and as a pre-commit hook. Open source. MIT license. ## For more information Introduction: - [Architectural decision (wikipedia.org)](https://wikipedia.org/wiki/Architectural_decision) - [Architecturally significant requirements (wikipedia.org)](https://wikipedia.org/wiki/Architecturally_significant_requirements) Templates: - [Documenting architecture decisions - Michael Nygard (thinkrelevance.com)](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) - [Markdown Architectural Decision Records (adr.github.io)](https://adr.github.io/madr/) - [Template for documenting architecture alternatives and decisions (stackoverflow.com)](http://stackoverflow.com/questions/7104735/template-for-documenting-architecture-alternatives-and-decisions) In-depth: - [ADMentor XML project (github.com)](https://github.com/IFS-HSR/ADMentor) - [Architectural Decision Guidance across Projects: Problem Space Modeling, Decision Backlog Management and Cloud Computing Knowledge (ifs.hsr.ch)](https://www.ifs.hsr.ch/fileadmin/user_upload/customers/ifs.hsr.ch/Home/projekte/ADMentor-WICSA2015ubmissionv11nc.pdf) - [The Decision View's Role in Software Architecture Practice (computer.org)](https://www.computer.org/csdl/mags/so/2009/02/mso2009020036-abs.html) - [Documenting Software Architectures: Views and Beyond (resources.sei.cmu.edu)](http://resources.sei.cmu.edu/library/asset-view.cfm?assetID=30386) - [Architecture Decisions: Demystifying Architecture (utdallas.edu)](https://www.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf) - [ThoughtWorks Technology Radar: Lightweight Architecture Decision Records (thoughtworks.com)](https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records) - [A Skeptic’s Guide to Software Architecture Decisions (infoq.com)](https://www.infoq.com/articles/architecture-skeptics-guide/) - [Architectural Decisions — The Making Of](https://ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html) - [Architectural Retrospectives: the Key to Getting Better at Architecting](https://www.infoq.com/articles/architectural-retrospectives/) - [Software Architecture Monday with Mark Richards](https://developertoarchitect.com/lessons/) - free monthly software architecture lesson - [Solution Architecture Decisions - By Gareth Morgan](https://www.linkedin.com/pulse/solution-architecture-decisions-gareth-morgan-0r5xe/) Tools: - [Command-line tools for working with Architecture Decision Records](https://github.com/npryce/adr-tools) - [Command line tools with python - by Victor Sluiter](https://bitbucket.org/tinkerer_/adr-tools-python/src/master/) - [Architectural Design Decision Support Framework (ADvISE)](https://swa.univie.ac.at/Software_Architecture/research-projects/architectural-design-decision-support-framework-advise/) - [Decision Guardian](https://github.com/DecispherHQ/decision-guardian) Company-Specific Guidance: - [Amazon: AWS Prescriptive Guidance: ADR Process](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html) - [GitHub: ADR GitHub organization](https://adr.github.io/) - [RedHat: Why you should use ADRs](https://www.redhat.com/architect/architecture-decision-records) Examples: - [Repository of Architecture Decision Records made for the Arachne Framework](https://github.com/arachne-framework/architecture) Videos: - [An introduction to arc42 with Savvas Kleanthous](https://www.youtube.com/watch?v=V5clR8c6D7o) - [The C4 model for visualising software architecture - by Simon Brown](https://www.youtube.com/watch?v=KvoBrUd1-5E) Podcasts: - [Software Architecture Bookclub Podcast](https://www.developertoarchitect.com/bookclub-podcast.html) Books: - [Software Architecture Metrics: Case Studies to Improve the Quality of Your Architecture - by Christian Ciceri, Dave Farley, Neal Ford, Andrew Harmel-Law, Michael Keeling and Carola Lilienthal](https://www.amazon.com/Software-Architecture-Metrics-Christian-Ciceri-ebook/dp/B0B1NZ8Z5V) - [Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives - by Nick Rozanski and Eoin Woods](https://www.amazon.com/Software-Systems-Architecture-Stakeholders-Perspectives/dp/032171833X) - [Software Architecture in Practice (SEI Series in Software Engineering)](https://www.amazon.com/Software-Architecture-Practice-SEI-Engineering-ebook/dp/B094CPJ96B) - [Documenting Software Architectures: Views and Beyond (SEI Series in Software Engineering)](https://www.amazon.com/Documenting-Software-Architectures-Beyond-Engineering-ebook/dp/B0046XS3RO) - [The Software Architect Elevator: Redefining the Architect's Role in the Digital Enterprise](https://www.amazon.com/Software-Architect-Elevator-Redefining-Architects-ebook/dp/B086WQ9XL1) - [Fundamentals of Software Architecture: An Engineering Approach - by Mark Richards and Neal Ford](https://www.amazon.com/Fundamentals-Software-Architecture-Engineering-Approach-ebook/dp/B0849MPK73) - [Building Evolutionary Architectures - by Neal Ford, Rebecca Parsons, Patrick Kua, Pramod Sadalage](https://www.amazon.com/Building-Evolutionary-Architectures-Neal-Ford-ebook/dp/B0BN4T1P27?crid=37FA31IFLAS0Z) - [Foundations of Decision Analysis by Ronald Howard and Ali Abbas](https://www.amazon.com/Foundations-Decision-Analysis-Ronald-Howard-ebook/dp/B00SZECJTI?crid=14BK5SDP76UN6) - [Head First Software Architecture - by Raju Gandhi, Neal Ford and Mark Richards](https://www.amazon.com/Head-First-Software-Architecture-Architectural-ebook/dp/B0CW1JMNF2) - [Communication Patterns: A Guide for Developers and Architects - by Jacqui Read](https://www.amazon.com/Communication-Patterns-Guide-Developers-Architects/dp/1098140540) See also: - REMAP (Representation and Maintenance of Process Knowledge) - DRL (Decision Representation Language) - IBIS (Issue-Based Information System) - QOC (Questions, Options, and Criteria) - IBM’s e-Business Reference Architecture Framework - [Decision Reasoning Format (DRF)](https://github.com/reasoning-formats/reasoning-formats) - A vendor-neutral, machine-readable YAML/JSON format for representing decisions with explicit reasoning, assumptions, cognitive state, and trade-offs. Complements ADRs by adding structured, validatable reasoning to decision documentation. ================================================ FILE: locales/cy/.locale-peer-id ================================================ 0b59cb46e5817b414866ebe33f4d7bcf ================================================ FILE: locales/cy/nogfennau/.locale-peer-id ================================================ abc7c72d426bc75e40b25a44ae37ce73 ================================================ FILE: locales/cy/nogfennau/awgrymiadau-ar-gyfer-ysgrifennu-adrs-da/.locale-peer-id ================================================ dc1a294e76821d6d3b086a2b17988427 ================================================ FILE: locales/cy/nogfennau/awgrymiadau-ar-gyfer-ysgrifennu-adrs-da/index.md ================================================ ## Awgrymiadau ar gyfer ysgrifennu ADRs da Nodweddion ADR da: * Rhesymeg: Esboniwch y rhesymau dros wneud yr hysbyseb benodol. Gall hyn gynnwys cyd -destun (gweler isod), manteision ac anfanteision amrywiol ddewisiadau posib, cymhariadau nodwedd, trafodaethau cost/budd, a mwy. * Penodol: Dylai pob ADR fod tua un hysbyseb, nid hysbysebion lluosog. * Timestamps: Nodwch pryd mae pob eitem yn yr ADR wedi'i hysgrifennu. Mae hyn yn arbennig o bwysig ar gyfer agweddau a allai newid dros amser, megis costau, amserlenni, graddio, ac ati. * Na ellir ei symud: Peidiwch â newid y wybodaeth bresennol mewn ADR. Yn lle hynny, diwygiwch yr ADR trwy ychwanegu gwybodaeth newydd, neu ddisodli'r ADR trwy greu ADR newydd. Nodweddion adran "cyd -destun" dda mewn ADR: * Esboniwch sefyllfa a blaenoriaethau busnes eich sefydliad. * Cynhwyswch resymeg ac ystyriaethau yn seiliedig ar golurion cymdeithasol a sgiliau eich timau. * Cynhwyswch fanteision ac anfanteision sy'n berthnasol, a'u disgrifio mewn termau sy'n cyd -fynd â'ch anghenion a'ch nodau. Nodweddion adran "Canlyniadau" da mewn ADR: * Esboniwch beth sy'n dilyn o wneud y penderfyniad. Gall hyn gynnwys yr effeithiau, canlyniadau, allbynnau, gwaith dilynol, a mwy. * Cynhwyswch wybodaeth am unrhyw ADRs dilynol. Mae'n gymharol gyffredin i un ADR sbarduno'r angen am fwy o ADRs, megis pan fydd un ADR yn gwneud dewis trosfwaol mawr, sydd yn ei dro yn creu anghenion am benderfyniadau mwy llai. * Cynhwyswch unrhyw brosesau adolygu ar ôl gweithredu. Mae'n nodweddiadol i dimau adolygu pob ADR fis yn ddiweddarach, i gymharu'r wybodaeth ADR â'r hyn sydd wedi digwydd mewn ymarfer gwirioneddol, er mwyn dysgu a thyfu. Gall ADR newydd gymryd lle ADR blaenorol: * Pan wneir hysbyseb sy'n disodli neu'n annilysu ADR blaenorol, yna dylid creu ADR newydd ================================================ FILE: locales/cy/nogfennau/beth-yw-cofnod-penderfyniad-pensaernïaeth/.locale-peer-id ================================================ 020ff535ed1a3347a265209291e756b6 ================================================ FILE: locales/cy/nogfennau/beth-yw-cofnod-penderfyniad-pensaernïaeth/index.md ================================================ ## Beth yw cofnod penderfyniad pensaernïaeth? Mae Cofnod Penderfyniad Pensaernïaeth ** ** (ADR) yn ddogfen sy'n cyfleu penderfyniad pensaernïol pwysig a wnaed ynghyd â'i gyd -destun a'i ganlyniadau. Mae Penderfyniad Pensaernïaeth ** ** (AD) yn ddewis dylunio meddalwedd sy'n mynd i'r afael â gofyniad sylweddol. Log Penderfyniad Pensaernïaeth ** ** (ADL) yw'r casgliad o'r holl ADRs a grëwyd ac a gynhelir ar gyfer prosiect (neu sefydliad) penodol. Mae gofyniad pensaernïol arwyddocaol ** (ASR) yn ofyniad sy'n cael effaith fesuradwy ar bensaernïaeth system feddalwedd. Mae'r rhain i gyd o fewn pwnc ** Rheoli Gwybodaeth Pensaernïaeth ** (AKM). Nod y ddogfen hon yw darparu trosolwg cyflym o ADRs, sut i'w creu, a ble i chwilio am ragor o wybodaeth. Byrfoddau: *** AD **: Penderfyniad Pensaernïaeth *** ADL **: log penderfyniad pensaernïaeth *** ADR **: cofnod penderfyniad pensaernïaeth *** AKM **: Rheoli Gwybodaeth Bensaernïaeth *** ASR **: gofyniad pensaernïol arwyddocaol ================================================ FILE: locales/cy/nogfennau/canllawiau-i-gyflawni-penderfyniadau-cynaliadwy/.locale-peer-id ================================================ 934d1c42a693fe004cd8bf8f5ecb97e6 ================================================ FILE: locales/cy/nogfennau/canllawiau-i-gyflawni-penderfyniadau-cynaliadwy/index.md ================================================ # Canllawiau i gyflawni penderfyniadau cynaliadwy Fe wnaethon ni ddysgu'r gwersi canlynol yn ein gwaith a all wasanaethu fel canllawiau ac asesiad ar gyfer cyflawni penderfyniadau cynaliadwy: 1. Defnyddiwch ddull main/minimalaidd ar gyfer y ddogfennaeth penderfyniad cychwynnol. 2. Blaenoriaethu a dal yr holl benderfyniadau pwysig sy'n ddigon perthnasol ar gyfer dogfennu a deall y bensaernïaeth darged. 3. Manylion y penderfyniadau arbennig o bwysig gyda thempledi wedi'u chwythu'n llawn dim ond ar ôl i'r gwaith cychwynnol gael ei wneud (hynny yw, pan fydd y rhai sy'n gwneud penderfyniadau yn fodlon â'r penderfyniadau pensaernïol a wnaed ac yn hyderus nad oes rhaid i'r penderfyniadau hyn gael eu hadolygu ar unrhyw adeg yn fuan ). 4. Defnyddiwch y fersiynau heb lawer o fraster/minimalaidd o Gam 1 fel fersiwn fer o benderfyniadau wedi'u dogfennu gyda'r lefel gronynnedd gywir i ddarparu trosolwg o'r penderfyniadau manwl, yn ogystal ag ar gyfer penderfyniadau dibwys neu amlwg. 5. Lle bynnag y bo hynny'n bosibl, defnyddiwch wybodaeth bensaernïol bresennol, naill ai o fodelau canllaw neu o ffynonellau eraill. Adolygu ac ymestyn gwybodaeth o'r fath a'i ffitio i gyd -destun y penderfyniad penodol. 6. Sicrhewch fod cysylltiadau olrhain yn cael eu sefydlu rhwng penderfyniadau a gofynion a dyluniadau/cod pensaernïol. 7. Darparu gwirio cysondeb awtomataidd i sicrhau bod y cysylltiadau olrhain mewn sync ar ôl newid. Cyfyngu ar nifer y dibyniaethau rhwng penderfyniadau ac arteffactau meddalwedd eraill. 8 Cymhwyso'r canllawiau ar gyfer y cyfiawnhad o ganlyniad ac yn rymus - dyna ran bwysicaf y ddogfennaeth benderfynu oherwydd eu bod yn rhoi'r rhesymeg. ================================================ FILE: locales/cy/nogfennau/confensiynau-enw-ffeil/.locale-peer-id ================================================ 89116b5647aa1e53186f3c44b5a284a0 ================================================ FILE: locales/cy/nogfennau/confensiynau-enw-ffeil/index.md ================================================ # Confensiynau Enw Ffeil Os dewiswch greu eich ADRs gan ddefnyddio ffeiliau testun nodweddiadol, yna efallai yr hoffech feddwl am eich Confensiwn Enw Ffeil ADR eich hun. Mae'n well gennym ddefnyddio confensiwn enw ffeil sydd â fformat penodol. Enghreifftiau: * dewiswch-database.md * format-timestamps.md * rheoli-passwords.md * trin-exceptions.md Ein Confensiwn Enw Ffeil: * Mae gan yr enw ymadrodd berf hanfodol amser presennol. Mae hyn yn helpu darllenadwyedd ac yn cyd -fynd â'n fformat neges ymrwymo. * Mae'r enw'n defnyddio llythrennau bach a rhuthrau (yr un fath â'r repo hwn). Mae hwn yn gydbwysedd o ddarllenadwyedd a defnyddioldeb system. * Mae'r estyniad yn marcio. Gall hyn fod yn ddefnyddiol ar gyfer fformatio hawdd. ================================================ FILE: locales/cy/nogfennau/cwestiynau-gwaith-tîm-ar-gyfer-adrau/.locale-peer-id ================================================ 60057747e4547af35fd888021e41f332 ================================================ FILE: locales/cy/nogfennau/cwestiynau-gwaith-tîm-ar-gyfer-adrau/index.md ================================================ ## Cwestiynau gwaith tîm ar gyfer ADRau ### Pwy all greu ADR? Ystyriwch feysydd fel pobl benodol, neu rolau penodol, neu dimau penodol, neu adrannau penodol; ystyriwch hefyd a oes pobl, neu rolau, neu dimau, neu adran a all gomisiynu ADR, sy'n golygu eu bod yn gofyn am un y bydd rhywun arall yn ei awduro. Ateb enghreifftiol: Gall unrhyw berson yn ein sefydliad sydd wedi darllen tudalen README cofnod penderfyniad pensaernïaeth gynnig ADR, sy'n golygu y gall y person ddechrau ei ysgrifennu, a'i rannu gyda'r tîm. ### Beth sy'n cyfiawnhau codi ADR? Ystyriwch feysydd fel ffyrdd gweithio tîm eich sefydliad, strwythur eich system feddalwedd, cydlynu traws-dîm, cynaladwyedd hirdymor, rhyngwynebau allanol, pwy rydych chi am iddo fod o fudd, a'r cyffelyb. Ateb enghreifftiol: Rydym am greu ADR pan fyddwn am i ddatblygwyr y dyfodol ddeall y "pam" dros yr hyn rydym yn ei wneud. ### Beth sy'n cyfiawnhau peidio â chodi ADR? Ystyriwch feysydd fel penderfyniadau nad ydynt yn ymwneud â phensaernïaeth, neu sy'n fach fel risg leiaf neu hunangynhwysol neu ddatblygwr sengl, neu sydd eisoes wedi'u cynnwys yn llawn mewn mannau eraill fel gan safonau neu bolisïau neu ddogfennaeth, neu sy'n dros dro fel atebion dros dro neu brofion o gysyniadau neu arbrofion. Ateb enghreifftiol: Rydym am hepgor ADR pan fo penderfyniad yn gyfyngedig o ran cwmpas ac amser a risg a chost, neu pan fydd eisoes wedi'i gynnwys mewn mannau eraill. ### Beth yw cylch bywyd ADR? Ystyriwch feysydd fel y broses greu, y broses ymchwil, y broses benderfynu, y broses weithredu, a'r broses machlud. Ystyriwch sut i olrhain cylch bywyd yr ADR dros amser, fel sut i symud yr ADR o un cyflwr i'r cyflwr nesaf, a hefyd sut i gyfleu hyn i randdeiliaid. Ateb enghreifftiol: Rydym am i ADR gael cam cylch bywyd: Cychwyn → Ymchwilio → Gwerthuso → Gweithredu → Cynnal → Machlud. ### Beth yw'r meini prawf ar gyfer camau cylch bywyd ADR? Ystyriwch feysydd fel meini prawf derbyn ar gyfer ADR, sy'n golygu sut ydych chi'n gwybod ei fod yn ddigon da i symud ymlaen o un cam cylch bywyd i'r nesaf? A yw'r broblem wedi'i mynegi'n glir? A yw'r dewisiadau amgen wedi'u hystyried? A yw cyfaddawdau wedi'u deall a'u dogfennu'n ddigon da? A yw'r holl gyd-destun perthnasol ar waith? A yw'r holl randdeiliaid perthnasol wedi'u cynnwys? A yw'r holl adborth wedi'i ymgorffori? Ateb enghreifftiol: Rydym am i randdeiliaid bleidleisio ar ADR pan fydd y tîm gweithredol wedi 1) cwblhau eu hymchwil, 2) cwblhau eu gwerthusiad, 3) cyhoeddi'r cynnig ADR i'r rhanddeiliaid gyda chais am sylwadau ac amserlen o un wythnos, 4) bod yr holl sylwadau gan randdeiliaid wedi'u hymgorffori a'u trin. ### Pa rolau a chyfrifoldebau sy'n rhyngweithio ag ADR? Ystyriwch rolau fel cynigydd, ymchwilydd, gwerthuswr, adolygydd, cymeradwywr, cynhaliwr, a'r fel. Ystyriwch gyfrifoldebau fel cyfathrebu â rhanddeiliaid, sicrhau bod disgwyliadau'n cael eu bodloni, rhannu ar y wefan neu'r fewnrwyd, ac adolygu'r gwaith yn rheolaidd ac yn enwedig pan fydd newidiadau perthnasol yn digwydd. Ateb enghreifftiol: Rydym am i bob ADR gael prif berson cyswllt, ail berson cyswllt, a thîm atebol bob amser; mae'r rhain yn gyfrifol am gyfathrebu, cyhoeddiadau, cynnal a chadw, adolygiad cyfnodol o leiaf unwaith y flwyddyn, a'i machlud yn y pen draw yn ôl yr angen. ### Sut mae llywodraethu'n rhyngweithio ag ADR? Ystyriwch feysydd fel ffyrdd gweithio eich sefydliad, unrhyw anghenion cydymffurfio arbennig fel ar gyfer agweddau cyfreithiol neu agweddau adnoddau dynol, sut rydych chi am ymdrin â chonsensws yn erbyn gwrthdaro yn erbyn dwysáu. A oes meysydd neu bobl neu dimau a all gael mwy o ddylanwad nag eraill ynghylch ADR, fel gallu ei gymeradwyo, neu bleidleisio arno, neu ei feto? Ateb enghreifftiol: Mae llywodraethu ADR yn y drefn flaenoriaeth hon: y Prif Swyddog Gweithredol, y Prif Swyddog Technoleg, y Prif Swyddog Cyswllt, y tîm sy'n gweithredu ADR, yr arbenigwyr yn y tîm sydd fwyaf gwybodus am yr ADD. Nid oes gan unrhyw un arall lywodraethu oni bai ei fod wedi'i ddisgrifio yn y ADR. ### Pa egwyddorion sy'n rhyngweithio ag ADR? Ystyriwch feysydd fel ffyrdd gweithio eich sefydliad sy'n cynnwys symud yn gyflym yn erbyn symud yn araf, ar gyfer consensws penderfyniadau yn erbyn gwrthdaro penderfyniadau, ac ar gyfer dewisiadau risg yn erbyn dewisiadau diogelwch, trafodaeth gyhoeddus yn erbyn trafodaeth breifat, a'r cyffelyb. Ateb enghreifftiol: Rydym yn defnyddio egwyddorion arweinyddiaeth rhagfarn ar gyfer gweithredu, anghytuno ac ymrwymo, mae amcangyfrifon o 70% yn ddigon da ar gyfer penderfyniadau y gellir eu gwrthdroi'n hawdd ac y gellir eu hynysu'n hawdd, a ffyrdd cyhoeddus o weithio ac eithrio gwybodaeth gyfrinachol fel y disgrifir yng nghytundeb cyfrinachedd ein sefydliad. ================================================ FILE: locales/cy/nogfennau/cyngor-gwaith-tîm-ar-gyfer-adrs/.locale-peer-id ================================================ 875a7715e592ceb45eac5e155ee16318 ================================================ FILE: locales/cy/nogfennau/cyngor-gwaith-tîm-ar-gyfer-adrs/index.md ================================================ # Cyngor gwaith tîm ar gyfer ADRs Os ydych chi'n ystyried defnyddio cofnodion penderfyniadau gyda'ch tîm, yna dyma ychydig o gyngor rydyn ni wedi'i ddysgu trwy weithio gyda llawer o dimau. Mae gennych gyfle i arwain eich cyd -chwaraewyr, trwy siarad gyda'i gilydd am y "pam", yn hytrach na gorfodi'r "beth". Er enghraifft, mae cofnodion penderfyniadau yn ffordd i dimau feddwl yn ddoethach a chyfathrebu'n well; Nid yw cofnodion penderfyniadau yn werthfawr os mai dim ond gofyniad gwaith papur gorfodol ar ôl y ffaith ydyn nhw. Mae'n well gan rai timau'r enw "penderfyniadau" dros y talfyriad "ADRS". Pan fydd rhai timau'n defnyddio'r enw cyfeiriadur "penderfyniadau", yna mae fel petai bwlb golau yn troi ymlaen, ac mae'r tîm yn dechrau rhoi mwy o wybodaeth yn y cyfeiriadur, megis penderfyniadau gwerthwr, penderfyniadau cynllunio, penderfyniadau amserlennu, ac ati. Mae'r holl fathau hyn o Gall gwybodaeth ddefnyddio'r un templed. Rydym yn damcaniaethu bod pobl yn dysgu'n gyflymach gyda geiriau ("penderfyniadau") dros fyrfoddau ("ADRs"), ac mae pobl yn fwy cymhelliant i ysgrifennu docs gwaith ar y gweill pan fydd y gair "record" yn cael ei dynnu, a hefyd rhai datblygwyr a rhai rheolwyr Ddim yn hoffi'r gair "pensaernïaeth". Mewn theori, mae anfarwoldeb yn ddelfrydol. Yn ymarferol, mae treiglad wedi gweithio'n well i'n timau. Rydym yn mewnosod y wybodaeth newydd yr ADR presennol, gyda stamp dyddiad, a nodyn bod y wybodaeth wedi cyrraedd ar ôl y penderfyniad. Mae'r math hwn o ddull yn arwain at "ddogfen fyw" y gallwn ni i gyd ei diweddaru. Diweddariadau nodweddiadol yw pan gawn wybodaeth diolch i gyd-chwaraewyr newydd, neu offrymau newydd, neu ganlyniadau'r byd go iawn o'n defnyddiau, neu newidiadau trydydd parti ar ôl y ffaith fel capabilties gwerthwyr, cynlluniau prisio, cytundebau trwydded, ac ati. ================================================ FILE: locales/cy/nogfennau/meini-prawf-cynaliadwyedd-penderfynu/.locale-peer-id ================================================ 71d59ed566ae148b8bf42331a84754ac ================================================ FILE: locales/cy/nogfennau/meini-prawf-cynaliadwyedd-penderfynu/index.md ================================================ # Meini Prawf Cynaliadwyedd Penderfynu Er mwyn diffinio cynaliadwyedd penderfyniadau yn fanwl, gwnaethom ddeillio pum maen prawf allweddol. ## Strategol Wrth wneud penderfyniadau, dylai rhywun sy’n edrych ar ganlyniadau strategol ystyried pethau fel effaith hirdymor y penderfyniadau ’-er enghraifft, gweithrediadau yn y dyfodol ac ymdrech cynnal a chadw. ## Mesuradwy ac yn hylaw Gallwch fesur a gwerthuso canlyniad penderfyniad dros amser yn unol â meini prawf gwrthrychol, yn ddelfrydol rhai rhifol (fel, er enghraifft, wedi'u lluosogi gan senarios priodoledd ansawdd a gweithdai4). Nid yw dal yr holl benderfyniadau graen mân yn bosibl, felly rhaid i benseiri gyfyngu gronynnedd y penderfyniadau i lefel benodol o fanylion (megis creu dosbarth dylunio). Bydd hyn yn arwain at set fwy cynaliadwy o benderfyniadau a llai o gysylltiadau olrhain. Ar ben hynny, mae cyfyngu ar nifer y dibyniaethau rhwng penderfyniadau yn lleihau effaith cryfhau newidiadau. ## Cyflawnadwy a realistig Dylai'r rhesymeg dros ffitio'r ateb i'r broblem gael ei ddewis yn bragmatig a'i wneud yn eglur. Er enghraifft, gall penseiri nodi eu bod wedi cymryd gofal i osgoi gor-beiriannu neu danseilio (hynny yw, dylent gymhwyso'r dull “digon da”). ## wedi'i wreiddio mewn gofynion Dylai gwneud penderfyniadau gael ei seilio ar brofiad pensaernïaeth a chyd-destun pensaernïaeth parth-benodol. Dylai ystyried amgylchedd y cwmni yn ogystal â gofynion a chyfyngiadau prosiect, gan gynnwys sgiliau cyfredol y tîm datblygu, cyllideb hyfforddi a phroses. ## Amserol Dylai penderfyniadau fod yn seiliedig ar brofiad a gwybodaeth nad ydynt yn debygol o fod wedi dyddio cyn bo hir. Er enghraifft, gall penseiri ddewis patrymau neu dactegau pensaernïol niwtral platfform. ================================================ FILE: locales/cy/nogfennau/proses-cofnodion-penderfynol-pensaernïol-aws/.locale-peer-id ================================================ 7d4adf16004ca42546dee49922ae4ccf ================================================ FILE: locales/cy/nogfennau/proses-cofnodion-penderfynol-pensaernïol-aws/index.md ================================================ # Proses Cofnodion Penderfynol Pensaernïol AWS https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html Mae cofnod penderfyniad pensaernïol (ADR) yn ddogfen sy'n disgrifio dewis y mae'r tîm yn ei wneud am agwedd sylweddol ar y bensaernïaeth feddalwedd y maent yn bwriadu ei hadeiladu. Mae pob ADR yn disgrifio'r penderfyniad pensaernïol, ei gyd -destun, a'i ganlyniadau. Mae gan ADRs wladwriaethau ac felly'n dilyn cylch bywyd. Am enghraifft o ADR, gweler yr Atodiad. Mae'r broses ADR yn allbynnu casgliad o gofnodion penderfyniadau pensaernïol. Mae'r casgliad hwn yn creu'r log penderfyniadau. Mae'r log penderfyniadau yn darparu cyd -destun y prosiect yn ogystal â gwybodaeth weithredu a dylunio fanwl. Mae aelodau'r prosiect yn sgimio penawdau pob ADR i gael trosolwg o gyd -destun y prosiect. Maent yn darllen yr ADRs i blymio'n ddwfn i weithrediadau prosiect a dewisiadau dylunio. Pan fydd y tîm yn derbyn ADR, mae'n dod yn anadferadwy. Os oes angen penderfyniad gwahanol ar fewnwelediadau newydd, mae'r tîm yn cynnig ADR newydd. Pan fydd y tîm yn derbyn yr ADR newydd, mae'n disodli'r ADR blaenorol. ## Cwmpas y broses ADR Dylai aelodau'r prosiect greu ADR ar gyfer pob penderfyniad pensaernïol arwyddocaol sy'n effeithio ar y prosiect meddalwedd neu'r cynnyrch, gan gynnwys y canlynol (Richards a Ford 2020): * Strwythur (er enghraifft, patrymau fel microservices) * Gofynion an swyddogaethol (diogelwch, argaeledd uchel, a goddefgarwch nam) * Dibyniaethau (cyplu cydrannau) * Rhyngwynebau (APIs a chontractau cyhoeddedig) * Technegau adeiladu (llyfrgelloedd, fframweithiau, offer a phrosesau) * Gofynion swyddogaethol ac an swyddogaethol yw'r mewnbynnau mwyaf cyffredin i'r broses ADR. ## CYNNWYS ADR Pan fydd y tîm yn nodi'r angen am ADR, mae aelod o'r tîm yn dechrau ysgrifennu'r ADR yn seiliedig ar dempled ledled y prosiect. (Gweler Sefydliad ADR GitHub er enghraifft templedi.) Mae'r templed yn symleiddio creu ADR ac yn sicrhau bod yr ADR yn cyfleu'r holl wybodaeth berthnasol. O leiaf, dylai pob ADR ddiffinio cyd -destun y penderfyniad, y penderfyniad ei hun, a chanlyniadau'r penderfyniad ar gyfer y prosiect a'i gyflawniadau. (Am enghreifftiau o'r adrannau hyn, gweler yr Atodiad.) Un o agweddau mwyaf pwerus strwythur yr ADR yw ei fod yn canolbwyntio ar y rheswm dros y penderfyniad yn hytrach na sut y gwnaeth y tîm ei weithredu. Mae deall pam y gwnaeth y tîm y penderfyniad yn ei gwneud hi'n haws i aelodau eraill y tîm fabwysiadu'r penderfyniad, ac mae'n atal penseiri eraill nad oeddent yn rhan o'r broses benderfynu i ddiystyru'r penderfyniad hwnnw yn y dyfodol. ## Proses fabwysiadu ADR Gall pob aelod o'r tîm greu ADR, ond dylai'r tîm sefydlu diffiniad o berchnogaeth ar gyfer ADR. Dylai pob awdur sy'n berchennog ADR gynnal a chyfleu'r cynnwys ADR yn weithredol. Er mwyn egluro'r berchnogaeth hon, mae'r canllaw hwn yn cyfeirio at awduron ADR fel perchnogion ADR yn yr adrannau canlynol. Gall aelodau eraill y tîm bob amser gyfrannu at ADR. Os yw cynnwys ADR yn newid cyn i'r tîm dderbyn yr ADR, dylai'r perchennog gymeradwyo'r newidiadau hyn. Ar ôl i'r tîm nodi penderfyniad pensaernïol a'i berchennog, mae perchennog yr ADR yn darparu'r ADR yn y wladwriaeth ** ** ** ar ddechrau'r broses. Mae ADRs yn y wladwriaeth arfaethedig yn barod i'w hadolygu. Yna mae perchennog yr ADR yn cychwyn y broses adolygu ar gyfer yr ADR. Nod y broses adolygu ADR yw penderfynu a yw'r tîm yn derbyn yr ADR, yn penderfynu bod angen ei ailweithio, neu'n gwrthod yr ADR. Mae tîm y prosiect, gan gynnwys y perchennog, yn adolygu'r ADR. Dylai'r cyfarfod adolygu ddechrau gyda slot amser pwrpasol i ddarllen yr ADR. Ar gyfartaledd, dylai 10 i 15 munud fod yn ddigon. Yn ystod yr amser hwn, mae pob aelod o'r tîm yn darllen y ddogfen ac yn ychwanegu sylwadau a chwestiynau i dynnu sylw at bynciau aneglur. Ar ôl y cam adolygu, mae perchennog yr ADR yn darllen allan ac yn trafod pob sylw gyda'r tîm. Os yw'r tîm yn dod o hyd i bwyntiau gweithredu i wella'r ADR, mae cyflwr yr ADR yn aros ** arfaethedig **. Mae perchennog ADR yn llunio'r gweithredoedd, ac, mewn cydweithrediad â'r tîm, yn ychwanegu aseinai at bob gweithred. Gall pob aelod o'r tîm gyfrannu a datrys y pwyntiau gweithredu. Cyfrifoldeb perchennog yr ADR yw aildrefnu'r broses adolygu. Gall y tîm hefyd benderfynu gwrthod yr ADR. Yn yr achos hwn, mae perchennog yr ADR yn ychwanegu rheswm dros y gwrthod i atal trafodaethau ar yr un pwnc yn y dyfodol. Mae'r perchennog yn newid y wladwriaeth ADR i ** Gwrthod **. Os yw'r tîm yn cymeradwyo'r ADR, mae'r perchennog yn ychwanegu stamp amser, fersiwn, a rhestr o randdeiliaid. Yna mae'r perchennog yn diweddaru'r wladwriaeth i ** a dderbynnir **. Mae ADRs a'r log penderfyniadau y maent yn ei greu yn cynrychioli penderfyniadau a wneir gan y tîm ac yn darparu hanes o'r holl benderfyniadau. Mae'r tîm yn defnyddio'r ADRs fel cyfeiriad yn ystod adolygiadau cod a phensaernïol lle bo hynny'n bosibl. Yn ogystal â pherfformio adolygiadau cod, tasgau dylunio, a thasgau gweithredu, dylai aelodau'r tîm ymgynghori ag ADRs ar gyfer penderfyniadau strategol ar gyfer y cynnyrch. Fel arfer da, dylai pob newid meddalwedd fynd trwy adolygiadau cymheiriaid ac mae angen o leiaf un gymeradwyaeth. Yn ystod yr adolygiad cod, gallai adolygydd cod ddod o hyd i newidiadau sy'n torri un neu fwy o ADRs. Yn yr achos hwn, mae'r adolygydd yn gofyn i awdur y newid cod ddiweddaru'r cod, ac mae'n rhannu dolen i'r ADR. Pan fydd yr awdur yn diweddaru'r cod, caiff ei gymeradwyo gan adolygwyr cymheiriaid a'i uno â'r prif sylfaen cod. ## Proses Adolygu ADR Dylai'r tîm drin ADRs fel dogfennau na ellir eu symud ar ôl i'r tîm eu derbyn neu eu gwrthod. Mae angen creu ADR newydd, sefydlu proses adolygu ar gyfer yr ADR newydd i newidiadau i ADR sy'n bodoli eisoes, a chymeradwyo'r ADR. Os yw'r tîm yn cymeradwyo'r ADR newydd, dylai'r perchennog newid cyflwr yr hen ADR i ** disodli **. ================================================ FILE: locales/cy/nogfennau/sut-i-ddechrau-defnyddio-adrs/.locale-peer-id ================================================ 8196518140224596af99a46d512feba3 ================================================ FILE: locales/cy/nogfennau/sut-i-ddechrau-defnyddio-adrs/index.md ================================================ # Sut i ddechrau defnyddio ADRs I ddechrau defnyddio ADRs, siaradwch â'ch cyd -chwaraewyr am yr ardaloedd hyn. Adnabod Penderfyniadau: * Pa mor frys a pha mor bwysig yw'r hysbyseb? * A oes rhaid ei wneud nawr, neu a all aros nes bod mwy yn hysbys? * Gall profiad personol a chyfunol, yn ogystal â dulliau ac arferion dylunio cydnabyddedig, gynorthwyo gydag adnabod penderfyniadau. * Yn ddelfrydol, cadw rhestr todo penderfyniad sy'n ategu'r rhestr TODO cynnyrch. Gwneud penderfyniadau: * Mae nifer o dechnegau gwneud penderfyniadau yn bodoli, mae rhai cyffredinol a phensaernïaeth meddalwedd yn benodol i rai, er enghraifft, mapio deialog. * Mae gwneud penderfyniadau grŵp yn bwnc ymchwil gweithredol. Deddfu a gorfodi penderfyniadau: * Defnyddir hysbysebion wrth ddylunio meddalwedd; Felly mae'n rhaid eu cyfleu i randdeiliaid y system sy'n cronni, datblygu a gweithredu gan, a derbyn. * Mae arddulliau codio amlwg yn bensaernïol ac adolygiadau cod sy'n canolbwyntio ar bryderon pensaernïol a phenderfyniadau yn ddau arfer cysylltiedig. * Rhaid ystyried hysbysebion hefyd (ail-) wrth foderneiddio system feddalwedd yn esblygiad meddalwedd. Rhannu Penderfyniadau (dewisol): * Mae llawer o hysbysebion yn digwydd eto ar draws prosiectau. * Felly, gall profiadau â phenderfyniadau yn y gorffennol, da a drwg, fod yn asedau gwerthfawr y gellir eu hailddefnyddio wrth ddefnyddio strategaeth rheoli gwybodaeth benodol. Dogfennaeth Penderfyniad: * Mae llawer o dempledi ac offer ar gyfer dal penderfyniadau yn bodoli. * Gweler cymunedau ystwyth, e.e. ADRs M. Nygard. * Gweler Prosesau Peirianneg Meddalwedd a Phensaernïaeth Traddodiadol, e.e. Cynlluniau bwrdd a awgrymwyd gan IBM UMF a chan Tyree ac Akerman o Capitalone. Am fwy: * Mabwysiadir y camau uchod o'r cofnod Wikipedia ar [penderfyniad pensaernïol] (https://en.wikipedia.org/wiki/Architectural_Decision) ================================================ FILE: locales/cy/nogfennau/sut-i-ddechrau-defnyddio-adrs-gyda-git/.locale-peer-id ================================================ d6fb3c7d91f95003163e694e74058e9d ================================================ FILE: locales/cy/nogfennau/sut-i-ddechrau-defnyddio-adrs-gyda-git/index.md ================================================ # Sut i ddechrau defnyddio ADRs gyda git Os ydych chi'n hoffi defnyddio rheolaeth fersiwn GIT, yna dyma sut rydyn ni'n hoffi dechrau defnyddio ADRs gyda GIT ar gyfer prosiect meddalwedd nodweddiadol gyda'r cod ffynhonnell. Creu cyfeiriadur ar gyfer ffeiliau ADR: `` `sh $ mkdir adr `` ` Ar gyfer pob ADR, crëwch ffeil testun, fel `database.txt`: `` `sh $ vi database.txt `` ` Ysgrifennwch unrhyw beth rydych chi ei eisiau yn yr ADR. Gweler y templedi yn yr ystorfa hon am syniadau. Ymrwymwch yr ADR i'ch repo git. ================================================ FILE: locales/cy/nogfennau/sut-i-ddechrau-defnyddio-adrs-gydag-offer/.locale-peer-id ================================================ 1a5a03dd6f20cea9f78fb4655a9a7f87 ================================================ FILE: locales/cy/nogfennau/sut-i-ddechrau-defnyddio-adrs-gydag-offer/index.md ================================================ ## Sut i ddechrau defnyddio ADRs gydag offer Gallwch chi ddechrau defnyddio ADRs gydag offer unrhyw ffordd rydych chi ei eisiau. Er enghraifft: * Os ydych chi'n hoffi defnyddio Google Drive a Golygu Ar -lein, yna gallwch chi greu Google Doc, neu Google Sheet. * Os ydych chi'n hoffi defnyddio rheolaeth fersiwn cod ffynhonnell, fel Git, yna gallwch chi greu ffeil ar gyfer pob ADR. * Os ydych chi'n hoffi defnyddio offer cynllunio prosiect, fel Atlassian Jira, yna gallwch ddefnyddio traciwr cynllunio'r offeryn. * Os ydych chi'n hoffi defnyddio wicis, fel mediawiki, yna gallwch chi greu wici ADR. ================================================ FILE: locales/cy/templedi/.locale-peer-id ================================================ 70f1f9b3530831bc891a6e9b9b0d27de ================================================ FILE: locales/cy/templedi/index.md ================================================ # Templedi cofnodion penderfyniadau * [Templed cofnod penderfyniad gan Jeff Tyree ac Art Akerman](templed-cofnod-penderfyniad-gan-jeff-tyree-and-art-akerman) * [Templed cofnod penderfyniad gan Michael Nygard](templed-cofnod-penderfyniad-gan-michael-nygard) * [Templed cofnod penderfyniad gan EdgeX](templed-cofnod-penderfyniad-gan-edgex) * [Templed cofnod penderfyniad ar gyfer patrwm Alecsandraidd](templed-cofnod-penderfyniad-ar-gyfer-patrwm-alecsandraidd) * [Templed cofnod penderfyniad ar gyfer achos busnes](templed-cofnod-penderfyniad-ar-gyfer-achos-busnes) * [Templed cofnod benderfyniad y Prosiect MADR](templed-cofnod-penderfyniad-y-prosiect-madr) * [Templed cofnod penderfyniad gan ddefnyddio Planguage](templed-cofnod-penderfyniad-gan-planguage) ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-ar-gyfer-achos-busnes/.locale-peer-id ================================================ f6d1fb662640a00f4c66c586233dead9 ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-ar-gyfer-achos-busnes/index.md ================================================ # Templed cofnod penderfyniad ar gyfer achos busnes Mae’r templed ADR hwn yn pwysleisio creu achos busnes ar gyfer penderfyniad, gan gynnwys meini prawf, ymgeiswyr, a chostau. ## Lefel uchaf * Teitl * Statws * Meini prawf gwerthuso * Ymgeiswyr i'w hystyried * Ymchwilio a dadansoddi pob ymgeisydd * A yw/ddim yn bodloni'r meini prawf a pham * Dadansoddiad cost * Dadansoddiad SWOT * Barn ac adborth *Argymhelliad ## Plymio dwfn lefel isel **Teitl**: * Cymal hanfodol amser byr, llai na 50 nod, fel neges ymrwymo git. **Statws**: * Un o'r rhai a gynigiwyd, a dderbyniwyd, a wrthodwyd, a anghymeradwywyd, a ddisodlwyd, etc. **Meini prawf gwerthuso**: * Crynodeb: eglurwch yn fyr yr hyn yr ydym yn ceisio ei ddarganfod a pham. * Manylebau **Ymgeiswyr i'w hystyried**: * Crynodeb: eglurwch yn gryno sut y gwnaethom ddarganfod ymgeiswyr, a thynnwch sylw at unrhyw allgleifion. * Rhestrwch yr holl ymgeiswyr a'r opsiynau cysylltiedig; beth ydym yn ei werthuso fel atebion posibl? * Manylebau **Ymchwil a dadansoddiad o bob ymgeisydd**: * Crynodeb: eglurwch yn fyr y dulliau ymchwil, a thynnwch sylw at batrymau, clystyrau, ac allgleifion. * A yw/ddim yn bodloni'r meini prawf a pham * Crynodeb * Manylebau * Dadansoddiad cost * Crynodeb * Enghreifftiau * Trwyddedu, megis cytundebau contract ac ymrwymiadau cyfreithiol * Hyfforddiant, fel uwchsgilio a rheoli newid * Gweithredu, fel cymorth a chynnal a chadw * Mesuryddion, fel lled band a defnydd CPU * Dadansoddiad SWOT * Crynodeb * Cryfderau * Gwendidau * Cyfleoedd * Bygythiadau * Barn ac adborth mewnol * Crynodeb * Enghreifftiau * Gan y tîm, yn ddelfrydol wedi'i ysgrifennu gan y person go iawn * Gan randdeiliaid eraill * Priodoleddau ansawdd a.k.a. gofynion traws-swyddogaethol * Barn ac adborth allanol * Crynodeb * Pwy sy'n rhoi'r farn? * Beth ydych chi wedi ystyried ymgeiswyr eraill? * Beth ydych chi'n ei greu? * Enghreifftiau * B2B neu B2C * wynebu allanol neu gyflogai yn unig * bwrdd gwaith neu ffôn symudol * peilot neu gynhyrchiad * monolith neu ficrowasanaethau * Sut wnaethoch chi werthuso'r ymgeiswyr? * Pam wnaethoch chi ddewis yr enillydd? * Beth sy'n digwydd ers hynny? * Enghreifftiau * Sut mae'r enillydd yn perfformio? * Pa % o draffig defnyddwyr cynhyrchiad y byd go iawn sy'n llifo trwy'r enillydd? * Pa fathau o integreiddiadau sydd dan sylw, megis gyda phiblinellau cyflenwi parhaus, systemau rheoli cynnwys, dadansoddeg a metrigau, ac ati? * Gan wybod beth rydych chi'n ei wybod nawr, beth fyddech chi'n cynghori pobl i'w wneud yn wahanol? * Hanesion **Argymhelliad**: * Crynodeb * Manylebau ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-ar-gyfer-patrwm-alecsandraidd/.locale-peer-id ================================================ f33e4eb0409f956de201b791749dc9aa ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-ar-gyfer-patrwm-alecsandraidd/index.md ================================================ # Templed cofnod penderfyniad ar gyfer patrwm Alecsandraidd ## Rhagymadrodd * Prologue (Crynodeb) * Trafodaeth (Cyd-destun) * Ateb (Penderfyniad) * Canlyniadau (Canlyniadau) ## Manylebau ## * Prologue (Crynodeb) * Datganiad i grynhoi: * Yng nghyd-destun (achos defnydd)
wynebu (pryder)
penderfynon ni ar gyfer (opsiwn)
i gyflawni (ansawdd)
derbyn (anfantais). * Trafodaeth (Cyd-destun) * Yn egluro'r grymoedd sydd ar waith (technegol, gwleidyddol, cymdeithasol, prosiect). * Dyma'r stori sy'n esbonio'r broblem yr ydym am ei datrys. * Ateb * Egluro sut y bydd y penderfyniad yn datrys y broblem. * Canlyniadau * Yn egluro canlyniadau'r penderfyniad dros y tymor hir. * A weithiodd, nid gweithio, ei newid, ei uwchraddio, ac ati. ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-gan-edgex/.locale-peer-id ================================================ 01939db0c341e9092c344d904065da12 ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-gan-edgex/index.md ================================================ # Templed Cofnod Penderfyniad Pensaernïaeth (ADR) yn ei le Mae hwn yn dempled ar gyfer EdgeX Foundry ADR. Ffynhonnell: https://docs.edgexfoundry.org/2.3/design/adr/template/ ### Cyflwynwyr Rhestrwch y rhai sy'n cyflwyno ADR. Fformat: - Enw (Sefydliad) ## Log Newid Rhestrwch y newidiadau i'r ddogfen, gan gynnwys. cyflwr, dyddiad, a PR URL. Mae'r wladwriaeth yn un o: arfaeth, cymeradwy, diwygio, anghymeradwy. Mae'r dyddiad yn llinyn ISO 8601 (BBBB-MM-DD). PR yw’r cais tynnu a gyflwynodd y newid, gan gynnwys gwybodaeth fel y diffynnydd, cyfranwyr, ac adolygwyr. Fformat: - \[ Statws ADR e.e. cymeradwyo, diwygio, ac ati\]\(URL cais tynnu\) BBBB-MM-DD ## Achos(ion) Defnydd Cyfeiriedig Rhestrwch yr holl ddogfennau achos defnydd / gofynion perthnasol. Mae ADR yn gofyn am o leiaf un achos defnydd cymeradwy perthnasol. Fformat: - \[Defnyddiwch Enw'r Achos\]\(URL\) Ychwanegu esboniadau os nad yw'r ADR yn mynd i'r afael â holl ofynion achos defnydd. ## Cyd-destun Disgrifiwch: - sut mae'r dyluniad yn arwyddocaol yn bensaernïol - gwarantu ADR (yn erbyn mater syml a chysylltiadau cyhoeddus i ddatrys problem) - y dull dylunio lefel uchel (manylion a ddisgrifir yn y dyluniad arfaethedig isod) ## Dyluniad Arfaethedig Manylion y dyluniad (heb ddechrau gweithredu lle bo modd). Amlinelliad: - gwasanaethau/modiwlau i gael eu heffeithio (newid) - gwasanaethau/modiwlau newydd i'w hychwanegu - effaith model ac DTO (newidiadau/ychwanegiadau/dileu) - Effaith API (newidiadau / ychwanegiadau / dileu) - effaith cyfluniad cyffredinol (sefydlu adrannau newydd, newidiadau / ychwanegiadau / dileu) - devops effaith ## Ystyriaethau Dogfennu dewisiadau eraill, pryderon, materion ategol neu gysylltiedig, cwestiynau a gododd wrth drafod yr ADR. Nodwch os/sut y cawsant eu datrys neu eu moli. ## Penderfyniad Dogfennu unrhyw fanylion gweithredu pwysig y cytunwyd arnynt, rhybuddion, ystyriaethau yn y dyfodol, materion dylunio sy'n weddill neu'n cael eu gohirio. Dogfennu unrhyw ran o'r gofynion nad ydynt yn cael eu bodloni gan y dyluniad arfaethedig. ## ADRs Cysylltiedig Eraill Rhestrwch unrhyw ADRs perthnasol - megis penderfyniad dylunio ar gyfer is-gydran o nodwedd, dyluniad sydd wedi'i anghymeradwyo o ganlyniad i'r dyluniad hwn, ac ati. Fformat: - \[ADR Title\]\(URL\) - Perthnasedd ## Cyfeiriadau Rhestrwch gyfeiriadau ychwanegol. Fformat: - \[Teitl\]\(URL\) ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-gan-jeff-tyree-and-art-akerman/.locale-peer-id ================================================ f4ca0a94124a91279e1929ea23ab864d ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-gan-jeff-tyree-and-art-akerman/index.md ================================================ # Templed cofnod penderfyniad gan Jeff Tyree ac Art Akerman Dyma'r templed disgrifiad penderfyniad pensaernïaeth a gyhoeddwyd yn ["Architecture Decisions: Demystifying Architecture" gan Jeff Tyree ac Art Akerman, Capital One Financial]( https://www.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions- tyree-05.pdf). * **Mater**: Disgrifiwch y mater dylunio pensaernïol rydych chi'n mynd i'r afael ag ef, heb adael unrhyw gwestiynau ynghylch pam rydych chi'n mynd i'r afael â'r mater hwn nawr. Gan ddilyn ymagwedd finimalaidd, rhowch sylw i'r materion y mae angen mynd i'r afael â hwy ar wahanol adegau yn ystod y cylch bywyd a'u dogfennu. * **Penderfyniad**: Nodwch yn glir gyfeiriad y bensaernïaeth - hynny yw, y swydd rydych chi wedi'i dewis. * **Statws**: Statws y penderfyniad, megis yr arfaeth, y penderfynwyd arno, neu a gymeradwywyd. * **Grŵp**: Gallwch ddefnyddio grwpio syml - fel integreiddio, cyflwyniad, data, ac yn y blaen - i helpu i drefnu'r set o benderfyniadau. Gallech hefyd ddefnyddio ontoleg pensaernïaeth fwy soffistigedig, fel John Kyaruzi a Jan van Katwijk's, sy'n cynnwys categorïau mwy haniaethol fel digwyddiad, calendr, a lleoliad. Er enghraifft, gan ddefnyddio'r ontoleg hon, byddech chi'n grwpio penderfyniadau sy'n delio â digwyddiadau lle mae angen gwybodaeth ar y system dan ddigwyddiad. * ** Tybiaethau**: Disgrifiwch yn glir y tybiaethau sylfaenol yn yr amgylchedd lle rydych chi'n gwneud y penderfyniad - cost, amserlen, technoleg, ac ati. Sylwch y gallai cyfyngiadau amgylcheddol (fel safonau technoleg derbyniol, pensaernïaeth menter, patrymau a ddefnyddir yn gyffredin, ac yn y blaen) gyfyngu ar y dewisiadau eraill rydych chi'n eu hystyried. * **Cyfyngiadau**: Nodwch unrhyw gyfyngiadau ychwanegol i'r amgylchedd y gallai'r dewis arall a ddewiswyd (y penderfyniad) ei achosi. * **Swyddi**: Rhestrwch y swyddi (opsiynau hyfyw neu ddewisiadau eraill) y gwnaethoch eu hystyried. Mae'r rhain yn aml yn gofyn am esboniadau hir, weithiau hyd yn oed modelau a diagramau. Nid yw hon yn rhestr gyflawn. Fodd bynnag, nid ydych chi eisiau clywed y cwestiwn "Wnest ti feddwl am...?" yn ystod adolygiad terfynol; mae hyn yn arwain at golli hygrededd a chwestiynu penderfyniadau pensaernïol eraill. Mae’r adran hon hefyd yn helpu i sicrhau eich bod wedi clywed barn pobl eraill; mae datgan barnau eraill yn benodol yn helpu i gofrestru eu heiriolwyr yn eich penderfyniad. * **Dadl**: Amlinellwch pam y dewisoch chi swydd, gan gynnwys eitemau fel cost gweithredu, cyfanswm cost perchnogaeth, amser i’r farchnad, ac argaeledd yr adnoddau datblygu gofynnol. Mae'n debyg bod hyn yr un mor bwysig â'r penderfyniad ei hun. * **Goblygiadau**: Daw llawer o oblygiadau i benderfyniad, fel y mae metamodel REMAP yn ei ddynodi. Er enghraifft, gallai penderfyniad gyflwyno angen i wneud penderfyniadau eraill, creu gofynion newydd, neu addasu gofynion presennol; gosod cyfyngiadau ychwanegol ar yr amgylchedd; gofyn am ail-negodi cwmpas neu amserlen gyda chwsmeriaid; neu angen hyfforddiant staff ychwanegol. Yn amlwg, gall deall a datgan goblygiadau eich penderfyniad fod yn effeithiol iawn wrth ennill cefnogaeth a chreu map ffordd ar gyfer gweithredu pensaernïaeth. * **Penderfyniadau cysylltiedig**: Mae’n amlwg bod llawer o benderfyniadau yn gysylltiedig; gallwch eu rhestru yma. Fodd bynnag, yn ymarferol, rydym wedi canfod bod matrics olrhain, coed penderfynu, neu fetamodelau yn fwy defnyddiol. Mae metafodelau yn ddefnyddiol ar gyfer dangos perthnasoedd cymhleth ar ffurf diagramau (fel modelau Rose). * **Gofynion cysylltiedig**: Dylai penderfyniadau gael eu gyrru gan fusnes. I ddangos atebolrwydd, mapiwch eich penderfyniadau yn benodol i'r amcanion neu'r gofynion. Gallwch gyfrif y gofynion cysylltiedig hyn yma, ond rydym wedi ei chael yn fwy cyfleus cyfeirio at fatrics olrhain. Gallwch asesu cyfraniad pob penderfyniad pensaernïaeth at fodloni pob gofyniad, ac yna asesu pa mor dda y bodlonir y gofyniad ar draws pob penderfyniad. Os nad yw penderfyniad yn cyfrannu at fodloni gofyniad, peidiwch â gwneud y penderfyniad hwnnw. * **Arteffactau cysylltiedig**: Rhestrwch y dogfennau pensaernïaeth, dyluniad neu gwmpas cysylltiedig y mae'r penderfyniad hwn yn effeithio arnynt. * **Egwyddorion cysylltiedig**: Os oes gan y fenter set o egwyddorion y cytunwyd arnynt, gwnewch yn siŵr bod y penderfyniad yn gyson ag un neu fwy ohonynt. Mae hyn yn helpu i sicrhau aliniad ar hyd parthau neu systemau. * **Nodiadau**: Gan fod y broses benderfynu yn gallu cymryd wythnosau, rydym wedi ei chael yn ddefnyddiol i gasglu nodiadau a materion y mae’r tîm yn eu trafod yn ystod y broses gymdeithasoli. ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-gan-michael-nygard/.locale-peer-id ================================================ b1e90e6556c1c8f1e2eb3ac22c8c5077 ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-gan-michael-nygard/index.md ================================================ # Templed cofnod penderfyniad gan Michael Nygard Dyma'r templed yn [Dogfennu penderfyniadau pensaernïaeth - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). Gallwch ddefnyddio [adr-tools](https://github.com/npryce/adr-tools) ar gyfer rheoli'r ffeiliau ADR. Ym mhob ffeil ADR, ysgrifennwch yr adrannau hyn: # Teitl ## Statws Beth yw'r statws, megis y rhai a gynigir, a dderbyniwyd, a wrthodwyd, a anghymeradwywyd, a ddisodlwyd, ac ati? ## Cyd-destun Beth yw'r mater yr ydym yn ei weld sy'n ysgogi'r penderfyniad neu'r newid hwn? ## Penderfyniad Beth yw'r newid rydym yn ei gynnig a/neu'n ei wneud? ## Canlyniadau Beth sy'n dod yn haws neu'n anos i'w wneud oherwydd y newid hwn? ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-gan-planguage/.locale-peer-id ================================================ bb37e19df57d398b0704d6bd30ee6e6d ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-gan-planguage/index.md ================================================ # Templed cofnod penderfyniad gan ddefnyddio Planguage Gweler https://www.iaria.org/conferences2012/filesICCGI12/Tutorial%20Specifying%20Effective%20Non-func.pdf ## Beth yw Planguage? Mae Planguage yn iaith gynllunio sy'n defnyddio'r geiriau allweddol hyn: * Tag: Dynodwr unigryw, parhaus * Gist: Crynodeb byr o'r gofyniad neu'r maes dan sylw * Gofyniad: Y testun sy'n manylu ar y gofyniad ei hun * Rhesymeg: Y rhesymu sy'n cyfiawnhau'r gofyniad * Blaenoriaeth: Datganiad o flaenoriaeth a hawliad ar adnoddau * Rhanddeiliaid: Partïon yr effeithir arnynt yn sylweddol gan y gofyniad * Statws: Statws y gofyniad (drafft, wedi'i adolygu, wedi ymrwymo, ac ati) * Perchennog: Y person sy'n gyfrifol am weithredu'r gofyniad * Awdur: Y person a ysgrifennodd y gofyniad * Adolygu: Rhif fersiwn ar gyfer y datganiad * Dyddiad: Dyddiad y diwygiad diweddaraf * Tybiaethau: Unrhyw beth a allai achosi problemau os yw'n anwir nawr neu'n hwyrach * Risgiau: Unrhyw beth a allai achosi camweithio, oedi, neu effeithiau negyddol eraill * Diffiniedig: Diffiniad o derm (gwell defnyddio geirfa) ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-y-prosiect-madr/.locale-peer-id ================================================ 0a9f88e5cda952db0a82d071f585d090 ================================================ FILE: locales/cy/templedi/templed-cofnod-penderfyniad-y-prosiect-madr/index.md ================================================ # [teitl byr y broblem a'r datrysiad a ddatryswyd] * Statws: [ arfaethedig | gwrthodwyd | derbyn | anghymeradwy | … | wedi'i ddisodli gan [ADR-0005](0005-example.md)] * Penderfynwyr: [rhestrwch bawb sy'n rhan o'r penderfyniad] *Dyddiad: [YYYY-MM-DD pan gafodd y penderfyniad ei ddiweddaru ddiwethaf] Stori Dechnegol: [disgrifiad | URL tocyn/rhifyn] ## Datganiad Cyd-destun a Phroblem [Disgrifiwch y cyd-destun a gosodiad y broblem, e.e., ar ffurf rydd gan ddefnyddio dwy neu dair brawddeg. Efallai y byddwch am fynegi’r broblem ar ffurf cwestiwn.] ## Gyrwyr Penderfyniad * [gyrrwr 1, e.e., llu, yn wynebu pryder, …] * [gyrrwr 2, e.e., llu, yn wynebu pryder, …] * … ## Opsiynau a Ystyrir * [opsiwn 1] * [opsiwn 2] * [opsiwn 3] * … ## Canlyniad Penderfyniad Dewis a ddewiswyd: "[opsiwn 1]", oherwydd [cyfiawnhad. e.e., opsiwn yn unig, sy'n bodloni k.o. gyrrwr penderfyniad maen prawf | sy'n datrys grym grym | … | yn dod allan orau (gweler isod)]. ### Canlyniadau Cadarnhaol * [e.e., gwella boddhad priodoledd ansawdd, penderfyniadau dilynol sydd eu hangen, …] *… ### Canlyniadau Negyddol * [e.e., cyfaddawdu priodoledd ansawdd, penderfyniadau dilynol sydd eu hangen, …] *… ## Manteision ac Anfanteision yr Opsiynau ### [opsiwn 1] [enghraifft | disgrifiad | pwyntydd at ragor o wybodaeth | …] * Da, oherwydd [dadl a] * Da, achos [dadl b] * Drwg, oherwydd [dadl c] * … ### [opsiwn 2] [enghraifft | disgrifiad | pwyntydd at ragor o wybodaeth | …] * Da, oherwydd [dadl a] * Da, achos [dadl b] * Drwg, oherwydd [dadl c] * … ### [opsiwn 3] [enghraifft | disgrifiad | pwyntydd at ragor o wybodaeth | …] * Da, oherwydd [dadl a] * Da, achos [dadl b] * Drwg, oherwydd [dadl c] * … ## Dolenni * [Math o ddolen] [Cyswllt i ADR] * … ================================================ FILE: locales/en/.locale-peer-id ================================================ 0b59cb46e5817b414866ebe33f4d7bcf ================================================ FILE: locales/en/documents/.locale-peer-id ================================================ abc7c72d426bc75e40b25a44ae37ce73 ================================================ FILE: locales/en/documents/aws-adr-process/.locale-peer-id ================================================ 7d4adf16004ca42546dee49922ae4ccf ================================================ FILE: locales/en/documents/aws-adr-process/index.md ================================================ # AWS Architectural Decision Records Process https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html An architectural decision record (ADR) is a document that describes a choice the team makes about a significant aspect of the software architecture they’re planning to build. Each ADR describes the architectural decision, its context, and its consequences. ADRs have states and therefore follow a lifecycle. For an example of an ADR, see the appendix. The ADR process outputs a collection of architectural decision records. This collection creates the decision log. The decision log provides the project context as well as detailed implementation and design information. Project members skim the headlines of each ADR to get an overview of the project context. They read the ADRs to dive deep into project implementations and design choices. When the team accepts an ADR, it becomes immutable. If new insights require a different decision, the team proposes a new ADR. When the team accepts the new ADR, it supersedes the previous ADR. ## Scope of the ADR process Project members should create an ADR for every architecturally significant decision that affects the software project or product, including the following (Richards and Ford 2020): * Structure (for example, patterns such as microservices) * Non-functional requirements (security, high availability, and fault tolerance) * Dependencies (coupling of components) * Interfaces (APIs and published contracts) * Construction techniques (libraries, frameworks, tools, and processes) * Functional and non-functional requirements are the most common inputs to the ADR process. ## ADR contents When the team identifies a need for an ADR, a team member starts to write the ADR based on a projectwide template. (See the ADR GitHub organization for example templates.) The template simplifies ADR creation and ensures that the ADR captures all the relevant information. At a minimum, each ADR should define the context of the decision, the decision itself, and the consequences of the decision for the project and its deliverables. (For examples of these sections, see the appendix.) One of the most powerful aspects of the ADR structure is that it focuses on the reason for the decision rather than how the team implemented it. Understanding why the team made the decision makes it easier for other team members to adopt the decision, and prevents other architects who weren’t involved in the decision-making process to overrule that decision in the future. ## ADR adoption process Every team member can create an ADR, but the team should establish a definition of ownership for an ADR. Each author who is the owner of an ADR should actively maintain and communicate the ADR content. To clarify this ownership, this guide refers to ADR authors as ADR owners in the following sections. Other team members can always contribute to an ADR. If the content of an ADR changes before the team accepts the ADR, the owner should approve these changes. After the team identifies an architectural decision and its owner, the ADR owner provides the ADR in the **Proposed** state at the beginning of the process. ADRs in the Proposed state are ready for review. The ADR owner then initiates the review process for the ADR. The goal of the ADR review process is to decide whether the team accepts the ADR, determines that it needs rework, or rejects the ADR. The project team, including the owner, reviews the ADR. The review meeting should start with a dedicated time slot to read the ADR. On average, 10 to 15 minutes should be enough. During this time, each team member reads the document and adds comments and questions to flag unclear topics. After the review phase, the ADR owner reads out and discusses each comment with the team. If the team finds action points to improve the ADR, the state of the ADR stays **Proposed**. The ADR owner formulates the actions, and, in collaboration with the team, adds an assignee to each action. Each team member can contribute and resolve the action points. It is the responsibility of the ADR owner to reschedule the review process. The team can also decide to reject the ADR. In this case, the ADR owner adds a reason for the rejection to prevent future discussions on the same topic. The owner changes the ADR state to **Rejected**. If the team approves the ADR, the owner adds a timestamp, version, and list of stakeholders. The owner then updates the state to **Accepted**. ADRs and the decision log they create represent decisions made by the team and provide a history of all decisions. The team uses the ADRs as a reference during code and architectural reviews where possible. In addition to performing code reviews, design tasks, and implementation tasks, team members should consult ADRs for strategic decisions for the product. As a good practice, each software change should go through peer reviews and require at least one approval. During the code review, a code reviewer might find changes that violate one or more ADRs. In this case, the reviewer asks the author of the code change to update the code, and shares a link to the ADR. When the author updates the code, it is approved by peer reviewers and merged into the main code base. ## ADR review process The team should treat ADRs as immutable documents after the team accepts or rejects them. Changes to an existing ADR requires creating a new ADR, establishing a review process for the new ADR, and approving the ADR. If the team approves the new ADR, the owner should change the state of the old ADR to **Superseded**. ================================================ FILE: locales/en/documents/decision-sustainability-criteria/.locale-peer-id ================================================ 71d59ed566ae148b8bf42331a84754ac ================================================ FILE: locales/en/documents/decision-sustainability-criteria/index.md ================================================ # Decision Sustainability Criteria To define decision sustainability in detail, we derived five key criteria. ## Strategic During decision making, someone looking at strategic consequences should consider things such as the decisions’ long-term impact—for example, future operations and maintenance effort. ## Measurable and Manageable You can measure and evaluate a decision’s outcome over time according to objective criteria, ideally numeric ones (as, for instance, propagated by quality attribute scenarios and workshops4). Capturing all fine-grained decisions isn’t possible, so architects must limit the decisions’ granularity to a certain level of detail (such as creating a design class). This will lead to a more sustainable set of decisions and fewer traceability links. Moreover, limiting the number of dependencies between decisions reduces changes’ ripple effect. ## Achievable and Realistic The rationale for fitting the solution to the problem should be chosen pragmatically and made explicit. For example, architects can indicate that they have taken care to avoid over- or underengineering (that is, they should apply the “good enough” approach). ## Rooted in Requirements Decision making should be grounded in domain-specific architecting experience and context. It should take into account the company environment as well as project requirements and constraints, including the development team’s current skills, training budget, and process. ## Timeless Decisions should be based on experience and knowledge that won’t likely be soon outdated. For example, architects can choose platform-neutral architectural patterns or tactics. ================================================ FILE: locales/en/documents/file-name-conventions-for-adrs/.locale-peer-id ================================================ 89116b5647aa1e53186f3c44b5a284a0 ================================================ FILE: locales/en/documents/file-name-conventions-for-adrs/index.md ================================================ # File name conventions If you choose to create your ADRs using typical text files, then you may want to come up with your own ADR file name convention. We prefer to use a file name convention that has a specific format. Examples: * choose-database.md * format-timestamps.md * manage-passwords.md * handle-exceptions.md Our file name convention: * The name has a present tense imperative verb phrase. This helps readability and matches our commit message format. * The name uses lowercase and dashes (same as this repo). This is a balance of readability and system usability. * The extension is markdown. This can be useful for easy formatting. ================================================ FILE: locales/en/documents/fitness-functions-for-decisions-as-code/.locale-peer-id ================================================ 23615a056e17c4097ee648d8c7352733 ================================================ FILE: locales/en/documents/fitness-functions-for-decisions-as-code/index.md ================================================ # Fitness functions for decisions as code Fitness functions are objective automated checks, written with programming code, that verify decisions are being maintained. - Fitness functions make decisions testable and assurable. - Fitness functions for decisions can greatly help quality assurance, regulatory processes, and governance goals. ## How fitness functions connect to decisions A decision record documents the decision, while a fitness function assures the decision. - Example decision: We use event sourcing for audit requirements. - Example fitness function: We use the continuous integration server to test that all state changes must produce events. ## Why fitness functions help decisions Objective measurements: Fitness functions pass or fail, so work is visible and clear. Continuous use: Fitness functions are your living rules, run on every commit and build. Confidence to refactor: Fitness functions automatically catch decision rule errors. Scalable governance: Fitness functions assure standards without creating bottlenecks. ## Can fitness functions use AI? Fitness functions can leverage AI LLMs for decisions by asking questions for your work, such as your plans, code, schemas, APIs, and more: ```txt IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning. IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search. This is a fitness function to evaluate if our work is using all our decisions, and is correct and accurate. - Our decisions are here: {url} - Our work to evaluate is here: {url} Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive. ``` ## Architecture unit testing [ArchUnit](https://www.archunit.org/): check architecture rules of Java code by using any plain Java unit test framework. [ArchUnitTS](https://github.com/LukasNiessen/ArchUnitTS): check architecture rules of TypeScript code and JavaScript code by using Jest, Vitest, Jasmine, etc. ================================================ FILE: locales/en/documents/guidelines-to-achieve-sustainable-decisions/.locale-peer-id ================================================ 934d1c42a693fe004cd8bf8f5ecb97e6 ================================================ FILE: locales/en/documents/guidelines-to-achieve-sustainable-decisions/index.md ================================================ # Guidelines to Achieve Sustainable Decisions We learned the following lessons in our work that can serve as guidelines and assessment for achieving sustainable decisions: 1. Use a lean/minimalistic approach for the initial decision documentation. 2. Prioritize and capture all important decisions that are relevant enough for documenting and understanding the target architecture. 3. Detail the particularly important decisions with full-blown templates only after the initial work has been done (that is, when the decision makers are content with the architectural decisions made and confident that these decisions don’t have to be revised any time soon). 4. Use the lean/minimalistic versions from step 1 as a short version of documented decisions with the right granularity level to provide an overview of the detailed decisions, as well as for trivial or obvious decisions. 5. Wherever possible, use existing architectural knowledge, either from guidance models or from other sources. Review and extend such knowledge and fit it to the context of the specific decision. 6. Ensure that traceability links are established between decisions and both requirements and architectural designs/code. 7. Provide automated consistency checking to make sure the traceability links are in sync after a change. Limit the number of dependencies between decisions and other software artifacts. 8. Apply the guidelines for the justifications consequently and forcefully—they’re the most important part of the decision documentation because they give the rationale. ================================================ FILE: locales/en/documents/how-to-start-using-adrs/.locale-peer-id ================================================ 8196518140224596af99a46d512feba3 ================================================ FILE: locales/en/documents/how-to-start-using-adrs/index.md ================================================ # How to start using ADRs To start using ADRs, talk with your teammates about these areas. Decision identification: * How urgent and how important is the AD? * Does it have to be made now, or can it wait until more is known? * Both personal and collective experience, as well as recognized design methods and practices, can assist with decision identification. * Ideally maintain a decision todo list that complements the product todo list. Decision making: * A number of decision making techniques exists, both general ones and software architecture specific ones, for instance, dialogue mapping. * Group decision making is an active research topic. Decision enactment and enforcement: * ADs are used in software design; hence they have to be communicated to, and accepted by, the stakeholders of the system that fund, develop, and operate it. * Architecturally evident coding styles and code reviews that focus on architectural concerns and decisions are two related practices. * ADs also have to be (re-)considered when modernizing a software system in software evolution. Decision sharing (optional): * Many ADs recur across projects. * Hence, experiences with past decisions, both good and bad, can be valuable reusable assets when employing an explicit knowledge management strategy. Decision documentation: * Many templates and tools for decision capturing exist. * See agile communities, e.g. M. Nygard's ADRs. * See traditional software engineering and architecture design processes, e.g. table layouts suggested by IBM UMF and by Tyree and Akerman from CapitalOne. For more: * The steps above are adopted from the Wikipedia entry on [Architectural Decision](https://en.wikipedia.org/wiki/Architectural_decision) ================================================ FILE: locales/en/documents/how-to-start-using-adrs-with-git/.locale-peer-id ================================================ d6fb3c7d91f95003163e694e74058e9d ================================================ FILE: locales/en/documents/how-to-start-using-adrs-with-git/index.md ================================================ # How to start using ADRs with git If you like using git version control, then here is how we like to start using ADRs with git for a typical software project with source code. Create a directory for ADR files: ```sh $ mkdir adr ``` For each ADR, create a text file, such as `database.txt`: ```sh $ vi database.txt ``` Write anything you want in the ADR. See the templates in this repository for ideas. Commit the ADR to your git repo. ================================================ FILE: locales/en/documents/how-to-start-using-adrs-with-tools/.locale-peer-id ================================================ 1a5a03dd6f20cea9f78fb4655a9a7f87 ================================================ FILE: locales/en/documents/how-to-start-using-adrs-with-tools/index.md ================================================ ## How to start using ADRs with tools You can start using ADRs with tools any way you want. For example: * If you like using Google Drive and online editing, then you can create a Google Doc, or Google Sheet. * If you like use source code version control, such as git, then you can create a file for each ADR. * If you like using project planning tools, such as Atlassian Jira, then you can use the tool's planning tracker. * If you like using wikis, such as MediaWiki, then you can create an ADR wiki. ================================================ FILE: locales/en/documents/suggestions-for-writing-good-adrs/.locale-peer-id ================================================ dc1a294e76821d6d3b086a2b17988427 ================================================ FILE: locales/en/documents/suggestions-for-writing-good-adrs/index.md ================================================ ## Suggestions for writing good ADRs Characteristics of a good ADR: * Rationale: Explain the reasons for doing the particular AD. This can include the context (see below), pros and cons of various potential choices, feature comparisons, cost/benefit discussions, and more. * Specific: Each ADR should be about one AD, not multiple ADs. * Timestamps: Identify when each item in the ADR is written. This is especially important for aspects that may change over time, such as costs, schedules, scaling, and the like. * Immutable: Don't alter existing information in an ADR. Instead, amend the ADR by adding new information, or supersede the ADR by creating a new ADR. Characteristics of a good "Context" section in an ADR: * Explain your organization's situation and business priorities. * Include rationale and considerations based on social and skills makeups of your teams. * Include pros and cons that are relevant, and describe them in terms that align with your needs and goals. Characteristics of good "Consequences" section in an ADR: * Explain what follows from making the decision. This can include the effects, outcomes, outputs, follow ups, and more. * Include information about any subsequent ADRs. It's relatively common for one ADR to trigger the need for more ADRs, such as when one ADR makes a big overarching choice, which in turn creates needs for more smaller decisions. * Include any after-action review processes. It's typical for teams to review each ADR one month later, to compare the ADR information with what's happened in actual practice, in order to learn and grow. A new ADR may take the place of a previous ADR: * When an AD is made that replaces or invalidates a previous ADR, then a new ADR should be created ================================================ FILE: locales/en/documents/teamwork-advice-for-adrs/.locale-peer-id ================================================ 875a7715e592ceb45eac5e155ee16318 ================================================ FILE: locales/en/documents/teamwork-advice-for-adrs/index.md ================================================ # Teamwork advice for ADRs If you're considering using decision records with your team, then here's some advice that we've learned by working with many teams. You have an opportunity to lead your teammates, by talking together about the "why", rather than mandating the "what". For example, decision records are a way for teams to think smarter and communicate better; decision records are not valuable if they're just an after-the-fact forced paperwork requirement. Some teams much prefer the name "decisions" over the abbreviation "ADRs". When some teams use the directory name "decisions", then it's as if a light bulb turns on, and the team starts putting more information into the directory, such as vendor decisions, planning decisions, scheduling decisions, etc. All of these kinds of information can use the same template. We hypothesize that people learn faster with words ("decisions") over abbreviations ("ADRs"), and people are more motivated to write work-in-progress docs when the word "record" is removed, and also some developers and some managers dislike the word "architecture". In theory, immutability is ideal. In practice, mutability has worked better for our teams. We insert the new info the existing ADR, with a date stamp, and a note that the info arrived after the decision. This kind of approach leads to a "living document" that we all can update. Typical updates are when we get information thanks to new teammates, or new offerings, or real-world results of our usages, or after-the-fact third-party changes such as vendor capabilities, pricing plans, license agreements, etc. ================================================ FILE: locales/en/documents/teamwork-questions-for-adrs/.locale-peer-id ================================================ 60057747e4547af35fd888021e41f332 ================================================ FILE: locales/en/documents/teamwork-questions-for-adrs/index.md ================================================ ### Who can create an ADR? Consider areas such as specific people, or specific roles, or specific teams, or specific departments; also consider if there are people, or roles, or teams, or department that can commission an ADR, meaning they request one that someone else will author. Example answer: Any person in our organization who has read the architecture decision record README page can propose an ADR, meaning the person can start writing it, and share it with the team. ### What justifies raising an ADR? Consider areas such as your organization's team ways of working, your software system structure, cross-team coordination, long-term maintainability, external interfaces, who you want to benefit, and the like. Example answer: We want to create an ADR when we want future developers to understand the “why” of what we're doing. ### What justifies not raising an ADR? Consider areas such as decisions that are not about architecture, or are tiny such as minimal-risk or self-contained or single-developer, or are already fully covered elsewhere such as by standards or policies or documentation, or are temporary such as workarounds or proofs of concepts or orexperiments. Example answer: We want to skip an ADR when a decision is limited in scope and time and risk and cost, or is already covered elsewhere. ### What is the lifecycle of an ADR? Consider areas such as the creation process, research process, decisioning process, implementation process, and sunsetting process. Consider how to track the ADR lifecycle over time, such as how to move the ADR from one state to the next state, and also how to communicate this to stakeholders. Example answer: We want an ADR to have five lifecycle stages: Initiating → Researching → Evaluating → Implementing → Maintaining → Sunsetting. ### What are criteria for lifecycle steps of an ADR? Consider areas such as acceptance criteria for an ADR, meaning how do you know it's good enough to progress from one lifecycle step to the next? Is the problem clearly articulated? Have the alternatives been considered? Are trade-offs well-enough understood and documented? Is all relevant context in place? Are all relevant stakeholders involved? Has all feedback been incorporated? Example answer: We want an ADR to be voted on by stakeholders when the active team has 1) completed their research, 2) completed their evaluation, 3) published the ADR proposal to the stakeholders with a request for comments and a timebox of one week, 4) all stakeholder comments have been incorporated and addressed. ### What roles and responsibilities interact with an ADR? Consider roles such as proposer, researcher, evaluator, reviewer, approver, maintainer, and the like. Consider responsibilities such as communication with stakeholders, ensuring expectations are met, sharing on the website or intranet, and reviewing the work periodically and especially when relevant changes happen. Example answer: We want each ADR to always have a primary contact person, secondary contact person, and accountable team; these are responsible for communications, publications, maintenance, periodic review at least once per year, and eventual sunsetting as needed. ### How does governance interact with an ADR? Consider areas such as your organization's ways of working, any special compliance needs such as for legal aspects or human resource aspects, how you want to handle consensus versus conflict versus escalation. Are there areas or people or teams that can have more influence than others regarding an ADR, such as being able to approve it, or vote on it, or veto it? Example answer: The governance of an ADR is in this priority order: the CEO, the CTO, the CLO, the team that implements an ADR, the experts on the team that are most-knowledgeable about the ADD. No one else has governance unless described in the ADR. ### What principles interact with an ADR? Consider areas such as your organization's ways of working that include moving quickly versus moving slowly, for decision consensus versus decision conflict, and for risk preferences versus safety preferences, public discussion versus private discussion, and the like. Example answer: We use the leadership principles of bias for action, disagree-and-commit, 70% estimates are good enough for easily-reversable easily-isolatable decisions, and public ways of working with the exception of confidential information as described in our organization's confidentiality agreement. ================================================ FILE: locales/en/documents/what-is-an-architecture-decision-record/.locale-peer-id ================================================ 020ff535ed1a3347a265209291e756b6 ================================================ FILE: locales/en/documents/what-is-an-architecture-decision-record/index.md ================================================ ## What is an architecture decision record? An **architecture decision record** (ADR) is a document that captures an important architectural decision made along with its context and consequences. An **architecture decision** (AD) is a software design choice that addresses a significant requirement. An **architecture decision log** (ADL) is the collection of all ADRs created and maintained for a particular project (or organization). An **architecturally-significant requirement** (ASR) is a requirement that has a measurable effect on a software system’s architecture. All these are within the topic of **architecture knowledge management** (AKM). The goal of this document is to provide a fast overview of ADRs, how to create them, and where to look for more information. Abbreviations: * **AD**: architecture decision * **ADL**: architecture decision log * **ADR**: architecture decision record * **AKM**: architecture knowledge management * **ASR**: architecturally-significant requirement ================================================ FILE: locales/en/examples/.locale-peer-id ================================================ ================================================ FILE: locales/en/examples/4-day-work-week/.locale-peer-id ================================================ fb15d0e84550135e2e7a280693ba5848 ================================================ FILE: locales/en/examples/4-day-work-week/index.md ================================================ # Decision record for 4-day work-week Title: Implementation of 4-Day Work-week ## Context and Problem Statement Our organization has been considering a switch to a 4-day workweek. The current work schedule of 5 days per week, 8 hours per day, has resulted in low productivity, employee burnout, and high turnover rates. The proposed change aims to increase employee satisfaction, engagement, and retention, and ultimately improve organizational performance. ## Decision We have decided to implement a 4-day workweek starting from the next quarter for all employees across the organization. ## Rationale The decision was based on the following factors: 1. Employee feedback: A survey conducted among the employees highlighted the desire for a more flexible work schedule and a better work-life balance. The majority of the respondents expressed interest in a 4-day workweek. 2. Research findings: Studies on companies that have implemented a 4-day workweek have shown increased employee productivity, reduced absenteeism, and improved work-life balance. 3. Competitive advantage: Offering a 4-day workweek can be an attractive benefit to potential employees and can help retain existing talent. 4. Organizational goals: The switch to a 4-day workweek aligns with our organizational goals to create a healthier and more productive work environment. ## Implementation Plan The following steps will be taken to implement the 4-day workweek: 1. Communication: The decision will be communicated to all employees via a company-wide email and a meeting with team leaders. 2. Schedule: The new schedule will be Monday to Thursday for full-time employees, with the option of flexible schedules for part-time employees. Work hours will be extended to 10 hours per day. 3. Policy updates: Human resources policies, such as leave policies and benefits, will be updated to align with the new schedule. 4. Training: Managers will be trained on how to manage teams under the new schedule and how to properly track employee performance and productivity. 5. Evaluation: The new work schedule will be evaluated after six months to determine its impact on employee satisfaction, engagement, and retention. ## Anticipated outcomes The implementation of a 4-day workweek is expected to result in the following outcomes: 1. Increased employee satisfaction, engagement, and retention. 2. Improved work-life balance for employees. 3. Increased productivity and reduced absenteeism. 4. More attractive employee benefit package and a competitive advantage in the hiring market. ## Conclusion We believe that the implementation of a 4-day workweek will benefit our organization and our employees. We look forward to seeing the positive impact of this decision on our employees and our overall organizational performance. ================================================ FILE: locales/en/examples/agile-software-development/.locale-peer-id ================================================ a4bc089ce8e95a6dce0fb0845081674a ================================================ FILE: locales/en/examples/agile-software-development/index.md ================================================ # Decision record for agile software development Title Introduction of Agile Software Development Date: [Insert Date] Team Members Present: [Insert Names] ## Background The Team has been considering the adoption of Agile software development methodology to increase productivity, improve efficiency, and better adapt to the rapidly changing software development industry. Key Points: - Agile emphasizes iterative development, frequent communication, and flexibility in requirements - Agile can lead to better collaboration among team members - Agile can help anticipate and respond to changes in project scope and requirements - Agile can lead to improved time-to-market and better overall project outcomes ## Decision After much deliberation and discussion, the Team has decided to adopt Agile software development methodology. ## Reasoning We believe that Agile will help us better adapt to the rapidly changing software development industry and help us deliver high-quality products to our customers. Our decision to adopt Agile was based on an assessment of our current workflow, discussions with industry experts, and our long-term organizational goals. ## Action Items - Assess team member familiarity with Agile methodology and provide necessary training and resources as required - Develop and communicate Agile-based project management processes and workflows - Establish key performance indicators (KPIs) to track the effectiveness of the Agile methodology - Monitor progress towards KPIs to evaluate the effectiveness of the new Agile methodology ## Conclusion The adoption of Agile software development methodology is an important decision for our team. We believe that our transition to Agile will help us deliver better products efficiently and effectively. ================================================ FILE: locales/en/examples/amazon-web-services/.locale-peer-id ================================================ c4beaa505311198b2b00341fe42c948f ================================================ FILE: locales/en/examples/amazon-web-services/index.md ================================================ # Architecture Decision Record for Amazon Web Services Title: Adopting Amazon Web Services for Cloud Infrastructure ## Decision After a thorough evaluation of various cloud infrastructure platforms, it has been decided that Amazon Web Services (AWS) will be adopted by our organization for our cloud infrastructure needs. ## Background Our organization is growing rapidly and we need a reliable and scalable cloud infrastructure to meet the demands of our business. After considering a number of cloud infrastructure providers, it was concluded that AWS offers the most suitable range of services to meet our current and future requirements. ## Considerations There are numerous cloud infrastructure providers in the market that have proven to be reliable and efficient. However, AWS not only offers a comprehensive set of services to cater to our needs, but it also has an extensive customer base and a track record of successful deployments. AWS also provides a broad range of support and training resources to ensure that our team can work effectively with the platform. Furthermore, AWS has an extensive global presence with data centers located in various regions around the world. This ensures that our data is secure and our applications and services will be highly available. AWS also has a robust security framework that is critical for our business. Lastly, AWS provides a pay-as-you-go model which offers us the flexibility to scale our infrastructure based on demand. This means that we will only be charged for what we use, which allows us to optimize our costs and invest in other areas of the business. ## Decision Based on the evaluations performed and the advantages offered by AWS, it has been decided that AWS will be adopted for our cloud infrastructure needs. ## Consequences The adoption of AWS may require training for our teams to ensure that they are familiar with the platform and can effectively utilize it. There may also be some initial costs to move our current infrastructure to the AWS platform. ## Ownership The responsibility for ensuring the effective utilization of AWS and the management of associated risks will fall within the remit of the cloud infrastructure team. Any issues that arise must be addressed by this team. ## Review The decision to adopt AWS will be reviewed on an annual basis to ensure that it continues to meet our needs and that the benefits of the platform are being fully realized. ================================================ FILE: locales/en/examples/api-using-json-v-grpc/.locale-peer-id ================================================ 7c91a4cc326aecb7f1a62a6d41b8b4fd ================================================ FILE: locales/en/examples/api-using-json-v-grpc/index.md ================================================ # Architecture Decision Record: API using JSON v. gRPC ## Status Accepted ## Context We are designing an API for a new service that will be used by multiple clients. We have been considering two options for implementing the API: using JSON over HTTP or using gRPC. JSON over HTTP is a widely-used approach for building APIs, and it is supported by many programming languages and frameworks. This approach is simple, lightweight, and easy to understand, making it a good choice for many projects. However, it can be less efficient than other options, especially when it comes to handling large amounts of data. gRPC, on the other hand, is a newer technology that offers a more efficient way of building APIs. It uses binary serialization to transfer data, which can be faster and more compact than using JSON. gRPC also supports bidirectional streaming, making it a good choice for real-time applications. ## Decision After considering the pros and cons of both options, we have decided to use gRPC for our API. Although JSON over HTTP is a simpler option, we believe that gRPC will provide a more efficient and scalable solution for our service. We also anticipate that our API will handle a large amount of data, and gRPC's binary serialization will be more efficient for this use case. In addition, we believe that gRPC's support for bidirectional streaming will be beneficial for real-time applications that we may develop in the future. ## Consequences By choosing gRPC, we will need to use a different set of tools and libraries to build our API compared to using JSON over HTTP. This may require additional time and effort to learn and implement these technologies. Additionally, clients who want to use our API will need to use gRPC-compatible libraries, which may not be as widely supported as JSON over HTTP libraries. However, we believe that the benefits of using gRPC outweigh these potential drawbacks, and we are confident that this decision will result in a more efficient and scalable API. ================================================ FILE: locales/en/examples/authentication-authorization-options/index.md ================================================ # Architecture Decision Record: authentication authorization options Web application authentication and authorization are two crucial concepts in securing access to applications and services. Both deal with the identity of users and how permissions are granted, but they focus on different aspects: - **Authentication** is the process of verifying the identity of a user or system. - **Authorization** is the process of determining what resources or actions the authenticated user or system can access. Now, let's dive into the specific protocols and technologies you've mentioned, which are commonly used in modern web applications for managing authentication and authorization. ### 1. **OAuth (Open Authorization)** **OAuth** is an open standard for authorization. It allows a user to grant a third-party application limited access to their resources without sharing their credentials. The key idea is **delegated access**. OAuth is often used in situations where users can log in to a third-party service (e.g., signing in with Google) without directly providing their username and password to the third-party. - **Flow**: OAuth typically follows a **token-based** flow, where an authorization server issues an access token to the third-party application. This token represents the user's permissions, and the application uses it to access the user's data or resources from an API. - **Example**: A user signs into a third-party app using their Google account. Google verifies the user's identity and then grants a token that allows the third-party app to access some Google data (e.g., Google Calendar). OAuth **does not** handle authentication directly; it’s about granting access. For authentication, OAuth is often paired with other protocols, like **OpenID Connect**. ### 2. **OpenID Connect (OIDC)** **OpenID Connect (OIDC)** is an identity layer built on top of **OAuth 2.0** that adds authentication to OAuth’s authorization capabilities. Essentially, OpenID Connect extends OAuth to handle **user authentication** and provides a standardized way for applications to verify the identity of a user. - **Flow**: When a user logs in using OpenID Connect, the third-party application requests an ID token (in addition to the OAuth access token). The ID token contains information about the user (such as their username, email, and other claims). This allows the application to know who the user is and whether they are authenticated. - **Example**: Logging into a service like Slack using your Google account (Google being the OpenID Connect provider) involves authentication via OpenID Connect, while OAuth manages the access to your Google resources. OIDC makes it easier for third-party apps to **authenticate users** while still allowing fine-grained control over what resources those apps can access. ### 3. **SAML (Security Assertion Markup Language)** **SAML** is an older, XML-based standard used for exchanging authentication and authorization data between parties, particularly in **Single Sign-On (SSO)** scenarios. It's primarily used in enterprise environments to enable users to authenticate once and access multiple applications without re-entering credentials. - **Flow**: The user first authenticates with an identity provider (IdP). The IdP generates a signed **SAML assertion** that includes the user's identity and related attributes. The assertion is sent to the service provider (SP), which uses it to authorize access to the application. - **Example**: An employee logs into their corporate portal (the IdP) and is automatically logged into other systems like email, CRM, etc., without re-entering credentials. The authentication process is based on the SAML assertion sent by the IdP. SAML is commonly used in **enterprise SSO solutions** and works well for web applications in corporate environments, but it’s less mobile-friendly compared to OAuth/OIDC. ### 4. **WS-Federation (Web Services Federation)** **WS-Federation** is another protocol used for **Single Sign-On (SSO)**, especially in Microsoft-based enterprise environments. It's part of the **WS-* (Web Services)** family of specifications and allows for identity federation across different security domains (such as between different organizations or between different services). - **Flow**: WS-Federation allows a **trusted identity provider (IdP)** to authenticate users and issue tokens that the service provider can use for authorization. It’s similar to SAML but is often used in scenarios that rely heavily on Microsoft technologies. - **Example**: A user logs into an enterprise application hosted by Microsoft Azure Active Directory (AD), and their identity can be used to access other federated services, including applications hosted by third-party vendors. Although WS-Federation is largely replaced by newer protocols like OAuth2.0 and OpenID Connect in many modern web environments, it’s still used in legacy systems, especially in Microsoft-centric enterprises. ### 5. **LDAP (Lightweight Directory Access Protocol)** **LDAP** is a protocol used to access and manage directory services, commonly used for **storing user credentials** and managing access control in a centralized directory (often called a **Directory Service**). LDAP isn't specifically about authentication or authorization but is used to store and retrieve identity data, which is then used in those processes. - **Authentication**: LDAP allows an application to authenticate users by querying the directory service for credentials (like passwords). - **Authorization**: It also manages user roles and permissions, helping determine whether a user has access to certain resources. - **Example**: Many enterprises use LDAP-based directories (e.g., **Active Directory**) for authentication and authorization, especially within Windows environments. LDAP is crucial for enterprises to manage user access across internal systems, but in a modern web context, LDAP is often integrated with other protocols like SAML or OAuth for more complete identity management. ### 6. **Social SSO Providers** Social **Single Sign-On (SSO)** providers like **Facebook**, **Google**, **Twitter**, **GitHub**, and others allow users to authenticate into third-party applications using their social media credentials. This is a type of **OAuth-based authentication** where the third-party service (e.g., Google) is the identity provider. - **Flow**: The user clicks "Log in with Google" (for example). The app redirects to Google, where the user logs in (if not already logged in). Google then provides an access token or ID token to the third-party app, which can be used to authenticate the user and possibly access their data. - **Example**: Many applications allow you to log in using your Google or Facebook credentials. The app will use OAuth or OpenID Connect behind the scenes to verify your identity and, in some cases, access certain social media data. Social SSO is a convenient and widely adopted method for authentication because it reduces friction for users, who may not want to create yet another username and password. --- ### Summary of Differences: - **OAuth**: Used for authorization, allows third-party apps to access user data without exposing credentials. - **OpenID Connect**: Extends OAuth to provide authentication, enabling apps to verify user identity. - **SAML**: XML-based protocol used for SSO, often in enterprise environments. - **WS-Federation**: A Microsoft-specific protocol for identity federation, used in legacy systems. - **LDAP**: A protocol for querying directory services to authenticate users and manage authorization. - **Social SSO Providers**: OAuth-based systems (like Google, Facebook) that allow third-party apps to authenticate users using their social media credentials. Each of these technologies has its own strengths and use cases, and in modern applications, you may see a combination of them being used for different aspects of security (e.g., OAuth/OIDC for API access, SAML for enterprise SSO). ================================================ FILE: locales/en/examples/browser-automation-framework-for-e2e-testing-playwright-vs-selenium/index.md ================================================ ## Architecture decision record: browser automation framework for E2E testing (Playwright vs Selenium) ### 1. **Context** We are in the process of selecting a browser automation framework for our end-to-end (E2E) testing pipeline. This framework will be integral to our CI/CD processes, running tests that simulate real user interactions on our platform. Specifically, the tests will cover scenarios such as user sign-up/sign-in, file uploads, dashboard interactions, and report downloads. As a **startup**, our focus is on **agile development**, with a need to rapidly iterate and evolve. Our team predominantly works with **TypeScript** and **Python**, and the ability to write tests in these languages is essential. Additionally, the platform contains **interactive charts and dashboards**, which makes it critical that the automation tool supports rich, dynamic UIs well. The two contenders for this task are **Playwright** and **Selenium**, each with its strengths and trade-offs. We need to evaluate these frameworks based on the features and requirements outlined below. ### 2. **Considered Options** - **Playwright** (by Microsoft) - **Selenium** (by the Selenium Project) ### 3. **Decision Drivers** The factors influencing our decision are as follows: 1. **Agile Development**: The chosen tool must enable fast, flexible development cycles. 2. **Language Support**: Our team requires support for both **TypeScript** and **Python**. 3. **Interactive UI Testing**: The ability to test interactive charts, dashboards, and dynamic elements reliably is essential. 4. **Runtime Speed**: While not a primary concern, performance in CI/CD pipelines is a consideration. 5. **Scalability**: We are not planning for massive scaling in the immediate future, but we want to ensure the solution can handle future growth. 6. **Backwards Compatibility**: Legacy systems and compatibility with older browsers are not critical for our project at this time. 7. **Mobile Testing**: While not an immediate focus, the framework should be capable of testing mobile-responsive features or be extensible for such use cases. 8. **Multi-monitor Testing**: Support for multi-monitor configurations is a secondary requirement, especially if we ever scale to testing for more complex user workflows. 9. **File Upload Testing**: The framework must handle file uploads efficiently, a core requirement of our testing needs. ### 4. **Evaluation Criteria** - **Ease of Use**: How easy is it to write and maintain tests? - **Language Support**: Does the framework support TypeScript and Python, the two languages our team uses most frequently? - **Interactive UI Testing**: How well does the framework handle complex, interactive user interfaces such as charts, file uploads, and dynamic data? - **CI/CD Integration**: How well does the framework integrate into common CI/CD tools and services? - **Cross-browser Support**: What browsers are supported and how well do they perform? - **Performance and Speed**: How quickly do tests run, especially in a CI/CD pipeline? - **Scalability**: How well can the framework scale if more tests or more complex scenarios are added? - **Community and Ecosystem**: How active is the framework's community? Are there plenty of integrations and extensions available? ### 5. **Considerations** #### 5.1 **Playwright** ##### **Pros**: 1. **Smarter API for Local File Uploads**: Playwright’s API for interacting with local files and performing file uploads is simpler and more intuitive. This would make file upload testing easier to implement and maintain. 2. **Syntax and Code Generation**: Playwright has a shorter, more concise syntax. This results in less boilerplate code, which improves maintainability and developer efficiency. Additionally, this shorter syntax improves OpenAI code generation quality, making it easier to automatically generate test scripts. 3. **Interactive UI Testing**: Playwright excels at testing dynamic, interactive web applications, such as those with rich charts, complex user interactions, and real-time updates. It handles WebSockets, WebRTC, shadow DOMs, and other modern web technologies very effectively. 4. **Cross-browser Support**: Playwright supports **Chromium**, **WebKit**, and **Firefox**. It has consistent performance across these browsers, which should cover most of our testing needs. 5. **CI/CD Integration**: Playwright integrates seamlessly with modern CI/CD platforms (GitHub Actions, Jenkins, etc.). It can run tests in parallel across different browsers, optimizing test run times and making it suitable for rapid development. 6. **Fast and Reliable**: Playwright is faster than Selenium in general, especially in headless mode, and more resilient when dealing with asynchronous web elements. ##### **Cons**: 1. **Limited Mobile Testing**: While Playwright does support mobile emulation for browsers, it lacks native mobile testing capabilities like Selenium’s integration with Appium for true mobile testing. 2. **Smaller Ecosystem**: Playwright is still newer and less established than Selenium. While it has a rapidly growing community and good documentation, it might not yet have the vast ecosystem of plugins and integrations that Selenium offers. 3. **Limited Browser Support**: While Playwright covers the major modern browsers (Chrome, Safari, Firefox), its support for legacy browsers (e.g., Internet Explorer) is not as robust as Selenium’s. #### 5.2 **Selenium** ##### **Pros**: 1. **Longer History and Maturity**: Selenium has been around for a long time and has a proven track record. It’s widely used across many teams and industries, which has led to a vast ecosystem of plugins, integrations, and resources. 2. **Cross-browser and Cross-platform Support**: Selenium supports a **wide variety of browsers** and versions, including **Internet Explorer**, and can also be integrated with various tools like **Docker**, **Selenium Grid**, and **cloud services** for distributed testing. 3. **Mobile Testing**: Selenium, through its integration with **Appium**, is much more robust for mobile testing, including both Android and iOS applications. This makes it the better choice for projects with a mobile-first or mobile-heavy focus. 4. **Multi-monitor Testing**: Selenium provides better support for scenarios involving **multiple monitors** or complex multi-window interactions. ##### **Cons**: 1. **Complexity**: Selenium’s API is more verbose and explicit. While this can be an advantage in some cases, it means more code to write and maintain, which may reduce developer agility—especially important in a startup environment. 2. **Performance**: Selenium generally runs slower than Playwright, especially in headless mode. This could impact CI/CD pipelines, particularly as the number of tests grows. 3. **Interactive UI Testing**: Selenium is not as smooth as Playwright when it comes to testing modern, interactive web UIs, particularly with charts and real-time data updates. It requires more setup and handling to reliably interact with dynamic content. ### 6. **Comparison Summary** | Feature | Playwright | Selenium | |-----------------------------------|-----------------------------------------------|-------------------------------------------| | **Ease of Use** | Shorter syntax, more intuitive for modern UIs | More explicit, requires more boilerplate | | **Language Support** | TypeScript, Python, JavaScript | TypeScript, Python, Java, Ruby, C# | | **Interactive UI Testing** | Excellent for dynamic, real-time UIs | Handles basic UIs, but more verbose and complex for rich interactions | | **File Upload Testing** | Smarter API for file uploads | More verbose, less intuitive API | | **CI/CD Integration** | Easy integration with GitHub Actions, Jenkins | Strong integration with many CI tools | | **Mobile Testing** | Limited, only emulation | Full support through Appium | | **Cross-browser Support** | Chromium, WebKit, Firefox | Full support across major and legacy browsers | | **Performance** | Fast, optimized for headless testing | Slower, especially in headless mode | | **Multi-monitor Testing** | Limited | Good support for multi-monitor setups | | **Community and Ecosystem** | Growing, good documentation | Large, mature, extensive ecosystem | ### 7. **Decision** After considering the requirements and trade-offs, **Playwright** is the better choice for our current needs. Its smarter API for local file upload testing, concise syntax, and strong support for interactive UI testing make it an ideal fit for our agile development cycle. The fact that it supports both **TypeScript** and **Python** is critical for our team, and the framework's modern approach to testing will allow us to write clean, maintainable code. While **Selenium** remains a great tool, particularly for mobile testing, legacy browser support, and multi-monitor setups, it is less well-suited to our current needs. Its verbosity, slower performance, and more complex handling of dynamic UIs like charts make it less optimal for our use case. ### 8. **Consequences** - **Immediate Action**: We will adopt **Playwright** for our E2E testing, focusing on testing user flows involving sign-up, sign-in, file uploads, dashboards, and report downloads. - **Long-Term Considerations**: We will keep an eye on the evolving Playwright ecosystem. If our needs change, particularly around mobile testing or support for legacy browsers, we may revisit Selenium. - **Training and Documentation**: Development teams will need to become familiar with Playwright's API, particularly for handling dynamic UIs and file uploads. - **Migration**: Existing Selenium tests (if any) will be gradually migrated to Playwright. ### 9. **Future Considerations** ================================================ FILE: locales/en/examples/chart-library-toolkit-for-data-visualization-using-typescript-and-json/index.md ================================================ # Architecture Decision Record: chart library toolkit for data visualization using TypeScript and JSON **Primary Objective:** To select an advanced charting toolkit for creating interactive visualizations, focusing on financial data, scientific data, and government data using TypeScript and JSON. The library should provide robust features, flexibility, and be open-source. ### Context and Requirements: 1. **Agile Development (High Priority)**: As a startup, quick iteration, prototyping, and flexibility in development are essential. The chart library must allow for fast development cycles. 2. **Chart Types (High Priority)**: - **Doughnut Chart** - **Radar Chart** - **Clustering Process Chart** - **Area Chart with Time Axis** - **Candlestick Chart** - **Nightingale Chart** - **Geo SVG Map** These chart types are specifically important for visualizing complex datasets, such as financial trends, scientific metrics, and geographical information. 3. **Free and Open Source (High Priority)**: The toolkit should be open-source to avoid licensing costs, provide transparency, and offer flexibility for customization. 4. **Low Importance Criteria**: - **Runtime Speed**: While performance is important, it is not a top priority for this decision. - **Scalability**: Although scalability is generally important, the immediate need is to build an MVP that may grow over time. Scalability concerns can be addressed later. - **Backwards Compatibility**: Not a primary concern for the initial build, as long as the library is modern and actively maintained. ### Libraries Evaluated: 1. **Apache ECharts** 2. **Chart.js** 3. **ApexCharts** 4. **AG Charts** 5. **Highcharts** 6. **Carbon Charts** 7. **Layer Cake** 8. **D3.js** --- ### 1. **Apache ECharts** **Overview**: Apache ECharts is a powerful, flexible charting library for interactive, customizable visualizations. It provides support for a wide variety of charts and is particularly strong in complex, dynamic visualizations. **Strengths**: - **Advanced Interactivity**: ECharts excels in providing interactive charts, offering features like zooming, panning, and dynamic data updates. - **Doughnut, Radar, Candlestick, Geo SVG Maps**: ECharts supports many of the required chart types, including doughnut, radar, candlestick, and geographical map visualizations. - **Free and Open Source**: ECharts is an open-source library, which fits the budget-conscious nature of a startup and provides freedom to modify the code. - **Flexibility and Extensibility**: Highly customizable, with extensive support for animations, custom visualizations, and advanced charting techniques. **Weaknesses**: - **Learning Curve**: ECharts, while powerful, can have a steeper learning curve due to its flexibility and extensive API. - **Documentation Complexity**: The documentation is comprehensive but can be overwhelming for developers just starting out with it. **Verdict**: ECharts is highly suitable for the project due to its support for interactive charts, including all the required types like candlestick charts, radar charts, and geo maps. Its open-source nature aligns with the project's need for flexibility and cost-effectiveness. --- ### 2. **Chart.js** **Overview**: Chart.js is a simple, easy-to-use charting library for building common chart types. It’s known for its simplicity and ease of integration. **Strengths**: - **Ease of Use**: Chart.js is very simple to set up and use, with a minimal learning curve. - **Open Source**: Chart.js is free and open-source, which is critical for reducing costs. - **Common Chart Types**: It supports basic charts like doughnut, area, radar, and line charts, which cover most of the primary needs. **Weaknesses**: - **Limited Advanced Charts**: Chart.js does not natively support complex chart types like candlestick charts, geo SVG maps, or clustering process charts. While these features can be added through plugins or customization, it is not as straightforward as with other libraries. - **Interactivity**: Although Chart.js supports basic interactivity (e.g., tooltips and hover effects), it does not offer as advanced features as ECharts or D3.js. **Verdict**: Chart.js is great for simple, quick projects, but its lack of support for complex chart types makes it unsuitable for a data-heavy application with advanced needs like candlestick charts and geo maps. It’s a good choice for prototyping, but for the required chart types, more advanced tools are recommended. --- ### 3. **ApexCharts** **Overview**: ApexCharts is a modern charting library that provides a variety of chart types and focuses on interactive visualizations with an easy-to-use API. **Strengths**: - **Interactive Features**: ApexCharts offers interactive charts with tooltips, zooming, panning, and updates. - **Support for Financial and Scientific Charts**: It supports a wide variety of chart types, including candlestick charts, radar charts, and area charts. - **Ease of Use**: It has a straightforward API and is simple to integrate into a project. - **Free and Open Source**: ApexCharts offers a free open-source version that is suitable for many use cases. **Weaknesses**: - **Complex Customization**: While it provides many features, the customization options are not as flexible as ECharts or D3.js for highly complex or custom charting needs. - **Geo Maps**: ApexCharts does not natively support geo maps or clustering process charts, which are required for this project. **Verdict**: ApexCharts is a strong contender due to its ease of use and interactivity, but it falls short on certain advanced chart types, particularly the need for geo maps and clustering charts. It’s a good option for simpler charts but lacks some required features. --- ### 4. **AG Charts** **Overview**: AG Charts is a commercial-grade charting library designed for performance and precision. It is highly suitable for creating financial, scientific, and business dashboards. **Strengths**: - **Advanced Chart Types**: AG Charts supports many advanced chart types, including candlestick charts, area charts, radar charts, and more. It also offers deep integration with other AG-Grid products. - **High Performance**: It offers excellent performance, especially when dealing with large datasets. - **Interactivity**: AG Charts supports a variety of interactive features like zooming, tooltips, and dynamic updates. **Weaknesses**: - **Not Fully Free**: While AG Charts offers a free version, the full-featured version is paid, which could be a barrier for startups looking to minimize costs. - **Complexity**: While the library is feature-rich, it may be overkill for simpler projects and can require more setup and configuration compared to other options. **Verdict**: AG Charts is powerful and feature-rich but may not be the best fit due to its commercial nature and cost structure. Its suitability depends on whether the budget can accommodate paid versions or if open-source alternatives are preferred. --- ### 5. **Highcharts** **Overview**: Highcharts is a popular charting library known for its wide range of chart types and powerful customization options. **Strengths**: - **Comprehensive Chart Types**: Highcharts supports a wide variety of charts, including candlestick, radar, area, and geo maps. - **Interactive and Dynamic**: Highcharts provides rich interactive features, including drill-downs, zooming, and panning. - **Ease of Use**: It has a user-friendly API and good documentation, making it easy to get started. **Weaknesses**: - **Commercial License**: While Highcharts offers a free version for non-commercial use, the commercial license is expensive, which could be a significant drawback for startups. - **Learning Curve**: Although not as steep as ECharts, the learning curve for Highcharts can still be challenging for beginners. **Verdict**: Highcharts is a feature-rich library, but its commercial licensing makes it less suitable for open-source, cost-sensitive projects. Its comprehensive charting options are a plus, but the licensing issue limits its appeal for this use case. --- ### 6. **Carbon Charts** **Overview**: Carbon Charts is a charting library developed by IBM, designed for creating visually appealing and highly customizable charts. **Strengths**: - **Customizability**: Carbon Charts allows for extensive customization of chart appearance and behavior. - **Open Source**: It is free and open-source, which aligns with the project’s requirement for budget-friendly solutions. - **Support for Common Charts**: It supports common chart types like doughnut, radar, and area charts, though it lacks support for more advanced types like geo maps or candlestick charts. **Weaknesses**: - **Limited Advanced Chart Types**: It does not support geo maps, clustering process charts, or candlestick charts, which are essential for the project. - **Smaller Ecosystem**: Carbon Charts has a smaller community and ecosystem compared to larger chart libraries like ECharts or Highcharts. **Verdict**: Carbon Charts is open-source and customizable but lacks support for the more complex chart types needed for this project. It is more suitable for simpler charting needs. --- ### 7. **Layer Cake** **Overview**: Layer Cake is a data visualization library designed for creating flexible, layered visualizations. **Strengths**: - **Customizable Layers**: It provides powerful layering options for complex visualizations. - **Open Source**: It’s free and open-source, making it a viable option for budget-conscious projects. **Weaknesses**: - **Limited Documentation**: Layer Cake lacks extensive documentation and community support, making it more difficult to work with compared to more established libraries. - **Not Built for Charts**: Layer Cake is better suited for non-chart visualizations, so its out-of-the-box charting options are limited. **Verdict**: While interesting for unique visualizations, Layer Cake is not ideal for traditional charting requirements like candlestick charts or radar charts. It’s more suited for custom visualizations outside the scope of standard charts. --- ### 8. **D3.js** **Overview**: D3.js is a powerful JavaScript library for creating data-driven visualizations through HTML, SVG, and CSS. **Strengths**: - **Unmatched Flexibility**: D3.js allows for creating virtually any type of custom visualization, making it highly powerful for advanced and interactive charts. - **Extensive Features**: It supports all chart types required, including geo maps, clustering charts, and more. - **Customizable**: The level of customization in D3.js is unparalleled, allowing developers to build highly tailored visualizations. **Weaknesses**: - **Steep Learning Curve**: D3.js has a steep learning curve and is more complex to integrate compared to other libraries. - **Time-Consuming**: Building charts in D3.js can be time-consuming, especially for common charts like candlestick or doughnut charts. **Verdict**: D3.js is incredibly powerful for advanced, customized charts but is overkill for many typical use cases due to its steep learning curve and development time. It’s best for situations where the other chart libraries do not provide the required level of customization. --- ### Conclusion After evaluating the libraries based on the project’s needs, **Apache ECharts** stands out as the best option. It supports the full range of required charts, including geo maps, candlestick charts, and clustering charts. It’s open-source, feature-rich, and highly interactive, which aligns perfectly with the project's goals. While **D3.js** offers the most flexibility, its complexity and time investment make it less ideal for a startup looking to iterate quickly. **ApexCharts** and **Chart.js** are good alternatives for simpler projects but lack support for advanced chart types. ================================================ FILE: locales/en/examples/choosing-a-database-technology/.locale-peer-id ================================================ ee24129d8750e5ceebb9b4ff7b3cfb1a ================================================ FILE: locales/en/examples/choosing-a-database-technology/index.md ================================================ # Architecture Decision Record: Choosing a Database Technology ## Status Accepted ## Context We are designing a new application that requires storing and retrieving data in a scalable and performant manner. We have identified three types of database technologies that are commonly used: relational databases, document databases, and event databases. Relational databases store data in tables with fixed schemas and enforce strict data integrity constraints. They are suitable for applications that require complex data relationships and transactions. Examples include MySQL, PostgreSQL, and Oracle. Document databases store data in JSON-like documents and are schema-less. They are well-suited for applications that require flexible data models and scaling horizontally. Examples include MongoDB, Couchbase, and Amazon DynamoDB. Event databases store data as a series of events, capturing every change to the data. They are suitable for applications that require auditing, event sourcing, and complex data processing. Examples include Apache Kafka, Apache Pulsar, and AWS Kinesis. Decision After carefully evaluating the requirements and constraints of our application, we have decided to use a document database. ## Rationale We have chosen a document database because: 1. Our application requires a flexible data model that can evolve over time. Document databases allow us to store data in a schema-less format, which means we can add new fields or change the structure of existing documents without having to modify the database schema. 2. Our application needs to scale horizontally to handle large volumes of data and traffic. Document databases provide built-in support for sharding and replication, which enables us to distribute data across multiple servers and handle high read and write throughput. 3. Our application requires fast and efficient data retrieval. Document databases provide powerful indexing and querying capabilities that enable us to retrieve data quickly and efficiently. 4. Our application does not require complex transactions or data relationships. While relational databases excel at enforcing data integrity constraints and handling complex transactions, our application does not have such requirements. Document databases can provide sufficient consistency and durability guarantees for our use case. ## Consequences By choosing a document database, we will need to invest in learning and understanding the specific technology we choose to use. Additionally, we will need to ensure that our application's data model fits well with the document database's data model to maximize performance and scalability. However, we believe that the benefits of using a document database outweigh the costs, and that it is the best fit for our application's requirements and constraints. ================================================ FILE: locales/en/examples/continuous-integration/.locale-peer-id ================================================ 45cdbd2e37d773b7e0592a142fd5de30 ================================================ FILE: locales/en/examples/continuous-integration/index.md ================================================ # Decision Record for continuous integration Title: Decision to Implement Continuous Integration ## Context The company has been experiencing challenges with the development process as a result of manual testing, build processes, and deployments. This has led to frequent delays, errors and inconsistencies in the quality and delivery of the software. ## Decision To implement continuous integration as a solution to the challenges experienced in the development process. ## Rationale Continuous integration will automatically build, test and deploy code changes to the delivery environment in a timely and efficient manner. It will enable integration of new features into the codebase without interfering with the stability of the software. Continuous integration will enhance the quality and delivery of the software, reduce the time taken to resolve errors and improve stakeholder satisfaction. ## Consequences Positive: - Improved quality and delivery of software - Time and cost savings through automation - Enhanced collaboration and integration within the development team Negative: - Initial costs associated with implementing the technology - Upfront investment in people, tools and processes required to implement continuous integration - Potential risk of technical difficulties during the implementation. ## Conclusion The benefits of implementing continuous integration outweigh the costs of investment and the potential risks. Therefore, the decision to implement continuous integration has been approved. ================================================ FILE: locales/en/examples/css-framework/.locale-peer-id ================================================ 694d2d4235299f058990c1cc470af15e ================================================ FILE: locales/en/examples/css-framework/index.md ================================================ # Architecture Decision Record: CSS framework Contents: - [Summary](#summary) - [Issue](#issue) - [Decision](#decision) - [Status](#status) - [Details](#details) - [Assumptions](#assumptions) - [Constraints](#constraints) - [Positions](#positions) - [Argument](#argument) - [Implications](#implications) - [Related](#related) - [Related decisions](#related-decisions) - [Related requirements](#related-requirements) - [Related artifacts](#related-artifacts) - [Related principles](#related-principles) - [Notes](#notes) ## Summary ### Issue We want to use a CSS framework to create our web applications: * We want user experience to be fast and reliable, on all popular browsers and screen sizes. * We want rapid iteration on design, layout, UI/UX, etc. * We want responsive applications, especially for smaller screens such as on mobile devices, larger screens such as on 4K widescreens, and dynamic screens such as rotatable displays. ### Decision Decided on Bulma. ### Status Decided on Bulma. Open to new CSS framework choices as they arrive. ## Details ### Assumptions We want to create web apps that are modern, fast, reliable, responsive, etc. Typical modern web apps are reducing/eliminating the use of jQuery because of multiple reasons: * Modern JavaScript is phasing in many capabilities that jQuery has provided, so jQuery is less needed, and there are better/faster/smaller modules that provide specific implementations * jQuery's broad approach is to do direct DOM manipulation, which is an anti-pattern for modern JavaScript frameworks (e.g. React, Vue, Svelte) * jQuery interferes with itself if it's loaded twice, etc. ### Constraints If we choose a CSS framework that uses jQuery, then we're stuck importing jQuery. For example, Semantic UI uses jQuery, and Tachyons does not. If we choose a CSS framework that is minimal, then we forego framework components that we may want now or soon. For example, Semantic UI provides an image carousel, and Tachyons does not. ### Positions We considered using no framework. This still seems viable, especially because CSS grid provides much of what we need for our project.. We considered many CSS frameworks using a quick shortlist triage: Bootstrap, Bulma, Foundation, Materialize, Semantic UI, Tachyons, etc. Our two selections for deeper review are Semantic UI (because it has the most-semantic approach) and Bulma (because it has the lightest-weight approach that provides the components we want now). We considered Semantic UI. This provides many components, including ones we want for our project: tabs, grids, buttons, etc. We did a pilot with Semantic UI two ways: using typical CDN files, and using NPM repos. We achieved success with Semantic UI in a static HTML page, but did not achieve success within our timebox to build a JavaScript SPA (primarily because of jQuery load issues). We discovered that other coders have been asking the Semantic UI developers to create a jQuery-free version, for the same reasons we have. Other coders have been requesting a jQuery-free version for many years, yet the developers have said no, and stated that any jQuery-free version would be too hard to write e.g. ~"the Semantic UI project has more than 22,000 touchpoints that use jQuery". Example with Semantic: ```html
Alpha Bravo
``` We considered Bulma. Bulma has many similar capabilities as Semantic UI, although not as many sophisticated components. Bulma is built with modern techniques, such as no jQuery. Bulma has some third-party components, some of which we may want to use. Example with Bulma: ```html
``` ### Argument As above. Specifically, Semantic UI seems to have a caution flag both in terms of technology (i.e. so many jQuery touchpoints) and also in terms of leadership (i.e. jQuery-free was a hard no, rather than attempting a roadmap, or continuous improvement, or donation fundraising, etc.). ### Implications If we find a good non-jQuery CSS framework, this is generally helpful and good overall. ## Related ### Related decisions The CSS framework we choose may affect testability. ### Related requirements We want to ship a purely-modern app fast. We do not want to spend time working on older frameworks (esp. Semantic UI) using older dependencies (esp. jQuery). ### Related artifacts Affects all the typical HTML that will use the CSS. ### Related principles Easily reversible. Need for speed. ## Notes Any notes here. ================================================ FILE: locales/en/examples/docker-swarm-container-orchestration/.locale-peer-id ================================================ 3d27355877340537b28efb2bae3a6907 ================================================ FILE: locales/en/examples/docker-swarm-container-orchestration/index.md ================================================ # Architecture Decision Record: Docker Swarm Container Orchestration Decision Number: 001 Decision Maker: [Your name or position] Date: [Date of decision] ## Context We are considering different container orchestration tools to manage our microservices-based architecture. We have evaluated different solutions like Kubernetes, Docker Swarm, and Mesosphere DC/OS. However, we have decided to focus on Docker Swarm due to its simplicity, integration with Docker, and built-in load balancing. ## Decision We have decided to use Docker Swarm as our container orchestration tool. Docker Swarm provides a simple and intuitive way to manage containerized applications across a cluster of nodes. It also allows us to leverage our existing Docker-based workflows and infrastructure. With Docker Swarm, we can easily deploy, scale, and manage our applications, all while taking advantage of built-in load balancing. ## Benefits - **Simplicity:** Docker Swarm follows the same principles as Docker, so there's no need to learn a new technology. The learning curve is relatively shallow for developers familiar with Docker. - **Integration:** Docker Swarm integrates seamlessly with Docker tools, like Docker Compose, making it easier to manage all our containers and services from one place. - **Load balancing:** Docker Swarm provides built-in load balancing, ensuring that our applications are always available and evenly distributed across the cluster. - **Scalability:** Docker Swarm makes it easy to scale our applications horizontally by adding or removing nodes from the cluster. - **High availability:** Docker Swarm automatically distributes our services across nodes, providing high availability in case of node failure. ## Risks - **Limited functionality:** Docker Swarm may lack some of the advanced features found in Kubernetes or Mesosphere DC/OS, like automatic scaling or self-healing. - **Docker-centric:** Docker Swarm is tightly coupled with Docker, which may limit our flexibility if we ever need to move away from Docker-based solutions. - **Immaturity:** Docker Swarm is still a relatively new technology, and there may be some stability issues or gaps in documentation. ## Alternatives - **Kubernetes:** Kubernetes is the most widely-used container orchestration platform and provides advanced features and a more mature ecosystem. However, it has a steeper learning curve and may be overkill for our needs. - **Mesosphere DC/OS:** Mesosphere DC/OS is a powerful tool that provides advanced features like multi-cloud support and native big data and AI platform capabilities. However, it requires significant expertise to implement and may be too complex for our requirements. ## Conclusion After careful consideration, we have decided to use Docker Swarm as our container orchestration tool. Docker Swarm provides the simplicity, integration, and built-in load balancing we need to manage our containerized applications. Although it may lack some advanced features, we believe Docker Swarm's benefits outweigh its risks for our current requirements.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/environment-variable-configuration/.locale-peer-id ================================================ 46b0910941ab1812cda52b34baca5798 ================================================ FILE: locales/en/examples/environment-variable-configuration/index.md ================================================ # Environment variable configuration Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications ](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes) ## Summary ### Issue We want our applications to be configurable beyond artifacts/binaries/source, such that one build can behave differently depending on its deployment environment. * To accomplish this, we want to use environment variable configuration. * We want to manage the configuration by using files that we can version control. * We want to provide some developer experience ergonomics, such as knowing what can be configured and any relevant defaults. ### Decision Decided on .env files with related default file and schema file. ### Status Decided. Open to considering to new capabilities as they come up. ## Details ### Assumptions We favor separating the application code and environment code. We assume the app needs to work differently in different environments, such as in a development environment, test environment, demo environment, production environment, etc. We favor the industry practice of "12 factor app" and even more the related practice of "15 factor app". Many of our previous projects have used the convention of a `.env` file or similar `.env` directory. There's a typical practice of keeping these out of version control, and instead using some other way to deploy them, version them, and manage them. ### Constraints We want to keep secrets out of our source code management (SCM) version control system (VCS). We want to aim for compatibility with popular software frameworks and libraries. For example, Node has a module "dotenv" for reading environment variable configuration. ### Positions We considered a few approaches: * Store config in the app such as in a file `config.js` file. * Store config in the environment such as in a file `.env`. * Fetch config from a known location such as a license server. ### Argument We selected the approach of a file .env because: * It is popular including among experts. * It follows the pattern of `.env` files which our teams have successfully used many times on many projects. * It is simple. Notably, We are fine for now with the significant trade-offs that we see, such as a lack of audit capabilities as compared to an approach of a license server. ### Implications We need to figure out a way to separate environment variable configuration that is public from any secrets management. ## Related ### Related decisions We expect all our applications to use this approach. We will plan to upgrade any of our applications that use a less-capable approach, such as hardcoding in a binary or in source code. We will keep as-is any of our applications that use a more-capable approach, such as a licensing server. ### Related requirements We will add devops capabilities for the files, including hooks, tests, and continuous integration. We need to train all developer teammates on this decision. ### Related artifacts Each area where we deploy will need its own .env file and related files. ### Related principles Easily reversible. ## Notes Example file `.env`: ```env NAME=Alice Anderson EMAIL=alice@example.com ``` Example file `.env.defaults`: ```env NAME=Joe Doe EMAIL=joe@example.com ``` Example file `.env.schema` with just the keys: ```env NAME EMAIL ``` ================================================ FILE: locales/en/examples/go-programming-language/.locale-peer-id ================================================ 77c69ad4fd10a2dc47f3f7a6dcbbef68 ================================================ FILE: locales/en/examples/go-programming-language/index.md ================================================ # Architecture Decision Record: Go programming language Title: Adoption of Go Programming Language Status: Accepted ## Context Our organization has been primarily using Java programming language for building web applications. However, we have been experiencing some challenges due to Java's verbosity and the complexity of some frameworks. Also, our team has shown interest in exploring modern programming languages for more efficient and robust development. After conducting research, we have identified Go as a potential solution to the problems we face with Java. ## Decision We will adopt Go programming language for building web applications going forward. ## Rationale 1. **Simplicity and readability:** Go is known for its simplicity and concise syntax. This makes it easy to read and write code, reducing the complexity of our development process. 2. **High-performance and scalability:** Go is compiled into machine code that runs natively on the server. This results in faster execution times and better performance compared to interpreted languages like Java. Additionally, Go's concurrency model handles multiple requests simultaneously, making it highly scalable. 3. **Strong community support:** Go has a vibrant community of developers who have contributed to its growth over the years. This means that there are plenty of resources, libraries, and frameworks to help us get started and build robust applications. 4. **Flexibility:** Go can be used for both frontend and backend development. This means that we can leverage its advantages in both areas for our development projects. ## Implications 1. **Training:** Our developers will need to undergo training to learn the Go programming language and its nuances. 2. **Experience:** We may face some challenges as we transition from Java to Go. It may take some time for our developers to become proficient with the new language. 3. **Tooling:** We will need to adopt new tools and frameworks that are specific to Go. However, we can leverage existing infrastructure that we have in place to minimize the impact of this change. 4. **Vendor lock-in:** Go is an open-source programming language, and we will not be tied to any vendor or service provider. ## Conclusion The adoption of Go programming language will help us improve our development process and build robust applications. We will need to invest resources in training and tools to support this transition, but we believe that the benefits of this decision outweigh the costs.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/google-cloud-platform/.locale-peer-id ================================================ 819cd06503cb318caf8f90fcff244b84 ================================================ FILE: locales/en/examples/google-cloud-platform/index.md ================================================ # Architecture Decision Record for Google Cloud Platform ## Context Google Cloud Platform (GCP) is a prominent cloud computing platform that offers various cloud services, including computing, storage, and networking solutions. This ADR aims to document the architectural decisions made for developing and implementing a GCP-based infrastructure for our organization. ## Decision Our organization has decided to use Google Cloud Platform as the cloud infrastructure for our application. The primary considerations for this decision are: - Cost-effectiveness - Scalability - Reliability - Flexibility ## Selections The following services from GCP have been selected to meet our requirements: - Compute Engine for virtual machines and computing resources - Cloud Storage for object storage and file hosting - Cloud SQL for managed database service - Firebase for app development and hosting ## Rationale - Cost-Effectiveness: Google Cloud Platform is highly cost-effective compared to other cloud platforms, making it an attractive option for organizations with budget constraints. - Scalability: GCP's easy-to-scale infrastructure enables handling any amount of traffic in real-time. - Reliability: GCP's managed services offer high reliability, with automated backups and disaster recovery capabilities that ensure high availability of resources and data. - Flexibility: The platform provides various tools and services across different domains such as AI, data analytics, and IoT, making it highly versatile. ## Consequences Migrating to Google Cloud Platform will require training our teams on GCP services, re-architecting the application to be compatible with the selected services, and updating the infrastructure code to support GCP services. However, it is expected that once the migration is completed, we will have a highly scalable, reliable, and cost-effective infrastructure for hosting our application. Also, we will need to manage the ongoing costs of provisioning resources on GCP. ## Conclusion Google Cloud Platform is an excellent choice for our cloud infrastructure due to its cost-effectiveness, scalability, reliability, and flexibility. By utilizing the selected services, we can provide a highly available and robust infrastructure for our application. ================================================ FILE: locales/en/examples/high-trust-teamwork/.locale-peer-id ================================================ 912115918de8642859827f500f4aca23 ================================================ FILE: locales/en/examples/high-trust-teamwork/index.md ================================================ # Decision Record for High Trust Teamwork Date: [Insert Date] Participants: [Insert Names of Participants] Decision Reach: [Unanimous/ Majority decision/ Individual Decision] ## Decision Description The decision to adopt High Trust Teamwork as a core value and belief in our team and organizational culture. ## Alternatives Considered We considered alternative approaches to teamwork, including low trust or no trust teamwork, as well as other frameworks such as cognitive diversity teams, centralized decision-making teams, and agile teams. ## Benefits and Risks The benefits of high trust teamwork include improved collaboration, better decision-making, increased motivation and engagement, higher job satisfaction and retention rates, and enhanced innovation and creativity. The risks associated with high trust teamwork include the potential for trust breaches, conflicts, and misunderstandings due to miscommunications or not adhering to the high trust principles. ## Decision Outcome It was unanimously agreed upon to adopt high trust teamwork as the core value and belief in our team and organizational culture. We acknowledged the importance of building and maintaining trust through transparency, honesty, integrity, and respect, and recognized that this approach would help us to establish a positive and rewarding work environment. ## Action Items To implement high trust teamwork, we will take the following steps: 1. Define high trust principles and practices and communicate these to all team members 2. Establish regular feedback mechanisms and communication channels to keep the team updated on progress, challenges, and opportunities 3. Attend training on high trust teamwork and actively participate in team-building activities 4. Encourage and recognize behaviors that demonstrate high trust principles in action 5. Develop a plan to address potential trust breaches, conflicts, or misunderstandings and have a process to handle such situations effectively ================================================ FILE: locales/en/examples/index.md ================================================ # Decision record examples * [CSS framework](css-framework) * [Environment variable configuration](environment-variable-configuration) * [Metrics, monitors, alerts](metrics-monitors-alerts) * [Microsoft Azure DevOps](microsoft-azure-devops) * [Monorepo vs multirepo](monorepo-vs-multirepo) * [Programming languages](programming-languages) * [Secrets storage](secrets-storage) * [snake_case v. camelCase for a REST API](snake-case-v-camelcase-for-a-rest-api) * [Timestamp format](timestamp-format) ChatGPT examples: * [API using JSON v. gRPC](api-using-json-v-grpc) * [Choosing a database technology](choosing-a-database-technology) Specific programming languages: * [Go programming language](go-programming-language) * [Rust programming language](rust-programming-language) * [Java programming language](java-programming-language) * [Python programming language](python-programming-language) Specific databases: * [MySQL database](mysql-database) * [PostgreSQL database](postgresql-database) Specific container orchestration: * [Docker Swarm container orchestration](docker-swarm-container-orchestration) * [Kubernetes container orchestration](kubernetes-container-orchestration) Specific web frameworks, libraries, and styles: * [React front end JavaScript library](react-front-end-javascript-library) * [Ruby on Rails framework](ruby-on-rails-framework) * [Svelte front end JavaScript library](svelte-front-end-javascript-library) * [SvelteKit framework](sveltekit-framework) * [Tailwind CSS](tailwind-css) * [Vue front end JavaScript library](vue-front-end-javascript-library) ================================================ FILE: locales/en/examples/java-programming-language/.locale-peer-id ================================================ 984e1e50927d81ec862d5899cd3cb077 ================================================ FILE: locales/en/examples/java-programming-language/index.md ================================================ # Architecture Decision Record: Java programming language Title: Choosing Java Programming Language for the Project Decision: After evaluating multiple programming languages, we have decided to use Java for our project. ### Background We intended to build a web-based application that could run on multiple operating systems. Our project required a language that could provide strong security features, handle concurrency, support large code bases, and be versatile enough to meet our future growth requirements. We evaluated several languages, considering their strengths and limitations, before deciding on Java. ### Considerations 1. **Security:** Java provides excellent security features through its well-defined security policies and access control. It also incorporates features like bytecode verification, which helps prevent malicious software from running on a system. 2. **Concurrency:** Java has built-in support for multithreading, which allows applications to perform several tasks simultaneously. This feature makes Java an excellent choice for developing large, complex applications with multiple features and functionalities. 3. **Large codebases:** Java supports object-oriented programming, which makes it a suitable choice for developing large codebases. Its modular nature and use of encapsulation and abstraction patterns further add to the software development process's ease. 4. **Versatility:** Java is versatile and provides the ability to use a wide range of libraries and frameworks, making it an excellent choice for both web-based and enterprise-level applications. ### Decision Outcome We have decided to use the Java programming language for our project, considering its security features, concurrency support, ability to handle large codebases, and versatility. This decision aligns with our project requirements, and we believe that choosing Java will ensure its success. ### Consequences 1. We will need developers who have experience with Java and can use it proficiently. 2. Any code written in the language must be compatible with the Java Virtual Machine (JVM). 3. Incorporating new features, functionalities, or frameworks may present some challenges. 4. Large, complex projects in Java may require more time and resources to develop.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/kubernetes-container-orchestration/.locale-peer-id ================================================ cb3edecf9181c9c28bbbbc5d323ec733 ================================================ FILE: locales/en/examples/kubernetes-container-orchestration/index.md ================================================ # Architecture Decision Record: Kubernetes container orchestration ## Problem Statement We need to select a container orchestration platform for our growing cloud-native application portfolio. Our current legacy platform deployment is too slow, and not agile enough to keep up with our growing needs. We’re looking for a system that will allow us to scale our services in the most efficient way possible without compromising on agility or ease of use. ## Considered Alternatives 1. Docker Swarm 2. Kubernetes 3. Apache Mesos ## Decision Made After conducting a thorough analysis of each container orchestration platform, we have decided to adopt Kubernetes as the best option for our enterprise needs. Our reasons for choosing Kubernetes are as follows: 1. **Scalability:** Kubernetes’s unique design is perfect for scaling applications, and as our requirements for scalability evolve over time, Kubernetes has the built-in ability to meet these changes without any issues. 2. **Decentralized Architecture:** Kubernetes’ master-worker topology ensures a decentralized architecture which ensures that there is no single point of failure. 3. **Community Support:** Kubernetes has the largest and most active open-source community, which means it has a large number of contributors, developers, and vendors making it easier for us to get help and find resources. 4. **Ecosystem Support:** Kubernetes has a growing ecosystem with a variety of third-party tools, integrations with container registries, CI/CD pipelines, data storage, and more. Therefore, we have decided to adopt Kubernetes as our container orchestration platform for the present and the immediate future.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/metrics-monitors-alerts/.locale-peer-id ================================================ d97e71af7770a8cfefb718b2ffd28062 ================================================ FILE: locales/en/examples/metrics-monitors-alerts/index.md ================================================ # Metrics, monitors, alerts Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes) * [Freeform text messages vs structured event messages](#freeform-text-messages-vs-structured-event-messages) * [Graylog is easier](#graylog-is-easier) * [Prometheus take some tuning](#prometheus-take-some-tuning) * [AWS services are mixed](#aws-services-are-mixed) * [Kafka](#kafka) * [Loki](#loki) * [Prometheus + alertmanager + Rollbar + Graylog + Grafana](#prometheus-alertmanager-rollbar-graylog-grafana) * [Thanos](#thanos) * [Prometheus HA](#prometheus-ha) * [Datadog + PagerDuty + Threat Stack](#datadog-pagerduty-threat-stack) * [Zabbix](#zabbix) * [Outlyer](#outlyer) * [Nagios + Nagiosgraph](#nagios-nagiosgraph) * [Prometheus + Grafana + AlertManager](#prometheus-grafana-alertmanager) * [DataDog + Sentry + PagerDuty.](#datadog-sentry-pagerduty) * [Sensu + Graphite + ELK](#sensu-graphite-elk) * [Prometheus + Alertmanager](#prometheus-alertmanager) * [Sensu + Grafana + Graylog + Kibana + NewRelic.](#sensu-grafana-graylog-kibana-newrelic) * [Prometheus + Circonus](#prometheus-circonus) * [icinga2 + VictorOps + NewRelic + Sentry + Slack](#icinga2-victorops-newrelic-sentry-slack) * [AppDynamics + Papertrail + PagerDuty + Healthchecks.io + Stackdriver](#appdynamics-papertrail-pagerduty-healthchecks-io-stackdriver) * [icinga2 + elasticsearch](#icinga2-elasticsearch) * [DataDog + New Relic + ELK + EFK + Sentry + Alertmanager + VictorOps](#datadog-new-relic-elk-efk-sentry-alertmanager-victorops) * [Wavefront + Scalyr + PagerDuty + Stackstorm + Slack](#wavefront-scalyr-pagerduty-stackstorm-slack) * [Telegraf + Prometheus + InfluxDB + Grafana](#telegraf-prometheus-influxdb-grafana) * [Sematext + Logagent + Experience](#sematext-logagent-experience) * [Azure Monitor/Analytics + OpsGenie](#azure-monitor-analytics-opsgenie) * [Prometheus + Alertmanager + Grafana + Splunk + PagerDuty](#prometheus-alertmanager-grafana-splunk-pagerduty) * [Telegraf + Prometheus + Grafana + Alertmanager](#telegraf-prometheus-grafana-alertmanager) * [Prometheus + Grafana + Cloudwatch + sentry + kibana + elasticsearch](#prometheus-grafana-cloudwatch-sentry-kibana-elasticsearch) * [PagerDuty + Monitis](#pagerduty-monitis) * [Prometheus + Grafana + Bosun](#prometheus-grafana-bosun) * [Azure Monitor/Analytics/Insights/Dashboards](#azure-monitor-analytics-insights-dashboards) * [Grafana + Monitis + OpsGenie + Slack](#grafana-monitis-opsgenie-slack) * [Checkly + AppOptics + Cloudwatch + Heroku + Pagerduty + Papertrail](#checkly-appoptics-cloudwatch-heroku-pagerduty-papertrail) * [Instana + Logz.io + slack](#instana-logz-io-slack) * [SignalFX + Splunk + PagerDuty + Slack](#signalfx-splunk-pagerduty-slack) * [ELK + Prometheus + Grafana](#elk-prometheus-grafana) * [Datadog + Prometheus + Grafana](#datadog-prometheus-grafana) * [Nagios + ELK](#nagios-elk) * [Datadog vs. Site24x7 + StatusCake + PagerDuty + SumoLogic + Slack](#datadog-vs-site24x7-statuscake-pagerduty-sumologic-slack) * [Prometheus + AlertManager + Grafana + Stackdriver](#prometheus-alertmanager-grafana-stackdriver) * [Zabbix](#zabbix) ## Summary ### Issue We want to use metrics, monitors, and alerts, because we want to know how well our applications are working, and to know when there's a problem. ### Decision WIP. ### Status Gathering information. We are starting with the plausible ends of the spectrum: the most-recommended older free tool (Nagios) and the most-recommended newer paid tool (New Relic). ## Details ### Assumptions We want to create web apps that are modern, fast, reliable, responsive, etc. We want to buy rather than build. ### Constraints We want tooling that works well with our devops pipeline and with our deployment clouds. ### Positions We are researching positions now. * AlertManager * AppDynamics * AppOptics * Azure Monitor/Analytics/Insights/Dashboards * Bosun * Checkly * Circonus * Cloudwatch * EFK * ELK * Grafana * Grafana * Graphite * Graylog * Healthchecks.io * Heroku * icinga2 * InfluxDB * Instana * Kafka * Logagent * Logz.io * Loki * Monitis * Nagios * Nagios * Nagiosgraph * NewRelic * OpsGenie * Outlyer * PagerDuty * Pagerduty * PagerDuty * Papertrail * Prometheus * Rollbar * Scalyr * Sematext Metrics, Logs, Experience, Tracing * Sensu * SignalFX * Slack * Splunk * Stackdriver * Stackstorm * Telegraf * Telegraf * Thanos * VictorOps * Wavefront * Zabbix ### Argument So far, Nagios and New Relic are the ends of the spectrum. Nagios is the oldest, simplest, free, viable tool. New Relic is the newest-featured, most-complete, paid, viable tool. We will start with evaluations of these. As needed, we will migrate into the spectrum. So far, Zabbix has the best recommendations, and also offers the most complete capabilities. So far, ELK has the best open-source build-over-buy popularity. So far, Prometheus + Graphana have the best popularity. ### Implications TODO. ## Related ### Related decisions The choices will affect testability, telemetry, and likely other systems such as for customer service, site reliability engineering, etc. ### Related requirements TODO. ### Related artifacts TODO. ### Related principles Easily reversible. Need for speed. ## Notes A pretty good open source stack is: * Prometheus for metrics and alerting based on metrics * Grafana to display metrics * Elasticsearch/Logstash/Kibana (ELK) for logs and structured events * Pushover for mobile notifications ### Freeform text messages vs structured event messages Freeform text messages: for example, the kind of random stuff you would find in /var/log/messages, and something generated intentionally by the application. The messages are useful for identifying other things that are happening on the box like out of memory or hardware errors, but have a lot of junk. Structured event messages: generated by the application, with a fixed or dynamic set of attributes, e.g. a HTTP request log, an accounting log, a user login. Generally speaking, it's nice to log details about every request in a way that you can drill down based on attributes. So adding e.g. a userid or sessionid to everything lets you trace. Explicit tracing is also good, of course. Using ELK for this is kind of a poor man's https://www.honeycomb.io/ ### Graylog is easier Graylog is easier to spin up from my experience. ### Prometheus take some tuning I am generally happy with Prometheus for metrics. The alerting takes some tuning, but is pretty good. It depends on your application. I think it's best to alert on end-user visible conditions, not underlying causes. For example, page load time is good, number of requests per second is not. Though zero requests per second indicates that something is wrong. The advantage of a service is that they offer additional intelligence out of the box. I generally like Datadog. The services can be frighteningly expensive if you have a lot of data, and sometimes have pricing models which are not cloud friendly, e.g. charging per instance, when instances are dynamic. There is also a difference between services where every request is from a paid user and ones that are advertising related, so only some small percentage of the requests make you money. You can end up with a lot of data and not that much budget. I work on some services that get 1B requests a day, so it makes sense to host our own monitoring and logging. If your volumes are lower, then hosted services are easier. ### AWS services are mixed My experience with AWS services has been mixed. Their Elasticsearch service has been flaky, so we run our own instances for that. CloudWatch metrics are expensive, so we generally only use them for "infrastructure" level metrics rather than the application, i.e. health-related metrics where AWS can know better what's going on than software running on the instance. CloudWatch Logs can be slow to update and don't have that much metadata. Running ELK helps with that. If I really want real time data, then using Kafka as the transport for logs is better. That's pretty well supported by Logstash. Managing a Kafka cluster is not for the faint hearted, though, there is a lot of exposed plumbing. ### Kafka Comment: Kafka can be super tricky at times, or Kafka can be rock solid and you almost forget about it being there tying everything together. Comment: Kafka has been solid, but it was a surprising amount of work getting it going. I think of it like a relational database but you are only working at the "physical" layer, e.g. tablespaces, files and partitions. There were some times early on where the management utilities were lacking, and we had to write programs to e.g. reset a consumer group. http://howfuckedismydatabase.com/nosql/ Comment: We use Kafka as a "buffer" for log messages and a place where we can do real time stream processing on data that is coming from multiple servers. If we get a DDOS attack, then we need a way of analyzing data across multiple instances. If we are logging directly from the servers to ELK, the load can blow up the Elasticsearch cluster. Comment: Kafka is good for us because if we get a DDOS attack, then we need a way of analyzing data across multiple instances. If we are logging directly from the servers to ELK, the load can blow up the Elasticsearch cluster. Comment: Kafka does less work and is more efficient, so it can handle the load better. And we queue the Kafka work and retry. And having Kafka be overloaded doesn't affect users who are trying to do interactive work with Kibana, the way it would if Elasticsearch is struggling. Comment: Stream processing is mostly looking for abuse, e.g. too much traffic from a single IP across the whole cluster, and then share the block across the whole cluster. Comment: The logstash-output-kafka plugin is quite unreliable at the moment though. I've been bit by several of the issues on its GitHub issues page, that never seem to get fixed. I want to move away from using it, to sending directly from our apps to Kafka. Comment: We are now sending structured events directly from the app to Kafka. The main motivation was touching the log data fewer times and avoiding reading and writing the disk multiple times. In high volume systems, logging can take more work than the app itself. I am thinking about making journald send logs directly as well, from a C program. ### Loki Keep a close eye on Loki. It’s not ready yet but when it is I’d expect it to be a better fit in this stack. Loki is a log aggregator created by grafana labs, it uses similar a scraping and tag syntax as Prometheus. ### Prometheus + alertmanager + Rollbar + Graylog + Grafana Prometheus + alertmanager for metrics. <3 Prometheus. Rollbar/Graylog for logging/error reporting (there's some overlap here; a small service probably doesn't need both). Currently, alerts just go to one of a few Slack channels that interested parties have notifications turned on for. If we were more serious about on-call they would go to PagerDuty/VictorOps/etc. Grafana for graphs and dashboarding. Also eagerly looking forward to seeing if their upcoming logging facilities will obviate Graylog. ### Thanos We use Thanos as a front-end for our HA setup. It knows how to de-duplicate HA pairs. We're currently keeping 6 months of local Prometheus data. This works reasonably well for us. But I'm just in the middle of rolling out bucket storage to our Thanos setup for long-term data storage. In theory, GCS storage will be about 30% cheaper than the GCE standard persistent disk we use right now. We don't backup Prometheus data right now. The data just isn't really important to us beyond having enough for alerting. Our overall fleet deployment changes so much year to year that historical data older than a few months just isn't that interesting. It might be interesting to have a few core stats year-over-year, I may setup a core-stats set of recording rules and store those with Federation or just let Thanos take care of it. EDIT: Minor disclaimer, I'm a Prometheus developer. ### Prometheus HA HA in Prometheus is done by duplication you run multiple poppers there’s ways to poll multiple and deduplicate the data The scaling is by deciding network and having different Prometheus poll different parts of the network Longterm storage isn’t proms strong point but is offloaded to something like influxes or timescaledb (which technically does the HA checkmark as well) article I read on it https://blog.timescale.com/prometheus-ha-postgresql-8de68d19b6f5?gi=7df160f10e07 Haven’t tried the longterm stuff yet as I’m still only experimenting and using it for short term graphs while librenms monitors my network for longterm ### Datadog + PagerDuty + Threat Stack We use Datadog (w/ PagerDuty) and Threat Stack and couldn't be happier. My only gripe with DD is the relatively high cost of metric storage. ### Zabbix Zabbix with custom scripts to monitor almost everything. Works like a charm. ### Outlyer I'm using Outlyer, but then I must disclaim that I work here, and dog fooding is a must. Still need Graylog, Sentry and Statuscake to enhance. Sounds biased, but having happily run Nagios and other monitoring systems internally, I would buy a hosted solution in any new gig and offload that pain. ### Nagios + Nagiosgraph We run Nagios for all monitoring and alerting. Alerts happen through e-mail (warnings and critical notifications) and audible app notifications (for critical alerts). Nagiosgraph is used for visualisations. This set-up has been very effective in keeping us comprehensively informed on what's happening in our environment. We run and monitor about 110 mission-critical servers and about 760 data points, and have had this morning system in place for over seven years. I would like to also aggregate logs with Graylog or ELk at some point. ### Prometheus + Grafana + AlertManager Prometheus + Grafana + AlertManager via the awesome Prometheus Operator helm chart. Log still goes to LogDNA birch plan as we noticed ELK is too heavyweight for our humble min 3 max 5 nodes on GKE. ### DataDog + Sentry + PagerDuty. I used to run all my own monitoring solutions using all kinds of software including Nagios, Icinga, Zabbix, ELK, Greylog2, Influx, and many other tools, but the truth is that there's just too much effort involved in running your own monitoring infrastructure, especially when you can pay someone else such low rates for someone else to do it for you! Paying others to run the monitoring infra frees my clients up to focus on running their platforms instead of monitoring the monitoring, meaning that the value they gain from the stability of their platform far outweighs any costs of Monitoring as a Service. ### Sensu + Graphite + ELK My company is real big on self-hosted stuff. Sensu -> PagerDuty Graphite/Grafana ELK (Elasticsearch, Logstash, Kibana) ### Prometheus + Alertmanager Prometheus + Alertmanager for alerting, my team believe that simple monitoring is good monitoring. Other systems like logging and tracing will provide rich context for diagnosing when the on-call receive an alert, but we never build alerting on these. ### Sensu + Grafana + Graylog + Kibana + NewRelic. Sensu, grafana, graylog, kibana, newrelic. ### Prometheus + Circonus Prometheus instrumented services => Circonus analytics and visualization ### icinga2 + VictorOps + NewRelic + Sentry + Slack We are using below services: icinga2 for monitoring and VictorOps for alerting NewRelic for details monitoring of the service Sentry for error tracking in the service Slack/Email is part of alerting which triggers from NewRelic or icinga2 ### AppDynamics + Papertrail + PagerDuty + Healthchecks.io + Stackdriver AppDynamics Papertrail PagerDuty Healthchecks.io Stackdriver ### icinga2 + elasticsearch icinga2 with elasticsearch integration for analysis and graphite+grafana integration for graphs. thanks to the flexibility of apply rules in icinga2, the developers can only see services they receive notifications for. and through icinga2 director, programmers can easily define their own checks (which they do, every few days - 100 checks go out, 100 other checks go in) on big scale with zero hassle. ### DataDog + New Relic + ELK + EFK + Sentry + Alertmanager + VictorOps What do we have now: DataDog for metrics New Relic for application monitoring ELK (Elastic Search + Logstash + Kibana) for the logs Sentry (self-hosted) for logging exceptions Emails + Slack + VictorOps for alerting (based on severity) What do we want to have: Prometheus for metrics (Grafana for visualization) New Relic (probably Elastic Search APM) for the application monitoring EFK (elastic search + fluentd + kibana) for logging. Probably, Loki by Grafana would be prod-ready till the time we get here Sentry for the exceptions Alertmanager + email + VictorOps for the alerts ### Wavefront + Scalyr + PagerDuty + Stackstorm + Slack Wavefront + Scalyr + PagerDuty + Stackstorm + Slack (Disclaimer: works at VMware) ### Telegraf + Prometheus + InfluxDB + Grafana Telegraf for server metrics like CPU, Disk, Memory and Network. We also use Telegraf for SNMP monitoring of our network devices. Prometheus for application metrics. We code health checks into our application that Prometheus scrapes. InfluxDB for time-series storage. This is where our Telegraf data gets sent. Grafana for dashboards and alerts. The alerting engine isn't super robust, but it does the job. We also fire alerts into Slack. What I don't have right now is a centralized logging solution. ELK is powerful but difficult to set up and manage, and I don't know of any free alternatives that are close enough to look into. ### Sematext + Logagent + Experience Sematext for metrics, for logs, for traces, soon for real user monitoring, too. Simpler/cheaper than using N different tools/services, IMHO. For log shipping we used to use rsyslog and then we switched to Logagent. For frontend crash reporting we use Sentry, but we'll switch to Experience shortly. Disclaimer: I'm a Sematextan. ### Azure Monitor/Analytics + OpsGenie I wish Log Analytics had a better interface. We’re moving away from splunk, which was much easier to navigate. ### Prometheus + Alertmanager + Grafana + Splunk + PagerDuty Prometheus, Alertmanager, Grafana, Splunk, PagerDuty You really do not want to run your own notification system. You can replace Splunk with ELK unless your Security team prefers Splunk. ### Telegraf + Prometheus + Grafana + Alertmanager Telegraf as a collector, Prometheus + Alertmanager for monitoring and alerting, integrated with slack channels and pagerduty for critical alerts. Grafana for host metrics visualization. ### Prometheus + Grafana + Cloudwatch + sentry + kibana + elasticsearch Prometheus for metrics + alerts Grafana for Prometheus dashboards Cloudwatch monitoring Prometheus instances sentry for exception tracking kibana + elasticsearch graylog prometheus Push Gateway for batch/cronjobs SOP https://github.com/rapidloop/sop to „push/forward“ metrics from 1 Prometheus instance to another clients either use the Prometheus clients . We try to use opencensus.io on the client side ### PagerDuty + Monitis PagerDuty + Monitis. Also some bespoke Azure Functions for testing the health of some services. Looking to introduce Prometheus and Grafana this year ### Prometheus + Grafana + Bosun Prometheus for storing the time series data. Grafana for visualization. Bosun for alert management. ### Azure Monitor/Analytics/Insights/Dashboards Azure only shop, Azure Monitor, Log Analytics, App Insights, Azure Dashboards + Pager Duty ### Grafana + Monitis + OpsGenie + Slack Grafana for monitoring container services in Kubernetes via Prometheus Monitis for end-to-end service monitoring mainly for web APIs and web applications OpsGenie for alert management Slack for getting status information from our systems ### Checkly + AppOptics + Cloudwatch + Heroku + Pagerduty + Papertrail Long time (dev)ops engineer here. Grew up on Nagios. Would love to have opinions on my bootstrapped SaaS https://checklyhq.com. We do API monitoring & site transaction monitoring with pretty in depth alerting. I started Checkly because active / synthetic monitoring in the API space was a bit limited (and pricey). Browser based / scripted monitoring is even more proprietary and expensive. We use Puppeteer and keep pricing as low as possible. Our monitoring stack: Checkly (dog fooding...) AppOptics (custom graphing) AWS Cloudwatch & SNS for SMS messages. built-in Heroku alerting. Pagerduty Papertrail ### Instana + Logz.io + slack Instana alerts us in slack about infrastructure problems or performance degradation, and we’ve configured logz.io to alert in slack on a certain volume of error level logs from the application layer. ### SignalFX + Splunk + PagerDuty + Slack Currently using: SignalFX, Splunk, PagerDuty and Slack. I'm not a huge fan of SignalFX although their support team is super friendly and responsive. I like Splunk (worth it if you can pay for it), PagerDuty and Slack. I used to use the TICK stack where most of the C was really a G, that is Grafana although I did use Chronograf a little bit. That was awesome but it was a pain to manage. The classic SaaS vs self-hosting dilemma. I have used DataDog, New Relic, Graylog, ELK and BugSnag. I like DataDog and New Relic a lot, Graylog is pretty good. I'm not a big ELK fan though. BugSnag is nice, I actually feel like tracking errors/exceptions is a pretty good standin for full log monitoring, in many cases. ### ELK + Prometheus + Grafana Just like others, we use ELK for logs and Prometheus+Grafana for everything else. Maintaining this setup is easy if you give yourself permission to occasionally lose data. For example, if our ElasticSearch database gets into a funk (which happens every 2-3 months for us unfortunately) we don't bother with HA and instead dump the data and get on with our lives. If you absolutely must have HA or long term retention, good luck. ### Datadog + Prometheus + Grafana I set up Datadog on a month to month because when I got here, there was no monitoring and no alerting. Only a couple of our sites were being monitored every 5m for uptime. Datadog hands down is the easiest to setup. When I finish addressing all the other issues, I will change to Prometheus+Grafana. Not 100% decided on log management yet. ### Nagios + ELK We have over 100+ products that we support. For on-prem, it's mostly Nagios and ELK. For the cloud, we're migrating from DataDog to NewRelic. ### Datadog vs. Site24x7 + StatusCake + PagerDuty + SumoLogic + Slack We used to use datadog but found it to be way to expensive for our needs. Don't get me wrong its amazing but, it does have a huge cost. We were able to setup site24x7.com with an annual subscription for about 2-3 months of cost from DD. Our monitoring stack: Site24x7 - APM, External URL monitoring, SMTP mailflow monitoring, ssl expirations and process monitoring. StatusCake - for URL monitoring and confirmation - It's our backup just in case site24x7 misses something (It does not) but SC is more flexible for external port and service monitoring for our needs. Both tools escalate to PagerDuty, and then we get our escalations in slack. SumoLogic - for log monitoring (it’s a great tool but a little complicated for our needs) From slack we can ack, or remedy the alert. We then have a lot of site24x7 automations that then connect to commando.io for 'BedOps' as we call it - where an alert gets triggered, we kick of a few scripts or automations as an attempt to remedy the situation (99% of the time the automation + our scripts keep us out of trouble) We have internal runbooks in our KB for when the automatons fail or if there is something out of the scope that needs to be fixed. ### Prometheus + AlertManager + Grafana + Stackdriver Prometheus (Operator) / AlertManager / Grafana for metrics in our GKE clusters and VMs. Google Stackdriver for Logs (as it’s included and active by default and is currently enough for our needs). ### Zabbix Zabbix for everything. No additional software needed. ================================================ FILE: locales/en/examples/microsoft-azure-cloud-infrastructure/.locale-peer-id ================================================ 4dce71df0db78d050f86e1a2cc4cb9d1 ================================================ FILE: locales/en/examples/microsoft-azure-cloud-infrastructure/index.md ================================================ # Architecture Decision Record: Microsoft Azure cloud infrastructure" Decision Title: Adopting Microsoft Azure as the cloud infrastructure for our organization Decision Maker: Chief Information Officer Date: 2021-10-15 Status: Approved ## Background The organization is planning to migrate from traditional on-premises infrastructure to cloud infrastructure. In order to achieve this, the organization has evaluated multiple cloud service providers such as Amazon Web Services (AWS), Google Cloud Platform (GCP), Microsoft Azure, and IBM Cloud. Each provider has its own set of features, benefits, and pricing structure. After a detailed analysis, it was concluded that Microsoft Azure is the most suitable option for our organization. ## Decision Adopt Microsoft Azure as the cloud infrastructure for our organization. ## Rationale The following are the reasons for adopting Microsoft Azure: 1. Comprehensive Services: Azure provides a complete range of cloud services from infrastructure as a service (IaaS) to software as a service (SaaS) and platform as a service (PaaS). This enables us to leverage Azure services to solve the organization's requirements, such as storage, compute, networking, and analytics. 2. Scalability and Flexibility: With Azure, we can easily scale up or down resources based on our business requirements. Azure also offers flexibility in choosing the operating system, programming language, and frameworks. 3. Security and Compliance: Azure offers a high level of security and compliance, as it is compliant with several industry standards such as ISO, SOC, HIPAA, and PCI DSS. Azure also provides advanced security features such as network security groups, firewalls, and DDoS protection. 4. Hybrid Cloud: Azure provides a seamless hybrid cloud experience, enabling organizations to connect their on-premises infrastructure with Azure. This makes it easy for us to migrate workloads to the cloud and provides us with the flexibility to choose where to store data. 5. Cost-effective: Azure offers a pay-as-you-go pricing model, which means we only pay for the resources used. This helps us save costs when compared to traditional on-premises infrastructure. ## Conclusion Adopting Microsoft Azure as the cloud infrastructure for our organization aligns with our business requirements and offers several benefits such as scalability, flexibility, security, and cost-effectiveness. Therefore, it is recommended to adopt Azure as our cloud infrastructure. ================================================ FILE: locales/en/examples/microsoft-azure-devops/.locale-peer-id ================================================ e1e84e31e7b1463322b083fd2983fe1a ================================================ FILE: locales/en/examples/microsoft-azure-devops/index.md ================================================ # Microsoft Azure DevOps Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes) * [Microsoft Devops CI: An Unsatisfying Adventure](#microsoft-devops-ci-an-unsatisfying-adventure) * [Hacker News discussion highlights](#hacker-news-discussion-highlights) * [Windows Development MVP](#windows-development-mvp) * [Edward Thomson (Azure PM) summary](#edward-thomson-azure-pm-summary) ## Summary ### Issue We want to use devops to build, integrate, deploy, and host our projects. We are considering Microsoft Azure DevOps. * We want developer experience to be fast and reliable, for the setup of the devops e.g. configuring as well as ongoing use e.g. fast build times. * We want to consider using Microsoft Azure as whole, for hosting the project apps, databases, etc. ### Decision Decided against Microsoft Azure DevOps. ### Status Decided. Open to revisiting if/when new significant info arrives. ## Details ### Assumptions All the usual devops assumptions, such as in the book Accelerate. * Fast builds are a significant help. This accelerates the feedback loops. * We can swap in/out pieces from alternate vendors i.e. we may want to bring our our higher-speed build servers, or use our own choice of version control system, or coordinate with a self-hosted continuous integration server. * Streamlined usabilitiy is a significant help, for developer experience, and in turn for subtle areas such as consistency, clarity, security, and ease of learning curve. * When anything is broken or problematic, we want an effective way to report the issue. This is especially important for any security-related issues. ### Constraints None known. Azure has a published commitment to playing well with external tools. ### Positions We considered using Microsoft Azure Devops vs. AWS which is incumbent. We experimented with Azure DevOps, Azure Pipelines, Azure Repo, and Azure spin up of new server via Terraform. We experimented with getting support from Microsoft representatives. We gathered information from peers on blogs and Hacker News. ### Argument Azure DevOps advertises an excellent set of offerings, but they do not hold up, and they do not work well together, and support is poor. Our firsthand experience: * Azure setup is a mess of UIs, some of which overlap with Microsoft accounts, some of which don't. E.g. there's an Azure sign in, a Microsoft.com sign in, a Live.com sign in, etc. and all are simultaneously in play. * We encountered a minor security issue during setup, and found no resolution. We tried many ways to report it, to many Microsoft reps, with no success. We successfully reported it to Microsoft security, which replied with won't fix. * Documentation is often either wrong or outdated. At least some of this is due to Microsoft's poor search engine, and some of this is due to sub-par SEO. * Terraform setup is well documented, and works. However, Terraform supoprt is weak compared to AWS because Microsoft is building business relationships with vendors to do chain-through Terraform setup examples. Our peer experiences: * After we did our own blind assessment, we looked for peer experiences. What we found confirmed our experiences. * Peers reported additional problems with build times, and problems with bring-your-own-build server. These problems are significantly more severe than UI problems, because doing builds is the core purpose of a build pipeline, and we expect to do many per day. * We found excellent participation by Azure teammates in the discussion areas. Kudos to Microsoft for this. We are especially impressed with Edward Thomson, Azure PM and coder, because of his participation, directness, and technical explanations. ### Implications Choosing Microsoft Azure DevOps looks likely to be more expensive (~3x) in time and cost than not choosing Azure. ## Related ### Related decisions If we choose Azure DevOps, there are many related offerings, including Azure Repo, Azure Pipeline, etc. We believe that if we choose Azure Devops, this may make it easier to use more Azure capabilities, or may make it harder to use other vendors' capabilities. We believe that Microsoft is making great strides in developer experience, and we see Microsoft making large acquisition of developer tools (e.g. GitHub) and dependencies (e.g. Citus). If we choose Azure DevOps, then we may want to emphasize choosing the Microsoft acquisition offerings, and we may also want to approach the acquisition offerings with more care/assessement because of potential tissue-rejection e.g. staff turnover risk. ### Related requirements We want build times to be very fast. We accept paying a high premium for this. This is because we want to iterate very fast. We want reliability to be very high. We accept paying a high premium for this. This is because we are testing high-value use cases, including financial transations, confidential transactions, etc. Our top 4 devops KPIs include mean time to recovery, which necessitates fast builds and high reliability. ### Related artifacts We want the build system to output artifacts suitable for using in other systems, such as Artifactory. ### Related principles Easily reversible. We can evaluate Azure DevOps in parallel with AWS incumbent. ## Notes ### Microsoft Devops CI: An Unsatisfying Adventure https://toxicbakery.github.io/vsts-devops/microsoft-devops-ci/ Blog post. "As a software developer, I know first-hand how difficult it is to build quality products quickly and cheaply. It’s an art form that we sometimes get right, and other times devolves into something akin to the Obama era healthcare government site. Our level of control over the resulting product varies, and blame for failure often falls on the wrong people in the decision-making hierarchy. Microsoft’s Azure DevOps (formerly known as Visual Studio Team Services), despite clearly good intentions, is a perfect storm of bad decisions and poor execution." ### Hacker News discussion highlights https://news.ycombinator.com/item?id=18983586 "We use Azure DevOps extensively at my work and, after having used GitHub, Gitlab, self hosted solutions, Jenkins, TeamCity... Azure DevOps ranks dead last." "The UI is terribly clunky everywhere. The worst for me are pull requests. Incredibly tough to work with people on a pull request. I can't even point you to "a" particular problem - for us it's broken everywhere." "Azure Devops is something I want to love. The UI keeps changing, but doesn't fix underlying bugs that have been around for ages." "The tools are not well integrated, the UI is really slow, there’s no dashboard view of active pull requests, builds, releases, etc for my favorite repos. Build/Deploy times are insanely slow." "We tried to also use Azure Boards (Work Items, Boards, Backlogs, etc). Ouch. It is a complete UI mess of disjointed ideas. Instead of implementing one thing well, they implemented two dozen things terribly." ### Windows Development MVP Windows Development MVP here. I feel like I must shoulder some of the responsibility here for not being louder about these issues. But must say, I'm disappointed to hear you're "surprised" about the UX issues. I've been telling your folks the UX is dreadful (e.g. as far back as pre-launch) and kept hearing back "we know, we're fixing it". I'll start formalizing the feedback and push it through the pipes, stay tuned. I'm also local (Bellevue), would love to come in and try to pipeline our relatively simple oss .net/wpf/uwp app. I suspect it'll be an eye opener for the both of us. Some examples: * You can't build a pipeline with a git repo. that contains submodules * Found it impossible to edit the PATH for some custom tooling * The New Pipeline experience just doesn't make a lot of sense, new users clicking around will eventually end up at the wrong Docs. ### Edward Thomson (Azure PM) summary I wrote the code that merges your pull requests. Program Manager for at Microsoft for Azure DevOps; formerly a software engineer on version control tools at GitHub, Microsoft, SourceGear. https://www.edwardthomson.com/ Co-maintainer of libgit2. https://libgit2.github.io Co-host of All Things Git, the Podcast about Git. https://www.allthingsgit.com/ Curator of Developer Tools Weekly, a newsletter about development tools. https://developertoolsweekly.com/ ================================================ FILE: locales/en/examples/monorepo-vs-multirepo/.locale-peer-id ================================================ b52cc745a00570dede6cd309dd35d7ac ================================================ FILE: locales/en/examples/monorepo-vs-multirepo/index.md ================================================ # Monorepo vs multirepo Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes) ## Summary ### Issue Our project involves developing three major categories of software: * Front-end GUIs * Middleware services * Back-end servers When we develop, our source code management (SCM) version control system (VCS) is git. We need to choose how we use git to organize our code. The top-level choice is to organize as a "monorepo" or "polyrepo" or "hybrid": * Monorepo means we put all pieces into one big repo * Polyrepo means we put each piece in its own repo * Hybrid means some mix of monorepo and polyrepo For more please see https://github.com/joelparkerhenderson/monorepo-vs-polyrepo ### Decision Monorepo when an organization/team/project is relatively small, and rapid iteration is higher priority than sustaining stability. Polyrepo when an organization/team/project is relatively large, and sustaining stability is higher priority than rapid iteration. ### Status Decided. Open to revisiting if/when new tooling becomes available for managing monorepos and/or polyrepos. ## Details ### Assumptions All the code that we're developing is for one organization's offerings, and not for the general public. I.e. the Broker-Dealer isn't aiming to have anything like general public volunteer developers. ### Constraints Constraints are well-documented at https://github.com/joelparkerhenderson/monorepo-vs-polyrepo ### Positions We considered monorepos in the style of Google, Facebook, etc. We think any monorepo scaling issues are so far in the future that we will be able to leverage the same practices as Google and Facebook, by the time we need them. We considered polyrepos in the style of typical Git open source projects, such as Google Android, Facebook React, etc. We think these are the best choice for general public participation (e.g. anyone in the world can work on the code) and individual availability (e.g. the project is used on its own, without any other pieces). ### Argument When an organization/team/project is relatively small, we choose monorepo, because rapid iteration is significantly higher in priority than sustaining stability When an organization/team/project is relatively large, we choose polyrepo, because sustaining stability is significantly higher in priority than rapid iteration. ### Implications If there's an existing pipeline for CI+CD, then we may need to adjust it for testing multiple projects within one repo. CI+CD could take more time for a full build for a monorepo, because CI+CD could build all the projects in the monorepo. If an organization/team/project grows, then a monorepo will have scaling issues. Monorepo scaling issues may make it increasing valuable to transition to a polyrepo. Transition from monorepo to polyrepo is a significant devops task, and will need to be planned, managed, and programmed. ## Related ### Related decisions We will create decisions for related tooling to manage monorepos (e.g. Google Bazel) and polyrepos (e.g. Lyft Refactorator). ### Related requirements We need to develop the CI+CD pipeline to work well with git. ### Related artifacts We expect the repo organization to have related artifacts for provisioning, configuration management, testing, and similar devops areas. ### Related principles Easily reversible. If the monorepo doesn't work in practice, or isn't wanted by leadership, it's simple to change to polyrepo. Customer Obsession. We value getting the project in the hands of customers, and we believe that a monoreop can get us there faster than a polyrepo, and also help us iterate faster. Think big. Google and Facebook are very strong advocates for monorepos over polyrepos, because all the core offerings can be developed/tested/deployed in concert. ## Notes Add any notes here. ================================================ FILE: locales/en/examples/mysql-database/.locale-peer-id ================================================ 4f4246ee263e7d47d7533ed048c2c7ef ================================================ FILE: locales/en/examples/mysql-database/index.md ================================================ # Architecture Decision Record: MySQL database Title: Choosing MySQL as Database Management System for Project X ## Context and Problem Statement We need to decide on which database management system (DBMS) to use for Project X. The database will be used to store and manage large amounts of data from multiple sources. We need a DBMS that can handle transactions, offer scalability, and provide high reliability and security. Among various options available, we are considering MySQL as a possible choice. ## Decision Considerations - Ease of use and maintenance - Community support and resources - Performance and scalability - Security and reliability - Cost and licensing - Compatibility with our technology stack ## Considered Options - MySQL - PostgreSQL - Oracle - Microsoft SQL Server - MongoDB ## Decision Outcome After evaluating the above options based on our decision considerations, we have decided to choose MySQL as our DBMS for Project X. MySQL is a popular open-source system with a strong development community and a large pool of resources for problem-solving and knowledge sharing. It is well-known for its excellent performance and scalability capabilities, making it ideal for handling vast amounts of data with high levels of efficiency. The platform is secure, reliable, and has a wide range of features that are essential for our project, including ACID compliance for transactions, flexible data model, and support for various programming languages and frameworks. MySQL is also compatible with the majority of our technology stack, including our web development framework, hosting solutions, and other essential tools. Plus, its cost and licensing terms are competitive compared to other proprietary systems like Oracle and Microsoft SQL Server. ## Consequences We anticipate the following outcomes and consequences of our decision: ### Positive - **High performance and scalability:** MySQL offers exceptional performance and scalability capabilities, making it ideal for handling large amounts of data efficiently. - **Secure and reliable:** MySQL provides excellent security features and reliability, which is essential for managing critical data. - **Wide community support:** MySQL has a vast community and various online resources, making it easier to seek help and solve problems. - **Compatibility:** MySQL is compatible with our technology stack and programming languages, streamlining our development process. ### Negative - **Learning curve:** There might be a learning curve for the development team, especially those not experienced with MySQL and SQL databases. - **Limitations:** MySQL may have some limitations when it comes to handling certain data types and complex data models, requiring careful development and optimization. ## Conclusion Based on the available data and our decision considerations, we believe that MySQL is the right choice for our database management system for Project X. MySQL offers high-performance, reliability, security, and scalability capabilities and is widely compatible with our technology stack. The development team will need to get familiar with using MySQL, but the available community support and resources should help in the process.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/postgresql-database/.locale-peer-id ================================================ 4ea514a9c996ef7af8eca37ec2b96d69 ================================================ FILE: locales/en/examples/postgresql-database/index.md ================================================ # Architecture Decision Record: PostgreSQL database Title: Use of PostgreSQL Database ## Context Our organization is currently evaluating options for the most suitable database management system to be used in our upcoming project. We have narrowed our search down to two options – PostgreSQL and MySQL. After careful consideration, we have decided to use PostgreSQL due to its advanced features and performance capabilities. ## Decision We will use PostgreSQL as the preferred database management system for our organization's upcoming project. ## Justification After analyzing and comparing the features of both PostgreSQL and MySQL, we have come to the conclusion that PostgreSQL is the better option because of the following reasons: 1. **Advanced features:** PostgreSQL has a wide range of advanced features like JSON support, full-text search, and spatial data management, which are essential for our project. 2. **Performance:** PostgreSQL has a proven track record of excellent performance capabilities, which will ensure that our project runs smoothly without any performance issues. 3. **Community support:** PostgreSQL has a large and active community that provides regular updates and support, making it easier to resolve any issues that arise during the project development phase. 4. **Scalability:** PostgreSQL is highly scalable, and it can handle large amounts of data with ease, which will be essential for our project. 5. **Security:** PostgreSQL has a robust security mechanism that will ensure that our project data is secure at all times, and it meets all our organization's security requirements. ## Alternatives The other option that we considered was MySQL. MySQL is also a highly capable database management system, but it lacks some of the advanced features that PostgreSQL offers, and its performance capacity is not as good as that of PostgreSQL. ## Conclusion Based on our analysis, we have decided to use PostgreSQL as the preferred database management system for our upcoming project. This decision has been made after careful consideration, and we believe that it will help us achieve our project goals efficiently and effectively.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/programming-code-editors/.locale-peer-id ================================================ 8aec4ce83bd164e7b2945f37c052a6d1 ================================================ FILE: locales/en/examples/programming-code-editors/index.md ================================================ # Architecture Decision Record: Programming Code Editors ## Context Programming code editors are an essential tool for developers to write and edit code. There are numerous code editors available, each with its own set of features, advantages, and disadvantages. The purpose of this ADR is to document the architectural decisions made for programming code editors. ## Priorities The architecture for programming code editors should prioritize the following: * **Modularity**: The code editor should be designed in a modular way, allowing developers to customize and extend it as needed. This allows for a flexible architecture that can adapt to the needs of different developers and teams. * **Performance**: The code editor should be performant and responsive, allowing developers to work efficiently without being slowed down by the tool they are using. * **User Interface**: The user interface should be intuitive and easy to use, allowing developers to focus on their code rather than struggling with the editor. * **Extensibility**: The code editor should be designed to allow for easy extension with third-party plugins and integrations. * **Compatibility**: The code editor should be compatible with a wide range of programming languages and technologies, making it a useful tool for a broad range of developers. ## Decision Based on these priorities, the architecture for programming code editors should be designed with the following components: * **Core**: This component provides the basic functionality of the code editor, such as syntax highlighting, text editing, and file management. * **UI**: This component provides the user interface for the code editor, including menus, toolbars, and keyboard shortcuts. * **Plugins**: This component allows developers to extend the functionality of the code editor by installing third-party plugins. Plugins can provide additional features, such as code completion, linting, or debugging. * **Integrations**: This component allows the code editor to integrate with other tools and technologies, such as version control systems, build systems, or debugging tools. ## Rationale The modularity of the code editor allows developers to customize and extend it as needed. This is important because different developers and teams have different needs and workflows, and a flexible architecture can accommodate these differences. * **Performance**: crucial because developers need to be able to work efficiently without being slowed down by their tools. A performant code editor is essential for productivity and can help developers maintain their focus and concentration. * **UI**: important because it allows developers to focus on their code rather than struggling with the editor. This can lead to better productivity and less frustration for developers. * **Extensibility**: powerful because it allows the code editor to be adapted to different needs and workflows. Third-party plugins and integrations can provide additional features and capabilities that are not included in the core editor. * **Compatibility**: valuable because it allows the code editor to be used with a wide range of programming languages and technologies. This makes the editor a more useful tool for a broad range of developers. The core, plugins, integrations, and UI components provide a clear separation of concerns and allow for a modular architecture that can be easily extended and customized. This architecture is flexible, performant, and compatible with a wide range of programming languages and technologies, making it a useful tool for developers. ================================================ FILE: locales/en/examples/programming-languages/.locale-peer-id ================================================ 1984c4f82b0b1364c6a3fae147697337 ================================================ FILE: locales/en/examples/programming-languages/index.md ================================================ # Programming languages Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes) ## Summary ### Issue We need to choose programming languages for our software. We have two major needs: a front-end programming language suitable for web applications, and a back-end programming language suitable for server applications. ### Decision We are choosing TypeScript for the front-end. We are choosing Rust for the back-end. ### Status Decided. We are open to new alternatives as they arise. ## Details ### Assumptions The front-end applications are typical: * Typical users and interactions * Typical browsers and systems * Typical developments and deployments The front-end applications is likely to evolve quickly: * We want to ensure fast easy developments, deployments, iterations, etc. * We value provability, such as type safety, and we are fine doing a bit more work to achieve it. * We do not need legacy compatibility. The back-end applications are higher-than-typical: * Higher-than-typical goals for quality, especially provability, reliability, security, etc. * Higher-than-typical goals for near-real-time, i.e. we do not want pauses due to virtual machine garbage collection. * Higher-than-typical goals for functional programming, especially for parallelization, multi-core processing, and memory safety. We accept lower compile-time speeds in favor of compile-time safety and runtime speeds. ### Constraints We have a strong constraint on languages that are usable with major cloud provider services for functions, such as Amazon Lambda. ### Positions We considered these languages: * C * C++ * Clojure * Elixir * Erlang * Elm * Flow * Go * Haskell * Java * JavaScript * Kotlin * Python * Ruby * Rust * TypeScript ### Argument Summary per language: * C: rejected because of low safety; Rust can do nearly everything better. * C++: rejected because it's a mess; Rust can do nearly everything better. * Clojure: excellent modeling; best Lisp approximation; great runtime on the JVM. * Elixir: excellent runtime including deployability and concurrency; excellent developer experience; relatively small ecosystem. * Erlang: excellent runtime including deployability and concurrency; challenging developer experience; relatively small ecosystem. * Elm: looks very promising; IBM is publishing major case studies with good results; smaller ecosystem. * Flow: interesting improvement over JavaScript; however; developers are moving away from it. * Go: excellent developer experience; excellent concurrency; but a track record of bad decisions that cripple the language. * Haskell: best functional language; smaller developer community; hasn't achieved enough published production successes. * Java: excellent runtime; excellent ecosystem; sub-par developer experience. * JavaScript: most popular language ever; most widespread ecosystem. * Kotlin: fixes so much of Java; excellent backing by JetBrains; good published cases of porting from Java to Kotlin. * Python: most popular language for systems administration; great analytics tooling; good web frameworks; but abandoned by Google in favor of Go. * Ruby: best developer experience ever; best web frameworks; nicest community; but very slow; somewhat hard to package. * Rust: best new language; zero-abstraction emphasis; concurrency emphasis; however relatively small ecosystem; and has deliberate limits on some kinds of compiler accelerations e.g. direct memory access needs to be explicitly unsafe. * TypeScript: adds types to JavaScript; great transpiler; growing developer emphasis on porting from JavaScript to TypeScript; strong backing from Microsoft. We decided that VMs have a set of tradeoffs that we do not need right now, such as additional complexity that provides runtime capabilities. We believe that our core decision is driven by two cross-cutting concerns: * For fastest runtime speed and tightest system access, we would choose JavaScript and C. * For close-to-fastest runtime speed and close-to-tightest system access, we choose TypeScript and Rust. Honorable mentions go to the VM languages and web frameworks that we would choose if we wanted a VM language: * Clojure and Luminus * Java and Spring * Elixir and Phoenix ### Implications Front-end developers will need to learn TypeScript. This is likely an easy learning curve if the developer's primary experience is using JavaScript. Back-end developers will need to learn Rust. This is likely a moderate learning curve if the developer's primary experience is using C/C++, and a hard learning curve if the developer's primary experience is using Java, Python, Ruby, or similar memory-managed languages. TypeScript and Rust are both relatively new. This means that many tools do not yet have documentation for these languages. For example, the devops pipeline will need to be set up for these languages, and so far, none of the devops tools that we are evaluating have default examples for these languages. Compile times for TypeScript and Rust are quite slow. Some of this may be due to the newness of the languages. We may want to look at how to mitigate slow compile times, such as by compile-on-demand, compile-concurrency, etc. IDE support for these languages is not yet ubiquitous and not yet first-class. For example, JetBrains sells the PyCharm IDE for first-class support for Python, but does not sell and IDE with first-class support for Rust; instead, JetBrains can use a Rust plug-in that provides perhaps 80% of Rust language support vis a vis Python language support. ## Related ### Related decisions We will aim toward ecosystem choices that align with these languages. For example, we want to choose an IDE that has good capabilities for these languages. For example, for our front-end web framework, we are more-likley to decide on a framework that tends to aim toward TypeScript (e.g. Vue) than a framework that tends to aim toward plain JavaScript (e.g. React). ### Related requirements Our entire toolchain must support these languages. ### Related artifacts We expect we may export some secrets to environment variables. ### Related principles Measure twice, build once. We are prioritizing some safety over some speed. Runtime is more valuable than compile time. We are prioritizing customer usage over developer usage. ## Notes Any notes here. ================================================ FILE: locales/en/examples/python-django-framework/.locale-peer-id ================================================ b8f60539494aed8b17e1b8969ae2f10b ================================================ FILE: locales/en/examples/python-django-framework/index.md ================================================ # Architecture Decision Record for Python Django Framework Decision Date: 2021-07-15 Status: Accepted ## Context Our organization is planning to develop a web application that manages customer data. We have chosen Python as the programming language and are considering Django as the web framework for the development of the application. ## Decision We have decided to use the Django web framework for the development of the web application. Django provides a robust set of tools and features for building web applications quickly and efficiently. ## Factors Some of the factors that influenced our decision include: 1. Object-Relational Mapping (ORM): Django has a built-in ORM that allows us to interact with the database without writing SQL queries. This makes it easier to develop the application and maintain it in the long run. 2. MVC framework: Django follows a Model-View-Controller (MVC) architecture, making it easier to separate the business logic and presentation layers of the application. 3. Scalability: Django is known for its scalability capabilities, making it an excellent choice for developing large-scale applications. 4. Security: Django has built-in security features, such as protection against common web attacks like cross-site scripting (XSS) and SQL injection. 5. Community Support: Django has a large and active community that provides support and contributes to the development of the framework. ## Alternatives Considered We considered other web frameworks such as Flask and Pyramid. However, we found that Django is a more mature and well-established framework with a robust set of features. We also discussed developing the application without a web framework and using libraries like SQLAlchemy and Flask-RESTful. However, we found that Django offers broader functionality, making it a better choice for a complete web application. ## Consequences The adoption of Django will lead to the following consequences: 1. Easier to develop and maintain the application due to Django’s built-in tools and features. 2. Separation of business logic and presentation layer, leading to more organized and easier to maintain code. 3. Scalability and robustness of the application. 4. Built-in security features that help protect the application against common web attacks. 5. Access to a large and active community for support. We understand that Django has a steeper learning curve than other frameworks, but we find that it is worth the investment for the long-term benefits it provides. ## Conclusion Based on the factors considered, we have decided to use the Django web framework for the development of the web application. We believe that Django’s features, community support, and scalability capabilities make it the best choice for building a complete web application. We will train our developers to use Django to ensure that the framework is used effectively and efficiently. ================================================ FILE: locales/en/examples/python-programming-language/.locale-peer-id ================================================ 42fd8a00f5f37e2f2a9c4a3f2fd61356 ================================================ FILE: locales/en/examples/python-programming-language/index.md ================================================ # Architecture Decision Record: Python programming language ## Context We need to decide on whether to use Python as a programming language for our project. Our project involves data analysis, machine learning, and web development. ## Decision We have decided to use Python as our primary programming language for our project. ## Rationale Python is a versatile programming language that is widely used in the areas of data analysis, machine learning, and web development. It is an interpreted language, which means that it does not need to be compiled, and it has an easy-to-read and understand syntax. Other important factors for our decision include the following: 1. **Availability of libraries:** Python has a huge collection of libraries and frameworks, such as NumPy, Pandas, and Scikit-learn, which makes it easier for developers to implement machine learning algorithms and data analysis. 2. **Community support:** Python has a large and active community of developers who contribute to its development and provide support and guidance on various forums and websites. This makes it easier for beginners to find help and learn the language. 3. **Scalability:** Python is scalable, which means that it can handle large datasets and complex applications. It can also be used for rapid prototyping or building small applications with minimal effort, making it easier for us to start our project and iterate quickly. 4. **Flexibility:** Python can be used for various types of projects, including web development, scientific computing, machine learning, etc. It is also compatible with other programming languages, such as Java and C++, which makes it easier to integrate with other systems. ## Consequences There are some potential consequences to using Python as our programming language, such as: 1. **Performance:** Python can be slower than compiled languages like C++ when it comes to executing certain algorithms, but this can be mitigated by using optimized libraries or writing critical code in C++ and interfacing with it using Python. 2. **Learning curve:** While Python has an easy-to-learn syntax, it can be challenging to learn the best practices for writing efficient and scalable code. This can be overcome by following conventions, using frameworks and libraries, and seeking guidance from experienced developers. 3. **Version compatibility:** Different versions of Python can have different syntax and capabilities, which can make it difficult to maintain and update projects. It is important to choose a version of Python that is widely supported and compatible with our project requirements. ## Conclusion After considering the pros and cons of using Python as our programming language, we have decided that it is the best choice for our project. We believe that it will provide us with the most flexibility, availability of libraries, and community support, while also being scalable and adaptable to our changing needs.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/react-front-end-javascript-library/.locale-peer-id ================================================ 9eadfd943b9e3d2404a28e8ad14d3076 ================================================ FILE: locales/en/examples/react-front-end-javascript-library/index.md ================================================ # Architecture Decision Record: React Front-End JavaScript Library ## Context We need to choose a front-end JavaScript library for our application to develop a responsive and interactive user interface. ## Option Considered 1. React 2. Vue 3. Svelte ## Decision We will use React as our front-end JavaScript library. ## Rationale 1. **Component-Based Architecture:** React provides a component-based architecture that allows us to break down the UI into small reusable components. This helps improve the modularity of our code and makes it easier to maintain, scale, and update the application. 2. **Declarative programming:** React uses a declarative style of programming that makes our code more intuitive and easier to read. It also provides a virtual DOM, which allows our code to run faster and more efficiently. 3. **Large Community:** React has a large and active community, and it is one of the most popular front-end libraries. This means that there are a lot of resources, tools, and libraries available that can help us develop our application faster and more efficiently. 4. **Better performance:** React uses a one-way data flow, which helps simplify the application logic and makes it more efficient. It also provides server-side rendering, which helps improve the performance and SEO of our application. 5. **Flexibility:** React can be used with other libraries and frameworks, which gives us the freedom to choose the best technology stack that suits our project's requirements. ## Consequences 1. **Learning Curve:** React has a learning curve, and it may take some time for developers who are new to React to get up to speed. 2. **Build Tools:** React requires additional build tools such as Babel and Webpack, which may add complexity to the development process. 3. **Browser compatibility:** React has compatibility issues with older browsers since it uses ES6 features that are not supported in older browsers. 4. Steep learning curve: It may take time for developers who are not familiar with React to learn how to use it efficiently, which may lead to slower development times. ## Conclusion We have decided to use React for our application's front-end JavaScript library. Although it may have a learning curve, the benefits that React provides, such as its component-based architecture, declarative style of programming, better performance, flexibility, and large community, outweigh the potential drawbacks.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/ruby-on-rails-framework/.locale-peer-id ================================================ b107a749a966e10cc337420370e34063 ================================================ FILE: locales/en/examples/ruby-on-rails-framework/index.md ================================================ # Architecture Decision Record: Ruby on Rails Framework ## Context - The organization is developing a web application with complex business logic and multiple integrations with third-party services. - The team has experience in building web applications with Ruby on Rails. - There is a need to choose a web framework that promotes rapid development, scalability, and maintainability. ## Decision - Use Ruby on Rails as the framework for developing the web application. ## Justification - Ruby on Rails is a mature, stable, and widely adopted web framework that has proven its effectiveness in building complex web applications. - The framework follows the Model-View-Controller (MVC) architecture pattern, which promotes separation of concerns and enhances code reusability and maintainability. - Rails provides many built-in features, such as ActiveRecord for database interactions and ActionMailer for email management, which can save development time and simplify code. - The framework has a large and active community, with many reusable modules and plugins available to enhance functionality and resolve common problems. - Ruby on Rails supports Test-Driven Development (TDD) and Behavior-Driven Development (BDD), which enables developers to write automated tests for their code, ensuring that it works as expected and reducing bugs and regressions. - Ruby is a high-level language that promotes developer productivity and code readability, and acts as a powerful glue language for integrating with a wide range of third-party services and APIs. ## Consequences - The team needs to ensure that the web application's architecture and design follow Rails conventions and best practices to maximize the benefits of the framework. - Developers need to have a good understanding of the Ruby language and the Rails framework, although the Rails documentation and community can provide guidance and support. - There may be a learning curve for developers who are new to Ruby and Rails, although the benefits of the framework can justify the investment in training and onboarding. - The team needs to monitor the application's performance and scalability, and may need to fine-tune database queries and optimize caching to handle large amounts of data and traffic.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/rust-programming-language/.locale-peer-id ================================================ d21b58847a2e92716ef2f68b44156564 ================================================ FILE: locales/en/examples/rust-programming-language/index.md ================================================ # Architecture Decision Record: Rust programming language Decision Number: AR-001 Decision Title: Adoption of Rust programming language Date: December 1, 2021 Status: Accepted ### Problem Statement As we continue to develop software applications, we have observed that it is increasingly challenging to mitigate potential security vulnerabilities and prevent runtime errors. With the existing programming languages, such as C and C++, we continue to experience issues such as buffer overflows, memory leaks, and undefined behavior leading to applications' crashes. We require a programming language that provides memory safety guarantees and is efficient enough to support performance-critical applications. ### Considerations Several programming languages are designed to address the existing problems. Among them, Rust programming language has gained significant attention from the developers' community due to its unique design features. Considerations include; 1. Memory safety and security 2. Performance and efficiency 3. Community support and adoption 4. Learning curve 5. Tools and ecosystem 6. Compatibility with existing software systems. ### Constraints Adopting a new programming language requires retraining developers, which takes time and resources. Integrating the language into the existing development workflow may be a challenge. We must ensure compatibility with the existing systems and avoid breaking changes to maintain continuity. ### Implementation 1. Our development team will undergo training to learn and familiarize themselves with the Rust programming language. 2. We will create a new project using Rust on a trial basis to evaluate its compatibility and suitability for our development purposes. 3. We will gradually migrate existing systems written in C and C++ to Rust. 4. We will collaborate with the Rust community to explore the available tools and libraries that can enhance our development workflow. 5. We will monitor the performance of Rust and compare it to the performance of the existing programming languages regularly. 6. We will adopt a long-term approach that balances the costs of training, integration, and potential benefits of using Rust. ### Rationale We have adopted Rust due to its unique features designed to provide memory safety and security guarantees while maintaining performance and efficiency. Rust's robust type system, borrow checker, and memory safety concepts make it highly suitable for developing performance-critical and safety-critical applications. Moreover, Rust has a significant community of developers, enabling us to access a wide range of tools, libraries, and ecosystem that support our development workflow. Although Rust comes with a learning curve, we believe the benefits of adopting Rust outweigh the costs and provide an excellent opportunity for continued growth and innovation. ### Consequences 1. The adoption of Rust will require a significant investment in time and resources to train developers and integrate the language into the existing development workflow. 2. Adopting Rust may cause some degree of compatibility issues with existing systems, requiring refactoring, and modifications. 3. Rust's adoption may increase the number of developers who can contribute to our project by attracting Rust developers who want to work on exciting projects. 4. The adoption could lead to improved performance, efficiency, and safety as compared to the existing languages. 5. Finally, adopting Rust comes with the potential benefit of reducing security vulnerabilities in our applications.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/secrets-storage/.locale-peer-id ================================================ 8123c8089cda027baecab9c034e947c6 ================================================ FILE: locales/en/examples/secrets-storage/index.md ================================================ # Secrets storage Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes) * [Vault by HashiCorp](#vault-by-hashicorp) * [LastPass](#lastpass) * [Bitwarden](#bitwarden) * [EnvKey](#envkey) * [Confidant by Lyft](#confidant-by-lyft) * [Devolutions Password Server](#devolutions-password-server) * [Secret Server by Thycotic](#secret-server-by-thycotic) ## Summary ### Issue We need to store secrets, such as passwords, private keys, authentication tokens, etc. Some of the secrets are user-oriented. For example, our developer wants to be able to use their mobile phone to look up a password to a service. Some of the secrets are system-oriented. For example, our continuous delivery pipeline needs to be able to look up the credentials for our cloud hosting. ### Decision Bitwarden for user-oriented secrets Vault by HashiCorp for system-oriented secrets. ### Status Decided. We are open to new alternatives as they arise. ## Details ### Assumptions For this purpose, and our current state, we value user-oriented convenience, such as usable mobile apps. * We want to ensure fast easy access on the go, such as for a developer doing on-call system reliability engineering. * We want to be able to share some secrets among selected people, such as a team. We are not trying to solve for single-provider, such as storing all secrets exclusively on Amazon or Azure or Google. We do not want ad-hoc approaches such as "remember it" or "write it on a note" or "figure out your own way to store it". Our security model for this purpose is fine with using well-respected COTS vendors, such as SaaS password management tools. ### Constraints Right now we want something that is easy i.e. no need to write code, no need to install servers, no need to make a major commitment, no need to standardize everyone. ### Positions We considered: 1. User-oriented off-the-self password managers: LastPass, 1Password, Bitwarden, Dashlane, KeePass, pass, GPG, etc. 2. System-oriented COTS password managers: AWS KMS, Vault by HashiCorp, EnvKy, Secret Server by Thycotic, Devolutions Password Server, Confidant by Lyft. 3. Sharing-oriented approaches: using a shared Google document, or shared Slack channel, or shared network folder, etc. 4. Low-tech ad-hoc approaches, such as remembering, writing a note, or relying on each user to figure out their own approach. ### Argument Bitwarden, LastPass, 1Password, and Dashlane all are commercial off-the-shelf products. * Similar kinds of features for users, teams, organizations, etc. * Desktop capability for Windows and Mac, and mobile capability for Android and iOS. * Browser extensions for Chrome and Firefox, for automatic form fill in, etc. Bitwarden has two advantages over the others: * Bitwarden is open source, which means the security can be peer reviewed and also the company is widely-appreciated by security-oriented developers. * Anecdotes by software workers describe a significant preference for Bitwarden over the others. A typical good example writeup: https://jcs.org/2017/11/17/bitwarden A typical side-by-side voting site: https://stackshare.io/stackups/bitwarden-vs-dashlane We defer KeyPass, pass, GPG, etc. because there's additional complexity. All of these look like fine solutions for technical users. GPG looks especially good for technical users who want cross-system command-oriented capabilities. We defer KMS because it has single-provider lock-in. We choose Vault for system-oriented needs, because the reviews are amazingly positive, and because HashiCorp has an excellent track record fup top-quality software and support. We veto the approaches of sharing approaches such as via shared documents, shared channels, shared network folders, etc. These do not provide the security qualities that we want. We veto the ad-hoc low-tech approaches, because we all agree it's not a long-term path forward. ### Implications Developers may need to track secrets in two places: Bitwarden for user-oriented access, and Vault for system-oriented access. ## Related ### Related decisions The decision of which CI/CD server must include proof of capability for accessing secrets. We will need to decide how to managea the secrets, in terms of policies, rotations, organizations, etc. ### Related requirements The secrets will have related requirements for compliance, auditing, and HR onboarding/offboarding. ### Related artifacts We expect we may export some secrets to environment variables. ### Related principles Easily reversible. Easily parallel i.e. it's easy to use a variety of password managers. Cheap to try i.e. there's a free trial and no commitment. ## Notes Evaluation notes here. The notes are all public comments on various devops discussion boards. ### Vault by HashiCorp Vault is exactly what you want here. Don't just throw Vault into production though, stand it up in a test environment first, because HashiCorp's documentation can be pretty lacking even if their products are amazing. Very steep learning curve and is not trivial to stand up. The initial setup is a bit of a pain. It's well worth it though, and the community will support it will enough for you to get by. Horrid docs but there are lots of guides online of people setting it up and if you put a few of them together you will have a working setup. Initial setup took fiddling with their helm charts (vault and consul). While technically you can use lots of other back-ends, I really really don't recommend it. The back-end/consul can be teeny tiny if you don't have a ton of data to store. Definitely get comfortable/familiar with using the CLI, because the GUI is more like a proof-of-concept/advertisement portal for their enterprise edition. The fact that you cannot just "fill it up" is a pain. For example if you have 5 fields you need to manually add each field for each item. So it's not like you pre-define fields for a specific category, and fill those fields for all the items in that category, it's more like "you generate everything every time", which (in my mind) is a pain in the ass. You may want to also look at goldfish as a UI for on top of vault. Makes it rather nice to get your team on board with it. They also have a demo. 1. Set up consul. 2. Set up vault pointing to consul. 3. Set up goldfish pointing to vault. 3. Setup some cron job to run consul snapshot for backups. ### LastPass LastPass Teams. We use it, has custom templates, ACL, nothing missing IMO. I implemented LastPass at my org and give it a C+/B-. The biggest issue lately is a lack of reliability. In the past 90 days there have been multiple hours where vaults were forced into offline mode. This isn't ideal for my org due to having, literally, 4,000+ passwords stored across 20+ shared folders. As you can imagine with that many passwords at least a few get updated or added daily. We have a DR plan if issues last more than an hour or two: a script signs and encrypts a CSV dump of vault every night that can be imported into keepass. LastPass has had unreported blips of degraded service: login 'works' but doesn't pull sites, random features broken in the admin panel, and not properly sharing keys for new top level shared folders. I have a specific 'key push'/backup user that is in every group. Usually logging in as that user will fix any key sharing issues but not when the service is degraded despite what the status page says... For integration it can be easy if you have proper ACLs with a least privileged model e.g. if a user has read & write and read only on an entry or folder they only get read only permissions. Unfortunately my org's ACLs are not the best so I ended up using the JSON provisioning API and ~500 lines of python due to the dependent nature of our hundreds of ACLs not mapping well to the least privileged model. I ended up getting all ACLs a user was in and do a dependency walk of sorts. If your ACL or group structure is already built with a least privileged structure in mind the AD/LDAP sync tool for Windows will work well. Reach out to their sales team and they can hook you up with a longer Enterprise trial. Be sure you fully understand its limitations before pulling the trigger. We had a good number of growing pains but aside from outages or impairments on the server side it's been incredibly smooth. ### Bitwarden Bitwarden has a nice tooling around it (WebUI, CLI, Mobile, Desktop). Self-hosted and fairly easy to setup. Fairly good documentation and recommended tool by PrivacyTools. ### EnvKey https://www.envkey.com/ Is a saas. Really easy to implement, integrate and manage. Features: * Protect API keys and credentials. * Keep configuration in sync everywhere. * Smart, end-to-end encrypted configuration and secrets management. * Prevent insecure sharing and config sprawl. * Integrate in minutes. Capabilities: * Manage configuration and access levels for all your apps, environments, and teams in one place. * Configure any development or server environment with just a single environment variable. Pros: * Good home page. * Clear value prop. * Visually excellent web app. * Superior example data e.g. Algolia, AWS, Datadog, GitHub, Stripe, etc. * Spoke with the founder for 30m about the company, UI, etc. Dane sounds well-informed, honest about the pros/cons, and a viable partner. * The company is essentially a typical Y Combinator company, with 1 founder. Raised $120K in 2018-01. * Focus is on getting to enterprise features, esp. moving from EnvKey cloud-hosting to either on-prem or BYOC. * Potential path forward starting with EnvKey for ease of use, then later (or in parallel) adding Vault. ### Confidant by Lyft https://lyft.github.io/confidant/ Confidant is a open source secret management service that provides user-friendly storage and access to secrets in a secure way, from the developers at Lyft. KMS Authentication: Confidant solves the authentication chicken and egg problem by using AWS KMS and IAM to allow IAM roles to generate secure authentication tokens that can be verified by Confidant. Confidant also manages KMS grants for your IAM roles, which allows the IAM roles to generate tokens that can be used for service-to-service authentication, or to pass encrypted messages between services. At-rest encryption of versioned secrets: Confidant stores secrets in an append-only way in DynamoDB, generating a unique KMS data key for every revision of every secret, using Fernet symmetric authenticated cryptography. A user-friendly web interface for managing secrets: Confidant provides an AngularJS web interface that allows end-users to easily manage secrets, the mappings of secrets to services and the history of changes. ### Devolutions Password Server https://server.devolutions.net/ Secure, manage, and monitor access to privileged accounts and sessions. A comprehensive, highly-secured password vault that lets you control access to your privileged accounts, while also improving overall network visibility for sysadmins and providing a seamless experience for end users. Features: centralized organization password vault, user-specific private vault, password manager, credential injection, Active Directory integration, role-based access control, two-factor authentication, enterprise ready, IP restrictions, management capabilities, automated password generator, mobile app access, password history, access reports, email alerts. * supports data encryption * supports multiple Authentication schemes including LDAP, O365, and Local users WITH support for MFA from multiple sources * multiple repositories/vaults with fine-grained access controls for multiple teams * modern Web UI * private credential and connection vaults for personal creds/connections * mobile apps for IOS/Android * audit logs for each entry, who/what/when with an optional prompt for why they're accessing * customizable templates (though they support hundreds of connection types natively) * tons more features and a Windows/Mac thick client (Remote Desktop Manager) that you can sync to that greatly expands the options...one-click connections * pricing isn't all that bad - up to 15 users is $500 a year for the password server ### Secret Server by Thycotic https://thycotic.com/products/secret-server/ On-premise version features: * Total control over your end-to-end security systems and infrastructure * Deploy software within your on-premise data center or your own virtual private cloud instance * Meet legal and regulatory obligations that require all data and systems to reside on premise Cloud version features: * Software-as-a-service model lets you sign up and start right away * Elastic scalability as you grow * Controls and redundancy delivered by Azure with 99.9% uptime SLA User feedback: * We used to use that product. It was so easily bypassed and the rules only work for smart people. Lazy or dumb users can easily screw it up in a team area. Prices are negotiable when you talk to them. * You can run it using SQL express and an Win 7box. * Cheap. ================================================ FILE: locales/en/examples/snake-case-v-camelcase-for-a-rest-api/.locale-peer-id ================================================ 56bcc02899f133bd74208e58e020ad3a ================================================ FILE: locales/en/examples/snake-case-v-camelcase-for-a-rest-api/index.md ================================================ # Architecture Decision Record: snake_case v. camelCase for a REST API? Decision: snake_case naming convention will be used for REST API endpoints Status: Accepted ## Context In naming conventions for REST APIs, there are two popular formats: snake_case and camelCase. The snake_case format is where each word in the name is separated by underscores, whereas camelCase is where the first word of the name is in lower case, and the subsequent words have their first letter capitalized. This decision will determine which naming convention should be used for a REST API. ## Decision Drivers - Consistency with existing naming conventions in the project - Readability and clarity for anyone who may be working on the API - Alignment with industry best practices for REST API naming conventions - Ease of implementation and maintenance ## Decision The snake_case naming convention will be used for REST API endpoints. This choice is driven by the following factors: 1. **Consistency**: The project already uses snake_case naming convention for all endpoints, and it would be beneficial to maintain this convention to ensure consistency across the entire project. 2. **Readability and clarity**: The snake_case convention is more readable and easier to understand. The underscores provide a clear separation between words, making it easier to parse and understand the meaning of the name. 3. **Alignment with industry best practices**: The snake_case convention is widely used in the industry and is considered to be a best practice for REST APIs, making it a good choice for the project. 4. **Ease of implementation and maintenance**: Keeping with the existing naming convention is easier to implement and maintain as all existing code and documentation would need to be updated if a new convention was chosen. ## Consequences There are potential consequences of this decision. * If any new team members joining the project are unfamiliar with snake_case naming convention, it could lead to confusion and mistakes in development. However, since snake_case is a widely-used convention, such a risk is minimal. * If other tools or frameworks are used in the project that are heavily based on camelCase convention, it may require extra effort to convert between naming conventions. However, it is not a significant concern since the project has standardized on the snake_case convention. Overall, the decision to use snake_case naming convention for REST API endpoints results in a consistent, readable, and industry-standard approach while being easy to implement and maintain.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/svelte-components/index.md ================================================ # Architecture Decision Record (ADR) for Svelte Components ## Context We are selecting a Svelte UI component library to provide full features for: - **Tables** - **Charts** - **Lists** - **Grids** - **Gantt charts** The goal is to choose a library that balances ease of integration, full feature support, performance, and long-term maintainability. The options under consideration are: 1. **SVAR** 2. **Carbon** 3. **Flowbite** 4. **SkeletonUI** 5. **MeltUI** 6. **SvelteUI** 7. **shadcn-svelte** ## Options Analysis ### 1. **SVAR** - **Overview**: SVAR is a modern, feature-rich component library for Svelte, with a focus on design systems and enterprise-ready components. - **Pros**: - Full-featured components, including tables, forms, and charts. - High customization options with built-in theme support. - Built-in support for accessibility and responsiveness. - Well-documented with community contributions. - **Cons**: - It might be heavier compared to other simpler libraries. - Limited support for specific components like Gantt charts and advanced grids. - **Best For**: Enterprise-level applications where a full-featured design system is necessary. - **Table/Chart Support**: Moderate to good. - **Grid/Gantt Support**: Minimal. ### 2. **Carbon** - **Overview**: Carbon Design System is an open-source design system from IBM, offering a robust set of UI components. - **Pros**: - High-quality, polished design with extensive documentation. - Very accessible and responsive. - Large component library, including grids, tables, and form controls. - **Cons**: - Not focused on Svelte, so integration can be cumbersome. - Could require additional customization for full Svelte compatibility. - No out-of-the-box support for advanced components like Gantt charts or complex charts. - **Best For**: Large-scale projects requiring a consistent, polished UI. - **Table/Chart Support**: Good (with charting library integrations). - **Grid/Gantt Support**: Good (Grid support available, but no Gantt charts). ### 3. **Flowbite** - **Overview**: Flowbite is a component library that’s built with Tailwind CSS, offering various components and UI elements. - **Pros**: - Tailwind CSS-based, which makes it easy to customize. - Easy to integrate and use with Svelte. - Provides rich components like tables, charts, and UI controls. - **Cons**: - Lacks advanced features (e.g., Gantt charts or complex grids). - Doesn’t have native charting components; relies on external libraries. - **Best For**: Projects requiring quick development with a focus on Tailwind CSS integration. - **Table/Chart Support**: Good (requires integration with third-party chart libraries). - **Grid/Gantt Support**: Minimal. ### 4. **SkeletonUI** - **Overview**: SkeletonUI is a lightweight component library for Svelte, focusing on simplicity and minimalism. - **Pros**: - Extremely lightweight and fast. - Simple and intuitive API. - Good for small projects or where performance is critical. - **Cons**: - Very few components are included, so it's not feature-rich. - Lacks advanced table/grid/chart/Gantt components. - Limited community support and less comprehensive documentation. - **Best For**: Projects that require lightweight components with minimal overhead. - **Table/Chart Support**: Minimal. - **Grid/Gantt Support**: Minimal. ### 5. **MeltUI** - **Overview**: MeltUI is a collection of accessible UI components for Svelte, focusing on simplicity and composability. - **Pros**: - Lightweight and fully customizable. - Good accessibility features out-of-the-box. - Modern and minimalistic design. - **Cons**: - Less feature-rich compared to other libraries. - Lacks advanced grid and table components. - No Gantt charts or complex charting options. - **Best For**: Minimalistic designs that prioritize accessibility and performance. - **Table/Chart Support**: Minimal. - **Grid/Gantt Support**: Minimal. ### 6. **SvelteUI** - **Overview**: SvelteUI is a comprehensive and customizable UI component library for Svelte, designed for building modern web apps with elegant UI. - **Pros**: - Comprehensive set of components, including tables, grids, charts, and forms. - Provides both light and dark mode support. - Highly customizable and easy to extend. - Built-in integrations for charting libraries like `chart.js` or `d3.js`. - **Cons**: - Can be heavier than simpler component libraries. - Requires some setup to integrate external libraries for more complex features like Gantt charts. - **Best For**: Projects needing a comprehensive, customizable set of components. - **Table/Chart Support**: Excellent (charting libraries supported). - **Grid/Gantt Support**: Good (Grid components available; Gantt needs external integration). ### 7. **shadcn-svelte** - **Overview**: A Svelte version of ShadCN, which focuses on utility-first design and provides modern, styled components. - **Pros**: - Utility-first design, built on top of Tailwind CSS, making it easy to customize. - Rich set of components and fully styled out-of-the-box. - Easy to integrate with other libraries. - **Cons**: - Not as feature-complete as some others in terms of advanced UI elements. - Lacks built-in support for tables, charts, or grids. - No out-of-the-box support for Gantt charts. - **Best For**: Small-to-medium projects requiring a utility-first, customizable approach. - **Table/Chart Support**: Minimal. - **Grid/Gantt Support**: Minimal. ## Decision ### Recommended Option: **SvelteUI** - **Rationale**: SvelteUI offers a well-rounded, comprehensive suite of components that cater to the need for tables, charts, grids, and forms. It’s highly customizable, integrates well with other charting libraries (like `chart.js` and `d3.js`), and has a good balance of lightweight performance and feature richness. While it may not provide out-of-the-box Gantt chart support, it can be easily extended with third-party integrations, making it ideal for a full-featured, scalable solution. - **Pros**: - Excellent table and chart support. - Full grid and layout components. - Customizable and integrates well with external charting libraries. - Good community and documentation. - **Cons**: - Heavier than some other minimalist libraries. - Needs external integration for complex charts like Gantt charts. ### Alternative: **Flowbite** or **Carbon** (for larger enterprise projects) - If a polished, Tailwind-based, or more consistent design system is required, **Flowbite** (with Tailwind CSS) or **Carbon** (for enterprise-grade solutions) may be suitable alternatives. However, they may require extra effort for integrations with more complex charts and components. ## Conclusion The best fit for your requirements (full features for tables, charts, lists, grids, Gantt) is **SvelteUI**, followed by **Flowbite** and **Carbon** depending on the project needs and design preferences. ================================================ FILE: locales/en/examples/svelte-front-end-javascript-library/.locale-peer-id ================================================ bdca98499db7dd51eeb5add1ca5ec974 ================================================ FILE: locales/en/examples/svelte-front-end-javascript-library/index.md ================================================ # Architecture Decision Record: Svelte Front-end JavaScript Library Status: Accepted ## Context We are developing a web application using a modern front-end JavaScript framework. We want to choose a library that is lightweight, fast, and easy to use. We have evaluated several libraries, including React, Vue, and Angular. We have also heard about Svelte, which claims to be a new kind of lightweight framework. We need to evaluate Svelte and decide whether it is a good fit for our application. ## Decision After considering the benefits and drawbacks of each library, we have decided to use Svelte as our front-end JavaScript library for the following reasons: 1. **Lightweight:** Svelte is one of the lightest libraries available, which will help us keep our application size small and improve page load times. 2. **Fast:** Svelte is known for its fast rendering speed, which will make our application feel responsive and snappy. 3. **Easy to use:** Svelte's syntax is simple and easy to understand, which will make it easier for our team to adopt it and write clean code. 4. **Optimized for UI rendering:** Svelte is optimized for rendering UI components, which will make it easier for us to create dynamic and reusable UI elements. 5. **Good documentation and community support:** Svelte has a growing community and good documentation, which will help us get started quickly and resolve any issues that arise. ## Alternatives We considered React, Vue, and Angular, but decided against them for the following reasons: 1. **React:** While React has a large user base and a wealth of libraries and resources, it can be complex and difficult to learn, especially for beginners. 2. **Vue:** Vue is a lightweight library that is easy to learn and use, but it may not be as fast or optimized as Svelte. 3. **Angular:** Angular is a comprehensive framework that offers many features and tools, but it can be heavy and complex, and may require more maintenance than Svelte. ## Consequences Using Svelte as our front-end JavaScript library will have the following consequences: 1. Our application will be lightweight and fast, which will improve user experience and engagement. 2. Our team will need to learn a new library, but the syntax of Svelte is simple and easy to understand, so the learning curve should be manageable. 3. Svelte is still a relatively new library, so we may encounter some issues that are not well documented or supported by the community. 4. The community of Svelte users is growing, so we may see more third-party libraries and resources become available in the future that can be used to supplement the core library. ## Conclusion Based on our evaluation, we have decided to use Svelte as our front-end JavaScript library for our web application. We believe that Svelte's lightweight and fast nature, ease of use, and optimized UI rendering make it the best choice for our needs. We will continue to monitor the development of Svelte and its community and make modifications to our choice if needed.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/sveltekit-framework/.locale-peer-id ================================================ 0bc6820a0b59edb03d91948dcfcd6cd0 ================================================ FILE: locales/en/examples/sveltekit-framework/index.md ================================================ # Architecture Decision Record: SvelteKit framework * Date: [Current Date] * Status: [proposed, approved, rejected, deprecated] ## Context We are building a new web application that requires a scalable and efficient front-end architecture. After conducting a thorough analysis of various front-end frameworks, we have chosen SvelteKit as our preferred framework. ## Decision We have decided to implement the SvelteKit front-end architecture for our web application. SvelteKit provides an advanced front-end development system that is fast, efficient, and flexible. It can be used for optimizing large and small applications. ## Rationale SvelteKit is a new and comprehensive front-end solution that offers an array of features such as server-side rendering, hot reloading, simplified configuration, and many more. It enables us to create high-quality front-end architecture that can handle the largest applications with ease. SvelteKit's component-based architecture enables us to develop reusable and scalable UI components that can be integrated seamlessly between different projects. The framework offers excellent support for TypeScript, allowing us to create clean and structured code that is easy to maintain. In addition, SvelteKit provides an easy-to-use document management system that allows us to track all of our project's architectural decisions and changes. ## Alternatives Considered We have evaluated several alternatives, such as React, Vue, Angular, and Next.js, but with its features, ease of use, and robustness, SvelteKit was the clear choice for our project. ## Consequences Implementing SvelteKit front-end architecture will provide enhanced user experience, performance, and flexibility. We can achieve better productivity through the framework’s simpler configurations, component-based architecture, and modularity. As a result, our project can be more efficient and stable. ## Conclusion We decided to implement the SvelteKit front-end architecture to achieve a modern, scalable, and efficient web application with the features and modularity we need. With its excellent support for TypeScript, server-side rendering, and simplification of configurations, we feel that SvelteKit is the best choice for our project.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/tailwind-css/.locale-peer-id ================================================ 496e7846025a0701822dc65ca71180a5 ================================================ FILE: locales/en/examples/tailwind-css/index.md ================================================ # Architecture Decision Record: Tailwind CSS Decision: Use Tailwind CSS as the CSS framework to style a user interface. ## What is Tailwind CSS? Tailwind is a utility-first CSS framework that allows for rapid development and customization of user interfaces. It is designed to be highly customizable and allows developers to write leaner and more efficient CSS. This framework provides a set of pre-defined classes to style the UI very fast. ## Context We are building a web application for a client that requires a responsive and customizable user interface. The client has asked for consistent and modern styling. The development team has experience using custom CSS but wants to explore CSS frameworks that can save time and effort. We are looking for a framework that is easy to use, customizable, and has a large community for support. ## Decision Drivers - **Easy to use:** We want a framework that is simple to learn and can be integrated into our development workflow. - **Customizable:** We want a framework that can be customized to match the client's brand guidelines and theme. - **Large community support:** We want a framework that has an active community of developers and designers that can provide help and resources when needed. - **Time-saving:** We want a framework that can save time and effort in styling the UI. ## Considered Options - **Bootstrap:** A popular CSS framework with a lot of pre-built components and a large community of developers. - **Foundation:** Another popular CSS framework that was designed for mobile-first development. - **Materialize:** A CSS framework based on Google's Material Design language with pre-built components for UI development. - **Tailwind CSS:** A utility-first CSS framework with a focus on customization and efficiency. ## Decision Outcome After considering the options, we decided to use Tailwind CSS for the following reasons: - **Easy to use:** Tailwind's approach is simple and easy to understand. Its utility classes make building a UI faster. - **Customizable:** Tailwind allows for customization by providing a set of configuration files that allow developers to modify the framework's default styles with ease. - **Large community support:** Tailwind has a very active community of developers and designers that are consistently creating new resources, plugins, and tools. - **Time-saving:** Tailwind can save time, enabling developers to focus on other areas of the project. We will use Tailwind CSS's utility classes to build the UI for our project. The development team will use its atomic and modular design system to write efficient and scalable CSS code. We will leverage Tailwind's pre-built templates and visual components to speed up the development process while utilizing custom styles to match the branding and theme of the client.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/timestamp-format/.locale-peer-id ================================================ 9374af360cb954bffd75c8518a93b25d ================================================ FILE: locales/en/examples/timestamp-format/index.md ================================================ # Timestamp format Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes) ## Summary ### Issue We want to be able to track when things happen by using timestamps and by using a consistent timestamp format that works well across all our systems and third-party systems. We interact with systems that have different timestamp formats: * JSON messages do not have a native timestamp format, so we need to choose how to convert a timestamp to a string, and convert a string to a timestamp, i.e. how to serialize/deserialize. * Some applications are set to use local time, rather than UTC time. This can be convenient for projects that must adjust to local time, such as projects that trigger events that are based on local time. * Some systems have different time precision needs and capabilities, such as using a time resolution of seconds vs. milliseconds vs. nanoseconds. For example, the Linux operating system `date` command uses a default time precision of seconds, whereas the Nasdaq stock exchange wants a default time precision of nanoseconds. ### Decision We choose the timestamp standard format ISO 8601 with nanosecond precision, specifically "YYYY-MM-DDTHH:MM:SS.NNNNNNNNNZ". The format shows the year, month, day, hour, minute, second, nanoseconds, and Zulu time zone a.k.a. UTC, GMT. ### Status Decided. ## Details ### Assumptions We need to handle these timestamp text strings, to convert from a timestamp to a string (a.k.a. serialize) and convert from a string to a timestamp (a.k.a. deserialize). We want a format that is generally easy to use, easy to convert, and easy for a person to read. We want compatibility with a wide range of external systems that we cannot control, such as analytics systems, database systems, financial systems. ### Constraints Some systems have time precision limitations. For example, the macOS operating system `date` command can print time precision in seconds, but not in nanoseconds. ### Positions We considered a range of options: * Unix epoch i.e. one incrementing number. * Terse text format "YYYYMMDDTHHMMSSNNNNNNNNN". * Using a local time zone vs. the UTC time zone. ### Argument For typical use, we value easy to read/write by humans, more than raw speed/size. For typical use, we want a format that works fine in machine systems, and also works well manually, such as writing sample data, reading JSON output, grepping a log file, etc. For atypical use, such as high performance computing, we expect we'll want to optimize any text format we choose by converting the text to a faster format, such as a programming language's built-in date object type. So the text format doesn't matter much for HPC. ### Implications Our various text systems and time systems will converge on this format. ## Related ### Related decisions We may want a fast/easy way to also track time deltas a.k.a. durations. These are easy with Unix epoch timestamps. ### Related requirements We may want to adjust our decision e.g. if we have a related requirement for a specific kind of logging message stamp, such as for Splunk, Sumo, ELK, etc. ### Related artifacts Language formatters and parsers: * [date-fns: Modern JavaScript date utility library](https://date-fns.org/) * [Crono: date and time library for Rust](https://github.com/chronotope/chron) Rosetta Code examples: * [System time](https://www.rosettacode.org/wiki/System_time) * [Data format](https://www.rosettacode.org/wiki/Date_format) * [Show the epoch](https://www.rosettacode.org/wiki/Show_the_epoch) SixArm examples: * [now_string](https://github.com/SixArm/rosetta_code/tree/master/tasks/now_string) ### Related principles Easily reversible. We can change pretty easily to a different format, such as Unix epoch. Defer premature optimization. For typical use we don't care much about a handful of extra characters such as a format that uses dashes and colons. ## Notes Add notes here. ================================================ FILE: locales/en/examples/vue-front-end-javascript-library/.locale-peer-id ================================================ b43f7e984abc2ba89f2738c3e63203aa ================================================ FILE: locales/en/examples/vue-front-end-javascript-library/index.md ================================================ # Architecture Decision Record: Vue front-end JavaScript library Date: [Date of decision] Status: [Draft/Final/Postponed/Cancelled] Subject: Architecture Decision Record for Vue front-end JavaScript library ## Context Our web application requires a front-end JavaScript library to provide dynamic and responsive user interfaces. We have evaluated several popular libraries that include React, Angular, and Vue. Based on the evaluation, we have decided to use the Vue library as the primary front-end library for our web application. ## Decision We have decided to adopt the Vue front-end JavaScript library based on the following factors: 1. **Lightweight:** Vue is a lightweight library that offers functionality similar to that of React and Angular but with a smaller code footprint. 2. **Easy to learn:** Vue has a simple and intuitive API that makes it easy to learn and use. 3. **Flexibility:** Vue is a flexible library that works well with other libraries or frameworks to provide different functionalities. 4. **Performance:** Vue provides excellent performance with fast rendering and minimal overhead. 5. **Strong community:** Vue has a growing and strong community that offers support and resources to the users. ## Consequences The decision to use Vue as the primary front-end JavaScript library will have the following consequences: 1. Development and maintenance will be faster and easier because of the simplicity and flexibility of Vue. 2. Team members who are new to Vue can easily learn and use it because of its simple and intuitive API. 3. Integration with other libraries or frameworks will be easier because of the flexibility of Vue. 4. The application will have better performance and responsiveness with faster rendering and minimal overhead. 5. The team will have access to a growing and strong community that offers support and resources for Vue. ## Conclusion Based on the evaluation and the above factors, we have decided to use Vue as the primary front-end JavaScript library for our web application. This decision will provide us with the benefits of simplicity, flexibility, performance, and support from a growing and strong community.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/en/examples/web-application-framework-batteries-included-full-stack-for-a-startup-product/index.md ================================================ # Architecture Decision Record: web application framework, batteries included, full stack, for a startup product **Primary Objective:** To build a web application for paying customers to sign in, upload files, process data, and view reports, focusing on agile development, full-stack functionality, and strong compatibility with AI/ML tools, especially Project Jupyter notebooks. ### Context and Requirements: 1. **Agile Development (High Priority)**: As a startup, we need rapid iteration and flexibility. Agile practices, such as quick prototyping, iterative development, and adaptability to change, are key to our development cycle. 2. **Full-Stack Framework (High Priority)**: We aim to minimize overhead by selecting a framework that can handle both backend and frontend efficiently, reducing the need for separate front-end frameworks. 3. **Compatibility with AI/ML Tools (High Priority)**: The ability to integrate easily with data analysis tools like Jupyter notebooks and Python's data science ecosystem (NumPy, Pandas, TensorFlow, etc.) is essential. This would facilitate efficient data processing and reporting. 4. **Low Importance Criteria**: - **Runtime Speed**: While performance is relevant, it is not the most critical factor at the start since we are more concerned with development speed and feature completeness. - **Scalability**: We anticipate growth, but scalability concerns can be addressed later, and this is not a primary requirement right now. - **Backwards Compatibility**: We are focusing on current technologies and are not heavily concerned about backward compatibility with legacy systems. ### Frameworks Evaluated: 1. **Django (Python)** 2. **Ruby on Rails (Ruby)** 3. **Phoenix (Elixir)** 4. **Loco (Rust)** --- ### 1. **Django (Python)** **Overview**: Django is a high-level web framework for Python that promotes rapid development and clean, pragmatic design. It is known for its “batteries included” philosophy, meaning it includes many features such as authentication, routing, ORM, and form handling right out of the box. **Strengths**: - **Full-Stack**: Django is a comprehensive, full-stack framework that can handle both backend and frontend needs with integrated features (e.g., templating engine, admin interface). - **Agile Development**: Django's well-defined structure and conventions allow for rapid development and adaptability, crucial for a startup environment. The framework comes with excellent documentation and a rich ecosystem of third-party packages, which accelerates development. - **AI/ML Integration**: Python's ecosystem is unmatched when it comes to data science and machine learning. Django, being Python-based, integrates seamlessly with tools like Jupyter notebooks, Pandas, NumPy, TensorFlow, and scikit-learn. - **Community and Ecosystem**: Django has an extensive community, robust documentation, and a wide range of plugins and extensions, which significantly speeds up development and troubleshooting. **Weaknesses**: - **Runtime Speed**: Python tends to be slower compared to languages like Rust or Elixir. However, for this use case, where performance is not the primary concern, this may not be a dealbreaker. - **Scalability**: While Django is highly scalable, there might be challenges at the very high scale without careful optimization (e.g., when handling heavy concurrent requests). However, Django can still be scaled effectively using load balancing and caching techniques. **Verdict**: Django aligns well with the requirements for agile development, full-stack support, and AI/ML compatibility. Its Python integration offers seamless access to the data science tools and libraries necessary for the application. --- ### 2. **Ruby on Rails (Ruby)** **Overview**: Ruby on Rails (RoR) is a mature, full-stack web application framework known for its convention-over-configuration approach, which facilitates rapid development. **Strengths**: - **Full-Stack**: RoR comes with built-in tools for both backend and frontend development (e.g., views, templates, scaffolding), and its rich library of gems allows quick implementation of various features. - **Agile Development**: Ruby on Rails is particularly known for its fast iteration cycles, which is advantageous for startups looking to quickly iterate on features. RoR supports test-driven development (TDD) and has an established ecosystem for agile workflows. - **Community and Ecosystem**: RoR has a well-established, strong community and a wide array of gems that can speed up development. - **Ease of Use**: Rails has a very developer-friendly syntax and is known for making tasks such as database migrations, model-view-controller (MVC) architecture, and route handling quick and simple. **Weaknesses**: - **Performance**: Ruby tends to have slower runtime performance compared to Python or Elixir. While RoR can scale with the right infrastructure, Ruby’s performance might become a bottleneck for applications that require heavy real-time processing or high concurrent traffic. - **AI/ML Integration**: Although Ruby has some machine learning libraries, it is not as widely adopted in the AI/ML community as Python. Integration with tools like Jupyter notebooks is not as seamless, making Python a stronger choice for data-heavy applications. **Verdict**: While Ruby on Rails excels in agile development and rapid prototyping, it falls short in terms of AI/ML compatibility compared to Python (Django). It’s a viable choice for startups that prioritize fast iteration over deep data analysis integration. --- ### 3. **Phoenix (Elixir)** **Overview**: Phoenix is a web framework built with Elixir, a functional programming language designed for scalability and concurrency. Phoenix leverages the Erlang VM, which is known for handling massive concurrency and fault-tolerant systems. **Strengths**: - **Scalability and Performance**: Phoenix shines in scalability and handling high concurrency. It is built on the Erlang VM, which can support thousands (or even millions) of concurrent connections, making it a strong candidate for applications requiring real-time data processing or high-volume traffic. - **Full-Stack**: Phoenix includes everything needed to build both the backend and frontend of an application. It supports live views for interactive UI updates and includes a templating engine. - **Agile Development**: Phoenix is highly modular, allowing for rapid iteration on features. It is well-suited for startups that need to move quickly. - **AI/ML Compatibility**: While Elixir has emerging machine learning libraries, it is not as widely supported for AI/ML tasks as Python. Integrating with tools like Jupyter notebooks would require workarounds, as Elixir’s ecosystem for data science is not as mature as Python’s. **Weaknesses**: - **AI/ML Ecosystem**: Elixir is not the primary language used in data science or machine learning, and the ecosystem is not as mature as Python’s. Thus, integration with tools like Jupyter notebooks or popular AI libraries (TensorFlow, PyTorch) will be cumbersome. - **Learning Curve**: If the team is unfamiliar with functional programming and Elixir, there might be a steeper learning curve. **Verdict**: Phoenix is an excellent choice if scalability and concurrency are a primary concern. However, given the priority on AI/ML compatibility, Phoenix may not be the best fit due to Elixir's limited ecosystem in this space. --- ### 4. **Loco (Rust)** **Overview**: Loco is a web framework built with Rust, a systems programming language known for its performance, memory safety, and concurrency. Rust is increasingly popular for building high-performance applications. **Strengths**: - **Performance**: Rust’s primary strength lies in its high performance and memory safety, making it an excellent choice for applications requiring low-level control or extremely high performance. - **Concurrency**: Rust’s ownership system ensures memory safety while allowing safe concurrent programming, making it ideal for systems that need to scale efficiently and handle parallelism. **Weaknesses**: - **Full-Stack Development**: Loco, while promising, is not as mature as the other frameworks in terms of providing a complete full-stack solution. It is more suitable for backend development, and the front-end ecosystem around Rust is still emerging. - **Agile Development**: Developing with Rust can be slower compared to higher-level languages like Python or Ruby due to its lower-level nature and steeper learning curve. - **AI/ML Ecosystem**: Rust does not have the same extensive ecosystem for AI/ML as Python. While there are growing libraries in Rust for numerical computing, they are far less mature than Python’s offerings, such as Jupyter notebooks or machine learning frameworks. **Verdict**: While Rust and its framework Loco offer exceptional performance, the lack of full-stack support, agile development benefits, and AI/ML ecosystem make it less ideal for this specific use case. It is more suited for performance-critical applications rather than rapid web development with integrated data science tools. --- ### Conclusion After evaluating the options based on the project’s requirements, **Django (Python)** is the most suitable choice. It offers the following advantages: - **Full-Stack Capabilities**: Django is a full-stack framework that integrates both backend and frontend development. - **Agile Development**: The framework is well-suited to rapid prototyping and iteration, which is essential for a startup environment. - **AI/ML Compatibility**: Python is the leading language in AI/ML, and Django’s compatibility with libraries like Jupyter notebooks ensures smooth integration for data analysis and processing. - **Community and Ecosystem**: Django’s strong community support and extensive library ecosystem provide numerous tools to accelerate development. While **Ruby on Rails** is also a strong contender for agile development, its limited AI/ML support makes it less ideal for this specific use case. **Phoenix (Elixir)** and **Loco (Rust)**, though excellent for scalability and performance, fall short in terms of AI/ML integration and full-stack development. Therefore, Django is the recommended framework for this project. ================================================ FILE: locales/en/examples/work-from-home/.locale-peer-id ================================================ 0a53cbdf9f479da77ad7e0a6128275a9 ================================================ FILE: locales/en/examples/work-from-home/index.md ================================================ # Decision record for work from home Title: Employees can work from home Decision Maker: Management Team Decision Date: July 1, 2021 ## Background Due to the ongoing COVID-19 pandemic, many employees have been working remotely from home. This arrangement has provided benefits such as increased flexibility, improved work-life balance and a decrease in the spread of the virus. Furthermore, numerous employees have expressed that they would like to continue working from home even after the pandemic has ended. ## Decision After weighing the pros and cons of allowing employees to work from home, the management team has decided to implement a permanent work from home policy for eligible employees. The policy applies to all full-time employees who can effectively perform their duties from home and have demonstrated success working remotely during the pandemic. Eligible employees can choose to work from home up to three days per week, while in-office work will be required for the remaining two days. To ensure effective communication and collaboration, regular check-ins with team members and managers will be required. Additionally, employees will be provided with the necessary equipment and resources to perform their duties effectively from home. The implementation of this policy will be reviewed and revisited regularly to ensure that it continues to benefit both the employees and the company. ## Reasoning The decision to continue allowing employees to work from home is based on several factors, including employee work-life balance, greater flexibility and freedom, improved productivity, and less exposure to the risk of infection. By implementing a flexible work model, the company can attract and retain top talent while also providing a positive company culture. ## Implications The implementation of the permanent work from home policy will have several implications, including the need for ongoing communication and coordination among team members, adjusting work processes and protocols to accommodate a remote workforce, and ensuring that all employees have access to the necessary equipment, tools and resources. ## Conclusion The decision to implement a permanent work from home policy is in line with the company's values of promoting a healthy work-life balance, supporting employee well-being and promoting a positive company culture. We believe that this decision will enable our organization to be more agile and better suited to adapt to changing business needs while improving employee satisfaction and productivity. ================================================ FILE: locales/en/templates/.locale-peer-id ================================================ 70f1f9b3530831bc891a6e9b9b0d27de ================================================ FILE: locales/en/templates/decision-record-template-by-arc42/LICENSE.md ================================================ # LICENSE Source: License: License: ================================================ FILE: locales/en/templates/decision-record-template-by-arc42/index.md ================================================ # Decision record template by arc42 ## 1. Introduction and Goals Short description of the requirements, driving forces, extract (or abstract) of requirements. Top three (max five) quality goals for the architecture which have highest priority for the major stakeholders. A table of important stakeholders with their expectation regarding architecture. ## 1.1 Requirements Overview ### Contents Short description of the functional requirements, driving forces, extract (or abstract) of requirements. Links to the (hopefully existing) requirements documents, with information where to find it. ### Motivation From the point of view of the end users a system is created or modified to improve support of a business activity and/or improve the quality. ### Form Short textual description, probably in tabular use-case format. If requirements documents exist this overview should refer to these documents. Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t. requirements documents. ## 1.2 Quality goals ### Content The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. We really mean quality goals for the architecture. Don’t confuse them with project goals. They are not necessarily identical. The ISO 25010 standard provides a nice overview of potential topics of interest. ### Motivation You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. Make sure to be very concrete about these qualities, avoid buzzwords. If you as an architect do not know how the quality of your work will be judged … ### Form A table with the most important quality goals and concrete scenarios, ordered by priorities. ## 1.3 Stakeholder ### Content Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that - should know the architecture - have to be convinced of the architecture - have to work with the architecture or with code - need the documentation of the architecture for their work - have to come up with decisions about the system or its development ### Motivation You should know all parties involved in development of the system or affected by the system. Otherwise, you may get nasty surprises later in the development process. These stakeholders determine the extent and the level of detail of your work and its results. ### Form Table with role names, person names, and their expectations with respect to the architecture and its documentation. ## 2. Constraints Anything that constrains teams in design and implementation decisions or decision about related processes. Can sometimes go beyond individual systems and are valid for whole organizations and companies. ### Content Any requirement that constrains software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies. ### Motivation Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though. ### Form Simple tables of constraints with explanations. If needed you can subdivide them into technical constraints, organizational and political constraints and conventions (e.g. programming or versioning guidelines, documentation or naming conventions) ## 3. Context and Scope Delimits your system from its (external) communication partners (neighboring systems and users). Specifies the external interfaces. Shown from a business/domain perspective (always) or a technical perspective (optional) ### Content System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces. If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware). ### Motivation The domain interfaces and technical interfaces to communication partners are among your system’s most critical aspects. Make sure that you completely understand them. ### Form - Various context diagrams - Lists of communication partners and their interfaces. ## 3.1 Business context ### Content Specification of all communication partners (users, IT-systems, …) with explanations of domain specific inputs and outputs or interfaces. Optionally you can add domain specific formats or communication protocols. ### Motivation All stakeholders should understand which data are exchanged with the environment of the system. ### Form All kinds of diagrams that show the system as a black box and specify the domain interfaces to communiations partners. Alternatively (or additionally) you can use a table. The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs. ## 3.2 Technical context ### Contents Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation with I/O uses which channel. ### Motivation Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces. ### Form E.g. UML deployment diagram describing channels to neighboring systems, together with a mapping table showing the relationships between channels and input/output. ## 4. Solution Strategy Summary of the fundamental decisions and solution strategies that shape the architecture. Can include technology, top-level decomposition, approaches to achieve top quality goals and relevant organizational decisions. ### Contents A short summary and explanation of the fundamental decisions and solution strategies, that shape the system’s architecture. These include - technology decisions - decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern - decisions on how to achieve key quality goals - relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties. ### Motivation These decisions form the cornerstones for your architecture. They are the basis for many other detailed decisions or implementation rules. ### Form Keep the explanation of these key decisions short. Motivate what you have decided and why you decided that way, based upon your problem statement, the quality goals and key constraints. Refer to details in the following sections (section 5 for structural details, section 8 for crosscutting concepts). You might use a list of solution-approaches or a table. ## 5. Building Block View Static decomposition of the system, abstractions of source-code, shown as hierarchy of white boxes (containing black boxes), up to the appropriate level of detail. ### Content The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, data structures, …) as well as their dependencies (relationships, associations, …) This view is mandatory for every architecture documentation. In analogy to a house this is the floor plan. ### Motivation Maintain an overview of your source code by making its structure understandable through abstraction. This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details. ### Form The building block view is a hierarchial collection of black boxes and white boxes (see figure below) and their descriptions. ## 5.1 Whitebox Overall System Here you describe the decomposition of the overall system using the following white box template. It contains - an overview diagram - a motivation for the decomposition - black box descriptions of the contained building blocks. For these we offer you alternatives: - use one table for a short and pragmatic overview of all contained building blocks and their interfaces - use a list of black box descriptions of the building blocks according to the black box template (see below). Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modelling tool). - (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box. Since there are so many ways to specify interfaces why do not provide a specific template for them. In the best case you will get away with examples or simple signatures. ## 5.2 Level 2 Here you can specify the inner structure of (some) building blocks from level 1 as white boxes. You have to decide which building blocks of your system are important enough to justify such a detailed description. Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks. Leave out normal, simple, boring or standardized parts of your system ### 5.2.1 White Box for building block 1 Specifies the internal structure of building block 1. Use the white box template (see above). ## 6. Runtime View Behavior of building blocks as scenarios, covering important use cases or features, interactions at critical external interfaces, operation and administration plus error and exception behavior. ### Content The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas: - important use cases or features: how do building blocks execute them? - interactions at critical external interfaces: how do building blocks cooperate with users and neighbouring systems? - operation and administration: launch, start-up, stop - error and exception scenarios Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevancy. It is not important to describe a large number of scenarios. You should rather document a representative selection. ### Motivation You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view). ### Form There are many notations for describing scenarios, e.g. - numbered list of steps (in natural language) - activity diagrams or flow charts - sequence diagrams - BPMN or EPCs (event process chains) - state machines - etc. ## 6.n Runtime Scenario n (1, 2, 3, etc.) Insert runtime diagram or textual description of the scenario. Insert description of the notable aspects of the interactions between the building block instances depicted in this diagram. ## 7. Deployment View Technical infrastructure with environments, computers, processors, topologies. Mapping of (software) building blocks to infrastructure elements. ### Content The deployment view describes: - the technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and - the mapping of (software) building blocks to that infrastructure elements. Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments. Especially document the deployment view when your software is executed as distributed system with more then one computer, processor, server or container or when you design and construct your own hardware processors and chips. From a software perspective it is sufficient to capture those elements of the infrastructure that are needed to show the deployment of your building blocks. Hardware architects can go beyond that and describe the infrastructure to any level of detail they need to capture. ### Motivation Software does not run without hardware. This underlying infrastructure can and will influence your system and/or some cross-cutting concepts. Therefore, you need to know the infrastructure. ### Form Maybe the highest level deployment diagram is already contained in section 3.2. as technical context with your own infrastructure as ONE black box. In this section you will zoom into this black box using additional deployment diagrams. - UML offers deployment diagrams to express that view. Use it, probably with nested diagrams, when your infrastructure is more complex. - When your (hardware) stakeholders prefer other kinds of diagrams rather than UML deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure. ## 7.1 Infrastructure Level 1 Describe (usually in a combination of diagrams, tables, and text): - the distribution of your system to multiple locations, environments, computers, processors, .. as well as the physical connections between them - important justification or motivation for this deployment structure - quality and/or performance features of the infrastructure - the mapping of software artifacts (building blocks) to elements of the infrastructure For multiple environments or alternative deployments please copy that section of arc42 for all relevant environments. ** ## 7.2 Infrastructure Level 2 Here you can include the internal structure of (some) infrastructure elements from infrastructure level 1. Please copy the structure from level 1 for each selected element. ## 8. Crosscutting Concepts Overall, principal regulations and solution approaches relevant in multiple parts (→ cross-cutting) of the system. Concepts are often related to multiple building blocks. Include different topics like domain models, architecture patterns and -styles, rules for using specific technology and implementation rules. ### Content This section describes crosscutting concepts (practices, patterns, regulations or solution ideas). Such concepts are often related to multiple building blocks. They may include many different topics. ### Motivation Concepts form the basis for conceptual integrity (consistency, homogeneity) of the architecture. Thus, they are an important contribution to achieve inner qualities of your system. This is the place in the template that we provided for a cohesive specification of such concepts. Many of these concepts relate to or influence several of your building blocks. ### Form The form can be varied: - concept papers with any kind of structure - example implementations, especially for technical concepts - cross-cutting model excerpts or scenarios using notations of the architecture views ### Structure of this section Pick only the most-needed topics for your system and assign each a level-2 heading in this section (e.g. 8.1, 8.2 etc). - DO NOT ATTEMPT to cover all of the topics of the aforementioned diagram. ### Background Some topics within systems often concern multiple building blocks, hardware elements or development processes. It might be easier to communicate or document such cross-cutting topics at a central location, instead of repeating them in the description of the concerned building blocks, hardware elements or development processes. Certain concepts might concern all elements of a system, others might only be relevant for a few. ## 9. Architectural Decisions Important, expensive, critical, large scale or risky architecture decisions including rationales. ### Content Important, expensive, large scale or risky architecture decisions including rationales. With “decisions” we mean selecting one alternative based on given criteria. Please use your judgement to decide whether an architectural decision should be documented here in this central section or whether you better document it locally (e.g. within the white box template of one building block). Avoid redundant texts. Refer to section 4, where you captured the most important decisions of your architecture already. ### Motivation Stakeholders of your system should be able to comprehend and retrace your decisions. ### Form - ADR (architecture decision record) for every important decision - list or table, ordered by importance and consequences or - more detailed in form of separate sections per decision ### Background (on ADRs) Smaller pieces of documentation are easier to read, create and maintain. When it comes to architecture decisions, development teams will often: - know about the decision, as it visible e.g. in source code, but - miss the motivation behind that decision (see Nygard 2011) Therefore you should document a few important decisions together with their motivation, reasoning ### Our proposal concerning decisions Keep a collection of architecturally significant decisions, those decisions that affect the structure, quality characteristics, important (especially external) dependencies and interfaces, or construction techniques (thanks to Michael Nygard for this proposal). ## 10. Quality Requirements Quality requirements as scenarios, with quality tree to provide high-level overview. The most important quality goals should have been described in section 1.2. (quality goals). ### Content This section contains all relevant quality requirements. The most important of these requirements have already been described in section 1.2. (quality goals), therefore they should only be referenced here. In this section 10 you should also capture quality requirements with lesser importance, which will not create high risks when they are not fully achieved (but might be nice-to-have). ### Motivation Since quality requirements will have a lot of influence on architectural decisions you should know what qualities are really important for your stakeholders, in a specific and measurable way. ### Further Information See the extensive Q42 quality model on https://quality.arc42.org. ## 10.1 Quality Requirements Overview ### Content An overview or summary of quality requirements. ### Motivation Often we encounter dozens (or even hundreds) of detailed quality requirements. In this overview section you should try to summarize, e.g. by describing categories or topics (as suggested by ISO 25010:2023 or Q42 If these summary descriptions are already precise, specific enough and measurable, you may skip section 10.2. ### Form Use a simple table in which each line contains a category or topic and a short description of the quality requirement. Alternatively, you may use a mindmap to structure these quality requirements. In literature, the idea of a quality attribute tree has also been described, which puts the generic term “quality” as the root and uses a tree-like refinement of the term “quality”. [Bass+21] introduced the term “Quality Attribute Utility Tree” for this purpose. ## 10.2 Quality Scenarios ### Content Quality scenarios make quality requirements concrete and allow to decide whether they are fulfilled (in the sense of acceptance criteria). Ensure that your scenarios are specific and measurable. Two kinds of scenarios are especially useful: - Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second. - Change scenarios describe the desired effect of a modification or extension of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change, and the effort or duration of the change is measured. ### Form Typical information for detailed scenarios include the following: In short form (favoured in the Q42 model): - Context/Background: What kind of system or component, what is the environment or situation? - Source/Stimulus: Who or what initiates or triggers a behaviour, reaction or action. - Metric/Acceptance Criteria: A response including a measure or metric The long form of scenarios (favoured by the SEI and [Bass+21]) is more detailed and includes the following information: - Scenario ID: A unique identifier for the scenario. - Scenario Name: A short, descriptive name for the scenario. - Source: The entity (user, system, or event) that initiates the scenario. - Stimulus: The triggering event or condition the system must address. - Environment: The operational context or condition under which the system experiences the stimulus. - Artifact: The building-blocks or other elements of the system affected by the stimulus. - Response: The outcome or behavior the system exhibits in reaction to the stimulus. - Response Measure: The criteria or metric by which the system’s response is evaluated. ### See also Since January 2023, arc42 provides a pragmatic quality model, that proposes to label quality requirements, with hashtags or labels like #flexible, #efficient, #usable, #operable, #testable, #secure, #safe, #reliable. ## 11. Risks and Technical Debt Known technical risks or technical debt. What potential problems exist within or around the system? What does the development team feel miserable about? ### Content A list of identified technical risks or technical debts, ordered by priority ### Motivation “Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.) This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning. ### Form List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts. ================================================ FILE: locales/en/templates/decision-record-template-by-edgex/.locale-peer-id ================================================ 01939db0c341e9092c344d904065da12 ================================================ FILE: locales/en/templates/decision-record-template-by-edgex/LICENSE.md ================================================ # LICENSE Source: https://docs.edgexfoundry.org/2.3/design/adr/template/ License: https://github.com/edgexfoundry/edgex-go/blob/main/LICENSE ================================================ FILE: locales/en/templates/decision-record-template-by-edgex/index.md ================================================ # Architecture Decision Record (ADR) template This is a template for EdgeX Foundry ADR. Source: https://docs.edgexfoundry.org/2.3/design/adr/template/ ### Submitters List ADR submitters. Format: - Name (Organization) ## Change Log List the changes to the document, incl. state, date, and PR URL. State is one of: pending, approved, amended, deprecated. Date is an ISO 8601 (YYYY-MM-DD) string. PR is the pull request that submitted the change, including information such as the diff, contributors, and reviewers. Format: - \[Status of ADR e.g. approved, amended, etc.\]\(URL of pull request\) YYYY-MM-DD ## Referenced Use Case(s) List all relevant use case / requirements documents. ADR requires at least one relevant, approved use case. Format: - \[Use Case Name\]\(URL\) Add explanations if the ADR is not addressing all the requirements of a use case. ## Context Describe: - how the design is architecturally significant - warranting an ADR (versus simple issue and PR to fix a problem) - the high level design approach (details described in the proposed design below) ## Proposed Design Details of the design (without getting into implementation where possible). Outline: - services/modules to be impacted (changed) - new services/modules to be added - model and DTO impact (changes/additions/removals) - API impact (changes/additions/removals) - general configuration impact (establishment of new sections, changes/additions/removals) - devops impact ## Considerations Document alternatives, concerns, ancillary or related issues, questions that arose in debate of the ADR. Indicate if/how they were resolved or mollified. ## Decision Document any agreed upon important implementation detail, caveats, future considerations, remaining or deferred design issues. Document any part of the requirements not satisfied by the proposed design. ## Other Related ADRs List any relevant ADRs - such as a design decision for a sub-component of a feature, a design deprecated as a result of this design, etc.. Format: - \[ADR Title\]\(URL\) - Relevance ## References List additional references. Format: - \[Title\]\(URL\) ================================================ FILE: locales/en/templates/decision-record-template-by-gareth-morgan/README.md ================================================ index.md ================================================ FILE: locales/en/templates/decision-record-template-by-gareth-morgan/index.md ================================================ # [000] Title *Allocate each ADR a number for easy reference and cataloging* \ *NOTE: All italicised text provides hints and should be removed for production* ## Status - DRAFT / ACTIVE / DEPRECATED by [000] / SUPERSEDES [000] ## Context *Briefly describe the problem(s) that this ADR intends to address, and why the problems exist.* ## Decided Approach *Detail the architecturally significant decision that has been / will be made and describe how it addresses the problems outlined in the Context section.* ## Consequences *What is the impact of this decision on the architecture characteristics and functional requirements of the system?* ## Governance *How will the outcomes of this decision be monitored?* \ *How will compliance with this decision be ensured?* ## Options Analysis *If applicable, include or link to any trade-off analysis which has been performed to arrive at the decision made in this document.* ### Key *Optional: Provide visual aids to stakeholders which can help to quickly spot the positive and the negative trade-offs - for example simple traffic-light highlights with positive or negative prefixes.* A green background indicates a good fit, worsening through amber, with red being the worst fit. \ \+ indicates a positive impacting comment \ \- indicates a negative impacting comment ### High-Level Overview *How well does each option fit the problem context at a glance?*
Summary Option 1 Option 2 Option 3
Ease of Implementation + Super easy - Tricky - Large implementation requiring expert knowledge
Timescales + Very quick - Fairly slow - Very slow
Strategic Value - No strategic value, purely tactical + Slightly improves the customer onboarding experience + Ideal for the upcoming merger
### Functional Requirements *How well does each potential option fit the desired functional requirements?*
Scenario Option 1 Option 2 Option 3
Scenario 1
Scenario 2
Scenario 3
*Optional: Add rows / another table to cover known future scenarios.* ### Non-Functional Requirements *How well does each potential option fit the desired architecture characteristics? Note: ‘Architecture Characteristics’ would be a more appropriate title, but tailor this to familiar language for your business domain.*
Architecture
Characteristic		 Option 1 Option 2 Option 3
Scalability
Performance
Availability
*Optional: Add in or link to definitions of the architecture characteristics as they pertain to your business / product.* ================================================ FILE: locales/en/templates/decision-record-template-by-gig-cymru-nhs-wales/index.md ================================================ # {Your Title Here} !!! info **Status**: { Proposed | Under Review | Accepted | Rejected | Superseded | Deprecated } **Updated**: {YYYY-MM-DD} ## Summary {This is the 'executive summary' or 'elevator pitch' for your ADR. In a few concise sentences (typically 2-4), clearly state the core problem, question, or opportunity this ADR addresses. Include a brief hint at the decision made or the area of focus. The goal is to help readers quickly understand what this ADR is about and decide if it's relevant to them, without needing to read the entire document. Think of it as the abstract of a technical paper or a very brief introduction to the main topic.} ## Drivers {This section explains **why** this decision is being made **now**. Clearly articulate the primary motivations, needs, or problems that necessitate this architectural decision. Think about the underlying reasons and pressures.} * {e.g. We are developing a new feature/capability that needs...} * {e.g. We need to improve performance, accessibility, remove debt...} * {e.g. Feedback from users suggests...} * {e.g. The current approach imposes these limitations...} ## Options {This is where you list the different options you are considering. Stick to the facts and avoid opinions, the next section covers the analysis. Include a concise description, links to relevant documentation or examples. Include all significant alternatives you explored, even if they were ultimately not chosen. The goal is to give readers a clear, unbiased understanding of each alternative before you dive into the evaluation.} ### {Option 1 Title} {Describe the option, provide a summary, list the facts, provide links etc.} ### {Option n Title} ... ## Options Analysis {This is where you critically evaluate each option presented in the *Options* section. For each option, provide a balanced view of its advantages, disadvantages, and any other relevant considerations or trade-offs. Be specific and, where possible, relate your points back to the *Drivers*. Consider aspects like: * Cost (development, operational, licensing) * Complexity (implementation, maintenance, learning curve) * Risks (technical, operational, security) * Alignment with architectural principles or existing standards * Impact on performance, scalability, usability, maintainability, security, etc. Include as may Pro/Con/Other statements as required. } ### {Option 1 Assessment} * Pro: {A specific advantage or benefit of this option.} * Con: {A specific disadvantage, risk, or cost associated with this option.} * Other: {A relevant point that isn't strictly a pro or con.} ### {Option n Assessment} ... ## Recommendation {This is where you clearly state the final decision, and explicitly name the option that has been selected. Explain in detail **why** this option was chosen. You should clearly articulate how the chosen option best addresses the *Drivers* and meets the key requirements or solves the stated problem.} ### Consequences {This section is **optional**.} {Now that a decision has been made what are the expected outcomes and impacts, both positive and negative? What known limitations, costs, or risks are being accepted by making this decision? How will this decision affect different stakeholders, other systems, development practices, operational procedures, or user experience?} * Pro: {A specific positive outcome or benefit expected from this decision.} * Con: {A specific accepted downside, cost, or risk resulting from this decision. } * Other: {A consequence that isn't strictly a pro or con.} ### Confirmation {This section is **optional**.} {Outline how the implementation of this decision will be verified and how ongoing compliance will be ensured. This helps demonstrate that the decision isn't just theoretical but will be actively put into practice and monitored. How will you check that the decision has been correctly implemented? (e.g., code reviews, specific tests, demonstrations, peer review). How will adherence to this decision be maintained over time? (e.g., automated checks, periodic audits, updates to team guidelines, training). Are there specific metrics or indicators that will show the decision is achieving its intended positive outcomes? (e.g., performance benchmarks, adoption rates, reduction in specific errors, user feedback scores). Who is responsible for overseeing this, and what happens if the decision is not followed?} ## More Information {This section is **optional**.} {Use this section to provide any supplementary information that supports the decision, adds context, or guides future actions. Links to other decisions and resources might appear here as well. You could briefly note who was involved in the decision-making process and if/how consensus was reached. You may also want to suggest a timeframe or specific events that might prompt a re-evaluation of this decision in the future.} ================================================ FILE: locales/en/templates/decision-record-template-by-jeff-tyree-and-art-akerman/.locale-peer-id ================================================ f4ca0a94124a91279e1929ea23ab864d ================================================ FILE: locales/en/templates/decision-record-template-by-jeff-tyree-and-art-akerman/LICENSE-WIP.md ================================================ # LICENSE WIP ```email From:Joel Parker Henderson To:Help@computer.org Subject:License question for Architecture Decision Records Date:Monday, September 08, 2025 06:39 Hello, I'm seeking your copyright/permission person or team please. I'm an individual who maintains an education resource that includes one of your magazine articles, I'm seeking your guidance please on how to ask for permission to use the information and how to credit it the way your authors wish. The education resource is a summary introduction called "Architecture Decision Record" and it gathers a dozen or so architecture decision record templates into one place. The intended audience is software developers such as myself. There's no profit of any kind. The purpose is to help discussions among software developer peers. The project URL is: https://github.com/joelparkerhenderson/architecture-decision-record/ The item by your authors is: https://github.com/joelparkerhenderson/architecture-decision-record/tree/main/locales/en/templates/decision-record-template-by-jeff-tyree-and-art-akerman What are options for next steps please? Best, Joel -- (CONTACT INFO) ``` ================================================ FILE: locales/en/templates/decision-record-template-by-jeff-tyree-and-art-akerman/index.md ================================================ # Decision record template by Jeff Tyree and Art Akerman This is the architecture decision description template published in ["Architecture Decisions: Demystifying Architecture" by Jeff Tyree and Art Akerman, Capital One Financial](https://www.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf). * **Issue**: Describe the architectural design issue you’re addressing, leaving no questions about why you’re addressing this issue now. Following a minimalist approach, address and document only the issues that need addressing at various points in the life cycle. * **Decision**: Clearly state the architecture’s direction—that is, the position you’ve selected. * **Status**: The decision’s status, such as pending, decided, or approved. * **Group**: You can use a simple grouping—such as integration, presentation, data, and so on—to help organize the set of decisions. You could also use a more sophisticated architecture ontology, such as John Kyaruzi and Jan van Katwijk’s, which includes more abstract categories such as event, calendar, and location. For example, using this ontology, you’d group decisions that deal with occurrences where the system requires information under event. * **Assumptions**: Clearly describe the underlying assumptions in the environment in which you’re making the decision—cost, schedule, technology, and so on. Note that environmental constraints (such as accepted technology standards, enterprise architecture, commonly employed patterns, and so on) might limit the alternatives you consider. * **Constraints**: Capture any additional constraints to the environment that the chosen alternative (the decision) might pose. * **Positions**: List the positions (viable options or alternatives) you considered. These often require long explanations, sometimes even models and diagrams. This isn’t an exhaustive list. However, you don’t want to hear the question "Did you think about...?" during a final review; this leads to loss of credibility and questioning of other architectural decisions. This section also helps ensure that you heard others’ opinions; explicitly stating other opinions helps enroll their advocates in your decision. * **Argument**: Outline why you selected a position, including items such as implementation cost, total ownership cost, time to market, and required development resources’ availability. This is probably as important as the decision itself. * **Implications**: A decision comes with many implications, as the REMAP metamodel denotes. For example, a decision might introduce a need to make other decisions, create new requirements, or modify existing requirements; pose additional constraints to the environment; require renegotiating scope or schedule with customers; or require additional staff training. Clearly understanding and stating your decision’s implications can be very effective in gaining buy-in and creating a roadmap for architecture execution. * **Related decisions**: It’s obvious that many decisions are related; you can list them here. However, we’ve found that in practice, a traceability matrix, decision trees, or metamodels are more useful. Metamodels are useful for showing complex relationships diagrammatically (such as Rose models). * **Related requirements**: Decisions should be business driven. To show accountability, explicitly map your decisions to the objectives or requirements. You can enumerate these related requirements here, but we’ve found it more convenient to reference a traceability matrix. You can assess each architecture decision’s contribution to meeting each requirement, and then assess how well the requirement is met across all decisions. If a decision doesn’t contribute to meeting a requirement, don’t make that decision. * **Related artifacts**: List the related architecture, design, or scope documents that this decision impacts. * **Related principles**: If the enterprise has an agreed-upon set of principles, make sure the decision is consistent with one or more of them. This helps ensure alignment along domains or systems. * **Notes**: Because the decision-making process can take weeks, we’ve found it useful to capture notes and issues that the team discusses during the socialization process. ================================================ FILE: locales/en/templates/decision-record-template-by-michael-nygard/.locale-peer-id ================================================ b1e90e6556c1c8f1e2eb3ac22c8c5077 ================================================ FILE: locales/en/templates/decision-record-template-by-michael-nygard/LICENSE.md ================================================ # LICENSE This content comes from this URL: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions The content site says this: [CC0](https://creativecommons.org/publicdomain/zero/1.0/). To the extent possible under law, Cognitect, a Nu Holdings, Ltd. company. has waived all copyright and related or neighboring rights to "Documenting Architecture Decisions". This work is published from: United States. ================================================ FILE: locales/en/templates/decision-record-template-by-michael-nygard/index.md ================================================ # Decision record template by Michael Nygard This is the template in [Documenting architecture decisions - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). You can use [adr-tools](https://github.com/npryce/adr-tools) for managing the ADR files. In each ADR file, write these sections: # Title ## Status What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.? ## Context What is the issue that we're seeing that is motivating this decision or change? ## Decision What is the change that we're proposing and/or doing? ## Consequences What becomes easier or more difficult to do because of this change? ================================================ FILE: locales/en/templates/decision-record-template-for-alexandrian-pattern/.locale-peer-id ================================================ f33e4eb0409f956de201b791749dc9aa ================================================ FILE: locales/en/templates/decision-record-template-for-alexandrian-pattern/index.md ================================================ # Decision record template for Alexandrian pattern ## Introduction * Prologue (Summary) * Discussion (Context) * Solution (Decision) * Consequences (Results) ## Specifics ## * Prologue (Summary) * Statement to summarize: * In the context of (use case)
facing (concern)
we decided for (option)
to achieve (quality)
accepting (downside). * Discussion (Context) * Explains the forces at play (technical, political, social, project). * This is the story explaining the problem we are looking to resolve. * Solution * Explains how the decision will solve the problem. * Consequences * Explains the results of the decision over the long term. * Did it work, not work, was changed, upgraded, etc. ================================================ FILE: locales/en/templates/decision-record-template-for-business-case/.locale-peer-id ================================================ f6d1fb662640a00f4c66c586233dead9 ================================================ FILE: locales/en/templates/decision-record-template-for-business-case/index.md ================================================ # Decision record template for business case This ADR template emphasizes creating a business case for a decision, including criteria, candidates, and costs. ## Top-level * Title * Status * Evaluation criteria * Candidates to consider * Research and analysis of each candidate * Does/doesn't meet criteria and why * Cost analysis * SWOT analysis * Opinions and feedback * Recommendation ## Low-level deep dive **Title**: * A short present tense imperative phrase, less than 50 characters, like a git commit message. **Status**: * One of proposed, accepted, rejected, deprecated, superseded, etc. **Evaluation criteria**: * Summary: explain briefly what we seek to discover and why. * Specifics **Candidates to consider**: * Summary: explain briefly how we discovered candidates, and draw attention to any outliers. * List all candidates and related options; what are we evaluating as potential solutions? * Specifics **Research and analysis of each candidate**: * Summary: explain briefly the research methods, and draw attention to patterns, clusters, and outliers. * Does/doesn't meet criteria and why * Summary * Specifics * Cost analysis * Summary * Examples * Licensing, such as contract agreements and legal commitments * Training, such as upskilling and change management * Operating, such as support and maintenance * Metering, such as bandwidth and CPU usage * SWOT analysis * Summary * Strengths * Weaknesses * Opportunities * Threats * Internal opinions and feedback * Summary * Examples * By the team, ideally written by the actual person * From other stakeholders * Quality attributes a.k.a. cross-functional requirements * External opinions and feedback * Summary * Who is providing the opinion? * What are other candidates you considered? * What are you creating? * Examples * B2B or B2C * external-facing or employee-only * desktop or mobile * pilot or production * monolith or microservices * How did you evaluate the candidates? * Why did you choose the winner? * What is happening since then? * Examples * How is the winner performing? * What % of real-world production user traffic is flowing through the winner? * What kinds of integrations are involved, such as with continuous delivery pipelines, content management systems, analytics and metrics, etc.? * Knowing what you know now, what would you advise people to do differently? * Anecdotes **Recommendation**: * Summary * Specifics ================================================ FILE: locales/en/templates/decision-record-template-of-the-madr-project/.locale-peer-id ================================================ 0a9f88e5cda952db0a82d071f585d090 ================================================ FILE: locales/en/templates/decision-record-template-of-the-madr-project/LICENSE.md ================================================ # LICENSE Source: https://github.com/adr/madr/ License: https://github.com/adr/madr/blob/develop/LICENSE Code: MIT OR CC0-1.0 ================================================ FILE: locales/en/templates/decision-record-template-of-the-madr-project/index.md ================================================ # [short title of solved problem and solution] * Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] * Deciders: [list everyone involved in the decision] * Date: [YYYY-MM-DD when the decision was last updated] Technical Story: [description | ticket/issue URL] ## Context and Problem Statement [Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.] ## Decision Drivers * [driver 1, e.g., a force, facing concern, …] * [driver 2, e.g., a force, facing concern, …] * … ## Considered Options * [option 1] * [option 2] * [option 3] * … ## Decision Outcome Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)]. ### Positive Consequences * [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …] * … ### Negative Consequences * [e.g., compromising quality attribute, follow-up decisions required, …] * … ## Pros and Cons of the Options ### [option 1] [example | description | pointer to more information | …] * Good, because [argument a] * Good, because [argument b] * Bad, because [argument c] * … ### [option 2] [example | description | pointer to more information | …] * Good, because [argument a] * Good, because [argument b] * Bad, because [argument c] * … ### [option 3] [example | description | pointer to more information | …] * Good, because [argument a] * Good, because [argument b] * Bad, because [argument c] * … ## Links * [Link type] [Link to ADR] * … ================================================ FILE: locales/en/templates/decision-record-template-using-planguage/.locale-peer-id ================================================ bb37e19df57d398b0704d6bd30ee6e6d ================================================ FILE: locales/en/templates/decision-record-template-using-planguage/index.md ================================================ # Decision record template using Planguage See https://www.iaria.org/conferences2012/filesICCGI12/Tutorial%20Specifying%20Effective%20Non-func.pdf ## What is Planguage? Planguage is a planning language that uses these keywords: * Tag: A unique, persistent identifier * Gist: A brief summary of the requirement or area addressed * Requirement: The text that details the requirement itself * Rationale: The reasoning that justifies the requirement * Priority: A statement of priority and claim on resources * Stakeholders: Parties materially affected by the requirement * Status: The status of the requirement (draft, reviewed, committed, etc.) * Owner: The person responsible for implementing the requirement * Author: The person that wrote the requirement * Revision: A version number for the statement * Date: The date of the most recent revision * Assumptions: Anything that could cause problems if untrue now or later * Risks: Anything that could cause malfunction, delay, or other negative impacts * Defined: The definition of a term (better to use a glossary) ================================================ FILE: locales/en/templates/index.md ================================================ # Decision record templates * [Decision record template by Jeff Tyree and Art Akerman](decision-record-template-by-jeff-tyree-and-art-akerman) * [Decision record template by Michael Nygard](decision-record-template-by-michael-nygard) * [Decision record template by EdgeX](decision-record-template-by-edgex) * [Decision record template by arc42](locales/en/templates/decision-record-template-by-arc42/) * [Decision record template for Alexandrian pattern](decision-record-template-for-alexandrian-pattern) * [Decision record template for business case](decision-record-template-for-business-case) * [Decision record template of the MADR Project](decision-record-template-of-the-madr-project) * [Decision record template using Planguage](decision-record-template-using-planguage) * [Decision record template by Gareth Morgan](decision-record-template-by-gareth-morgan) * [Decision record template by GIG Cymru NHS Wales](locales/en/templates/decision-record-template-by-gig-cymru-nhs-wales/) ================================================ FILE: locales/es/.locale-peer-id ================================================ 0b59cb46e5817b414866ebe33f4d7bcf ================================================ FILE: locales/es/documentos/.locale-peer-id ================================================ abc7c72d426bc75e40b25a44ae37ce73 ================================================ FILE: locales/es/documentos/consejo-de-trabajo-en-equipo-para-adrs/.locale-peer-id ================================================ 875a7715e592ceb45eac5e155ee16318 ================================================ FILE: locales/es/documentos/consejo-de-trabajo-en-equipo-para-adrs/index.md ================================================ # Consejo de trabajo en equipo para ADRS Si está considerando usar registros de decisión con su equipo, aquí hay algunos consejos que hemos aprendido trabajando con muchos equipos. Tienes la oportunidad de liderar a tus compañeros de equipo, hablando juntos sobre el "por qué", en lugar de ordenar el "qué". Por ejemplo, los registros de decisión son una forma para que los equipos piensen más inteligente y se comuniquen mejor; Los registros de decisión no son valiosos si son solo un requisito de papeleo forzado después del hecho. Algunos equipos prefieren el nombre de "decisiones" sobre la abreviatura "ADR". Cuando algunos equipos usan las "decisiones" del nombre del directorio, entonces es como si se encienda una bombilla, y el equipo comienza a poner más información en el directorio, como decisiones de proveedores, decisiones de planificación, decisiones de programación, etc. La información puede usar la misma plantilla. Presumimos que las personas aprenden más rápido con las palabras ("decisiones") sobre las abreviaturas ("ADR"), y las personas están más motivadas para escribir documentos de trabajo en progreso cuando se elimina la palabra "registro", y también algunos desarrolladores y algunos gerentes No me gusta la palabra "arquitectura". En teoría, la inmutabilidad es ideal. En la práctica, la mutabilidad ha funcionado mejor para nuestros equipos. Insertamos la nueva información del ADR existente, con un sello de fecha, y una nota que la información llegó después de la decisión. Este tipo de enfoque lleva a un "documento vivo" que todos podemos actualizar. Las actualizaciones típicas son cuando obtenemos información gracias a nuevos compañeros de equipo, nuevas ofertas, o resultados del mundo real de nuestros usos, o cambios de terceros después de los hechos, como capacidades de proveedores, planes de precios, acuerdos de licencia, etc. ================================================ FILE: locales/es/documentos/convenciones-de-nombre-de-archivo/.locale-peer-id ================================================ 89116b5647aa1e53186f3c44b5a284a0 ================================================ FILE: locales/es/documentos/convenciones-de-nombre-de-archivo/index.md ================================================ # Convenciones de nombre de archivo Si elige crear sus ADR usando archivos de texto típicos, es posible que desee crear su propia convención de nombre de archivo ADR. Preferimos usar una convención de nombre de archivo que tenga un formato específico. Ejemplos: * elija-database.md * format-timestamps.md * administrar-passwords.md * mango-excepciones.md Nuestra convención de nombre de archivo: * El nombre tiene una frase verbal imperativa de tiempo presente. Esto ayuda a la legibilidad y coincide con nuestro formato de mensaje de confirmación. * El nombre usa minúsculas y guiones (igual que este repositorio). Este es un equilibrio de legibilidad y usabilidad del sistema. * La extensión es Markdown. Esto puede ser útil para un fácil formato. ================================================ FILE: locales/es/documentos/criterios-de-sostenibilidad-de-decisión/.locale-peer-id ================================================ 71d59ed566ae148b8bf42331a84754ac ================================================ FILE: locales/es/documentos/criterios-de-sostenibilidad-de-decisión/index.md ================================================ # Criterios de sostenibilidad de decisión Para definir la sostenibilidad de la decisión en detalle, derivamos cinco criterios clave. ## estratégico Durante la toma de decisiones, alguien que analice las consecuencias estratégicas debe considerar cosas como el impacto a largo plazo de las decisiones, por ejemplo, operaciones futuras y esfuerzos de mantenimiento. ## Medible y manejable Puede medir y evaluar el resultado de una decisión a lo largo del tiempo de acuerdo con los criterios objetivos, idealmente numéricos (como, por ejemplo, propagados por escenarios de atributos de calidad y talleres4). La captura de todas las decisiones de grano fino no es posible, por lo que los arquitectos deben limitar la granularidad de las decisiones a un cierto nivel de detalle (como crear una clase de diseño). Esto conducirá a un conjunto de decisiones más sostenible y menos enlaces de trazabilidad. Además, limitar el número de dependencias entre las decisiones reduce el efecto de dominio de los cambios. ## alcanzable y realista La justificación para ajustar la solución al problema debe elegirse pragmáticamente y hacerse explícito. Por ejemplo, los arquitectos pueden indicar que han tenido cuidado de evitar la sobrenadería o subenvenimiento (es decir, deben aplicar el enfoque "lo suficientemente bueno"). ## arraigado en requisitos La toma de decisiones debe basarse en la experiencia y el contexto de arquitectura específica del dominio. Debe tener en cuenta el entorno de la empresa, así como los requisitos y limitaciones del proyecto, incluidas las habilidades actuales, el presupuesto de capacitación y el proceso del equipo de desarrollo. ## atemporal Las decisiones deben basarse en la experiencia y el conocimiento que probablemente no estarán anticuados pronto. Por ejemplo, los arquitectos pueden elegir patrones de arquitectura neutrales de plataforma o tácticas. ================================================ FILE: locales/es/documentos/cómo-comenzar-a-usar-adr-con-git/.locale-peer-id ================================================ d6fb3c7d91f95003163e694e74058e9d ================================================ FILE: locales/es/documentos/cómo-comenzar-a-usar-adr-con-git/index.md ================================================ # Cómo comenzar a usar ADR con Git Si le gusta usar el control de versiones Git, entonces así es cómo nos gusta comenzar a usar ADR con Git para un proyecto de software típico con el código fuente. Cree un directorio para archivos ADR: `` `SH $ mkdir adr `` `` `` Para cada ADR, cree un archivo de texto, como `database.txt`: `` `SH $ vi database.txt `` `` `` Escribe lo que quieras en el ADR. Vea las plantillas en este repositorio de ideas. Comprometa el ADR a tu repositorio git. ================================================ FILE: locales/es/documentos/cómo-comenzar-a-usar-adr-con-herramientas/.locale-peer-id ================================================ 1a5a03dd6f20cea9f78fb4655a9a7f87 ================================================ FILE: locales/es/documentos/cómo-comenzar-a-usar-adr-con-herramientas/index.md ================================================ ## Cómo comenzar a usar ADR con herramientas Puede comenzar a usar ADR con herramientas de la manera que desee. Por ejemplo: * Si le gusta usar Google Drive y la edición en línea, puede crear un Doc Google o Google Sohad. * Si desea usar el control de versiones del código fuente, como GIT, puede crear un archivo para cada ADR. * Si le gusta usar herramientas de planificación de proyectos, como Atlassian JIRA, puede usar el rastreador de planificación de la herramienta. * Si te gusta usar wikis, como MediaWiki, entonces puedes crear un wiki ADR. * ================================================ FILE: locales/es/documentos/cómo-comenzar-a-usar-adrs/.locale-peer-id ================================================ 8196518140224596af99a46d512feba3 ================================================ FILE: locales/es/documentos/cómo-comenzar-a-usar-adrs/index.md ================================================ # Cómo comenzar a usar ADRS Para comenzar a usar ADR, hable con sus compañeros de equipo sobre estas áreas. Identificación de decisión: * ¿Qué tan urgente y qué tan importante es el anuncio? * ¿Tiene que hacerse ahora, o puede esperar hasta que se conozca más? * Tanto la experiencia personal como la colectiva, así como los métodos y prácticas de diseño reconocidos, pueden ayudar con la identificación de decisiones. * Idealmente, mantenga una lista de decisión que complementa la lista de TODO del producto. Toma de decisiones: * Existen una serie de técnicas de toma de decisiones, tanto generales como la arquitectura de software específicas, por ejemplo, el mapeo de diálogo. * La toma de decisiones grupales es un tema de investigación activo. Promulgación de decisiones y aplicación: * Los anuncios se utilizan en el diseño de software; Por lo tanto, deben ser comunicados y aceptados por los interesados del sistema que financian, desarrollan y operan. * Los estilos de codificación y las revisiones de código arquitectónicamente evidentes que se centran en las preocupaciones y decisiones arquitectónicas son dos prácticas relacionadas. * Los anuncios también deben ser (re) considerados al modernizar un sistema de software en la evolución del software. Compartir decisiones (opcional): * Muchos anuncios se repiten en todos los proyectos. * Por lo tanto, las experiencias con decisiones pasadas, tanto buenas como malas, pueden ser activos reutilizables valiosos al emplear una estrategia explícita de gestión del conocimiento. Documentación de decisión: * Existen muchas plantillas y herramientas para la captura de decisiones. * Ver comunidades ágiles, p. M. Nygard's ADRS. * Consulte los procesos tradicionales de diseño de ingeniería de software y arquitectura, p. Diseños de mesa sugeridos por IBM UMF y por Tyree y Akerman de CapitalOne. Para más: * Los pasos anteriores se adoptan de la entrada de Wikipedia en [Decisión arquitectónica] (https://en.wikipedia.org/wiki/architectural_decision) ================================================ FILE: locales/es/documentos/directrices-para-lograr-decisiones-sostenibles/.locale-peer-id ================================================ 934d1c42a693fe004cd8bf8f5ecb97e6 ================================================ FILE: locales/es/documentos/directrices-para-lograr-decisiones-sostenibles/index.md ================================================ # Directrices para lograr decisiones sostenibles Aprendimos las siguientes lecciones en nuestro trabajo que pueden servir como directrices y evaluación para lograr decisiones sostenibles: 1. Use un enfoque Lean/Minimalista para la documentación de decisión inicial. 2. Priorice y capture todas las decisiones importantes que sean lo suficientemente relevantes como para documentar y comprender la arquitectura objetivo. 3. Detalle las decisiones particularmente importantes con plantillas en toda regla solo después de que se haya realizado el trabajo inicial (es decir, cuando los tomadores de decisiones se contentan con las decisiones arquitectónicas tomadas y confían en que estas decisiones no tienen que revisarse pronto ). 4. Use las versiones Lean/Minimalista del Paso 1 como una versión corta de las decisiones documentadas con el nivel de granularidad correcto para proporcionar una visión general de las decisiones detalladas, así como para decisiones triviales o obvias. 5. Siempre que sea posible, use el conocimiento arquitectónico existente, ya sea a partir de modelos de orientación o de otras fuentes. Revise y extienda dicho conocimiento y lo ajuste al contexto de la decisión específica. 6. Asegúrese de que se establezcan enlaces de trazabilidad entre las decisiones y los requisitos y los diseños/código arquitectónico. 7. Proporcione una verificación de consistencia automatizada para asegurarse de que los enlaces de trazabilidad estén sincronizados después de un cambio. Limite el número de dependencias entre decisiones y otros artefactos de software. 8 Aplicar las pautas para las justificaciones consecuentemente y con fuerza: son la parte más importante de la documentación de decisión porque dan la justificación. ================================================ FILE: locales/es/documentos/proceso-de-registros-de-decisiones-arquitectónicas-de-aws/.locale-peer-id ================================================ 7d4adf16004ca42546dee49922ae4ccf ================================================ FILE: locales/es/documentos/proceso-de-registros-de-decisiones-arquitectónicas-de-aws/index.md ================================================ # Proceso de registros de decisiones arquitectónicas de AWS https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html Un registro de decisión arquitectónica (ADR) es un documento que describe una elección que el equipo hace sobre un aspecto significativo de la arquitectura de software que planean construir. Cada ADR describe la decisión arquitectónica, su contexto y sus consecuencias. Los ADR tienen estados y, por lo tanto, siguen un ciclo de vida. Para un ejemplo de un ADR, consulte el apéndice. El proceso ADR genera una colección de registros de decisión arquitectónica. Esta colección crea el registro de decisiones. El registro de decisiones proporciona el contexto del proyecto, así como información detallada de implementación y diseño. Los miembros del proyecto escabullen los titulares de cada ADR para obtener una visión general del contexto del proyecto. Leen los ADR para sumergirse profundamente en las implementaciones del proyecto y las opciones de diseño. Cuando el equipo acepta un ADR, se vuelve inmutable. Si las nuevas ideas requieren una decisión diferente, el equipo propone un nuevo ADR. Cuando el equipo acepta el nuevo ADR, reemplaza al ADR anterior. ## alcance del proceso ADR Los miembros del proyecto deben crear un ADR para cada decisión arquitectónicamente significativa que afecte el proyecto o producto de software, incluido el siguiente (Richards y Ford 2020): * Estructura (por ejemplo, patrones como microservicios) * Requisitos no funcionales (seguridad, alta disponibilidad y tolerancia a fallas) * Dependencias (acoplamiento de componentes) * Interfaces (API y contratos publicados) * Técnicas de construcción (bibliotecas, marcos, herramientas y procesos) * Los requisitos funcionales y no funcionales son las entradas más comunes para el proceso ADR. ## Contenido ADR Cuando el equipo identifica la necesidad de un ADR, un miembro del equipo comienza a escribir el ADR basado en una plantilla en todo el proyecto. (Consulte la organización ADR Github, por ejemplo, plantillas.) La plantilla simplifica la creación de ADR y asegura que el ADR capture toda la información relevante. Como mínimo, cada ADR debe definir el contexto de la decisión, la decisión en sí y las consecuencias de la decisión para el proyecto y sus entregables. (Para ejemplos de estas secciones, consulte el Apéndice). Uno de los aspectos más poderosos de la estructura ADR es que se centra en la razón de la decisión en lugar de cómo la implementó el equipo. Comprender por qué el equipo tomó la decisión facilita que otros miembros del equipo adopten la decisión y evite que otros arquitectos que no estuvieran involucrados en el proceso de toma de decisiones anulen esa decisión en el futuro. ## Proceso de adopción de ADR Cada miembro del equipo puede crear un ADR, pero el equipo debe establecer una definición de propiedad para un ADR. Cada autor que es el propietario de un ADR debe mantener y comunicar activamente el contenido de ADR. Para aclarar esta propiedad, esta guía se refiere a los autores de ADR como propietarios de ADR en las siguientes secciones. Otros miembros del equipo siempre pueden contribuir a un ADR. Si el contenido de un ADR cambia antes de que el equipo acepte el ADR, el propietario debe aprobar estos cambios. Después de que el equipo identifica una decisión arquitectónica y su propietario, el propietario de la ADR proporciona el ADR en el estado ** propuesto ** al comienzo del proceso. Los ADR en el estado propuesto están listos para su revisión. El propietario de ADR luego inicia el proceso de revisión para el ADR. El objetivo del proceso de revisión de ADR es decidir si el equipo acepta el ADR, determina que necesita reelaborar o rechaza el ADR. El equipo del proyecto, incluido el propietario, revisa el ADR. La reunión de revisión debe comenzar con un horario dedicado para leer el ADR. En promedio, de 10 a 15 minutos deberían ser suficientes. Durante este tiempo, cada miembro del equipo lee el documento y agrega comentarios y preguntas para marcar temas poco claros. Después de la fase de revisión, el propietario de ADR lee y discute cada comentario con el equipo. Si el equipo encuentra puntos de acción para mejorar el ADR, el estado del ADR permanece ** propuesto **. El propietario de ADR formula las acciones y, en colaboración con el equipo, agrega un cesionario a cada acción. Cada miembro del equipo puede contribuir y resolver los puntos de acción. Es responsabilidad del propietario de ADR reprogramar el proceso de revisión. El equipo también puede decidir rechazar el ADR. En este caso, el propietario de ADR agrega una razón para el rechazo para evitar futuras discusiones sobre el mismo tema. El propietario cambia el estado ADR a ** rechazado **. Si el equipo aprueba el ADR, el propietario agrega una marca de tiempo, la versión y la lista de partes interesadas. El propietario luego actualiza el estado a ** aceptado **. Los ADR y el registro de decisiones que crean representan decisiones tomadas por el equipo y proporcionan un historial de todas las decisiones. El equipo usa el ADR como referencia durante el código y las revisiones arquitectónicas cuando sea posible. Además de realizar revisiones de código, tareas de diseño y tareas de implementación, los miembros del equipo deben consultar a los ADR para decisiones estratégicas para el producto. Como buena práctica, cada cambio de software debe pasar por revisiones por pares y requiere al menos una aprobación. Durante la revisión del código, un revisor de código puede encontrar cambios que violen uno o más ADR. En este caso, el revisor solicita al autor del cambio de código que actualice el código y comparte un enlace al ADR. Cuando el autor actualiza el código, es aprobado por los revisores de pares y se fusiona con la base del código principal. ## Proceso de revisión de ADR El equipo debe tratar a los ADR como documentos inmutables después de que el equipo los acepta o rechaza. Los cambios en un ADR existente requieren crear un nuevo ADR, establecer un proceso de revisión para el nuevo ADR y aprobar el ADR. Si el equipo aprueba el nuevo ADR, el propietario debe cambiar el estado del antiguo ADR a ** reemplazado **. ================================================ FILE: locales/es/documentos/qué-es-un-registro-de-decisión-de-arquitectura/.locale-peer-id ================================================ 020ff535ed1a3347a265209291e756b6 ================================================ FILE: locales/es/documentos/qué-es-un-registro-de-decisión-de-arquitectura/index.md ================================================ ## ¿Qué es un registro de decisión de arquitectura? Un registro de decisión de arquitectura ** ** (ADR) es un documento que captura una decisión arquitectónica importante tomada junto con su contexto y consecuencias. Una decisión de arquitectura ** ** (AD) es una opción de diseño de software que aborda un requisito significativo. Un registro de decisión de arquitectura ** (ADL) es la colección de todos los ADR creados y mantenidos para un proyecto (u organización) en particular. Un requisito de ** arquitectónicamente significativo ** (ASR) es un requisito que tiene un efecto medible en la arquitectura de un sistema de software. Todos estos están dentro del tema de ** Gestión del conocimiento de la arquitectura ** (AKM). El objetivo de este documento es proporcionar una descripción rápida de los ADR, cómo crearlos y dónde buscar más información. Abreviaturas: *** AD **: Decisión de arquitectura *** ADL **: Registro de decisiones de arquitectura *** ADR **: Registro de decisión de arquitectura *** AKM **: Gestión del conocimiento de la arquitectura *** asr **: requisito arquitectúramente significativo ================================================ FILE: locales/es/documentos/sugerencias-para-escribir-buenos-adr/.locale-peer-id ================================================ dc1a294e76821d6d3b086a2b17988427 ================================================ FILE: locales/es/documentos/sugerencias-para-escribir-buenos-adr/index.md ================================================ ## Sugerencias para escribir buenos ADR Características de un buen ADR: * Justificación: explique las razones para hacer el anuncio particular. Esto puede incluir el contexto (ver más abajo), pros y contras de varias opciones potenciales, comparaciones de características, discusiones de costos/beneficios y más. * Específico: cada ADR debe ser aproximadamente un anuncio, no múltiples anuncios. * Marcas de tiempo: identifique cuándo se escribe cada elemento en el ADR. Esto es especialmente importante para aspectos que pueden cambiar con el tiempo, como costos, horarios, escala y similares. * Inmutable: no altere la información existente en un ADR. En su lugar, modifique el ADR agregando nueva información o reemplazar el ADR creando un nuevo ADR. Características de una buena sección de "contexto" en un ADR: * Explique la situación y las prioridades comerciales de su organización. * Incluya justificación y consideraciones basadas en maquilladores sociales y de habilidades de sus equipos. * Incluya pros y contras que sean relevantes, y descrita en términos que se alineen con sus necesidades y objetivos. Características de las buenas "consecuencias" en un ADR: * Explique qué sigue al tomar la decisión. Esto puede incluir los efectos, los resultados, los resultados, los seguimientos y más. * Incluya información sobre cualquier ADR posterior. Es relativamente común que un ADR active la necesidad de más ADR, como cuando un ADR hace una gran opción general, lo que a su vez crea necesidades para decisiones más pequeñas. * Incluya cualquier proceso de revisión posterior a la acción. Es típico que los equipos revisen cada ADR un mes después, comparar la información de ADR con lo que sucedió en la práctica real, para aprender y crecer. Un nuevo ADR puede tomar el lugar de un ADR anterior: * Cuando se realiza un anuncio que reemplaza o invalida un ADR anterior, entonces se debe crear un nuevo ADR ================================================ FILE: locales/es/plantillas/.locale-peer-id ================================================ 70f1f9b3530831bc891a6e9b9b0d27de ================================================ FILE: locales/es/plantillas/index.md ================================================ # Plantilla de registro de decisiones * [Plantilla de registro de decisión de Jeff Tyree y Art Akerman](plantilla-de-registro-de-decisión-de-jeff-tyree-y-art-akerman/) * [Plantilla de registro de decisión de Michael Nygard](plantilla-de-registro-de-decisión-de-michael-nygard/) * [Plantilla de registro de decisión para el patrón alejandrino](plantilla-de-registro-de-decisión-para-el-patrón-alejandrino/) * [Plantilla de registro de decisión para caso de negocio](plantilla-de-registro-de-decisión-para-caso-de-negocio/) * [Plantilla de registro de decisión del proyecto MADR](plantilla-de-registro-de-decisión-del-proyecto-madr/) * [Plantilla de registro de decisión usando Planguage](plantilla-de-registro-de-decisión-usando-planguage/) ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-de-edgex/.locale-peer-id ================================================ 01939db0c341e9092c344d904065da12 ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-de-edgex/index.md ================================================ # Plantilla de registro de decisión de arquitectura (ADR) Esta es una plantilla para EdgeX Foundry ADR. Fuente: https://docs.edgexfoundry.org/2.3/design/adr/template/ ### Remitentes Enumere los remitentes de ADR. Formato: - Nombre (Organización) ## Registro de cambios Enumere los cambios en el documento, incl. estado, fecha y URL de PR. El estado es uno de: pendiente, aprobado, modificado, obsoleto. La fecha es una cadena ISO 8601 (AAAA-MM-DD). PR es la solicitud de extracción que envió el cambio, incluida información como la diferencia, los contribuyentes y los revisores. Formato: - \[Estado del ADR, p. aprobado, modificado, etc.\]\(URL de la solicitud de extracción\) AAAA-MM-DD ## Caso(s) de uso referenciados Enumere todos los documentos de requisitos/casos de uso relevantes. ADR requiere al menos un caso de uso relevante y aprobado. Formato: - \[Usar nombre de caso\]\(URL\) Agregue explicaciones si el ADR no aborda todos los requisitos de un caso de uso. ## Contexto Describir: - la importancia arquitectónica del diseño - la garantía de una ADR (en lugar de un simple problema y relaciones públicas para solucionar un problema) - el enfoque de diseño de alto nivel (los detalles se describen en el diseño propuesto a continuación) ## Diseño propuesto Detalles del diseño (sin entrar en implementación cuando sea posible). Describir: - servicios/módulos que se verán afectados (cambiados) - nuevos servicios/módulos que se agregarán - impacto del modelo y del DTO (cambios/adiciones/eliminaciones) - Impacto de API (cambios/adiciones/eliminaciones) - impacto de la configuración general (establecimiento de nuevas secciones, cambios/adiciones/eliminaciones) - impacto devops ## Consideraciones Documentar alternativas, inquietudes, cuestiones auxiliares o relacionadas, dudas que surgieron en el debate del ADR. Indique si y cómo se resolvieron o apaciguaron. ## Decisión Documente cualquier detalle importante de implementación acordado, advertencias, consideraciones futuras y cuestiones de diseño pendientes o diferidas. Documente cualquier parte de los requisitos que no cumpla el diseño propuesto. ## Otros ADR relacionados Enumere cualquier ADR relevante, como una decisión de diseño para un subcomponente de una característica, un diseño obsoleto como resultado de este diseño, etc. Formato: - \[Título ADR\]\(URL\) - Relevancia ## Referencias Enumere referencias adicionales. Formato: - \[Título\]\(URL\) ​Buscar detalles 2.205 / 5.000 Resultados de traducción Resultado de la traducción Algunas oraciones pueden contener alternativas específicas de género. Haga clic en una oración para ver alternativas. Aprende más # Plantilla de registro de decisión de arquitectura (ADR) Esta es una plantilla para EdgeX Foundry ADR. Fuente: https://docs.edgexfoundry.org/2.3/design/adr/template/ ### Remitentes Enumere los remitentes de ADR. Formato: - Nombre (Organización) ## Registro de cambios Enumere los cambios en el documento, incl. estado, fecha y URL de PR. El estado es uno de: pendiente, aprobado, modificado, obsoleto. La fecha es una cadena ISO 8601 (AAAA-MM-DD). PR es la solicitud de extracción que envió el cambio, incluida información como la diferencia, los contribuyentes y los revisores. Formato: - \[Estado del ADR, pág. aprobado, modificado, etc.\]\(URL de la solicitud de extracción\) AAAA-MM-DD ## Caso(s) de uso referenciados Enumere todos los documentos de requisitos/casos de uso relevantes. ADR requiere al menos un caso de uso relevante y aprobado. Formato: - \[Usar nombre de caso\]\(URL\) Agregue explicaciones si el ADR no aborda todos los requisitos de un caso de uso. ## Contexto Describir: - la importancia arquitectónica del diseño - la garantía de una ADR (en lugar de un simple problema y relaciones públicas para solucionar un problema) - el enfoque de diseño de alto nivel (los detalles se describen en el diseño propuesto a continuación) ## Diseño propuesto Detalles del diseño (sin entrar en implementación cuando sea posible). Describir: - servicios/módulos que se verán afectados (cambiados) - nuevos servicios/módulos que se agregarán - impacto del modelo y del DTO (cambios/adiciones/eliminaciones) - Impacto de API (cambios/adiciones/eliminaciones) - impacto de la configuración general (establecimiento de nuevas secciones, cambios/adiciones/eliminaciones) - impacto devops ## Consideraciones Documentar alternativas, inquietudes, cuestiones auxiliares o relacionadas, dudas que surgieron en el debate del ADR. Indique si y cómo se resolvieron o apaciguaron. ## Decisión Documente cualquier detalle importante de implementación acordada, advertencias, consideraciones futuras y cuestiones de diseño pendientes o diferidas. Documente cualquier parte de los requisitos que no cumplan el diseño propuesto. ## Otros ADR relacionados Enumere cualquier ADR relevante, como una decisión de diseño para un subcomponente de una característica, un diseño obsoleto como resultado de este diseño, etc. Formato: - \[Título ADR\]\(URL\) - Relevancia ## Referencias Enumere referencias adicionales. Formato: - \[Título\]\(URL\) ​Buscar detalles Enviar comentarios Paneles laterales Resultados de traducción disponibles ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-de-jeff-tyree-y-art-akerman/.locale-peer-id ================================================ f4ca0a94124a91279e1929ea23ab864d ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-de-jeff-tyree-y-art-akerman/index.md ================================================ # Plantilla de registro de decisiones de Jeff Tyree y Art Akerman Esta es la plantilla de descripción de decisiones arquitectónicas publicada en ["Architecture Decisions: Demystifying Architecture" por Jeff Tyree y Art Akerman, Capital One Financial](https://www.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions- neumático-05.pdf). * **Problema**: Describa el problema de diseño arquitectónico que está abordando, sin dejar preguntas sobre por qué está abordando este problema ahora. Siguiendo un enfoque minimalista, aborde y documente sólo los problemas que deban abordarse en distintos puntos del ciclo de vida. * **Decisión**: Indique claramente la dirección de la arquitectura, es decir, la posición que ha seleccionado. * **Estado**: el estado de la decisión, como pendiente, decidida o aprobada. * **Grupo**: puede utilizar una agrupación simple (como integración, presentación, datos, etc.) para ayudar a organizar el conjunto de decisiones. También se podría utilizar una ontología de arquitectura más sofisticada, como la de John Kyaruzi y Jan van Katwijk, que incluye categorías más abstractas como evento, calendario y ubicación. Por ejemplo, al utilizar esta ontología, agruparía decisiones que se ocupan de sucesos en los que el sistema requiere información bajo el evento. * **Supuestos**: describa claramente los supuestos subyacentes en el entorno en el que está tomando la decisión: costo, cronograma, tecnología, etc. Tenga en cuenta que las limitaciones ambientales (como estándares tecnológicos aceptados, arquitectura empresarial, patrones comúnmente empleados, etc.) pueden limitar las alternativas que considere. * **Restricciones**: Capture cualquier restricción adicional al entorno que la alternativa elegida (la decisión) pueda plantear. * **Posiciones**: Enumere las posiciones (opciones viables o alternativas) que consideró. Estos suelen requerir largas explicaciones, a veces incluso modelos y diagramas. Esta no es una lista exhaustiva. Sin embargo, no querrás escuchar la pregunta "¿Pensaste en...?" durante una revisión final; esto conduce a la pérdida de credibilidad y al cuestionamiento de otras decisiones arquitectónicas. Esta sección también ayuda a garantizar que haya escuchado las opiniones de los demás; Expresar explícitamente otras opiniones ayuda a involucrar a sus defensores en su decisión. * **Argumento**: describa por qué seleccionó un puesto, incluidos elementos como el costo de implementación, el costo total de propiedad, el tiempo de comercialización y la disponibilidad de los recursos de desarrollo necesarios. Probablemente esto sea tan importante como la decisión misma. * **Implicaciones**: Una decisión tiene muchas implicaciones, como lo indica el metamodelo REMAP. Por ejemplo, una decisión podría introducir la necesidad de tomar otras decisiones, crear nuevos requisitos o modificar requisitos existentes; plantear limitaciones adicionales al medio ambiente; requerir renegociar el alcance o el cronograma con los clientes; o requerir capacitación adicional del personal. Comprender y expresar claramente las implicaciones de su decisión puede ser muy eficaz para lograr aceptación y crear una hoja de ruta para la ejecución de la arquitectura. * **Decisiones relacionadas**: Es obvio que muchas decisiones están relacionadas; puedes enumerarlos aquí. Sin embargo, hemos descubierto que, en la práctica, una matriz de trazabilidad, árboles de decisión o metamodelos son más útiles. Los metamodelos son útiles para mostrar relaciones complejas en forma de diagramas (como los modelos Rose). * **Requisitos relacionados**: Las decisiones deben estar impulsadas por el negocio. Para mostrar responsabilidad, asigne explícitamente sus decisiones a los objetivos o requisitos. Puede enumerar estos requisitos relacionados aquí, pero nos ha resultado más conveniente hacer referencia a una matriz de trazabilidad. Puede evaluar la contribución de cada decisión de arquitectura para cumplir cada requisito y luego evaluar qué tan bien se cumple el requisito en todas las decisiones. Si una decisión no contribuye a cumplir un requisito, no tome esa decisión. * **Artefactos relacionados**: enumere los documentos de arquitectura, diseño o alcance relacionados a los que afecta esta decisión. * **Principios relacionados**: si la empresa tiene un conjunto de principios acordados, asegúrese de que la decisión sea coherente con uno o más de ellos. Esto ayuda a garantizar la alineación entre dominios o sistemas. * **Notas**: Debido a que el proceso de toma de decisiones puede llevar semanas, nos resultó útil capturar notas y temas que el equipo analiza durante el proceso de socialización. ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-de-michael-nygard/.locale-peer-id ================================================ b1e90e6556c1c8f1e2eb3ac22c8c5077 ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-de-michael-nygard/index.md ================================================ # Plantilla de registro de decisiones de Michael Nygard Esta es la plantilla en [Documentación de decisiones de arquitectura - Michael Nygard] (http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). Puede utilizar [adr-tools](https://github.com/npryce/adr-tools) para administrar los archivos ADR. En cada archivo ADR, escriba estas secciones: # Título ## Estado ¿Cuál es el estado, como propuesto, aceptado, rechazado, obsoleto, reemplazado, etc.? ## Contexto ¿Cuál es el problema que estamos viendo que está motivando esta decisión o cambio? ## Decisión ¿Cuál es el cambio que estamos proponiendo y/o haciendo? ## Consecuencias ¿Qué se vuelve más fácil o más difícil de hacer debido a este cambio? ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-del-proyecto-madr/.locale-peer-id ================================================ 0a9f88e5cda952db0a82d071f585d090 ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-del-proyecto-madr/index.md ================================================ # [título breve del problema resuelto y solución] * Estado: [propuesto | rechazado | aceptado | en desuso | … | reemplazado por [ADR-0005](0005-example.md)] * Decidentes: [enumere a todos los involucrados en la decisión] * Fecha: [AAAA-MM-DD cuando se actualizó la decisión por última vez] Historia técnica: [descripción | URL del ticket/emisión] ## Contexto y planteamiento del problema [Describa el contexto y el planteamiento del problema, por ejemplo, en forma libre utilizando dos o tres oraciones. Es posible que desee articular el problema en forma de pregunta.] ## Impulsores de decisión * [conductor 1, por ejemplo, una fuerza, frente a una preocupación,…] * [conductor 2, por ejemplo, una fuerza, frente a una preocupación,…] * … ## Opciones consideradas * [Opción 1] * [opcion 2] * [opción 3] * … ## Resultado de la decisión Opción elegida: "[opción 1]", porque [justificación. por ejemplo, única opción que cumple con k.o. criterio de decisión conductor | que resuelve fuerza fuerza | … | sale mejor (ver más abajo)]. ### Consecuencias positivas * [por ejemplo, mejora de la satisfacción de los atributos de calidad, decisiones de seguimiento requeridas,…] *… ### Consecuencias negativas * [por ejemplo, comprometer el atributo de calidad, se requieren decisiones de seguimiento,…] *… ## Pros y contras de las opciones ### [Opción 1] [ejemplo | descripción | puntero a más información | …] * Bien, porque [argumento a] * Bien, porque [argumento b] * Malo, porque [argumento c] * … ### [opcion 2] [ejemplo | descripción | puntero a más información | …] * Bien, porque [argumento a] * Bien, porque [argumento b] * Malo, porque [argumento c] * … ### [opción 3] [ejemplo | descripción | puntero a más información | …] * Bien, porque [argumento a] * Bien, porque [argumento b] * Malo, porque [argumento c] * … ## Enlaces * [Tipo de enlace] [Enlace a ADR] * … ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-para-caso-de-negocio/.locale-peer-id ================================================ f6d1fb662640a00f4c66c586233dead9 ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-para-caso-de-negocio/index.md ================================================ # Plantilla de registro de decisión para caso de negocio Esta plantilla de ADR hace hincapié en la creación de un caso de negocio para una decisión, incluidos criterios, candidatos y costos. ## Nivel superior * Título * Estado * Criterios de evaluación * Candidatos a considerar * Investigación y análisis de cada candidato. * Cumple/no cumple con los criterios y por qué * Análisis de costos * Análisis FODA * Opiniones y comentarios *Recomendación ## Inmersión profunda a bajo nivel **Título**: * Una frase corta en tiempo presente imperativo, de menos de 50 caracteres, como un mensaje de confirmación de git. **Estado**: * Uno de los propuestos, aceptados, rechazados, obsoletos, reemplazados, etc. **Criterios de evaluación**: * Resumen: explicar brevemente qué buscamos descubrir y por qué. * Detalles **Candidatos a considerar**: * Resumen: explique brevemente cómo descubrimos candidatos y llame la atención sobre cualquier valor atípico. * Enumerar todos los candidatos y opciones relacionadas; ¿Qué estamos evaluando como posibles soluciones? * Detalles **Investigación y análisis de cada candidato**: * Resumen: explique brevemente los métodos de investigación y llame la atención sobre patrones, grupos y valores atípicos. * Cumple/no cumple con los criterios y por qué * Resumen * Detalles * Análisis de costos * Resumen * Ejemplos * Licencias, como acuerdos contractuales y compromisos legales. * Capacitación, como mejora de habilidades y gestión del cambio. *Operación, como soporte y mantenimiento. * Medición, como ancho de banda y uso de CPU. * Análisis FODA * Resumen * Fortalezas * Debilidades * Oportunidades * Amenazas * Opiniones y comentarios internos. * Resumen * Ejemplos * Por el equipo, idealmente escrito por la persona real * De otras partes interesadas * Atributos de calidad, también conocidos como requisitos multifuncionales. * Opiniones y comentarios externos. * Resumen * ¿Quién da la opinión? * ¿Cuáles son otros candidatos que consideró? * ¿Qué estás creando? * Ejemplos * B2B o B2C * orientado al exterior o solo para empleados * computadora de escritorio o móvil * piloto o producción * monolito o microservicios * ¿Cómo evaluó a los candidatos? * ¿Por qué elegiste al ganador? * ¿Qué está pasando desde entonces? * Ejemplos * ¿Cómo se desempeña el ganador? * ¿Qué porcentaje del tráfico de usuarios de producción del mundo real fluye a través del ganador? * ¿Qué tipos de integraciones están involucradas, como canales de entrega continua, sistemas de gestión de contenido, análisis y métricas, etc.? * Sabiendo lo que sabes ahora, ¿qué aconsejarías a las personas que hicieran de manera diferente? * Anécdotas **Recomendación**: * Resumen * Detalles ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-para-el-patrón-alejandrino/.locale-peer-id ================================================ f33e4eb0409f956de201b791749dc9aa ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-para-el-patrón-alejandrino/index.md ================================================ # Plantilla de registro de decisión para el patrón alejandrino ## Introducción * Prólogo (Resumen) * Discusión (Contexto) * Solución (Decisión) * Consecuencias (Resultados) ## Detalles ## * Prólogo (Resumen) * Declaración para resumir: * En el contexto de (caso de uso)
enfrentando (preocupación)
nos decidimos por (opción)
lograr (calidad)
aceptar (desventaja). * Discusión (Contexto) * Explica las fuerzas en juego (técnicas, políticas, sociales, de proyecto). * Esta es la historia que explica el problema que buscamos resolver. * Solución * Explica cómo la decisión resolverá el problema. * Consecuencias * Explica los resultados de la decisión a largo plazo. * Funcionó, no funcionó, fue cambiado, actualizado, etc. ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-usando-planguage/.locale-directory-name-en.txt ================================================ decision-record-template-using-planguage ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-usando-planguage/.locale-peer-id ================================================ bb37e19df57d398b0704d6bd30ee6e6d ================================================ FILE: locales/es/plantillas/plantilla-de-registro-de-decisión-usando-planguage/index.md ================================================ # Plantilla de registro de decisión de arquitectura (ADR) Esta es una plantilla para EdgeX Foundry ADR. Fuente: https://docs.edgexfoundry.org/2.3/design/adr/template/ ### Remitentes Enumere los remitentes de ADR. Formato: - Nombre (Organización) ## Registro de cambios Enumere los cambios en el documento, incl. estado, fecha y URL de PR. El estado es uno de: pendiente, aprobado, modificado, obsoleto. La fecha es una cadena ISO 8601 (AAAA-MM-DD). PR es la solicitud de extracción que envió el cambio, incluida información como la diferencia, los contribuyentes y los revisores. Formato: - \[Estado del ADR, p. aprobado, modificado, etc.\]\(URL de la solicitud de extracción\) AAAA-MM-DD ## Caso(s) de uso referenciados Enumere todos los documentos de requisitos/casos de uso relevantes. ADR requiere al menos un caso de uso relevante y aprobado. Formato: - \[Usar nombre de caso\]\(URL\) Agregue explicaciones si el ADR no aborda todos los requisitos de un caso de uso. ## Contexto Describir: - la importancia arquitectónica del diseño - la garantía de una ADR (en lugar de un simple problema y relaciones públicas para solucionar un problema) - el enfoque de diseño de alto nivel (los detalles se describen en el diseño propuesto a continuación) ## Diseño propuesto Detalles del diseño (sin entrar en implementación cuando sea posible). Describir: - servicios/módulos que se verán afectados (cambiados) - nuevos servicios/módulos que se agregarán - impacto del modelo y del DTO (cambios/adiciones/eliminaciones) - Impacto de API (cambios/adiciones/eliminaciones) - impacto de la configuración general (establecimiento de nuevas secciones, cambios/adiciones/eliminaciones) - impacto devops ## Consideraciones Documentar alternativas, inquietudes, cuestiones auxiliares o relacionadas, dudas que surgieron en el debate del ADR. Indique si y cómo se resolvieron o apaciguaron. ## Decisión Documente cualquier detalle importante de implementación acordado, advertencias, consideraciones futuras y cuestiones de diseño pendientes o diferidas. Documente cualquier parte de los requisitos que no cumpla el diseño propuesto. ## Otros ADR relacionados Enumere cualquier ADR relevante, como una decisión de diseño para un subcomponente de una característica, un diseño obsoleto como resultado de este diseño, etc. Formato: - \[Título ADR\]\(URL\) - Relevancia ## Referencias Enumere referencias adicionales. Formato: - \[Título\]\(URL\) ​Buscar detalles 2.205 / 5.000 Resultados de traducción Resultado de la traducción Algunas oraciones pueden contener alternativas específicas de género. Haga clic en una oración para ver alternativas. Aprende más # Plantilla de registro de decisión de arquitectura (ADR) Esta es una plantilla para EdgeX Foundry ADR. Fuente: https://docs.edgexfoundry.org/2.3/design/adr/template/ ### Remitentes Enumere los remitentes de ADR. Formato: - Nombre (Organización) ## Registro de cambios Enumere los cambios en el documento, incl. estado, fecha y URL de PR. El estado es uno de: pendiente, aprobado, modificado, obsoleto. La fecha es una cadena ISO 8601 (AAAA-MM-DD). PR es la solicitud de extracción que envió el cambio, incluida información como la diferencia, los contribuyentes y los revisores. Formato: - \[Estado del ADR, pág. aprobado, modificado, etc.\]\(URL de la solicitud de extracción\) AAAA-MM-DD ## Caso(s) de uso referenciados Enumere todos los documentos de requisitos/casos de uso relevantes. ADR requiere al menos un caso de uso relevante y aprobado. Formato: - \[Usar nombre de caso\]\(URL\) Agregue explicaciones si el ADR no aborda todos los requisitos de un caso de uso. ## Contexto Describir: - la importancia arquitectónica del diseño - la garantía de una ADR (en lugar de un simple problema y relaciones públicas para solucionar un problema) - el enfoque de diseño de alto nivel (los detalles se describen en el diseño propuesto a continuación) ## Diseño propuesto Detalles del diseño (sin entrar en implementación cuando sea posible). Describir: - servicios/módulos que se verán afectados (cambiados) - nuevos servicios/módulos que se agregarán - impacto del modelo y del DTO (cambios/adiciones/eliminaciones) - Impacto de API (cambios/adiciones/eliminaciones) - impacto de la configuración general (establecimiento de nuevas secciones, cambios/adiciones/eliminaciones) - impacto devops ## Consideraciones Documentar alternativas, inquietudes, cuestiones auxiliares o relacionadas, dudas que surgieron en el debate del ADR. Indique si y cómo se resolvieron o apaciguaron. ## Decisión Documente cualquier detalle importante de implementación acordada, advertencias, consideraciones futuras y cuestiones de diseño pendientes o diferidas. Documente cualquier parte de los requisitos que no cumplan el diseño propuesto. ## Otros ADR relacionados Enumere cualquier ADR relevante, como una decisión de diseño para un subcomponente de una característica, un diseño obsoleto como resultado de este diseño, etc. Formato: - \[Título ADR\]\(URL\) - Relevancia ## Referencias Enumere referencias adicionales. Formato: - \[Título\]\(URL\) ​Buscar detalles Enviar comentarios Paneles laterales Resultados de traducción disponibles ================================================ FILE: locales/fr/.locale-peer-id ================================================ 0b59cb46e5817b414866ebe33f4d7bcf ================================================ FILE: locales/fr/documents/.locale-peer-id ================================================ abc7c72d426bc75e40b25a44ae37ce73 ================================================ FILE: locales/fr/documents/comment-commencer-à-utiliser-les-adr/.locale-peer-id ================================================ 8196518140224596af99a46d512feba3 ================================================ FILE: locales/fr/documents/comment-commencer-à-utiliser-les-adr/index.md ================================================ # Comment commencer à utiliser les ADR Pour commencer à utiliser les ADR, parlez avec vos coéquipiers de ces domaines. Identification de la décision: * Dans quelle mesure est-il urgent et est important l'annonce? * Doit-il être fait maintenant, ou peut-il attendre que plus soit connu? * Une expérience personnelle et collective, ainsi que des méthodes et pratiques de conception reconnues, peuvent aider à l'identification des décisions. * Idéalement, maintenir une liste de tâches de décision qui complète la liste des tâches du produit. Prise de décision: * Un certain nombre de techniques de prise de décision existent, à la fois générales et celles spécifiques à l'architecture logicielle, par exemple, la cartographie des dialogues. * La prise de décision de groupe est un sujet de recherche actif. Décision de décision et application: * Les annonces sont utilisées dans la conception de logiciels; Par conséquent, ils doivent être communiqués et acceptés par les parties prenantes du système qui le financent, le développent et l'exploitent. * Les styles de codage et les revues de code évidents architecturaux qui se concentrent sur les préoccupations et les décisions architecturales sont deux pratiques connexes. * Les annonces doivent également être (ré) considérées lors de la modernisation d'un système logiciel dans l'évolution des logiciels. Partage de décision (facultatif): * De nombreuses publicités se reproduisent dans les projets. * Par conséquent, les expériences avec les décisions passées, bonnes et mauvaises, peuvent être des actifs réutilisables précieux lors de l'utilisation d'une stratégie explicite de gestion des connaissances. Documentation de la décision: * De nombreux modèles et outils de capture de décision existent. * Voir les communautés agiles, par ex. ADRS de M. Nygard. * Voir les processus traditionnels d'ingénierie logicielle et de conception d'architecture, par ex. Disposés de table suggérés par IBM UMF et par Tyree et Akerman de Capitalone. Pour plus: * Les étapes ci-dessus sont adoptées à partir de l'entrée Wikipedia sur [DÉCISION ARCHITECTURAL] (https://en.wikipedia.org/wiki/architectural_decision) ================================================ FILE: locales/fr/documents/comment-commencer-à-utiliser-les-adr-avec-des-outils/.locale-peer-id ================================================ 1a5a03dd6f20cea9f78fb4655a9a7f87 ================================================ FILE: locales/fr/documents/comment-commencer-à-utiliser-les-adr-avec-des-outils/index.md ================================================ # Comment commencer à utiliser les ADR avec des outils Vous pouvez commencer à utiliser les ADR avec des outils comme vous le souhaitez. Par exemple: * Si vous aimez utiliser Google Drive et l'édition en ligne, vous pouvez créer un Google Doc ou Google Sheet. * Si vous aimez utiliser le contrôle de la version du code source, tel que GIT, vous pouvez créer un fichier pour chaque ADR. * Si vous aimez utiliser des outils de planification de projet, tels que Atlassian Jira, vous pouvez utiliser le tracker de planification de l'outil. * Si vous aimez utiliser des wikis, comme MediaWiki, vous pouvez créer un Wiki ADR. ================================================ FILE: locales/fr/documents/comment-commencer-à-utiliser-les-adr-avec-git/.locale-peer-id ================================================ d6fb3c7d91f95003163e694e74058e9d ================================================ FILE: locales/fr/documents/comment-commencer-à-utiliser-les-adr-avec-git/index.md ================================================ # Comment commencer à utiliser les ADR avec Git Si vous aimez utiliser Git Version Control, alors voici comment nous aimons commencer à utiliser ADRS avec GIT pour un projet logiciel typique avec le code source. Créez un répertoire pour les fichiers ADR: `` `sh $ mkdir adr `` ' Pour chaque ADR, créez un fichier texte, tel que `database.txt`: `` `sh $ vi database.txt `` ' Écrivez tout ce que vous voulez dans l'ADR. Voir les modèles de ce référentiel pour les idées. Engagez l'ADR dans votre dépôt Git. ================================================ FILE: locales/fr/documents/conseils-de-travail-déquipe-pour-les-adr/.locale-peer-id ================================================ 875a7715e592ceb45eac5e155ee16318 ================================================ FILE: locales/fr/documents/conseils-de-travail-déquipe-pour-les-adr/index.md ================================================ # Conseils de travail d'équipe pour les ADR Si vous envisagez d'utiliser des dossiers de décision avec votre équipe, voici quelques conseils que nous avons appris en travaillant avec de nombreuses équipes. Vous avez l'occasion de diriger vos coéquipiers, en parlant ensemble du "pourquoi", plutôt que d'imposer le "quoi". Par exemple, les dossiers de décision sont un moyen pour les équipes de penser plus intelligemment et de mieux communiquer; Les dossiers de décision ne sont pas précieux s'ils ne sont qu'une exigence de paperasse forcée après le fruits. Certaines équipes préfèrent de loin le nom des "décisions" à l'abréviation "ADRS". Lorsque certaines équipes utilisent le nom du répertoire "décisions", alors c'est comme si une ampoule s'allume, et que l'équipe commence à mettre plus d'informations dans le répertoire, telles que les décisions des fournisseurs, les décisions de planification, les décisions de planification, etc. Tous ces types de Les informations peuvent utiliser le même modèle. Nous émettons l'hypothèse que les gens apprennent plus rapidement avec les mots ("décisions") sur les abréviations ("ADR"), et les gens sont plus motivés pour rédiger des documents de travail lorsque le mot "enregistrement" est supprimé, ainsi que certains développeurs et certains gestionnaires déteste le mot «architecture». En théorie, l'immuabilité est idéale. Dans la pratique, la mutabilité a mieux fonctionné pour nos équipes. Nous insérons les nouvelles informations de l'ADR existante, avec un tampon de date et une note que les informations sont arrivées après la décision. Ce type d'approche mène à un "document de vie" que nous pouvons tous mettre à jour. Les mises à jour typiques sont lorsque nous obtenons des informations grâce aux nouveaux coéquipiers, ou à de nouvelles offres, ou aux résultats réels de nos usages, ou des modifications de tiers après le fait telles que les capabilties des fournisseurs, les plans de prix, les accords de licence, etc. ================================================ FILE: locales/fr/documents/conventions-de-noms-de-fichiers/.locale-peer-id ================================================ 89116b5647aa1e53186f3c44b5a284a0 ================================================ FILE: locales/fr/documents/conventions-de-noms-de-fichiers/index.md ================================================ # Conventions de noms de fichiers Si vous choisissez de créer votre ADR à l'aide de fichiers texte typiques, vous souhaiterez peut-être trouver votre propre convention de nom de fichier ADR. Nous préférons utiliser une convention de nom de fichier qui a un format spécifique. Exemples: * choisir-database.md * format-timestamps.md * gérer-les-mots-de-passe.md * manche-exception.md Notre convention de nom de fichier: * Le nom a une phrase verbale impérative actuelle. Cela aide la lisibilité et correspond à notre format de message de validation. * Le nom utilise des minuscules et des tirets (identiques à ce référentiel). Il s'agit d'un équilibre entre lisibilité et convivialité du système. * L'extension est Markdown. Cela peut être utile pour une mise en forme facile. ================================================ FILE: locales/fr/documents/critères-de-durabilité-de-décision/.locale-peer-id ================================================ 71d59ed566ae148b8bf42331a84754ac ================================================ FILE: locales/fr/documents/critères-de-durabilité-de-décision/index.md ================================================ # Critères de durabilité de décision Pour définir la durabilité de la décision en détail, nous avons dérivé cinq critères clés. ## stratégique Pendant la prise de décision, une personne qui examine les conséquences stratégiques devrait considérer des choses telles que l'impact à long terme des décisions - par exemple, les opérations futures et les efforts de maintenance. ## mesurable et gérable Vous pouvez mesurer et évaluer le résultat d'une décision au fil du temps en fonction des critères objectifs, idéalement numériques (comme, par exemple, propagés par des scénarios d'attribut de qualité et des ateliers4). La capture de toutes les décisions à grain fin n'est pas possible, donc les architectes doivent limiter la granularité des décisions à un certain niveau de détail (comme la création d'une classe de conception). Cela conduira à un ensemble plus durable de décisions et à moins de liens de traçabilité. De plus, la limitation du nombre de dépendances entre les décisions réduit l'effet d'entraînement des changements. ## réalisable et réaliste La justification de l'ajustement de la solution au problème doit être choisie de manière pragmatique et rendue explicite. Par exemple, les architectes peuvent indiquer qu'ils ont pris soin d'éviter la sur-intention ou la sous-intention (c'est-à-dire qu'ils devraient appliquer l'approche «assez bonne»). ## Enraciné dans les exigences La prise de décision doit être fondée sur l'expérience architectée et le contexte architectives spécifiques au domaine. Il devrait prendre en compte l'environnement de l'entreprise ainsi que les exigences et les contraintes du projet, y compris les compétences actuelles de l'équipe de développement, le budget de formation et le processus. ## Intemporel Les décisions devraient être basées sur l'expérience et les connaissances qui ne seront probablement pas bientôt dépassées. Par exemple, les architectes peuvent choisir des modèles architecturaux ou des tactiques architecturaux neutres. ================================================ FILE: locales/fr/documents/lignes-directrices-pour-atteindre-des-décisions-durables/.locale-peer-id ================================================ 934d1c42a693fe004cd8bf8f5ecb97e6 ================================================ FILE: locales/fr/documents/lignes-directrices-pour-atteindre-des-décisions-durables/index.md ================================================ # Lignes directrices pour atteindre des décisions durables Nous avons appris les leçons suivantes dans notre travail qui peuvent servir de directives et d'évaluation pour obtenir des décisions durables: 1. Utilisez une approche maigre / minimaliste pour la documentation de décision initiale. 2. Prioriser et capturer toutes les décisions importantes qui sont suffisamment pertinentes pour documenter et comprendre l'architecture cible. 3. Détaillez les décisions particulièrement importantes avec des modèles à part ). 4. Utilisez les versions maigres / minimalistes de l'étape 1 comme une version courte des décisions documentées avec le bon niveau de granularité pour fournir un aperçu des décisions détaillées, ainsi que pour les décisions triviales ou évidentes. 5. Dans la mesure du possible, utilisez des connaissances architecturales existantes, soit à partir de modèles de guidage, soit à partir d'autres sources. Examiner et étendre ces connaissances et l'ajuster au contexte de la décision spécifique. 6. Assurez-vous que les liens de traçabilité sont établis entre les décisions et les exigences et les conceptions / code architecturaux. 7. Fournissez la vérification de la cohérence automatisée pour vous assurer que les liens de traçabilité sont synchronisés après un changement. Limitez le nombre de dépendances entre les décisions et d'autres artefacts logiciels. 8 Appliquez les directives pour les justifications par conséquent et avec force - ils sont la partie la plus importante de la documentation de décision car elles donnent la justification. ================================================ FILE: locales/fr/documents/processus-des-dossiers-de-décision-architecturale-aws/.locale-peer-id ================================================ 7d4adf16004ca42546dee49922ae4ccf ================================================ FILE: locales/fr/documents/processus-des-dossiers-de-décision-architecturale-aws/index.md ================================================ # Processus des dossiers de décision architecturale AWS https://docs.aws.amazon.com/prescriptive-uidance/latest/architectural-decision-records/adr-process.html Un dossier de décision architecturale (ADR) est un document qui décrit un choix que l'équipe fait sur un aspect important de l'architecture logicielle qu'il prévoit de construire. Chaque ADR décrit la décision architecturale, son contexte et ses conséquences. Les ADR ont des États et suivent donc un cycle de vie. Pour un exemple d'ADR, voir l'annexe. Le processus ADR publie une collection de dossiers de décision architecturale. Cette collection crée le journal de décision. Le journal de décision fournit le contexte du projet ainsi que des informations détaillées sur la mise en œuvre et la conception. Les membres du projet font les gros titres de chaque ADR pour obtenir un aperçu du contexte du projet. Ils ont lu les ADR pour plonger profondément dans les implémentations du projet et les choix de conception. Lorsque l'équipe accepte une ADR, elle devient immuable. Si de nouvelles informations nécessitent une décision différente, l'équipe propose un nouvel ADR. Lorsque l'équipe accepte le nouvel ADR, il remplace l'ADR précédent. ## Portée du processus ADR Les membres du projet doivent créer un ADR pour chaque décision architecturale significative qui affecte le projet ou le produit logiciel, y compris les suivants (Richards et Ford 2020): * Structure (par exemple, des modèles tels que les microservices) * Exigences non fonctionnelles (sécurité, haute disponibilité et tolérance aux défauts) * Dépendances (couplage des composants) * Interfaces (API et contrats publiés) * Techniques de construction (bibliothèques, cadres, outils et processus) * Les exigences fonctionnelles et non fonctionnelles sont les entrées les plus courantes du processus ADR. ## Contenu ADR Lorsque l'équipe identifie le besoin d'un ADR, un membre de l'équipe commence à écrire l'ADR en fonction d'un modèle à l'échelle du projet. (Voir l'organisation ADR GitHub par exemple les modèles.) Le modèle simplifie la création de l'ADR et garantit que l'ADR capture toutes les informations pertinentes. Au minimum, chaque ADR devrait définir le contexte de la décision, la décision elle-même et les conséquences de la décision pour le projet et ses livrables. (Pour des exemples de ces sections, voir l'annexe.) L'un des aspects les plus puissants de la structure ADR est qu'il se concentre sur la raison de la décision plutôt que sur la façon dont l'équipe l'a mise en œuvre. Comprendre pourquoi l'équipe a pris la décision permet aux autres membres de l'équipe d'adopter plus facilement la décision et empêche d'autres architectes qui n'ont pas été impliqués dans le processus décisionnel pour annuler cette décision à l'avenir. ## Processus d'adoption de l'ADR Chaque membre de l'équipe peut créer une ADR, mais l'équipe doit établir une définition de la propriété pour un ADR. Chaque auteur qui est propriétaire d'un ADR doit conserver et communiquer activement le contenu ADR. Pour clarifier cette propriété, ce guide fait référence aux auteurs de l'ADR en tant que propriétaires de ADR dans les sections suivantes. D'autres membres de l'équipe peuvent toujours contribuer à un ADR. Si le contenu d'un ADR change avant que l'équipe n'accepte l'ADR, le propriétaire doit approuver ces modifications. Après que l'équipe ait identifié une décision architecturale et son propriétaire, le propriétaire de l'ADR fournit l'ADR dans l'état ** proposé ** au début du processus. Les ADR dans l'État proposé sont prêts à être révisés. Le propriétaire de l'ADR initie ensuite le processus d'examen de l'ADR. L'objectif du processus d'examen ADR est de décider si l'équipe accepte l'ADR, détermine qu'il doit être retravaillé ou rejette l'ADR. L'équipe de projet, y compris le propriétaire, passe en revue l'ADR. La réunion d'examen devrait commencer par un créneau horaire dédié pour lire l'ADR. En moyenne, 10 à 15 minutes devraient suffire. Pendant ce temps, chaque membre de l'équipe lit le document et ajoute des commentaires et des questions pour signaler des sujets peu clairs. Après la phase d'examen, le propriétaire de l'ADR lit et discute de chaque commentaire avec l'équipe. Si l'équipe trouve des points d'action pour améliorer l'ADR, l'état de l'ADR reste ** proposé **. Le propriétaire de l'ADR formule les actions et, en collaboration avec l'équipe, ajoute un cessionnaire à chaque action. Chaque membre de l'équipe peut contribuer et résoudre les points d'action. Il est de la responsabilité du propriétaire de l'ADR de reprogrammer le processus d'examen. L'équipe peut également décider de rejeter l'ADR. Dans ce cas, le propriétaire de l'ADR ajoute une raison pour le rejet pour empêcher les discussions futures sur le même sujet. Le propriétaire modifie l'état ADR en ** rejeté **. Si l'équipe approuve l'ADR, le propriétaire ajoute un horodatage, une version et une liste des parties prenantes. Le propriétaire met ensuite à jour l'état à ** accepté **. Les ADR et le journal de décision qu'ils créent représentent les décisions prises par l'équipe et fournissent une histoire de toutes les décisions. L'équipe utilise les ADR comme référence pendant le code et les revues architecturales dans la mesure du possible. En plus d'effectuer des avis de code, des tâches de conception et des tâches de mise en œuvre, les membres de l'équipe doivent consulter les ADR pour des décisions stratégiques pour le produit. En tant que bonne pratique, chaque changement de logiciel devrait passer par les examens par les pairs et nécessiter au moins une approbation. Au cours de l'examen du code, un réviseur de code peut trouver des modifications qui violent un ou plusieurs ADR. Dans ce cas, le réviseur demande à l'auteur de la modification du code pour mettre à jour le code et partage un lien vers l'ADR. Lorsque l'auteur met à jour le code, il est approuvé par les pairs examinateurs et fusionné dans la base de code principale. ## Processus d'examen ADR L'équipe doit traiter les ADR comme des documents immuables après que l'équipe les a acceptés ou les a rejetés. Les modifications à un ADR existant nécessitent la création d'un nouveau ADR, l'établissement d'un processus d'examen pour la nouvelle ADR et l'approbation de l'ADR. Si l'équipe approuve la nouvelle ADR, le propriétaire doit changer l'état de l'ancien ADR en ** remplacé **. ================================================ FILE: locales/fr/documents/quest-ce-quun-dossier-de-décision-darchitecture/.locale-peer-id ================================================ 020ff535ed1a3347a265209291e756b6 ================================================ FILE: locales/fr/documents/quest-ce-quun-dossier-de-décision-darchitecture/index.md ================================================ # Qu'est-ce qu'un dossier de décision d'architecture? Un ** dossier de décision d'architecture ** (ADR) est un document qui capture une décision architecturale importante prise avec son contexte et ses conséquences. Une ** décision d'architecture ** (AD) est un choix de conception de logiciels qui répond à une exigence importante. Un ** Log de décision d'architecture ** (ADL) est la collection de tous les ADR créés et entretenus pour un projet (ou une organisation) particulier. Une ** exigence architecturale ** (ASR) est une exigence qui a un effet mesurable sur l'architecture d'un système logiciel. Tout cela est dans le sujet de ** Architecture Knowledge Management ** (AKM). L'objectif de ce document est de fournir un aperçu rapide des ADR, comment les créer et où chercher plus d'informations. Abréviations: * ** AD **: Décision d'architecture * ** ADL **: Journal de décision d'architecture * ** ADR **: Enregistrement de décision d'architecture * ** AKM **: Gestion des connaissances en architecture * ** ASR **: exigence architecturale significative ================================================ FILE: locales/fr/documents/suggestions-pour-écrire-de-bonnes-adr/.locale-peer-id ================================================ dc1a294e76821d6d3b086a2b17988427 ================================================ FILE: locales/fr/documents/suggestions-pour-écrire-de-bonnes-adr/index.md ================================================ # Suggestions pour écrire de bonnes ADR Caractéristiques d'un bon ADR: * Justification: Expliquez les raisons de faire l'annonce particulière. Cela peut inclure le contexte (voir ci-dessous), les avantages et les inconvénients de divers choix potentiels, les comparations de fonctionnalités, les discussions sur les coûts / avantages, etc. * Spécifique: chaque ADR doit être environ une annonce, pas plusieurs annonces. * Timestaps: Identifiez quand chaque élément de l'ADR est écrit. Ceci est particulièrement important pour les aspects qui peuvent changer avec le temps, tels que les coûts, les horaires, la mise à l'échelle, etc. * Immutable: ne modifiez pas les informations existantes dans un ADR. Au lieu de cela, modifiez l'ADR en ajoutant de nouvelles informations ou remplacez l'ADR en créant un nouvel ADR. Caractéristiques d'une bonne section "contexte" dans une ADR: * Expliquez la situation et les priorités commerciales de votre organisation. * Incluez la justification et les considérations basées sur les maquillage social et de compétences de vos équipes. * Incluez les avantages et les inconvénients qui sont pertinents et décrivez-les en termes qui correspondent à vos besoins et à vos objectifs. Caractéristiques de la bonne section "conséquences" dans une ADR: * Expliquez ce qui suit de prendre la décision. Cela peut inclure les effets, les résultats, les sorties, les suivis, etc. * Inclure des informations sur les ADR ultérieurs. Il est relativement courant pour un ADR de déclencher le besoin de plus de ADR, comme lorsqu'un ADR fait un grand choix global, ce qui crée à son tour des besoins pour des décisions plus petites. * Inclure tout processus d'examen après action. Il est typique pour les équipes d'examiner chaque ADR un mois plus tard, de comparer les informations ADR avec ce qui s'est passé dans la pratique réelle, afin d'apprendre et de grandir. Un nouvel ADR peut remplacer un ADR précédent: * Lorsqu'une annonce est faite qui remplace ou invalide un ADR précédent, alors un nouvel ADR doit être créé ================================================ FILE: locales/fr/modèles/.locale-peer-id ================================================ 70f1f9b3530831bc891a6e9b9b0d27de ================================================ FILE: locales/fr/modèles/index.md ================================================ # Modèles d'enregistrement de décision * [Modèle d'enregistrement de décision par Jeff Tyree et Art Akerman](modèle-denregistrement-de-décision-par-jeff-tyree-et-art-akerman) * [Modèle d'enregistrement de décision par Michael Nygard](modèle-denregistrement-de-décision-par-michael-nygard) * [Modèle d'enregistrement de décision par EdgeX](modèle-denregistrement-de-décision-par-edgex) * [Modèle d'enregistrement de décision pour le modèle alexandrin](modèle-denregistrement-de-décision-pour-le-modèle-alexandrin) * [Modèle d'enregistrement de décision pour l'analyse de rentabilisation](modèle-denregistrement-de-décision-pour-lanalyse-de-rentabilisation) * [Modèle d'enregistrement de décision du projet MADR](modèle-denregistrement-de-décision-du-projet-madr) * [Modèle d'enregistrement de décision utilisant Plangage](modèle-denregistrement-de-décision-utilisant-plangage) ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision par jeff-tyree-et-art-akerman/.locale-peer-id ================================================ f4ca0a94124a91279e1929ea23ab864d ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision par jeff-tyree-et-art-akerman/index.md ================================================ # Modèle d'enregistrement de décision par Jeff Tyree et Art Akerman Il s'agit du modèle de description de décision d'architecture publié dans ["Architecture Decisions: Demystifying Architecture" par Jeff Tyree et Art Akerman, Capital One Financial](https://personal.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf). * **Problème** : décrivez le problème de conception architecturale que vous abordez, sans laisser de questions sur la raison pour laquelle vous abordez ce problème maintenant. En suivant une approche minimaliste, abordez et documentez uniquement les problèmes qui doivent être résolus à différents stades du cycle de vie. * **Décision** : indiquez clairement l'orientation de l'architecture, c'est-à-dire la position que vous avez sélectionnée. * **Statut** : le statut de la décision, par exemple en attente, décidé ou approuvé. * **Groupe** : vous pouvez utiliser un regroupement simple (tel que l'intégration, la présentation, les données, etc.) pour vous aider à organiser l'ensemble des décisions. Vous pouvez également utiliser une ontologie d'architecture plus sophistiquée, telle que celle de John Kyaruzi et Jan van Katwijk, qui comprend des catégories plus abstraites telles que l'événement, le calendrier et le lieu. Par exemple, en utilisant cette ontologie, vous regrouperiez les décisions qui traitent des occurrences pour lesquelles le système nécessite des informations sous un événement. * **Hypothèses** : décrivez clairement les hypothèses sous-jacentes à l'environnement dans lequel vous prenez la décision : coût, calendrier, technologie, etc. Notez que les contraintes environnementales (telles que les normes technologiques acceptées, l'architecture d'entreprise, les modèles couramment utilisés, etc.) peuvent limiter les alternatives que vous envisagez. * **Contraintes** : capturez toutes les contraintes supplémentaires à l'environnement que l'alternative choisie (la décision) pourrait poser. * **Positions** : répertoriez les postes (options ou alternatives viables) que vous avez envisagés. Celles-ci nécessitent souvent de longues explications, parfois même des modèles et des diagrammes. Il ne s’agit pas d’une liste exhaustive. Cependant, vous ne voulez pas entendre la question « Avez-vous pensé à… ? lors d'un examen final ; cela conduit à une perte de crédibilité et à une remise en question des autres décisions architecturales. Cette section permet également de garantir que vous avez entendu les opinions des autres ; exprimer explicitement d’autres opinions aide à inscrire leurs défenseurs dans votre décision. * **Argument** : expliquez pourquoi vous avez sélectionné un poste, y compris des éléments tels que le coût de mise en œuvre, le coût total de possession, le délai de mise sur le marché et la disponibilité des ressources de développement requises. C’est probablement aussi important que la décision elle-même. * **Implications** : une décision a de nombreuses implications, comme l'indique le métamodèle REMAP. Par exemple, une décision peut introduire le besoin de prendre d’autres décisions, de créer de nouvelles exigences ou de modifier des exigences existantes ; imposent des contraintes supplémentaires à l'environnement ; exiger une renégociation de la portée ou du calendrier avec les clients ; ou nécessitent une formation supplémentaire du personnel. Comprendre et énoncer clairement les implications de votre décision peut être très efficace pour obtenir l’adhésion et créer une feuille de route pour l’exécution de l’architecture. * **Décisions liées** : Il est évident que de nombreuses décisions sont liées ; vous pouvez les lister ici. Cependant, nous avons constaté qu’en pratique, une matrice de traçabilité, des arbres de décision ou des métamodèles sont plus utiles. Les métamodèles sont utiles pour représenter schématiquement des relations complexes (comme les modèles Rose). * **Exigences associées** : les décisions doivent être motivées par l'entreprise. Pour faire preuve de responsabilité, associez explicitement vos décisions aux objectifs ou aux exigences. Vous pouvez énumérer ces exigences connexes ici, mais nous avons trouvé plus pratique de référencer une matrice de traçabilité. Vous pouvez évaluer la contribution de chaque décision d’architecture à la satisfaction de chaque exigence, puis évaluer dans quelle mesure l’exigence est satisfaite dans toutes les décisions. Si une décision ne contribue pas à répondre à une exigence, ne prenez pas cette décision. * **Artefacts associés** : répertoriez les documents d'architecture, de conception ou de portée associés sur lesquels cette décision a un impact. * **Principes associés** : si l'entreprise a convenu d'un ensemble de principes, assurez-vous que la décision est cohérente avec un ou plusieurs d'entre eux. Cela permet de garantir l’alignement entre les domaines ou les systèmes. * **Notes** : étant donné que le processus de prise de décision peut prendre des semaines, nous avons trouvé utile de capturer les notes et les problèmes dont l'équipe discute au cours du processus de socialisation. ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision pour-lanalyse-de-rentabilisation/.locale-peer-id ================================================ f6d1fb662640a00f4c66c586233dead9 ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision pour-lanalyse-de-rentabilisation/index.md ================================================ # Modèle d'enregistrement de décision pour l'analyse de rentabilisation Ce modèle ADR met l'accent sur la création d'une analyse de rentabilisation pour une décision, comprenant les critères, les candidats et les coûts. ## Haut niveau * Titre * Statut * Critère d'évaluation * Candidats à considérer * Recherche et analyse de chaque candidat * Répond/ne répond pas aux critères et pourquoi * Analyse de coût * Analyse SWOT * Avis et retours * Recommandation ## Analyse approfondie de bas niveau **Titre**: * Une courte phrase impérative au présent, de moins de 50 caractères, comme un message git commit. **Statut**: * L'un des éléments proposés, acceptés, rejetés, obsolètes, remplacés, etc. **Critère d'évaluation**: * Résumé : expliquer brièvement ce que l'on cherche à découvrir et pourquoi. * Détails **Candidats à considérer** : * Résumé : expliquez brièvement comment nous avons découvert les candidats et attirez l'attention sur les valeurs aberrantes. * Répertorier tous les candidats et options associées ; qu’évaluons-nous comme solutions potentielles ? * Détails **Recherche et analyse de chaque candidat** : * Résumé : expliquez brièvement les méthodes de recherche et attirez l'attention sur les modèles, les clusters et les valeurs aberrantes. * Répond/ne répond pas aux critères et pourquoi * Résumé * Détails * Analyse de coût * Résumé * Exemples * Licences, telles que les accords contractuels et les engagements juridiques * Formation, telle que le perfectionnement et la gestion du changement * Exploitation, comme le support et la maintenance * Mesure, telle que la bande passante et l'utilisation du processeur * Analyse SWOT * Résumé * Forces * Faiblesses * Opportunités * Des menaces * Avis et retours internes * Résumé * Exemples * Par l'équipe, idéalement rédigé par la personne réelle *De la part d'autres parties prenantes * Attributs de qualité, c'est-à-dire exigences interfonctionnelles * Avis et retours externes * Résumé * Qui donne l'avis ? * Quels autres candidats avez-vous envisagés ? *Qu'est-ce que tu crées ? * Exemples *B2B ou B2C * destiné à l'externe ou réservé aux employés * ordinateur de bureau ou mobile * pilote ou production * monolithe ou microservices * Comment avez-vous évalué les candidats ? *Pourquoi avez-vous choisi le gagnant ? * Que s'est-il passé depuis ? * Exemples * Comment se comporte le gagnant ? * Quel pourcentage du trafic des utilisateurs de production réels passe par le gagnant ? * Quels types d'intégrations sont impliqués, par exemple avec les pipelines de livraison continue, les systèmes de gestion de contenu, les analyses et les mesures, etc. ? * Sachant ce que vous savez maintenant, que conseilleriez-vous aux gens de faire différemment ? *Anecdotes **Recommandation**: * Résumé * Détails ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision utilisant-plangage/.locale-peer-id ================================================ bb37e19df57d398b0704d6bd30ee6e6d ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision utilisant-plangage/index.md ================================================ # Modèle d'enregistrement de décision utilisant Plangage Voir https://www.iaria.org/conferences2012/filesICCGI12/Tutorial%20Specifying%20Effective%20Non-func.pdf ## Qu'est-ce que le Plangage ? Plangage est un langage de planification qui utilise ces mots-clés : * Tag : un identifiant unique et persistant * Gist : Un bref résumé de l'exigence ou du domaine abordé * Exigence : le texte qui détaille l'exigence elle-même * Justification : le raisonnement qui justifie l'exigence * Priorité : une déclaration de priorité et une réclamation sur les ressources * Parties prenantes : parties matériellement affectées par l'exigence * Statut : le statut de l'exigence (projet, révisé, validé, etc.) * Propriétaire : la personne responsable de la mise en œuvre de l'exigence * Auteur : la personne qui a rédigé l'exigence * Révision : un numéro de version pour la déclaration * Date : La date de la révision la plus récente * Hypothèses : tout ce qui pourrait causer des problèmes s'il était faux maintenant ou plus tard * Risques : tout ce qui pourrait entraîner un dysfonctionnement, un retard ou d'autres impacts négatifs *Défini : La définition d'un terme (mieux vaut utiliser un glossaire) ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision-du-projet-madr/.locale-peer-id ================================================ 0a9f88e5cda952db0a82d071f585d090 ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision-du-projet-madr/index.md ================================================ # [titre court du problème résolu et de la solution] * Statut : [proposé | rejeté | accepté | obsolète | … | remplacé par [ADR-0005](0005-example.md)] * Décideurs : [lister toutes les personnes impliquées dans la décision] * Date : [AAAA-MM-JJ de la dernière mise à jour de la décision] Histoire technique : [description | URL du ticket/problème] ## Contexte et énoncé du problème [Décrivez le contexte et l'énoncé du problème, par exemple sous forme libre en utilisant deux à trois phrases. Vous voudrez peut-être articuler le problème sous la forme d’une question.] ## Facteurs de décision * [conducteur 1, ex., une force, face à une inquiétude, …] * [conducteur 2, ex., une force, face à l'inquiétude, …] * … ## Options envisagées * [Option 1] * [Option 2] * [option 3] * … ## Résultat de la décision Option retenue : « [option 1] », car [justification. par exemple, seule option qui répond à k.o. critère déterminant de décision | qui résout la force force | … | ressort le mieux (voir ci-dessous)]. ### Conséquences positives * [par exemple, amélioration de la satisfaction des attributs de qualité, décisions de suivi requises, …] *… ### Conséquences négatives * [par exemple, attribut de qualité compromis, décisions de suivi requises, …) *… ## Avantages et inconvénients des options ### [Option 1] [exemple | descriptif | pointeur vers plus d'informations | …] * Bien, parce que [argument a] * Bien, parce que [argument b] * Mauvais, parce que [argument c] * … ### [Option 2] [exemple | descriptif | pointeur vers plus d'informations | …] * Bien, parce que [argument a] * Bien, parce que [argument b] * Mauvais, parce que [argument c] * … ### [option 3] [exemple | descriptif | pointeur vers plus d'informations | …] * Bien, parce que [argument a] * Bien, parce que [argument b] * Mauvais, parce que [argument c] * … ## Liens * [Type de lien] [Lien vers ADR] * … ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision-par michael-nygard/.locale-peer-id ================================================ b1e90e6556c1c8f1e2eb3ac22c8c5077 ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision-par michael-nygard/index.md ================================================ # Modèle d'enregistrement de décision par Michael Nygard Il s'agit du modèle dans [Documentation des décisions d'architecture - Michael Nygard] (http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). Vous pouvez utiliser [adr-tools](https://github.com/npryce/adr-tools) pour gérer les fichiers ADR. Dans chaque fichier ADR, écrivez ces sections : # Titre ## Statut Quel est le statut : proposé, accepté, rejeté, obsolète, remplacé, etc. ? ## Contexte Quel est le problème que nous constatons et qui motive cette décision ou ce changement ? ## Décision Quel est le changement que nous proposons et/ou faisons ? ## Conséquences Qu’est-ce qui devient plus facile ou plus difficile à faire à cause de ce changement ? ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision-par-edgex/.locale-peer-id ================================================ 01939db0c341e9092c344d904065da12 ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision-par-edgex/index.md ================================================ # Modèle d'enregistrement de décision d'architecture (ADR) Il s'agit d'un modèle pour EdgeX Foundry ADR. Source : https://docs.edgexfoundry.org/2.3/design/adr/template/ ### Soumissionnaires Répertoriez les demandeurs d’ADR. Format: - Nom (Organisation) ## Journal des modifications Répertoriez les modifications apportées au document, incl. état, date et URL PR. L'état est l'un des suivants : en attente, approuvé, modifié, obsolète. La date est une chaîne ISO 8601 (AAAA-MM-JJ). PR est la pull request qui a soumis la modification, y compris des informations telles que la différence, les contributeurs et les réviseurs. Format: - \[Statut de l'ADR, par ex. approuvé, modifié, etc.\]\(URL de la demande d'extraction\) AAAA-MM-JJ ## Cas d'utilisation référencés Répertoriez tous les cas d’utilisation/documents d’exigences pertinents. L’ADR nécessite au moins un cas d’utilisation pertinent et approuvé. Format: - \[Nom du cas d'utilisation\]\(URL\) Ajoutez des explications si l’ADR ne répond pas à toutes les exigences d’un cas d’utilisation. ## Contexte Décrire: - comment la conception est significative sur le plan architectural - justifiant un ADR (par rapport à un simple problème et un PR pour résoudre un problème) - l'approche de conception de haut niveau (détails décrits dans la conception proposée ci-dessous) ## Conception proposée Détails de la conception (sans entrer dans la mise en œuvre lorsque cela est possible). Contour: - services/modules à impacter (modifiés) - nouveaux services/modules à ajouter - impact modèle et DTO (modifications/ajouts/suppressions) - Impact API (modifications/ajouts/suppressions) - impact sur la configuration générale (création de nouvelles sections, modifications/ajouts/suppressions) - impact sur les développeurs ## Considérations Documenter les alternatives, les préoccupations, les questions accessoires ou connexes, les questions soulevées lors du débat sur l'ADR. Indiquez si/comment ils ont été résolus ou apaisés. ## Décision Documentez tous les détails de mise en œuvre importants convenus, les mises en garde, les considérations futures, les problèmes de conception restants ou différés. Documentez toute partie des exigences non satisfaites par la conception proposée. ## Autres ADR associés Répertoriez tous les ADR pertinents - comme une décision de conception pour un sous-composant d'une fonctionnalité, une conception obsolète en raison de cette conception, etc. Format: - \[Titre ADR\]\(URL\) - Pertinence ## Les références Énumérez les références supplémentaires. Format: - \[Titre\]\(URL\) ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision-pour-le modèle-alexandrin/.locale-peer-id ================================================ f33e4eb0409f956de201b791749dc9aa ================================================ FILE: locales/fr/modèles/modèle-denregistrement-de-décision-pour-le modèle-alexandrin/index.md ================================================ # Modèle d'enregistrement de décision pour le modèle alexandrin ## Introduction * Prologue (Résumé) * Discussion (Contexte) * Solution (Décision) * Conséquences (Résultats) ## Détails ## * Prologue (Résumé) * Déclaration pour résumer : * Dans le cadre de (cas d'utilisation)
faire face (préoccupation)
nous avons opté pour (option)
atteindre (la qualité)
accepter (inconvénient). * Discussion (Contexte) * Explique les forces en jeu (techniques, politiques, sociales, projet). * Ceci est l'histoire expliquant le problème que nous cherchons à résoudre. * Solution * Explique comment la décision résoudra le problème. * Conséquences * Explique les résultats de la décision sur le long terme. * Est-ce que cela a fonctionné, n'a pas fonctionné, a été modifié, mis à niveau, etc. ================================================ FILE: locales/index.md ================================================ * [Cymraeg](cy/) * [English](en/) * [Española](es/) * [Français](fr/) * [한국인](ko/) * [Türkçe](tr/) ================================================ FILE: locales/ja/.locale-peer-id ================================================ 0b59cb46e5817b414866ebe33f4d7bcf ================================================ FILE: locales/ja/テンプレート/.locale-peer-id ================================================ 70f1f9b3530831bc891a6e9b9b0d27de ================================================ FILE: locales/ja/テンプレート/EdgeX Foundryによる意思決定記録テンプレート/.locale-peer-id ================================================ 01939db0c341e9092c344d904065da12 ================================================ FILE: locales/ja/テンプレート/EdgeX Foundryによる意思決定記録テンプレート/index.md ================================================ # アーキテクチャ決定記録 (ADR) テンプレート これは EdgeX FoundryのADRのテンプレートです。 テンプレート元: https://docs.edgexfoundry.org/2.3/design/adr/template/ ### 編集者 ADR編集者を列挙します。 形式: - 氏名（組織名） ## 変更記録 ドキュメントの変更内容を、状態、日付、PRのURLを含めて列挙します。 状態は、保留中、承認済み、修正済み、非推奨のいずれかです。 日付は ISO 8601 (YYYY-MM-DD) 形式の文字列です。 PRは変更を送信したプルリクエストで、差分、コントリビューター、レビュアーなどの情報が含まれます。 形式: - \[ADR のステータス (承認済み、修正済みなど)\]\(プルリクエストのURL\) YYYY-MM-DD ## 参照ユースケース 関連するユースケース/要件ドキュメントをすべて列挙してください。 ADRには、少なくとも1つの関連する承認済みユースケースが必要です。 形式: - \[ユースケース名\]\(URL\) ADRがユースケースのすべての要件に対応していない場合は、説明を追加してください。 ## 背景 説明: - そのデザインがアーキテクチャ的に重要である理由 - ADR の必要性（単純な問題解決と PR ではなく） - 高レベルの設計アプローチ（詳細は以下の提案設計に記載） ## 提案設計 設計の詳細（可能な限り実装には触れない） 概要： - 影響を受ける（変更される）サービス／モジュール - 追加される新規サービス／モジュール - モデルおよびDTOへの影響（変更／追加／削除） - APIへの影響（変更／追加／削除） - 一般的な構成への影響​​（新規セクションの設定、変更／追加／削除） - DevOpsへの影響 ## 考慮事項 ADRの議論において生じた代替案、懸念事項、付随的または関連する問題、疑問点を文書化してください。 それらが解決または緩和されたかどうか、またどのように緩和されたかを記載してください。 ## 決定事項 合意された重要な実装の詳細、注意事項、将来的な検討事項、残存または延期された設計上の課題を文書化します。 提案された設計で満たされていない要件があれば、それを文書化します。 ## その他の関連 ADR 機能のサブコンポーネントの設計上の決定、この設計の結果として非推奨となった設計など、関連する ADR をすべてリストします。 形式: - \[ADRタイトル\]\(URL\) - 関連性 ## 参考文献 追加の参考文献を列挙してください。 形式: - \[タイトル\]\(URL\) ================================================ FILE: locales/ja/テンプレート/Jeff TyreeとArt Akermanによる意思決定記録テンプレート/.locale-peer-id ================================================ f4ca0a94124a91279e1929ea23ab864d ================================================ FILE: locales/ja/テンプレート/Jeff TyreeとArt Akermanによる意思決定記録テンプレート/index.md ================================================ # Jeff TyreeとArt Akermanによる意思決定記録テンプレート これは、[Capital One FinancialのJeff TyreeとArt Akerman著『Architecture Decisions: Demystifying Architecture』](https://www.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf)に掲載されているアーキテクチャ意思決定記述テンプレートです。 * **課題**: 取り組んでいるアーキテクチャ設計上の課題について説明し、なぜ今その課題に取り組むのかという疑問を残さないようにしてください。最小限のアプローチに従い、ライフサイクルの様々な段階で対処が必要な課題のみを取り上げ、文書化してください。 * **決定**: アーキテクチャの方向性、つまり選択した立場を明確に述べてください。 * **ステータス**: 決定のステータス（保留中、決定済み、承認済みなど） * **グループ**: 統合、プレゼンテーション、データといった単純なグループ分けを用いて、一連の意思決定を整理することができます。また、John Kyaruzi氏とJan van Katwijk氏による、イベント、カレンダー、場所といったより抽象的なカテゴリを含む、より洗練されたアーキテクチャ[オントロジー](https://ja.wikipedia.org/wiki/%E3%82%AA%E3%83%B3%E3%83%88%E3%83%AD%E3%82%B8%E3%83%BC_%28%E6%83%85%E5%A0%B1%E7%A7%91%E5%AD%A6%29)を使用することもできます。例えば、このオントロジーを用いて、システムが情報を必要とする事象に対応する意思決定を「イベント」の下にグループ化することができます。 * **前提**: 意思決定を行う環境における根本的な前提（コスト、スケジュール、テクノロジーなど）を明確に記述します。環境上の制約（一般的なテクノロジー標準、エンタープライズアーキテクチャ、一般的に採用されているパターンなど）によって、検討できる選択肢が制限される可能性があることに注意してください。 * **制約**: 選択された代替案（決定）が環境にもたらす可能性のある追加の制約をすべて記録します。 * **立場**: 検討した立場（実行可能な選択肢または代替案）をリストアップします。これらの説明には長い説明が必要になることが多く、モデルや図表が必要になる場合もあります。これは網羅的なリストではありません。しかし、最終レビュー中に「…について検討しましたか？」という質問は避けたいものです。これは信頼性の低下を招き、他のアーキテクチャ上の決定に疑問を投げかけることになります。このセクションは、他者の意見を聞いたことを確認するのにも役立ちます。他者の意見を明示的に述べることで、その支持者をあなたの決定に賛同させることができます。 * **論拠**: 実装コスト、総所有コスト、市場投入までの時間、必要な開発リソースの可用性など、あるポジションを選択した理由を概説します。これは、おそらく決定自体と同じくらい重要です。 * **影響**: REMAPメタモデル（注：Representation and Mainte nance of Process Knowledge）が示すように、決定には多くの影響が伴います。例えば、ある決定によって、別の決定を行う必要性が生じたり、新しい要件を作成したり、既存の要件を変更したり、環境に新たな制約が生じたり、顧客とスコープやスケジュールの再交渉が必要になったり、スタッフの追加トレーニングが必要になったりする可能性があります。決定の影響を明確に理解し、明確に伝えることは、承認を得てアーキテクチャ実行のロードマップを作成する上で非常に効果的です。 * **関連する決定**: 多くの決定は関連していることは明らかであり、それをここで列挙します。ただし、実際には、トレーサビリティマトリックス、決定木、またはメタモデルの方が有用であることがわかりました。メタモデルは、複雑な関係を図式で示すのに役立ちます（[Rose](https://www.ibm.com/docs/ja/rsm/7.5.0?topic=migration-rational-rose-model)モデルなど）。 * **関連する要件**: 決定はビジネス主導で行う必要があります。説明責任を示すために、決定を目標または要件に明示的にマッピングします。これらの関連要件をここで列挙することもできますが、私たちの経験上、トレーサビリティマトリックスを参照する方が便利であることがわかりました。各アーキテクチャ決定が各要件の達成にどのように貢献しているかを評価し、さらにすべての決定において要件がどの程度達成されているかを評価できます。ある決定が要件の達成に貢献しない場合は、その決定は行わないでください。 * **関連成果物**: この決定が影響を与える関連するアーキテクチャ、設計、またはスコープに関するドキュメントの一覧。 * **関連原則**: 企業内で合意済みの原則がある場合は、決定がそれらの原則の1つ以上と整合していることを確認してください。これにより、ドメインまたはシステム間の整合性を確保できます。 * **メモ**: 意思決定プロセスには数週間かかる場合があるため、共有化プロセス中にチームが議論したメモや問題点を記録しておくことが有用であることがわかりました。 ================================================ FILE: locales/ja/テンプレート/Michael Nygard による意思決定記録テンプレート/.locale-peer-id ================================================ b1e90e6556c1c8f1e2eb3ac22c8c5077 ================================================ FILE: locales/ja/テンプレート/Michael Nygard による意思決定記録テンプレート/index.md ================================================ # Michael Nygardによる意思決定記録テンプレート これは、[アーキテクチャに関する意思決定の文書化 - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) に掲載されているテンプレートです。 ADR ファイルの管理には [adr-tools](https://github.com/npryce/adr-tools) を使用できます。 各 ADR ファイルに次のセクションを記述します。 # タイトル ## ステータス 提案済み、承認済み、却下済み、非推奨、置き換え済みなど、どんなステータスか？ ## 背景 この決定または変更の動機となっている問題は何か？ ## 決定 提案または実施する変更は何か？ ## 影響 この変更によって、何が簡単になり、何が難しくなるか？ ================================================ FILE: locales/ja/テンプレート/Planguageを使用した意思決定記録テンプレート/.locale-peer-id ================================================ bb37e19df57d398b0704d6bd30ee6e6d ================================================ FILE: locales/ja/テンプレート/Planguageを使用した意思決定記録テンプレート/index.md ================================================ # Planguageを使用した意思決定記録テンプレート https://www.iaria.org/conferences2012/filesICCGI12/Tutorial%20Specifying%20Effective%20Non-func.pdf も参照 ## Planguageとは? Planguage は、以下のキーワードを使用する計画言語です。 * タグ: 一意で永続的な識別子 * 要点: 要件または対象となる領域の簡潔な要約 * 要件: 要件自体の詳細を記述したテキスト * 根拠: 要件を正当化する根拠 * 優先度: 優先度とリソースの要求に関する記述 * 利害関係者: 要件によって実質的に影響を受ける関係者 * ステータス: 要件のステータス (ドラフト、レビュー済み、コミット済みなど) * 所有者: 要件の実装責任者 * 作成者: 要件を作成した人物 * リビジョン: 記述のバージョン番号 * 日付: 最新のリビジョン日 * 前提条件: 現在または将来、不正確であれば問題を引き起こす可能性のあるもの * リスク: 誤動作、遅延、その他の悪影響を引き起こす可能性のあるもの * 定義: 用語の定義 (用語集を使用することをお勧めします) ================================================ FILE: locales/ja/テンプレート/index.md ================================================ # Decision record templates * [Decision record template by Jeff Tyree and Art Akerman](decision-record-template-by-jeff-tyree-and-art-akerman) * [Decision record template by Michael Nygard](decision-record-template-by-michael-nygard) * [Decision record template by EdgeX](decision-record-template-by-edgex) * [Decision record template for Alexandrian pattern](decision-record-template-for-alexandrian-pattern) * [Decision record template for business case](decision-record-template-for-business-case) * [Decision record template of the MADR Project](decision-record-template-of-the-madr-project) * [Decision record template using Planguage](decision-record-template-using-planguage) ================================================ FILE: locales/ja/テンプレート/madrプロジェクトの意思決定記録テンプレート/.locale-peer-id ================================================ 0a9f88e5cda952db0a82d071f585d090 ================================================ FILE: locales/ja/テンプレート/madrプロジェクトの意思決定記録テンプレート/index.md ================================================ # [解決された問題と解決策の短いタイトル] * ステータス: [提案 | 却下 | 承認 | 非推奨 | … | [ADR-0005](0005-example.md) に置き換え]等 * 決定者: [決定に関与した全員をリストアップ] * 日付: [決定が最後に更新された YYYY-MM-DD] 技術的なストーリー: [説明 | チケット/課題の URL] ## 背景と問題提起 [背景と問題提起を、例えば2～3文で自由記述してください。問題を質問形式で明確に表現してもよいでしょう。] ## 意思決定推進者 * [推進者1、例: 力、直面している懸念事項、…] * [推進者2、例: 力、直面している懸念事項、…] * … ## 検討対象となるオプション * [オプション 1] * [オプション 2] * [オプション 3] * … ## 意思決定結果 選択された選択肢：「[選択肢 1]」。[理由。例：k.o.基準を満たす唯一の選択肢、意思決定要因 | フォースフォースを解決する | … | が最善の結果をもたらす（下記参照）]。 ### 肯定的な結果 * [例：品質特性の満足度の向上、フォローアップの意思決定が必要、 …] * … ### 否定的な結果 * [例：品質特性の低下、フォローアップの意思決定が必要、 …] * … ## オプションの長所と短所 ### [オプション 1] [例 | 説明 | 詳細情報へのポインタ | …] * 良い。なぜなら [議論 a] * 良い。なぜなら [議論 b] * 悪い。なぜなら [議論 c] * … ### [オプション 2] [例 | 説明 | 詳細情報へのポインタ | …] * 良い。なぜなら [議論 a] * 良い。なぜなら [議論 b] * 悪い。なぜなら [議論 c] * … ### [オプション 3] [例 | 説明 | 詳細情報へのポインタ | …] * 良い。なぜなら [議論 a] * 良い。なぜなら [議論 b] * 悪い。なぜなら [議論 c] * … ## リンク * [リンクの種類] [ADR へのリンク] * … ================================================ FILE: locales/ja/テンプレート/アレクサンドリアパターンの意思決定記録テンプレート/.locale-peer-id ================================================ f33e4eb0409f956de201b791749dc9aa ================================================ FILE: locales/ja/テンプレート/アレクサンドリアパターンの意思決定記録テンプレート/index.md ================================================ # アレクサンドリアパターンの意思決定記録テンプレート ## はじめに * プロローグ（要約） * 議論（背景） * 解決策（意思決定） * 結果（結果） ## 詳細 ## * プロローグ（概要） * 宣言の要約： * （ユースケース）の状況において、
（懸念事項）に直面し、
（品質）を達成するために、
（欠点）を受け入れ、
（オプション）を決定しました。 * 議論（背景） * 影響する力（技術的、政治的、社会的、プロジェクト的）についての説明をする。 * 解決しようとしている問題を説明するストーリーを書く。 * 解決策 * この決定がどのように問題を解決するかを説明する。 * 結果 * 決定の長期的な結果について説明する。 * うまくいったか、うまくいかなかったか、変更されたか、アップグレードされたかなどについて説明する。 ================================================ FILE: locales/ja/テンプレート/ビジネスケース用意思決定記録テンプレート/.locale-peer-id ================================================ f6d1fb662640a00f4c66c586233dead9 ================================================ FILE: locales/ja/テンプレート/ビジネスケース用意思決定記録テンプレート/index.md ================================================ # ビジネスケース用意思決定記録テンプレート このADRテンプレートは、判断基準、候補、コストなど、意思決定に関するビジネスケースの作成に重点を置いています。 ## トップレベル * 役職 * ステータス * 評価基準 * 検討すべき候補者 * 各候補者の調査と分析 * 基準を満たしているか満たしていないか、またその理由 * コスト分析 * SWOT分析 * 意見とフィードバック * 推薦 ## ロウレベルの詳細な説明 **タイトル**: * Gitのコミットメッセージのように、50文字未満の短いフレーズ。 **ステータス**: * 提案、承認、拒否、非推奨、置き換えなどのいずれか。 **評価基準**: * 概要: 発見したい内容とその理由を簡潔に説明してください。 * 詳細 **検討すべき候補** * 要約：候補をどのように発見したかを簡潔に説明し、外れ値があれば注意喚起してください。 * すべての候補と関連する選択肢をリストアップしてください。潜在的な解決策として何を評価していますか？ * 詳細 **各候補者の調査と分析** * 要約：調査方法を簡潔に説明し、パターン、クラスター、外れ値に注目してください。 * 基準を満たしているか満たしていないか、またその理由を記載してください。 * 要約 * 詳細 * コスト分析 * 要約 * 例 * ライセンス（契約合意や法的義務など） * トレーニング（スキルアップや変更管理など） * 運用（サポートや保守など） * 計測（帯域幅やCPU使用率など） * SWOT分析 * 要約 * 強み * 弱み * 機会 * 脅威 * 社内の意見とフィードバック * 要約 * 例 * チームによる（できれば担当者が作成） * 他のステークホルダーからの意見 * 品質特性、すなわち横断機能要件 * 外部からの意見とフィードバック * 要約 * 意見提供者は誰ですか？ * 他に検討した候補は何ですか？ * 何を作成していますか？ * 例 * B2B または B2C * 社外向けまたは従業員専用 * デスクトップまたはモバイル * パイロット版または本番環境 * モノリス版またはマイクロサービス版 * 候補をどのように評価しましたか？ * なぜそれを選んだのですか？ * その後、どのような変化がありましたか？ * 例 * 選んだもののパフォーマンスはどうですか？ * 実際の運用環境におけるユーザートラフィックの何パーセントが選んだものを経由していますか？ * 継続的デリバリーパイプライン、コンテンツ管理システム、分析機能、メトリクスなど、どのような統合が行われていますか？ * 現在の知見を踏まえて、人々にどのようなアドバイスをしますか？ * 逸話 **推奨事項**: * 概要 * 詳細 ================================================ FILE: locales/ja/ドキュメント/.locale-peer-id ================================================ abc7c72d426bc75e40b25a44ae37ce73 ================================================ FILE: locales/ja/ドキュメント/aws-adr-process/.locale-peer-id ================================================ 7d4adf16004ca42546dee49922ae4ccf ================================================ FILE: locales/ja/ドキュメント/aws-adr-process/index.md ================================================ # AWSのADRプロセス https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html ADR（Architectural Decision Record）とは、構築予定のソフトウェアアーキテクチャの重要な側面について、チームが行う選択を記述した文書です。各ADRには、アーキテクチャー決定、そのコンテキスト、およびその結果が記述されます。ADRには状態があるため、ライフサイクルに従います。ADRの例については、付録を参照のこと。 ADR プロセスは、アーキテクチャの決定記録のコレクションを出力します。このコレクションにより、決定ログが作成されます。決定ログは、プロジェクトのコンテキストのほか、詳細な実装および設計情報を提供します。プロジェクトメンバーは、各 ADR の見出しに目を通し、プロジェクトの概要を把握します。そして、ADRを読み、プロジェクトの実装やアーキテクチャの選択について深く掘り下げます。 チームがADRを受け入れると、そのADRは不変のものとなる。新たな洞察により異なる決定が必要になった場合、チームは新しいADRを提案する。チームが新しいADRを受け入れると、それは以前のADRに取って代わります。 ## ADRプロセスの範囲 プロジェクトメンバは、ソフトウェアプロジェクトやプロダクトに影響を与える、アーキテクチャ的に重要な決定ごとにADRを作成すべきです。これには以下のRichardsとFordの2020が含まれます。 * 構造（例えば、マイクロサービスなどのパターン） * 非機能要件（セキュリティ、高可用性、耐障害性） * 依存関係（コンポーネントの結合） * インターフェース（APIと公開コントラクト） * 構築手法（ライブラリ、フレームワーク、ツール、プロセス） * 機能要件と非機能要件は、ADRプロセスへの最も一般的なインプットである。 ## ADRコンテキスト チームが ADR の必要性を認識すると、チーム メンバーがプロジェクト全体のテンプレートに基づいて ADR の作成を開始します (サンプル テンプレートについては、ADR GitHub organization を参照してください)。テンプレートを使用すると ADR の作成が簡単になり、ADR にすべての関連情報が確実に取り込まれるようになります。各 ADR では少なくとも、決定のコンテキスト、決定自体、プロジェクトとその成果物に対する決定の結果を定義する必要があります (これらのセクションの例については、付録を参照してください)。ADR 構造の最も強力な側面の 1 つは、チームがどのように決定を実装したかではなく、決定の理由に焦点を当てていることです。チームが決定を下した理由を理解することで、他のチーム メンバーがその決定を採用しやすくなり、意思決定プロセスに関与していない他のアーキテクトが将来その決定を覆すことを防ぐことができます。 ## ADR導入プロセス チームメンバーは誰でも ADR を作成できますが、ADR の所有権はチームで明確に定義する必要があります。ADR の所有者である各作成者は、ADR のコンテンツを積極的に維持管理し、共有する必要があります。この所有権を明確にするため、このガイドでは以降のセクションでは ADR 作成者を ADR 所有者（ADR オーナー）と呼びます。他のチームメンバーはいつでも ADR に貢献できます。チームが ADR を承認する前に ADR の内容が変更された場合は、所有者がその変更を承認する必要があります。 チームがアーキテクチャ上の決定とその所有者を特定した後、ADR オーナーはプロセスの開始時に **提案済み** 状態の ADR を提供します。提案済み状態の ADR はレビューの準備が整っています。 ADRオーナーは、ADRのレビュープロセスを開始します。ADRレビュープロセスの目的は、チームがADRを承認するか、修正が必要と判断するか、あるいは却下するかを決定することです。所有者を含むプロジェクトチームがADRをレビューします。レビュー会議は、ADRを読むための専用の時間枠を設けることから始めます。平均10～15分あれば十分です。この時間内に、各チームメンバーはドキュメントを読み、不明な点があればコメントや質問を追加します。レビューフェーズの後、ADRオーナーは各コメントを読み上げ、チームと話し合います。 チームがADRを改善するためのアクションポイントを見つけた場合、ADRの状態は**提案済み**のままとなります。ADRオーナーはアクションを策定し、チームと協力して各アクションに担当者を追加します。各チームメンバーはアクションポイントに貢献し、解決することができます。レビュープロセスのスケジュール変更はADRオーナーの責任です。 チームはADRを拒否することもできます。この場合、ADRオーナーは拒否の理由を追加し、同じトピックに関する将来の議論を回避します。オーナーはADRの状態を「**拒否**」に変更します。 チームがADRを承認する場合、オーナーはタイムスタンプ、バージョン、関係者リストを追加します。その後、オーナーは状態を「**承認**」に更新します。 ADR とそれによって作成される意思決定ログは、チームによる意思決定を表し、すべての意思決定の履歴を提供します。チームは、可能な限り、コードレビューとアーキテクチャレビューの際に ADR を参照資料として使用します。コードレビュー、設計タスク、実装タスクの実行に加えて、チームメンバーは製品の戦略的な意思決定について ADR を参照する必要があります。 グッドプラクティスとして、すべてのソフトウェア変更はピアレビューを受け、少なくとも 1 回の承認を得る必要があります。コードレビュー中に、コードレビュー担当者が 1 つ以上の ADR に違反する変更を発見する場合があります。この場合、レビュー担当者はコード変更の作成者にコードの更新を依頼し、ADR へのリンクを共有します。作成者がコードを更新すると、ピアレビュー担当者によって承認され、メインのコードベースにマージされます。 ## ADRレビュープロセス チームは、ADR を承認または却下した後は、変更不可能なドキュメントとして扱う必要があります。既存の ADR を変更するには、新しい ADR を作成し、新しい ADR のレビュープロセスを確立し、ADR を承認する必要があります。チームが新しい ADR を承認した場合、オーナーは古い ADR の状態を **置換済み** に変更する必要があります。 ================================================ FILE: locales/ja/ドキュメント/decision-sustainability-criteria/.locale-peer-id ================================================ 71d59ed566ae148b8bf42331a84754ac ================================================ FILE: locales/ja/ドキュメント/decision-sustainability-criteria/index.md ================================================ # 意思決定の持続可能性基準 意思決定の持続可能性を詳細に定義するために、5 つの主要な基準を導き出しました。 ## 戦略的 意思決定において、戦略的な結果を検討する人は、意思決定の長期的な影響（例えば、将来の運用や保守の取り組みなど）を考慮する必要があります。 ## 測定可能で管理可能 意思決定の成果は、客観的な基準、理想的には数値基準（例えば、品質属性シナリオやワークショップ4 で普及するようなもの）に基づいて、時間の経過とともに測定・評価できます。すべてのきめ細かな意思決定を網羅することは不可能であるため、アーキテクトは意思決定の粒度をある程度の詳細レベル（設計クラスの作成など）に制限する必要があります。これにより、意思決定の持続可能性が向上し、トレーサビリティのリンク数が減少します。さらに、意思決定間の依存関係の数を制限することで、変更による波及効果を軽減できます。 ## 達成可能かつ現実的 問題に対するソリューションの適合根拠は、実用的に選択し、明確にする必要があります。例えば、アーキテクトは、過剰なエンジニアリングや不足したエンジニアリングを避けるよう配慮した（つまり、「十分に良い」アプローチを適用すべきである）ことを示します。 ## 要件に基づいているか 意思決定は、ドメイン固有の計の経験とコンテキストに基づいて行う必要があります。社内環境だけでなく、開発チームの現在のスキル、トレーニング予算、プロセスなど、プロジェクトの要件と制約も考慮する必要があります。 ## 時代を超えられるか 意思決定は、すぐに時代遅れになる可能性が低い経験と知識に基づいて行うべきです。例えば、アーキテクトはプラットフォームに依存しないアーキテクチャパターンや戦略を選択します。 ================================================ FILE: locales/ja/ドキュメント/file-name-conventions-for-adrs/.locale-peer-id ================================================ 89116b5647aa1e53186f3c44b5a284a0 ================================================ FILE: locales/ja/ドキュメント/file-name-conventions-for-adrs/index.md ================================================ # ファイル名の命名規則 一般的なテキストファイルを使用してADRを作成する場合は、独自のADRファイル名の命名規則を設定することをお勧めします。 特定の形式のファイル名の命名規則を使用することをお勧めします。 例： * データベース選定.md * タイムスタンプフォーマット.md * パスワード管理.md * 例外処理.md ファイル名の命名規則： * ファイル名は名詞で終わらせます。これは読みやすさを向上させます。 * ファイル名には日本語と必要に応じてダッシュを使用します（このリポジトリと同じです）。これは読みやすさとシステムの使いやすさのバランスです。 * 拡張子はmarkdownです。これは書式設定を容易にするのに役立ちます。 ================================================ FILE: locales/ja/ドキュメント/guidelines-to-achieve-sustainable-decisions/.locale-peer-id ================================================ 934d1c42a693fe004cd8bf8f5ecb97e6 ================================================ FILE: locales/ja/ドキュメント/guidelines-to-achieve-sustainable-decisions/index.md ================================================ # 持続可能な意思決定を実現するためのガイドライン 私たちは、この作業を通して、持続可能な意思決定を実現するためのガイドラインと評価基準となる以下の教訓を学びました。 1. 初期の意思決定文書には、無駄を省いたミニマリスト的なアプローチを採用する。 2. 対象アーキテクチャの文書化と理解に十分関連する重要な意思決定をすべて優先順位付けし、記録する。 3. 特に重要な意思決定については、初期作業が完了した後（つまり、意思決定者がアーキテクチャ上の意思決定に満足し、これらの意思決定をすぐに修正する必要がないと確信した後）にのみ、本格的なテンプレートを使用して詳細を記述する。 4. ステップ1で作成した簡潔なバージョンを、適切な粒度で文書化された意思決定の短縮版として使用し、詳細な意思決定だけでなく、些細な意思決定や明白な意思決定についても概要を示す。 5. 可能な限り、ガイダンスモデルやその他の情報源から得られる既存のアーキテクチャに関する知識を活用します。これらの知識をレビュー・拡張し、具体的な意思決定のコンテキストに適合させます。 6. 意思決定と要件、そしてアーキテクチャ設計／実装との間にトレーサビリティがしっかりと繋がっていることを確認する。 7. 変更後にトレーサビリティの繋がりが同期されていることを確認するために、自動化された整合性チェックを提供する。意思決定と他のソフトウェア成果物との間の依存関係の数を制限する。 8. 根拠の紐づいたガイドラインを、結果的かつ強力に適用する。このガイドラインは、合理性を示すものであるため、意思決定文書の中で最も重要な部分。 ================================================ FILE: locales/ja/ドキュメント/how-to-start-using-adrs/.locale-peer-id ================================================ 8196518140224596af99a46d512feba3 ================================================ FILE: locales/ja/ドキュメント/how-to-start-using-adrs/index.md ================================================ # ADR の始め方 ADR の活用を始めるには、以下の点についてチームメンバーと話し合ってください。 意思決定の特定: * どの程度ADに緊急性と重要性があるのか * 今すぐ行う必要があるか、それとも、詳細が判明するまで待つことができるか * 個人および集団の経験。そして広く認められた設計手法やプラクティス。これらは意思決定の特定に役立ちます。 * 理想を言うと、プロダクトの ToDo リストを補完する、意思決定 ToDo リストを保守できればよいです。 意思決定： * 意思決定手法には、数多くの手段が存在します。例えば、ダイアログマッピングなど一般的な手法とソフトウェアアーキテクチャ特有の手法の両方があります。 * グループによる意思決定は活発に研究されています。 意思決定の制定と執行： * AD はソフトウェア設計で使用されるため、システムの投資者、開発者、運用者などの関係者に伝達され、承認される必要があります。 * アーキテクチャ的に明確なコーディングスタイルと、アーキテクチャ上の懸念事項と意思決定に焦点を当てたコードレビューは、共に行われるべき実践です。 * ソフトウェアの大きな変革においてソフトウェアシステムを近代化する際にも、AD は（再）検討する必要があります。 意思決定の共有（オプション）： * 多くのADはプロジェクト間で繰り返し発生します。 * したがって、良いものも悪いものも含めた過去の意思決定に関する経験は、明白な知識管理戦略をとる際に、貴重な再利用可能な資産となり得ます。 意思決定のドキュメント化： * 意思決定を記録するためのテンプレートやツールは数多く存在します。 * アジャイルコミュニティ（M. NygardのADRなど）を参照してください。 * 従来のソフトウェアエンジニアリングおよびアーキテクチャ設計プロセス（IBM UMFやCapitalOneのTyreeとAkermanが提案したテーブルレイアウトなど）を参照してください。 詳細はこちら： * 上記の手順は、Wikipedia の [Architectural Decision（英語記事）](https://en.wikipedia.org/wiki/Architectural_decision) の項目から引用したものです。 ================================================ FILE: locales/ja/ドキュメント/how-to-start-using-adrs-with-git/.locale-peer-id ================================================ d6fb3c7d91f95003163e694e74058e9d ================================================ FILE: locales/ja/ドキュメント/how-to-start-using-adrs-with-git/index.md ================================================ # Git で ADR を使い始める方法 Git によるバージョン管理をしている場合、ソースコードを含む一般的なソフトウェアプロジェクトで Git で ADR を使い始める手順は以下のとおりです。 ADR ファイル用のディレクトリを作成します。 ```sh $ mkdir adr ``` 各 ADR に対して、`database.txt` などのテキスト ファイルを作成します。 ```sh $ vi database.txt ``` ADRには何でも書き込んでください。このリポジトリのテンプレートを参考に、アイデアを得てください。 ADRをGitリポジトリにコミットしてください。 ================================================ FILE: locales/ja/ドキュメント/how-to-start-using-adrs-with-tools/.locale-peer-id ================================================ 1a5a03dd6f20cea9f78fb4655a9a7f87 ================================================ FILE: locales/ja/ドキュメント/how-to-start-using-adrs-with-tools/index.md ================================================ ## ツールを使ってADRを使い始める方法 ツールを使ってADRを使い始める方法は自由です。 例: * Googleドライブとオンライン編集を使いたい場合は、GoogleドキュメントまたはGoogleスプレッドシートを作成できます。 * Gitなどのソースコードバージョン管理を使いたい場合は、ADRごとにファイルを作成できます。 * Atlassian Jiraなどのプロジェクト計画ツールを使いたい場合は、ツールの計画トラッカーを使用できます。 * MediaWikiなどのWikiを使いたい場合は、ADR Wikiを作成できます。 ================================================ FILE: locales/ja/ドキュメント/suggestions-for-writing-good-adrs/.locale-peer-id ================================================ dc1a294e76821d6d3b086a2b17988427 ================================================ FILE: locales/ja/ドキュメント/suggestions-for-writing-good-adrs/index.md ================================================ ## 良いADR作成のための提案 良いADRの特徴： * 根拠を示すこと: 特定のADを実施する理由を説明します。これには、「背景」（下記参照）、様々な選択肢の長所と短所、機能の比較、費用対効果の検討などが含まれます。 * 具体的であること: 各ADRは、複数のADではなく、1つのADについて記述する必要があります。 * タイムスタンプ: ADRの各項目がいつ作成されたかを明確にします。これは、コスト、スケジュール、規模感など、時間の経過とともに変化する可能性のある要素において特に重要です。 * 変更不可であること: ADR内の既存の情報を変更しないでください。代わりに、新しい情報を追加してADRを修正するか、新しいADRを作成して既存のADRを置き換えます。 ADRにおける適切な「背景」セクションの特徴： * 組織の状況とビジネス上の優先事項を説明する。 * チームの社会的・スキル構成に基づいた根拠と考慮事項を記載する。 * 関連する長所と短所を記載し、ニーズと目標に沿った言葉で説明する。 ADRにおける優れた「結果」セクションの特徴： * 意思決定の結果として何が起こるかを説明します。これには、影響、成果、アウトプット、フォローアップなどが含まれます。 * 後続のADRに関する情報も含めます。1つのADRが、より大きな包括的な選択を行い、それがさらにより小さな意思決定の必要性を生み出すなど、より多くのADRの必要性を引き起こすことは比較的よくあります。 * 事後レビュープロセスがあれば含めます。チームが1か月後に各ADRをレビューし、ADRの情報と実際の状況を比較することで、学習と成長を図るのが一般的です。 新しいADRが以前のADRに代わる場合があります： * 以前のADRを置き換える、または無効にするADが作成された場合は、新しいADRを作成する必要があります。 ================================================ FILE: locales/ja/ドキュメント/teamwork-advice-for-adrs/.locale-peer-id ================================================ 875a7715e592ceb45eac5e155ee16318 ================================================ FILE: locales/ja/ドキュメント/teamwork-advice-for-adrs/index.md ================================================ # ADR向けチームワークアドバイス チームで意思決定記録の活用を検討されている方は、ここの多くのチームとの協働を通して得られたアドバイスが参考になります。 「何を」ではなく「なぜ」を話し合うことで、チームメイトを導く機会が得られます。例えば、意思決定記録は、チームがよりスマートに考え、より効果的なコミュニケーションを図るための手段です。しかし、事後的に強制的に書類作成を求められるような意思決定記録では、意味がありません。 チームによっては、「ADR」という略語よりも「決定」という名称を好むところもあります。とあるチームでは、「decisions」というディレクトリを使うことで、まるで電球が点いたかのように、ベンダーの決定、計画の決定、スケジュールの決定など、より多くの情報をディレクトリに入力し始めました。これらの情報はすべて同じテンプレートを使用できます。私たちは、略語（「ADR」）よりも単語（「decisions」）の方が学習が早くなる、また「record」という単語を削除することで作業中のドキュメントを作成する意欲が高まる、そして一部の開発者やマネージャーは「architecture」という単語を嫌う、という仮説を立てています。 理論上、ADRは不変であることが理想的です。しかし実際、私たちのチームでは可変性の方がうまく機能していました。新しい情報を既存のADRに挿入し、日付スタンプと、決定後に情報が届いたことを示すメモを添えます。このようなアプローチにより、全員が更新できる「生きた文書」が生まれます。例えば典型的な更新の例でいうと、新しいチームメンバー、新しい提供物、実際の使用してみた結果、あるいはベンダーの機能、価格プラン、ライセンス契約などのサードパーティの事後的な変更などによって情報を入手した場合です。 ================================================ FILE: locales/ja/ドキュメント/what-is-an-architecture-decision-record/.locale-peer-id ================================================ 020ff535ed1a3347a265209291e756b6 ================================================ FILE: locales/ja/ドキュメント/what-is-an-architecture-decision-record/index.md ================================================ ## アーキテクチャ決定記録とは？ **アーキテクチャ決定記録** (ADR) は、重要なアーキテクチャ上の決定とその背景および結果を記録した文書です。 **アーキテクチャ決定** (AD) は、重要な要件に対応するソフトウェア設計上の選択です。 **アーキテクチャ決定ログ** (ADL) は、特定のプロジェクト (または組織) のために作成および維持されるすべての ADR の集合です。 **アーキテクチャ上重要な要件** (ASR) は、ソフトウェアシステムのアーキテクチャに測定可能な影響を与える要件です。 これらはすべて、**アーキテクチャ知識管理** (AKM) のトピックに含まれます。 このドキュメントの目的は、ADR の概要、作成方法、および詳細情報の参照先を簡単に説明することです。 略語： * **AD**: アーキテクチャ決定 * **ADL**: アーキテクチャ決定ログ * **ADR**: アーキテクチャ決定記録 * **AKM**: アーキテクチャ知識管理 * **ASR**: アーキテクチャ上重要な要件 ================================================ FILE: locales/ja/翻訳注.txt ================================================ 「ADR」の訳語はAWSやAzureに従って「アーキテクチャ決定レコード」とする。 AWS： https://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/architectural-decision-records/adr-process.html Azure： https://learn.microsoft.com/ja-jp/azure/well-architected/architect-role/architecture-decision-record ================================================ FILE: locales/ko/.locale-peer-id ================================================ 0b59cb46e5817b414866ebe33f4d7bcf ================================================ FILE: locales/ko/서류/.locale-peer-id ================================================ abc7c72d426bc75e40b25a44ae37ce73 ================================================ FILE: locales/ko/서류/adr-사용을-시작하는-방법/.locale-peer-id ================================================ 8196518140224596af99a46d512feba3 ================================================ FILE: locales/ko/서류/adr-사용을-시작하는-방법/index.md ================================================ # ADR 사용을 시작하는 방법 ADR 사용을 시작하려면 팀원과 이러한 영역에 대해 이야기하세요. 결정 식별: * AD는 얼마나 긴급하고 중요한가요? * 지금 만들어야 합니까, 아니면 더 많은 정보가 알려질 때까지 기다릴 수 있습니까? * 개인 및 집단 경험뿐만 아니라 인정된 설계 방법 및 관행도 의사 결정에 도움이 될 수 있습니다. * 제품의 할일 목록을 보완하는 의사결정의 할일 목록을 이상적으로 유지하세요. 의사결정: * 일반적인 의사결정 기술과 소프트웨어 아키텍처 특정 기술(예: 대화 매핑) 모두 다양한 의사결정 기술이 존재합니다. * 그룹의사결정은 활발한 연구주제입니다. 결정 제정 및 집행: * AD는 소프트웨어 설계에 사용됩니다. 따라서 시스템에 자금을 지원하고 개발하고 운영하는 시스템의 이해관계자에게 전달되고 승인되어야 합니다. * 구조적으로 분명한 코딩 스타일과 구조적 관심사 및 결정에 초점을 맞춘 코드 검토는 서로 관련된 두 가지 관행입니다. * 소프트웨어 진화에서 소프트웨어 시스템을 현대화할 때 AD도 (재)고려되어야 합니다. 의사결정 공유(선택사항): * 프로젝트 전반에 걸쳐 많은 AD가 반복됩니다. * 따라서 과거의 좋은 결정과 나쁜 결정에 대한 경험은 명시적 지식 관리 전략을 사용할 때 재사용 가능한 귀중한 자산이 될 수 있습니다. 결정 문서: * 의사결정 캡처를 위한 다양한 템플릿과 도구가 존재합니다. * 민첩한 커뮤니티를 참조하세요. M. Nygard의 ADR. * 전통적인 소프트웨어 엔지니어링 및 아키텍처 설계 프로세스를 참조하세요. IBM UMF와 CapitalOne의 Tyree 및 Akerman이 제안한 테이블 레이아웃. 이상: * 위 단계는 [건축적 결정](https://en.wikipedia.org/wiki/Architectural_decision)에 대한 Wikipedia 항목에서 채택되었습니다. ================================================ FILE: locales/ko/서류/adr을-위한-팀워크-조언/.locale-peer-id ================================================ 875a7715e592ceb45eac5e155ee16318 ================================================ FILE: locales/ko/서류/adr을-위한-팀워크-조언/index.md ================================================ # ADR을 위한 팀워크 조언 팀에서 의사결정 기록 사용을 고려하고 있다면 다음은 여러 팀과 협력하면서 배운 몇 가지 조언입니다. "무엇"을 강요하기보다는 "왜"에 대해 함께 이야기함으로써 팀원을 이끌 수 있는 기회가 있습니다. 예를 들어, 의사 결정 기록은 팀이 더 현명하게 생각하고 더 효과적으로 의사소통할 수 있는 방법입니다. 결정 기록이 사후 강제 서류 요구 사항일 뿐이라면 가치가 없습니다. 일부 팀은 "ADR"이라는 약어보다 "결정"이라는 이름을 더 선호합니다. 일부 팀에서 "결정"이라는 디렉터리 이름을 사용하면 마치 전구가 켜지는 것과 같으며 팀은 공급업체 결정, 계획 결정, 일정 결정 등과 같은 더 많은 정보를 디렉터리에 넣기 시작합니다. 정보는 동일한 템플릿을 사용할 수 있습니다. 우리는 사람들이 약어("ADR")보다 단어("결정")로 더 빨리 배우고 "기록"이라는 단어가 제거되면 진행 중인 문서를 작성하려는 동기가 더 높다고 가정합니다. 일부 개발자와 일부 관리자도 마찬가지입니다. "건축"이라는 단어를 싫어합니다. 이론적으로는 불변성이 이상적입니다. 실제로 우리 팀에서는 가변성이 더 잘 작동했습니다. 날짜 스탬프와 함께 기존 ADR에 새 정보를 삽입하고 결정 후 정보가 도착했다는 메모를 삽입합니다. 이러한 접근 방식은 우리 모두가 업데이트할 수 있는 "살아있는 문서"로 이어집니다. 일반적인 업데이트는 새로운 팀원, 새로운 제품, 실제 사용 결과, 공급업체 기능, 가격 계획, 라이선스 계약 등과 같은 사후 제3자 변경 사항을 통해 정보를 얻는 경우입니다. ================================================ FILE: locales/ko/서류/aws-아키텍처-결정-기록-프로세스/.locale-peer-id ================================================ 7d4adf16004ca42546dee49922ae4ccf ================================================ FILE: locales/ko/서류/aws-아키텍처-결정-기록-프로세스/index.md ================================================ # AWS 아키텍처 결정 기록 프로세스 https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html ADR(아키텍처 결정 기록)은 팀이 구축하려는 소프트웨어 아키텍처의 중요한 측면에 대해 내리는 선택을 설명하는 문서입니다. 각 ADR은 아키텍처 결정, 해당 컨텍스트 및 결과를 설명합니다. ADR에는 상태가 있으므로 수명 주기를 따릅니다. ADR의 예는 부록을 참조하세요. ADR 프로세스는 아키텍처 결정 기록 모음을 출력합니다. 이 컬렉션은 결정 로그를 생성합니다. 결정 로그는 프로젝트 컨텍스트는 물론 자세한 구현 및 설계 정보를 제공합니다. 프로젝트 구성원은 각 ADR의 헤드라인을 훑어보고 프로젝트 상황의 개요를 파악합니다. 그들은 ADR을 읽고 프로젝트 구현과 디자인 선택에 대해 자세히 알아봅니다. 팀이 ADR을 수락하면 변경할 수 없게 됩니다. 새로운 통찰력을 얻기 위해 다른 결정이 필요한 경우 팀은 새로운 ADR을 제안합니다. 팀이 새 ADR을 수락하면 이전 ADR을 대체합니다. ## ADR 프로세스의 범위 프로젝트 구성원은 다음을 포함하여 소프트웨어 프로젝트 또는 제품에 영향을 미치는 구조적으로 중요한 모든 결정에 대해 ADR을 생성해야 합니다(Richards 및 Ford 2020). * 구조(예: 마이크로서비스와 같은 패턴) * 비기능적 요구사항(보안, 고가용성, 내결함성) * 종속성(구성요소 결합) * 인터페이스(API 및 게시된 계약) * 구축 기술(라이브러리, 프레임워크, 도구 및 프로세스) * 기능적 및 비기능적 요구사항은 ADR 프로세스에 대한 가장 일반적인 입력입니다. ## ADR 내용 팀이 ADR의 필요성을 식별하면 팀 구성원은 프로젝트 전체 템플릿을 기반으로 ADR을 작성하기 시작합니다. (예제 템플릿은 ADR GitHub 조직을 참조하세요.) 템플릿은 ADR 생성을 단순화하고 ADR이 모든 관련 정보를 캡처하도록 보장합니다. 최소한 각 ADR은 결정의 맥락, 결정 자체, 프로젝트 및 결과물에 대한 결정의 결과를 정의해야 합니다. (이러한 섹션의 예는 부록을 참조하세요.) ADR 구조의 가장 강력한 측면 중 하나는 팀이 결정을 구현한 방법보다는 결정 이유에 초점을 맞춘다는 것입니다. 팀이 결정을 내린 이유를 이해하면 다른 팀 구성원이 결정을 더 쉽게 채택할 수 있으며 의사 결정 프로세스에 참여하지 않은 다른 설계자가 향후 해당 결정을 뒤집는 것을 방지할 수 있습니다. ## ADR 채택 프로세스 모든 팀 구성원은 ADR을 생성할 수 있지만 팀은 ADR에 대한 소유권 정의를 설정해야 합니다. ADR의 소유자인 각 작성자는 ADR 콘텐츠를 적극적으로 유지하고 전달해야 합니다. 이 소유권을 명확히 하기 위해 이 가이드에서는 다음 섹션에서 ADR 작성자를 ADR 소유자로 지칭합니다. 다른 팀 구성원은 언제든지 ADR에 기여할 수 있습니다. 팀이 ADR을 수락하기 전에 ADR의 내용이 변경되면 소유자는 이러한 변경 사항을 승인해야 합니다. 팀이 아키텍처 결정과 해당 소유자를 식별한 후 ADR 소유자는 프로세스 시작 시 **제안됨** 상태의 ADR을 제공합니다. 제안됨 상태의 ADR은 검토 준비가 되었습니다. 그런 다음 ADR 소유자는 ADR에 대한 검토 프로세스를 시작합니다. ADR 검토 프로세스의 목표는 팀이 ADR을 수락할지, 재작업이 필요하다고 판단할지, ADR을 거부할지 결정하는 것입니다. 소유자를 포함한 프로젝트 팀이 ADR을 검토합니다. 검토 회의는 ADR을 읽기 위한 전용 시간으로 시작해야 합니다. 평균적으로 10~15분이면 충분합니다. 이 시간 동안 각 팀원은 문서를 읽고 설명과 질문을 추가하여 불분명한 주제를 표시합니다. 검토 단계가 끝나면 ADR 소유자는 각 의견을 읽고 팀과 논의합니다. 팀이 ADR을 개선하기 위한 조치 사항을 찾으면 ADR 상태는 **제안됨**으로 유지됩니다. ADR 소유자는 작업을 공식화하고 팀과 협력하여 각 작업에 담당자를 추가합니다. 각 팀원은 액션 포인트에 기여하고 해결할 수 있습니다. 검토 프로세스 일정을 변경하는 것은 ADR 소유자의 책임입니다. 팀은 ADR을 거부하기로 결정할 수도 있습니다. 이 경우 ADR 소유자는 동일한 주제에 대한 향후 논의를 방지하기 위해 거부 이유를 추가합니다. 소유자는 ADR 상태를 **거부됨**으로 변경합니다. 팀이 ADR을 승인하면 소유자는 타임스탬프, 버전 및 이해관계자 목록을 추가합니다. 그런 다음 소유자는 상태를 **Accepted**로 업데이트합니다. ADR과 ADR이 생성하는 결정 로그는 팀이 내린 결정을 나타내고 모든 결정의 기록을 제공합니다. 팀은 가능한 경우 코드 및 아키텍처 검토 중에 ADR을 참조로 사용합니다. 코드 검토, 디자인 작업, 구현 작업을 수행하는 것 외에도 팀 구성원은 제품에 대한 전략적 결정을 위해 ADR에 문의해야 합니다. 모범 사례에 따르면, 각 소프트웨어 변경은 동료 검토를 거쳐야 하며 최소한 한 번의 승인이 필요합니다. 코드 검토 중에 코드 검토자는 하나 이상의 ADR을 위반하는 변경 사항을 발견할 수 있습니다. 이 경우 검토자는 코드 변경 작성자에게 코드 업데이트를 요청하고 ADR에 대한 링크를 공유합니다. 작성자가 코드를 업데이트하면 동료 검토자의 승인을 받고 기본 코드 베이스에 병합됩니다. ## ADR 검토 프로세스 팀은 ADR을 수락하거나 거부한 후에 ADR을 변경할 수 없는 문서로 처리해야 합니다. 기존 ADR을 변경하려면 새 ADR을 생성하고, 새 ADR에 대한 검토 프로세스를 설정하고, ADR을 승인해야 합니다. 팀이 새 ADR을 승인하면 소유자는 이전 ADR의 상태를 **대체됨**으로 변경해야 합니다. ================================================ FILE: locales/ko/서류/git에서-adr-사용을-시작하는-방법/.locale-peer-id ================================================ d6fb3c7d91f95003163e694e74058e9d ================================================ FILE: locales/ko/서류/git에서-adr-사용을-시작하는-방법/index.md ================================================ # git에서 ADR 사용을 시작하는 방법 git 버전 제어를 사용하고 싶다면 소스 코드가 포함된 일반적인 소프트웨어 프로젝트에 대해 git에서 ADR을 사용하는 방법을 소개합니다. ADR 파일용 디렉터리를 만듭니다. ``쉬 $ mkdir 주소 ```` 각 ADR에 대해 `database.txt`와 같은 텍스트 파일을 만듭니다. ``쉬 $ vi 데이터베이스.txt ```` ADR에 원하는 내용을 작성하세요. 아이디어를 얻으려면 이 저장소의 템플릿을 참조하세요. ADR을 git repo에 커밋합니다. ================================================ FILE: locales/ko/서류/도구를-사용하여-adr-사용을-시작하는-방법/.locale-peer-id ================================================ 1a5a03dd6f20cea9f78fb4655a9a7f87 ================================================ FILE: locales/ko/서류/도구를-사용하여-adr-사용을-시작하는-방법/index.md ================================================ # 도구를 사용하여 ADR 사용을 시작하는 방법 원하는 방식으로 도구를 사용하여 ADR을 사용할 수 있습니다. 예를 들어: * Google 드라이브와 온라인 편집을 좋아한다면 Google 문서나 Google 시트를 만들 수 있습니다. * git과 같은 소스 코드 버전 제어를 사용하려는 경우 각 ADR에 대한 파일을 생성할 수 있습니다. * Atlassian Jira와 같은 프로젝트 계획 도구를 사용하고 싶다면 도구의 계획 추적기를 사용할 수 있습니다. * MediaWiki와 같은 위키를 사용하고 싶다면 ADR 위키를 생성할 수 있습니다. ================================================ FILE: locales/ko/서류/아키텍처-결정-기록이란-무엇입니까/.locale-peer-id ================================================ 020ff535ed1a3347a265209291e756b6 ================================================ FILE: locales/ko/서류/아키텍처-결정-기록이란-무엇입니까/index.md ================================================ # 아키텍처 결정 기록이란 무엇입니까? **아키텍처 결정 기록**(ADR)은 컨텍스트 및 결과와 함께 내려진 중요한 아키텍처 결정을 포착하는 문서입니다. **아키텍처 결정**(AD)은 중요한 요구 사항을 해결하는 소프트웨어 설계 선택입니다. **아키텍처 결정 로그**(ADL)는 특정 프로젝트(또는 조직)를 위해 생성 및 유지 관리되는 모든 ADR의 모음입니다. **아키텍처적으로 중요한 요구사항**(ASR)은 소프트웨어 시스템의 아키텍처에 측정 가능한 영향을 미치는 요구사항입니다. 이 모든 것이 **아키텍처 지식 관리**(AKM) 주제 내에 있습니다. 이 문서의 목표는 ADR에 대한 빠른 개요, 생성 방법, 추가 정보를 찾을 수 있는 위치를 제공하는 것입니다. 약어: * **AD**: 아키텍처 결정 * **ADL**: 아키텍처 결정 로그 * **ADR**: 아키텍처 결정 기록 * **AKM**: 아키텍처 지식 관리 * **ASR**: 구조적으로 중요한 요구 사항 ================================================ FILE: locales/ko/서류/의사결정-지속가능성-기준/.locale-peer-id ================================================ 71d59ed566ae148b8bf42331a84754ac ================================================ FILE: locales/ko/서류/의사결정-지속가능성-기준/index.md ================================================ # 의사결정 지속가능성 기준 의사결정 지속가능성을 자세히 정의하기 위해 우리는 다섯 가지 핵심 기준을 도출했습니다. ## 전략적 의사 결정 과정에서 전략적 결과를 검토하는 사람은 의사 결정의 장기적인 영향(예: 향후 운영 및 유지 관리 노력) 등을 고려해야 합니다. ## 측정 및 관리 가능 객관적인 기준, 이상적으로는 수치 기준(예: 품질 속성 시나리오 및 워크숍4에 의해 전파됨)에 따라 시간이 지남에 따라 의사결정 결과를 측정하고 평가할 수 있습니다. 세밀한 결정을 모두 포착하는 것은 불가능하므로 설계자는 결정의 세분성을 특정 세부 수준(예: 디자인 클래스 생성)으로 제한해야 합니다. 이는 보다 지속 가능한 의사 결정과 추적성 링크 감소로 이어질 것입니다. 더욱이, 결정 간의 종속성 수를 제한하면 변경 사항의 파급 효과가 줄어듭니다. ## 달성 가능하고 현실적 문제에 대한 해결책을 맞추는 이론적 근거는 실용적으로 선택되어야 하며 명시적이어야 합니다. 예를 들어, 설계자는 과도한 엔지니어링이나 과소 엔지니어링을 피하기 위해 주의를 기울였다는 것을 나타낼 수 있습니다(즉, "충분히 좋은" 접근 방식을 적용해야 함). ## 요구사항에 뿌리를 두고 있음 의사결정은 도메인별 아키텍처 경험과 맥락을 바탕으로 이루어져야 합니다. 개발 팀의 현재 기술, 교육 예산 및 프로세스를 포함하여 회사 환경은 물론 프로젝트 요구 사항 및 제약 조건도 고려해야 합니다. ## 시대를 초월한 결정은 곧 구식이 되지 않을 경험과 지식을 바탕으로 이루어져야 합니다. 예를 들어 건축가는 플랫폼 중립적인 아키텍처 패턴이나 전술을 선택할 수 있습니다. ================================================ FILE: locales/ko/서류/좋은-adr-작성을-위한-제안/.locale-peer-id ================================================ dc1a294e76821d6d3b086a2b17988427 ================================================ FILE: locales/ko/서류/좋은-adr-작성을-위한-제안/index.md ================================================ # 좋은 ADR 작성을 위한 제안 좋은 ADR의 특징: * 근거: 특정 AD를 수행하는 이유를 설명하십시오. 여기에는 컨텍스트(아래 참조), 다양한 잠재적 선택의 장단점, 기능 비교, 비용/이점 논의 등이 포함될 수 있습니다. * 구체적: 각 ADR은 여러 개의 AD가 아닌 약 하나의 AD여야 합니다. * 타임스탬프: ADR의 각 항목이 기록되는 시기를 식별합니다. 이는 비용, 일정, 확장 등과 같이 시간이 지남에 따라 변경될 수 있는 측면에 특히 중요합니다. * 불변: ADR의 기존 정보를 변경하지 마십시오. 대신, 새로운 정보를 추가하여 ADR을 수정하거나 새로운 ADR을 생성하여 ADR을 대체하십시오. ADR에서 좋은 "컨텍스트" 섹션의 특징은 다음과 같습니다. * 조직의 상황과 비즈니스 우선순위를 설명하세요. * 팀의 사회적 및 기술 구성을 기반으로 한 이론적 근거와 고려 사항을 포함합니다. * 관련된 장단점을 포함하고 귀하의 필요와 목표에 맞는 용어로 설명하십시오. ADR에서 좋은 "결과" 섹션의 특징은 다음과 같습니다. * 결정을 내린 후 어떤 결과가 나오는지 설명하세요. 여기에는 효과, 결과, 결과, 후속 조치 등이 포함될 수 있습니다. * 후속 ADR에 대한 정보를 포함합니다. 하나의 ADR이 더 많은 ADR의 필요성을 촉발하는 것은 비교적 흔한 일입니다. 예를 들어 하나의 ADR이 중대한 선택을 하여 더 작은 결정이 필요한 경우입니다. * 사후 검토 프로세스를 포함합니다. 학습하고 성장하기 위해 팀에서는 한 달 후에 각 ADR을 검토하고 ADR 정보를 실제 사례와 비교하는 것이 일반적입니다. 새로운 ADR은 이전 ADR을 대신할 수 있습니다. * 이전 ADR을 대체하거나 무효화하는 AD가 생성되면 새로운 ADR을 생성해야 합니다. ================================================ FILE: locales/ko/서류/지속-가능한-결정을-달성하기-위한-지침/.locale-peer-id ================================================ 934d1c42a693fe004cd8bf8f5ecb97e6 ================================================ FILE: locales/ko/서류/지속-가능한-결정을-달성하기-위한-지침/index.md ================================================ # 지속 가능한 결정을 달성하기 위한 지침 우리는 지속 가능한 결정을 내리기 위한 지침과 평가가 될 수 있는 다음과 같은 교훈을 얻었습니다. 1. 초기 의사결정 문서화를 위해 간결하고 최소한의 접근 방식을 사용하십시오. 2. 대상 아키텍처를 문서화하고 이해하는 데 충분히 관련된 모든 중요한 결정의 우선순위를 지정하고 포착합니다. 3. 초기 작업이 완료된 후에만 본격적인 템플릿을 사용하여 특히 중요한 결정을 자세히 설명합니다. 즉, 의사 결정자가 아키텍처 결정에 만족하고 이러한 결정을 조만간 수정할 필요가 없다고 확신할 때입니다. ). 4. 1단계의 린/최소 버전을 올바른 세분성 수준의 문서화된 결정의 짧은 버전으로 사용하여 사소하거나 명백한 결정뿐만 아니라 자세한 결정에 대한 개요를 제공합니다. 5. 가능한 한 지침 모델이나 기타 소스에서 얻은 기존 건축 지식을 활용하십시오. 그러한 지식을 검토하고 확장하여 특정 결정의 맥락에 맞추십시오. 6. 의사결정과 요구사항 및 아키텍처 설계/코드 사이에 추적성 링크가 설정되어 있는지 확인하십시오. 7. 변경 후 추적성 링크가 동기화되는지 확인하기 위해 자동화된 일관성 검사를 제공합니다. 의사결정과 기타 소프트웨어 아티팩트 간의 종속성 수를 제한합니다. 8 정당화에 대한 지침을 결과적으로 강력하게 적용하십시오. 이는 근거를 제공하기 때문에 의사결정 문서에서 가장 중요한 부분입니다. ================================================ FILE: locales/ko/서류/파일-이름-규칙/.locale-peer-id ================================================ 89116b5647aa1e53186f3c44b5a284a0 ================================================ FILE: locales/ko/서류/파일-이름-규칙/index.md ================================================ # 파일 이름 규칙 일반적인 텍스트 파일을 사용하여 ADR을 생성하기로 선택한 경우 고유한 ADR 파일 이름 규칙을 생각해 볼 수 있습니다. 우리는 특정 형식의 파일 이름 규칙을 사용하는 것을 선호합니다. 예: * 선택-database.md * 형식-타임스탬프.md * 관리-passwords.md * 핸들 예외.md 파일 이름 규칙: * 이름에는 현재형 명령형 동사구가 있습니다. 이는 가독성을 높이고 커밋 메시지 형식과 일치합니다. * 이름은 소문자와 대시를 사용합니다(이 저장소와 동일). 이는 가독성과 시스템 유용성의 균형입니다. * 확장자는 마크다운입니다. 이는 쉬운 포맷에 유용할 수 있습니다. ================================================ FILE: locales/ko/템플릿/.locale-peer-id ================================================ 70f1f9b3530831bc891a6e9b9b0d27de ================================================ FILE: locales/ko/템플릿/index.md ================================================ # 의사결정 기록 템플릿 * [Jeff Tyree 및 Art Akerman의 의사결정 기록 템플릿](decision-record-template-by-jeff-tyree-and-art-akerman) * [Michael Nygard의 결정 기록 템플릿](decision-record-template-by-michael-nygard) * [EdgeX의 의사결정 기록 템플릿](decision-record-template-by-edgex) * [알렉산드리아 패턴에 대한 결정 기록 템플릿](decision-record-template-for-alexandrian-pattern) * [비즈니스 사례에 대한 의사결정 기록 템플릿](decision-record-template-for-business-case) * [MADR 프로젝트의 결정 기록 템플릿](decision-record-template-of-the-madr-project) * [P언어를 이용한 의사결정 기록 템플릿](decision-record-template-using-p언어) ================================================ FILE: locales/ko/템플릿/madr 프로젝트의 결정 기록 템플릿/.locale-peer-id ================================================ 0a9f88e5cda952db0a82d071f585d090 ================================================ FILE: locales/ko/템플릿/madr 프로젝트의 결정 기록 템플릿/index.md ================================================ # [해결된 문제 및 솔루션의 짧은 제목] * 상태: [제안됨 | 거부됨 | 허용됨 | 더 이상 사용되지 않음 | ... | [ADR-0005](0005-example.md)]로 대체됨 * 결정자: [결정에 관련된 모든 사람을 나열] * 날짜: [결정이 마지막으로 업데이트된 YYYY-MM-DD] 기술 스토리: [설명 | 티켓/발행 URL] ## 상황 및 문제 설명 [문맥과 문제 설명을 예를 들어 2~3개의 문장을 사용하여 자유 형식으로 설명합니다. 질문 형식으로 문제를 명확히 설명할 수도 있습니다.] ## 의사결정 동인 * [드라이버 1, 예를 들어 세력, 우려에 직면, ...] * [드라이버 2, 예를 들어 세력, 우려에 직면, ...] * … ## 고려되는 옵션 * [옵션 1] * [옵션 2] * [옵션 3] * … ## 결정 결과 선택한 옵션: "[옵션 1]", 왜냐하면 [정의. 예를 들어, k.o를 충족하는 유일한 옵션입니다. 기준 결정 동인 | 강제력을 해결하는 | ... | 가장 잘 나옵니다(아래 참조)]. ### 긍정적인 결과 * [예: 품질속성 만족도 향상, 후속결정 필요, …] * … ### 부정적인 결과 * [예: 품질 특성 저하, 후속 결정 필요, …] * … ## 옵션의 장점과 단점 ### [옵션 1] [예 | 설명 | 자세한 정보에 대한 포인터 | …] * 좋아요, 왜냐하면 [인수 a] * 좋아요, 왜냐하면 [인수 b] * 나쁘다. 왜냐하면 [인수 c] * … ### [옵션 2] [예 | 설명 | 자세한 정보에 대한 포인터 | …] * 좋아요, 왜냐하면 [인수 a] * 좋아요, 왜냐하면 [인수 b] * 나쁘다. 왜냐하면 [인수 c] * … ### [옵션 3] [예 | 설명 | 자세한 정보에 대한 포인터 | …] * 좋아요, 왜냐하면 [인수 a] * 좋아요, 왜냐하면 [인수 b] * 나쁘다. 왜냐하면 [인수 c] * … ## 링크 * [링크 유형] [ADR에 링크] * … ================================================ FILE: locales/ko/템플릿/결정 기록 템플릿별 edgex/.locale-peer-id ================================================ 01939db0c341e9092c344d904065da12 ================================================ FILE: locales/ko/템플릿/결정 기록 템플릿별 edgex/index.md ================================================ # 아키텍처 결정 기록(ADR) 템플릿 EdgeX Foundry의 ADR 템플릿입니다. 출처: https://docs.edgexfoundry.org/2.3/design/adr/template/ ### 제출자 ADR 제출자를 나열합니다. 형식: - 이름 (조직) ## 변경 로그 다음을 포함하여 문서의 변경 사항을 나열합니다. 상태, 날짜 및 PR URL. 상태는 다음 중 하나입니다: 보류 중(pending), 승인됨(approved), 수정됨(amended), 더 이상 사용되지 않음(deprecated) 날짜는 ISO 8601(YYYY-MM-DD) 문자열입니다. PR은 차이점(diff), 기여자, 검토자와 같은 정보를 포함하여 변경 사항을 제출한 풀 리퀘스트입니다. 형식: - \[ADR 상태(예: approved, amended 등\]\(풀 리퀘스트 URL\) YYYY-MM-DD ## 참조된 사용 사례 관련된 모든 사용 사례/요구 사항 문서를 나열합니다. ADR에는 관련 있고 승인된 사용 사례가 적어도 하나 이상 필요합니다. 형식: - \[사용 사례 이름\]\(URL\) ADR이 사용 사례의 모든 요구 사항을 해결하지 못하는 경우 설명을 추가합니다. ## 문맥 다음을 설명해야 합니다: - 설계가 구조적으로(architecturally) 얼마나, (간단한 이슈나 문제 해결을 위한 PR과 다르게) ADR을 해야할만큼, 중요한지 - 높은 수준의 설계 접근 방식(자세한 내용은 아래 설계 제안에 설명되어 있음) ## 설계 제안 설계 세부 사항(가능한 경우 구현하지 않음) 개요: - 영향을 받을(또는 변경될) 서비스/모듈 - 추가될 새로운 서비스/모듈 - 모델 및 DTO 영향(변경/추가/제거) - API 영향(변경/추가/제거) - 일반적인 구성 영향(새 섹션 설정, 변경/추가/제거) - 데브옵스 영향 ## 고려사항 ADR 토론에서 나온 대안, 우려 사항, 부수적이거나 관련한 이슈, 질문을 문서화합니다. 해결 또는 완화되었는지 여부/방법을 표시합니다. ## 결정 합의된 중요한 구현 세부 사항, 주의 사항, 향후 고려 사항, 남아 있거나 연기된 설계 이슈를 문서화합니다. 설계 제안을 충족하지 않는 부분의 요구사항을 문서화합니다. ## 기타 관련 ADR 기능 하위 요소에 대한 설계 결정, 이 설계의 결과로 더 이상 사용되지 않는 설계 등과 같은 관련 ADR을 나열합니다. 형식: - \[ADR 제목\]\(URL\) - 관련성 ## 참고자료 추가 참고문헌을 나열합니다. 형식: - \[제목\]\(URL\) ================================================ FILE: locales/ko/템플릿/비즈니스 사례에 대한 의사결정 기록 템플릿/.locale-peer-id ================================================ f6d1fb662640a00f4c66c586233dead9 ================================================ FILE: locales/ko/템플릿/비즈니스 사례에 대한 의사결정 기록 템플릿/index.md ================================================ # 비즈니스 사례에 대한 의사결정 기록 템플릿 이 ADR 템플릿은 기준, 옵션(candidates) 및 비용을 포함하여 결정에 대한 비즈니스 사례 생성을 강조합니다. ## 상위 수준 * 제목 * 상태 * 평가 기준 * 고려해야 할 옵션 * 각 옵션에 대한 조사 및 분석 * 기준을 충족/불만족하며 그 이유 * 비용 분석 * SWOT 분석 * 의견 및 피드백 * 추천 ## 하위 수준 상세 내용 **제목**: * Git 커밋 메시지와 같이 50자 미만의 짧은 현재형 명령문입니다. **상태**: * 제안됨, 수락됨, 거부됨, 더 이상 사용되지 않음, 대체됨 등 중 하나입니다. **평가 기준**: * 요약: 우리가 발굴하려는 내용과 그 이유를 간략하게 설명합니다. * 세부사항 **고려할 옵션**: * 요약: 옵션을 어떻게 발견했는지 간략하게 설명하고 이상값에 주의를 환기시킵니다. * 모든 옵션 및 관련 옵션을 나열하십시오. 우리는 잠재적인 해결책으로 무엇을 평가하고 있나요? * 세부사항 **각 옵션에 대한 조사 및 분석**: * 요약: 연구 방법을 간략하게 설명하고 패턴, 클러스터 및 이상값에 주목합니다. * 기준을 충족/불만족하며 그 이유 * 요약 * 세부 사항 * 비용 분석 * 요약 * 예시 * 계약 동의, 법적 약속 등 라이선스 부여 * 기술 향상, 변화 관리 등의 교육 * 지원, 유지보수 등 운영 * 대역폭, CPU 사용량 등의 측정 * SWOT 분석 * 요약 * 강점 * 약점 * 기회 * 위협 * 내부 의견 및 피드백 * 요약 * 예시 * 팀 작성, 이상적으로는 실제 사람이 작성함 * 기타 이해관계자로부터 * 품질 속성(일명 교차 기능 요구 사항) * 외부 의견 및 피드백 * 요약 * 의견을 제시하는 사람은 누구입니까? * 당신이 고려한 다른 옵션은 무엇입니까? * 당신은 무엇을 만들고 있나요? * 예시 * B2B 또는 B2C * 외부용 또는 직원 전용 * 데스크톱 또는 모바일 * 파일럿 또는 프로덕션 * 모놀리스 또는 마이크로서비스 * 옵션들을 어떻게 평가했나요? * 우승자를 선택한 이유는 무엇입니까? * 그 이후로 무슨 일이 일어나고 있나요? * 예시 * 우승자의 실적은 어떻습니까? * 실제 프로덕션 사용자 트래픽의 몇 %가 승자를 통해 전달됩니까? * 지속적인 전달 파이프라인, 콘텐츠 관리 시스템, 분석 및 지표 등과 같이 어떤 종류의 통합이 관련되어 있습니까? * 당신이 지금 알고 있는 것을 알면서 사람들에게 무엇을 다르게 하라고 조언하시겠습니까? * 일화 **추천**: * 요약 * 세부 사항 ================================================ FILE: locales/ko/템플릿/알렉산드리아 패턴에 대한 결정 기록 템플릿/.locale-peer-id ================================================ f33e4eb0409f956de201b791749dc9aa ================================================ FILE: locales/ko/템플릿/알렉산드리아 패턴에 대한 결정 기록 템플릿/index.md ================================================ # [해결된 문제 및 솔루션의 짧은 제목] * 상태: [제안됨 | 거부됨 | 허용됨 | 더 이상 사용되지 않음 | ... | [ADR-0005](0005-example.md)]로 대체됨 * 결정자: [결정에 관련된 모든 사람을 나열] * 날짜: [결정이 마지막으로 업데이트된 YYYY-MM-DD] 기술 스토리: [설명 | 티켓/발행 URL] ## 상황 및 문제 설명 [문맥과 문제 설명을 예를 들어 2~3개의 문장을 사용하여 자유 형식으로 설명합니다. 질문 형식으로 문제를 명확히 설명할 수도 있습니다.] ## 의사결정 동인 * [드라이버 1, 예를 들어 세력, 우려에 직면, ...] * [드라이버 2, 예를 들어 세력, 우려에 직면, ...] * … ## 고려되는 옵션 * [옵션 1] * [옵션 2] * [옵션 3] * … ## 결정 결과 선택한 옵션: "[옵션 1]", 왜냐하면 [정의. 예를 들어, k.o를 충족하는 유일한 옵션입니다. 기준 결정 동인 | 강제력을 해결하는 | ... | 가장 잘 나옵니다(아래 참조)]. ### 긍정적인 결과 * [예: 품질속성 만족도 향상, 후속결정 필요, …] * … ### 부정적인 결과 * [예: 품질 특성 저하, 후속 결정 필요, …] * … ## 옵션의 장점과 단점 ### [옵션 1] [예 | 설명 | 자세한 정보에 대한 포인터 | …] * 좋아요, 왜냐하면 [인수 a] * 좋아요, 왜냐하면 [인수 b] * 나쁘다. 왜냐하면 [인수 c] * … ### [옵션 2] [예 | 설명 | 자세한 정보에 대한 포인터 | …] * 좋아요, 왜냐하면 [인수 a] * 좋아요, 왜냐하면 [인수 b] * 나쁘다. 왜냐하면 [인수 c] * … ### [옵션 3] [예 | 설명 | 자세한 정보에 대한 포인터 | …] * 좋아요, 왜냐하면 [인수 a] * 좋아요, 왜냐하면 [인수 b] * 나쁘다. 왜냐하면 [인수 c] * … ## 링크 * [링크 유형] [ADR에 링크] * … ================================================ FILE: locales/ko/템플릿/의사 결정 기록 템플릿-by-michael-nygard/.locale-peer-id ================================================ b1e90e6556c1c8f1e2eb3ac22c8c5077 ================================================ FILE: locales/ko/템플릿/의사 결정 기록 템플릿-by-michael-nygard/index.md ================================================ # Michael Nygard의 결정 기록 템플릿 이는 [아키텍처 결정 문서화 - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)의 템플릿입니다. ADR 파일을 관리하려면 [adr-tools](https://github.com/npryce/adr-tools)를 사용할 수 있습니다. 각 ADR 파일에서 다음 섹션을 작성합니다. # 제목 ## 상태 제안됨, 승인됨, 거부됨, 더 이상 사용되지 않음, 대체됨 등의 상태는 무엇입니까? ## 문맥 이러한 결정이나 변화에 동기를 부여하는 문제는 무엇입니까? ## 결정 우리가 제안하거나 수행하는 변화는 무엇입니까? ## 결과 이번 변화로 인해 어떤 일이 더 쉬워지거나 더 어려워졌나요? ================================================ FILE: locales/ko/템플릿/의사결정 기록 템플릿 사용 p언어/.locale-peer-id ================================================ bb37e19df57d398b0704d6bd30ee6e6d ================================================ FILE: locales/ko/템플릿/의사결정 기록 템플릿 사용 p언어/index.md ================================================ # P언어를 이용한 의사결정 기록 템플릿 https://www.iaria.org/conferences2012/filesICCGI12/Tutorial%20Specifying%20Effective%20Non-func.pdf를 참조하세요. ## P언어란 무엇인가요? P언어는 다음 키워드를 사용하는 계획 언어입니다. * 태그: 고유하고 지속적인 식별자 * 요지: 요구사항이나 다루는 영역에 대한 간략한 요약 * 요구사항: 요구사항 자체를 자세히 설명하는 텍스트 * 근거(Rationale): 요구사항을 정당화하는 추론 * 우선순위: 자원에 대한 우선순위 및 주장에 대한 설명 * 이해관계자: 요구사항으로 인해 실질적으로 영향을 받는 당사자 * 상태: 요구사항의 상태(초안, 검토, 커밋 등) * 소유자: 요구사항 구현을 담당하는 사람 * 작성자 : 요구사항을 작성한 사람 * 개정: 명세서의 버전 번호 * 날짜 : 가장 최근 개정된 날짜 * 가정: 지금 또는 나중에 사실이 아닐 경우 문제를 일으킬 수 있는 모든 것 * 위험 : 오작동, 지연 또는 기타 부정적인 영향을 일으킬 수 있는 모든 것 * 정의: 용어의 정의(용어집을 사용하는 것이 더 좋음) ================================================ FILE: locales/ko/템플릿/의사결정 기록 템플릿-by-jeff-tyree-and-art-akerman/.locale-peer-id ================================================ f4ca0a94124a91279e1929ea23ab864d ================================================ FILE: locales/ko/템플릿/의사결정 기록 템플릿-by-jeff-tyree-and-art-akerman/index.md ================================================ # Jeff Tyree와 Art Akerman의 의사결정 기록 템플릿 이것은 ["Architecture Decisions: Demystifying Architecture" by Jeff Tyree 및 Art Akerman, Capital One Financial](https://www.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-)에 게시된 아키텍처 결정 설명 템플릿입니다. tyree-05.pdf). * **문제**: 현재 이 문제를 해결하는 이유에 대해 질문을 남기지 않고 해결 중인 아키텍처 설계 문제를 설명하세요. 최소한의 접근 방식에 따라 수명 주기의 다양한 지점에서 해결해야 하는 문제만 해결하고 문서화합니다. * **결정**: 아키텍처의 방향, 즉 선택한 위치를 명확하게 설명합니다. * **상태**: 보류, 결정, 승인 등 결정 상태입니다. * **그룹**: 통합, 프레젠테이션, 데이터 등과 같은 간단한 그룹화를 사용하여 일련의 의사결정을 구성하는 데 도움을 줄 수 있습니다. John Kyaruzi 및 Jan van Katwijk의 이벤트, 일정, 위치와 같은 보다 추상적인 범주를 포함하는 보다 정교한 아키텍처 온톨로지를 사용할 수도 있습니다. 예를 들어, 이 온톨로지를 사용하면 시스템이 이벤트 아래에 정보를 요구하는 발생을 처리하는 의사결정을 그룹화할 수 있습니다. * **가정**: 결정을 내리는 환경의 기본 가정(비용, 일정, 기술 등)을 명확하게 설명합니다. 환경적 제약(예: 허용되는 기술 표준, 엔터프라이즈 아키텍처, 일반적으로 사용되는 패턴 등)으로 인해 고려하는 대안이 제한될 수 있습니다. * **제약사항**: 선택한 대안(결정)이 제기할 수 있는 환경에 대한 추가 제약사항을 캡처합니다. * **직위**: 고려한 직위(실행 가능한 옵션 또는 대안)를 나열합니다. 여기에는 긴 설명이 필요한 경우가 많으며 때로는 모델과 다이어그램도 필요합니다. 이것은 완전한 목록이 아닙니다. 하지만 "...에 대해 생각해 보셨나요?"라는 질문은 듣고 싶지 않습니다. 최종 검토 중; 이로 인해 신뢰성이 떨어지고 다른 아키텍처 결정에 대한 의문이 제기됩니다. 이 섹션은 또한 귀하가 다른 사람의 의견을 듣는 데 도움이 됩니다. 다른 의견을 명시적으로 언급하는 것은 귀하의 결정에 그들의 옹호자를 포함시키는 데 도움이 됩니다. * **인론**: 구현 비용, 총 소유 비용, 시장 출시 시간, 필요한 개발 리소스 가용성 등의 항목을 포함하여 직위를 선택한 이유를 설명합니다. 이것은 아마도 결정 자체만큼 중요할 것입니다. * **의미**: REMAP 메타모델에서 알 수 있듯이 결정에는 많은 의미가 따릅니다. 예를 들어, 결정으로 인해 다른 결정을 내리거나, 새로운 요구 사항을 생성하거나, 기존 요구 사항을 수정해야 할 필요성이 발생할 수 있습니다. 환경에 추가적인 제약을 가합니다. 고객과 범위나 일정을 재협상해야 합니다. 또는 추가 직원 교육이 필요합니다. 결정의 의미를 명확하게 이해하고 기술하는 것은 동의를 얻고 아키텍처 실행을 위한 로드맵을 만드는 데 매우 효과적일 수 있습니다. * **관련 결정**: 많은 결정이 관련되어 있다는 것은 분명합니다. 여기에 나열할 수 있습니다. 그러나 실제로는 추적성 매트릭스, 의사결정 트리 또는 메타모델이 더 유용하다는 사실을 발견했습니다. 메타모델은 복잡한 관계를 도식적으로 표시하는 데 유용합니다(예: Rose 모델). * **관련 요구 사항**: 의사결정은 비즈니스 중심으로 이루어져야 합니다. 책임을 보여주기 위해 결정을 목표나 요구 사항에 명시적으로 매핑하십시오. 여기에 관련 요구 사항을 열거할 수 있지만 추적성 매트릭스를 참조하는 것이 더 편리하다는 것을 알았습니다. 각 요구 사항 충족에 대한 각 아키텍처 결정의 기여도를 평가한 다음 모든 결정에서 요구 사항이 얼마나 잘 충족되는지 평가할 수 있습니다. 결정이 요구 사항을 충족하는 데 도움이 되지 않으면 해당 결정을 내리지 마세요. * **관련 아티팩트**: 이 결정이 영향을 미치는 관련 아키텍처, 디자인 또는 범위 문서를 나열합니다. * **관련 원칙**: 기업이 합의한 일련의 원칙을 갖고 있는 경우 결정이 그 중 하나 이상과 일치하는지 확인하십시오. 이는 도메인이나 시스템에 따른 정렬을 보장하는 데 도움이 됩니다. * **참고**: 의사 결정 과정은 몇 주가 걸릴 수 있으므로 사회화 과정에서 팀이 논의하는 메모와 문제를 기록하는 것이 유용하다는 것을 알았습니다. ================================================ FILE: locales/tr/.locale-peer-id ================================================ 0b59cb46e5817b414866ebe33f4d7bcf ================================================ FILE: locales/tr/documents/.locale-peer-id ================================================ abc7c72d426bc75e40b25a44ae37ce73 ================================================ FILE: locales/tr/documents/aws-adr-process/.locale-peer-id ================================================ 7d4adf16004ca42546dee49922ae4ccf ================================================ FILE: locales/tr/documents/aws-adr-process/index.md ================================================ # AWS Mimari Karar Kayıtları Süreci https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html Bir mimari karar kaydı (ADR), ekibin oluşturmayı planladığı yazılım mimarisinin önemli bir yönü hakkında yaptığı bir seçimi açıklayan bir belgedir. Her ADR, mimari kararı, bağlamını ve sonuçlarını açıklar. ADR'lerin durumları vardır ve bu nedenle bir yaşam döngüsünü takip ederler. Bir ADR örneği için eke bakın. ADR süreci, mimari karar kayıtlarından oluşan bir koleksiyon oluşturur. Bu koleksiyon, karar günlüğünü oluşturur. Karar günlüğü, proje bağlamının yanı sıra ayrıntılı uygulama ve tasarım bilgileri sağlar. Proje üyeleri, proje bağlamına genel bir bakış elde etmek için her ADR'nin başlıklarını gözden geçirir. Proje uygulamalarına ve tasarım seçeneklerine derinlemesine dalmak için ADR'leri okurlar. Ekip bir ADR'yi kabul ettiğinde, ADR değişmez hale gelir. Yeni bilgiler farklı bir karar gerektiriyorsa, ekip yeni bir ADR önerir. Ekip yeni ADR'yi kabul ettiğinde, önceki ADR'nin yerini alır. ## ADR sürecinin kapsamı Proje üyeleri, yazılım projesini veya ürününü etkileyen mimari açıdan önemli her karar için bir ADR oluşturmalıdır, buna aşağıdakiler dahildir (Richards ve Ford 2020): * Yapı (örneğin, mikro hizmetler gibi desenler) * İşlevsel olmayan gereksinimler (güvenlik, yüksek kullanılabilirlik ve hata toleransı) * Bağımlılıklar (bileşenlerin bağlanması) * Arayüzler (API'ler ve yayınlanmış sözleşmeler) * İnşaat teknikleri (kütüphaneler, çerçeveler, araçlar ve süreçler) * İşlevsel ve işlevsel olmayan gereksinimler, ADR sürecine en yaygın girdilerdir. ## ADR içeriği Ekip bir ADR ihtiyacını belirlediğinde, bir ekip üyesi proje çapında bir şablona göre ADR'yi yazmaya başlar. (Örnek şablonlar için ADR GitHub kuruluşuna bakın.) Şablon, ADR oluşturmayı basitleştirir ve ADR'nin ilgili tüm bilgileri yakalamasını sağlar. Her ADR, en azından kararın bağlamını, kararın kendisini ve kararın proje ve çıktıları üzerindeki sonuçlarını tanımlamalıdır. (Bu bölümlerin örnekleri için eke bakın.) ADR yapısının en güçlü yönlerinden biri, ekibin kararı nasıl uyguladığından ziyade kararın nedenine odaklanmasıdır. Ekibin kararı neden verdiğini anlamak, diğer ekip üyelerinin kararı benimsemesini kolaylaştırır ve karar verme sürecine dahil olmayan diğer mimarların gelecekte bu kararı geçersiz kılmasını önler. ## ADR benimseme süreci Her ekip üyesi bir ADR oluşturabilir, ancak ekip bir ADR için bir sahiplik tanımı oluşturmalıdır. Bir ADR'nin sahibi olan her yazar, ADR içeriğini aktif olarak sürdürmeli ve iletmelidir. Bu sahipliği netleştirmek için bu kılavuz, aşağıdaki bölümlerde ADR yazarlarını ADR sahipleri olarak adlandırır. Diğer ekip üyeleri her zaman bir ADR'ye katkıda bulunabilir. Bir ADR'nin içeriği ekip ADR'yi kabul etmeden önce değişirse, mal sahibi bu değişiklikleri onaylamalıdır. Ekip bir mimari kararı ve sahibini belirledikten sonra, ADR sahibi sürecin başında **Önerilen** durumunda ADR'yi sağlar. Önerilen durumdaki ADR'ler incelemeye hazırdır. ADR sahibi daha sonra ADR için inceleme sürecini başlatır. ADR inceleme sürecinin amacı, ekibin ADR'yi kabul edip etmediğine, yeniden çalışılması gerektiğine karar verip vermediğine veya ADR'yi reddedip etmediğine karar vermektir. Sahibi de dahil olmak üzere proje ekibi ADR'yi inceler. İnceleme toplantısı, ADR'yi okumak için ayrılmış bir zaman dilimi ile başlamalıdır. Ortalama olarak 10 ila 15 dakika yeterli olacaktır. Bu süre zarfında, her ekip üyesi belgeyi okur ve belirsiz konuları işaretlemek için yorumlar ve sorular ekler. İnceleme aşamasından sonra, ADR sahibi her yorumu okur ve ekiple tartışır. Ekip ADR'yi iyileştirmek için eylem noktaları bulursa, ADR'nin durumu **Önerilen** olarak kalır. ADR sahibi eylemleri formüle eder ve ekiple işbirliği içinde her eyleme bir atanan ekler. Her ekip üyesi eylem noktalarına katkıda bulunabilir ve bunları çözebilir. İnceleme sürecini yeniden planlamak ADR sahibinin sorumluluğundadır. Ekip ayrıca ADR'yi reddetmeye de karar verebilir. Bu durumda, ADR sahibi gelecekte aynı konuda tartışmaları önlemek için ret nedenini ekler. Sahip, ADR durumunu **Reddedildi** olarak değiştirir. Ekip ADR'yi onaylarsa, mal sahibi bir zaman damgası, sürüm ve paydaş listesi ekler. Sahip daha sonra durumu **Kabul Edildi** olarak günceller. ADR'ler ve oluşturdukları karar günlüğü, ekip tarafından alınan kararları temsil eder ve tüm kararların bir geçmişini sağlar. Ekip, mümkün olan yerlerde kod ve mimari incelemeler sırasında ADR'leri referans olarak kullanır. Kod incelemeleri, tasarım görevleri ve uygulama görevlerini gerçekleştirmenin yanı sıra, ekip üyeleri ürün için stratejik kararlar için ADR'lere danışmalıdır. İyi bir uygulama olarak, her yazılım değişikliği akran değerlendirmelerinden geçmeli ve en az bir onay gerektirmelidir. Kod incelemesi sırasında, bir kod incelemecisi bir veya daha fazla ADR'yi ihlal eden değişiklikler bulabilir. Bu durumda, incelemeci kod değişikliğinin yazarından kodu güncellemesini ister ve ADR'ye bir bağlantı paylaşır. Yazar kodu güncellediğinde, akran incelemecileri tarafından onaylanır ve ana kod tabanına birleştirilir. ## ADR inceleme süreci Ekip, ADR'leri kabul ettikten veya reddettikten sonra değişmez belgeler olarak ele almalıdır. Mevcut bir ADR'de değişiklik yapmak, yeni bir ADR oluşturmayı, yeni ADR için bir inceleme süreci oluşturmayı ve ADR'yi onaylamayı gerektirir. Ekip yeni ADR'yi onaylarsa, mal sahibi eski ADR'nin durumunu **Geçersiz Kılındı** olarak değiştirmelidir. ================================================ FILE: locales/tr/documents/decision-sustainability-criteria/.locale-peer-id ================================================ 71d59ed566ae148b8bf42331a84754ac ================================================ FILE: locales/tr/documents/decision-sustainability-criteria/index.md ================================================ # Karar Sürdürülebilirlik Kriterleri Karar sürdürülebilirliğini ayrıntılı olarak tanımlamak için beş temel kriter türettik. ## Stratejik Karar verme sırasında, stratejik sonuçlara bakan biri, kararların uzun vadeli etkisini (örneğin, gelecekteki operasyonlar ve bakım çabası) gibi şeyleri dikkate almalıdır. ## Ölçülebilir ve Yönetilebilir Bir kararın sonucunu, ideal olarak sayısal olan (örneğin, kalite nitelik senaryoları ve atölye çalışmaları4 tarafından yayıldığı gibi) objektif kriterlere göre zaman içinde ölçebilir ve değerlendirebilirsiniz. Tüm ayrıntılı kararları yakalamak mümkün değildir, bu nedenle mimarlar kararların ayrıntı düzeyini belirli bir ayrıntı düzeyine (tasarım sınıfı oluşturmak gibi) sınırlamalıdır. Bu, daha sürdürülebilir bir karar setine ve daha az izlenebilirlik bağlantısına yol açacaktır. Ayrıca, kararlar arasındaki bağımlılıkların sayısını sınırlamak, değişikliklerin dalgalanma etkisini azaltır. ## Ulaşılabilir ve Gerçekçi Çözümü soruna uydurmanın mantığı pragmatik olarak seçilmeli ve açık hale getirilmelidir. Örneğin, mimarlar aşırı veya eksik mühendislikten kaçınmaya özen gösterdiklerini belirtebilirler (yani, “yeterince iyi” yaklaşımını uygulamalıdırlar). ## Gereksinimlere Dayalı Karar verme, alana özgü mimari deneyim ve bağlama dayanmalıdır. Geliştirme ekibinin mevcut becerileri, eğitim bütçesi ve süreci de dahil olmak üzere şirket ortamının yanı sıra proje gereksinimlerini ve kısıtlamalarını da dikkate almalıdır. ## Zamansız Kararlar, yakın zamanda güncelliğini yitirmeyecek deneyim ve bilgiye dayanmalıdır. Örneğin, mimarlar platformdan bağımsız mimari desenleri veya taktikleri seçebilirler. ================================================ FILE: locales/tr/documents/file-name-conventions-for-adrs/.locale-peer-id ================================================ 89116b5647aa1e53186f3c44b5a284a0 ================================================ FILE: locales/tr/documents/file-name-conventions-for-adrs/index.md ================================================ # Dosya adı kuralları ADR'lerinizi tipik metin dosyaları kullanarak oluşturmayı seçerseniz, kendi ADR dosya adı kuralınızı bulmak isteyebilirsiniz. Belirli bir biçime sahip bir dosya adı kuralı kullanmayı tercih ediyoruz. Örnekler: * veritabani-sec.md * zaman-damgalarini-bicimlendir.md * parolalari-yonet.md * istisnalari-ele-al.md Dosya adı kuralımız: * Ad, şimdiki zamanda bir zorunluluk fiil cümlesine sahiptir. Bu, okunabilirliğe yardımcı olur ve taahhüt mesajı biçimimizle eşleşir. * Ad, küçük harf ve kısa çizgi kullanır (bu depo ile aynı). Bu, okunabilirlik ve sistem kullanılabilirliğinin bir dengesidir. * Uzantı markdown'dır. Bu, kolay biçimlendirme için yararlı olabilir. ================================================ FILE: locales/tr/documents/guidelines-to-achieve-sustainable-decisions/.locale-peer-id ================================================ 934d1c42a693fe004cd8bf8f5ecb97e6 ================================================ FILE: locales/tr/documents/guidelines-to-achieve-sustainable-decisions/index.md ================================================ # Sürdürülebilir Kararlar Almak İçin Yönergeler Sürdürülebilir kararlar almak için yönergeler ve değerlendirme görevi görebilecek çalışmalarımızda aşağıdaki dersleri öğrendik: 1. İlk karar belgeleri için yalın/minimalist bir yaklaşım kullanın. 2. Hedef mimariyi belgelemek ve anlamak için yeterince ilgili olan tüm önemli kararları önceliklendirin ve yakalayın. 3. Özellikle önemli kararları, yalnızca ilk çalışma yapıldıktan sonra (yani, karar vericiler alınan mimari kararlardan memnun olduğunda ve bu kararların yakın zamanda revize edilmesi gerekmediğinden emin olduklarında) tam teşekküllü şablonlarla detaylandırın. 4. Adım 1'deki yalın/minimalist sürümleri, önemsiz veya bariz kararların yanı sıra ayrıntılı kararlara genel bir bakış sağlamak için doğru ayrıntı düzeyine sahip belgelenmiş kararların kısa bir sürümü olarak kullanın. 5. Mümkün olan her yerde, rehberlik modellerinden veya diğer kaynaklardan mevcut mimari bilgileri kullanın. Bu tür bilgileri gözden geçirin ve genişletin ve belirli kararın bağlamına uygun hale getirin. 6. Kararlar ile hem gereksinimler hem de mimari tasarımlar/kod arasında izlenebilirlik bağlantılarının kurulduğundan emin olun. 7. Bir değişiklikten sonra izlenebilirlik bağlantılarının senkronize olduğundan emin olmak için otomatik tutarlılık kontrolü sağlayın. Kararlar ve diğer yazılım eserleri arasındaki bağımlılıkların sayısını sınırlayın. 8. Gerekçeler için yönergeleri sonuç olarak ve zorla uygulayın - rasyonel verdikleri için karar belgelerinin en önemli parçasıdır. ================================================ FILE: locales/tr/documents/how-to-start-using-adrs/.locale-peer-id ================================================ 8196518140224596af99a46d512feba3 ================================================ FILE: locales/tr/documents/how-to-start-using-adrs/index.md ================================================ # ADR'leri kullanmaya nasıl başlanır? ADR'leri kullanmaya başlamak için ekip arkadaşlarınızla bu alanlar hakkında konuşun. Karar tespiti: * AD ne kadar acil ve ne kadar önemli? * Şimdi mi yapılmalı, yoksa daha fazlası bilinene kadar bekleyebilir mi? * Kişisel ve kolektif deneyimin yanı sıra tanınmış tasarım yöntemleri ve uygulamaları, karar tespitine yardımcı olabilir. * İdeal olarak, ürün yapılacaklar listesini tamamlayan bir karar yapılacaklar listesi tutun. Karar verme: * Genel olanlar ve yazılım mimarisine özgü olanlar olmak üzere bir dizi karar verme tekniği mevcuttur, örneğin diyalog haritalama. * Grup kararı verme aktif bir araştırma konusudur. Karar alma ve uygulama: * AD'ler yazılım tasarımında kullanılır; bu nedenle, onu finanse eden, geliştiren ve işleten sistemin paydaşlarına iletilmeli ve onlar tarafından kabul edilmelidir. * Mimari olarak belirgin kodlama stilleri ve mimari kaygılara ve kararlara odaklanan kod incelemeleri iki ilgili uygulamadır. * Yazılım evriminde bir yazılım sistemini modernleştirirken AD'ler de (yeniden) dikkate alınmalıdır. Karar paylaşımı (isteğe bağlı): * Birçok AD, projeler arasında tekrarlanır. * Bu nedenle, geçmişteki iyi ve kötü kararlarla ilgili deneyimler, açık bir bilgi yönetimi stratejisi uygularken değerli yeniden kullanılabilir varlıklar olabilir. Karar belgeleri: * Karar yakalamak için birçok şablon ve araç mevcuttur. * Çevik topluluklara bakın, örneğin M. Nygard'ın ADR'leri. * Geleneksel yazılım mühendisliği ve mimari tasarım süreçlerine bakın, örneğin IBM UMF ve CapitalOne'dan Tyree ve Akerman tarafından önerilen tablo düzenleri. Daha fazlası için: * Yukarıdaki adımlar [Mimari Karar](https://en.wikipedia.org/wiki/Architectural_decision) hakkındaki Wikipedia girişinden uyarlanmıştır. ================================================ FILE: locales/tr/documents/how-to-start-using-adrs-with-git/.locale-peer-id ================================================ d6fb3c7d91f95003163e694e74058e9d ================================================ FILE: locales/tr/documents/how-to-start-using-adrs-with-git/index.md ================================================ # ADR'leri git ile kullanmaya nasıl başlanır? Eğer git sürüm kontrolü kullanmayı seviyorsanız, burada kaynak kodlu tipik bir yazılım projesi için ADR'leri git ile kullanmaya nasıl başlayacağımızı anlatıyoruz. ADR dosyaları için bir dizin oluşturun: ```sh $ mkdir adr ``` Her ADR için, `database.txt` gibi bir metin dosyası oluşturun: ```sh $ vi database.txt ``` ADR'de istediğiniz her şeyi yazın. Fikirler için bu depodaki şablonlara bakın. ADR'yi git reponuza kaydedin. ================================================ FILE: locales/tr/documents/how-to-start-using-adrs-with-tools/.locale-peer-id ================================================ 1a5a03dd6f20cea9f78fb4655a9a7f87 ================================================ FILE: locales/tr/documents/how-to-start-using-adrs-with-tools/index.md ================================================ ## Araçlarla ADR kullanmaya nasıl başlanır? İstediğiniz şekilde araçlarla ADR'leri kullanmaya başlayabilirsiniz. Örneğin: * Google Drive ve çevrimiçi düzenlemeyi kullanmayı seviyorsanız, bir Google Dokümanı veya Google E-Tablosu oluşturabilirsiniz. * Git gibi kaynak kodu sürüm kontrolünü kullanmayı seviyorsanız, her ADR için bir dosya oluşturabilirsiniz. * Atlassian Jira gibi proje planlama araçlarını kullanmayı seviyorsanız, aracın planlama izleyicisini kullanabilirsiniz. * MediaWiki gibi wikileri kullanmayı seviyorsanız, bir ADR wikisi oluşturabilirsiniz. ================================================ FILE: locales/tr/documents/suggestions-for-writing-good-adrs/.locale-peer-id ================================================ dc1a294e76821d6d3b086a2b17988427 ================================================ FILE: locales/tr/documents/suggestions-for-writing-good-adrs/index.md ================================================ ## İyi ADR'ler yazmak için öneriler İyi bir ADR'nin özellikleri: * Gerekçe: Belirli bir AD'yi yapmanın nedenlerini açıklayın. Bu, bağlamı (aşağıya bakın), çeşitli potansiyel seçeneklerin artılarını ve eksilerini, özellik karşılaştırmalarını, maliyet/fayda tartışmalarını ve daha fazlasını içerebilir. * Özel: Her ADR, birden çok AD değil, bir AD ile ilgili olmalıdır. * Zaman damgaları: ADR'deki her bir öğenin ne zaman yazıldığını belirtin. Bu, maliyetler, programlar, ölçeklendirme ve benzerleri gibi zamanla değişebilecek yönler için özellikle önemlidir. * Değişmez: Bir ADR'deki mevcut bilgileri değiştirmeyin. Bunun yerine, yeni bilgiler ekleyerek ADR'yi değiştirin veya yeni bir ADR oluşturarak ADR'nin yerine geçin. Bir ADR'de iyi bir "Bağlam" bölümünün özellikleri: * Kuruluşunuzun durumunu ve iş önceliklerini açıklayın. * Ekiplerinizin sosyal ve beceri yapılarına dayalı gerekçeleri ve değerlendirmeleri ekleyin. * İlgili artıları ve eksileri ekleyin ve bunları ihtiyaç ve hedeflerinize uygun terimlerle açıklayın. Bir ADR'de iyi bir "Sonuçlar" bölümünün özellikleri: * Karar vermekten neyin kaynaklandığını açıklayın. Bu, etkileri, sonuçları, çıktıları, takiplerini ve daha fazlasını içerebilir. * Sonraki ADR'ler hakkında bilgi ekleyin. Bir ADR'nin daha fazla ADR'ye ihtiyaç duyması nispeten yaygındır, örneğin bir ADR büyük bir kapsayıcı seçim yaptığında, bu da daha küçük kararlar için ihtiyaçlar yaratır. * Herhangi bir işlem sonrası inceleme sürecini dahil edin. Ekiplerin, öğrenmek ve büyümek için ADR bilgilerini gerçekte olanlarla karşılaştırmak için bir ay sonra her ADR'yi incelemesi tipiktir. Yeni bir ADR, önceki bir ADR'nin yerini alabilir: * Önceki bir ADR'yi değiştiren veya geçersiz kılan bir AD yapıldığında, yeni bir ADR oluşturulmalıdır. ================================================ FILE: locales/tr/documents/teamwork-advice-for-adrs/.locale-peer-id ================================================ 875a7715e592ceb45eac5e155ee16318 ================================================ FILE: locales/tr/documents/teamwork-advice-for-adrs/index.md ================================================ # ADR'ler için ekip çalışması tavsiyesi Ekibinizle karar kayıtlarını kullanmayı düşünüyorsanız, burada birçok ekiple çalışarak öğrendiğimiz bazı tavsiyeler var. "Ne"yi zorunlu kılmak yerine "neden" hakkında birlikte konuşarak takım arkadaşlarınıza liderlik etme fırsatınız var. Örneğin, karar kayıtları ekiplerin daha akıllı düşünmeleri ve daha iyi iletişim kurmaları için bir yoldur; karar kayıtları, yalnızca sonradan zorunlu bir evrak gereksinimi ise değerli değildir. Bazı ekipler "ADR'ler" kısaltması yerine "kararlar" adını çok daha fazla tercih eder. Bazı ekipler "kararlar" dizin adını kullandığında, bir ampul yanar ve ekip, satıcı kararları, planlama kararları, zamanlama kararları vb. gibi daha fazla bilgiyi dizine koymaya başlar. Tüm bu tür bilgiler aynı şablonu kullanabilir. İnsanların kısaltmalar ("ADR'ler") yerine kelimelerle ("kararlar") daha hızlı öğrendiklerini ve "kayıt" kelimesi kaldırıldığında insanların devam eden çalışma belgeleri yazmaya daha motive olduklarını ve ayrıca bazı geliştiricilerin ve bazı yöneticilerin "mimari" kelimesini sevmediğini varsayıyoruz. Teoride, değişmezlik idealdir. Pratikte, değişkenlik ekiplerimiz için daha iyi çalıştı. Karardan sonra bilgilerin geldiğine dair bir not ve tarih damgasıyla mevcut ADR'ye yeni bilgileri ekliyoruz. Bu tür bir yaklaşım, hepimizin güncelleyebileceği "yaşayan bir belgeye" yol açar. Tipik güncellemeler, yeni takım arkadaşları, yeni teklifler veya kullanımlarımızın gerçek dünya sonuçları veya satıcı yetenekleri, fiyatlandırma planları, lisans sözleşmeleri vb. gibi sonradan yapılan üçüncü taraf değişiklikleri sayesinde bilgi edindiğimizde yapılır. ================================================ FILE: locales/tr/documents/teamwork-questions-for-adrs/.locale-peer-id ================================================ 60057747e4547af35fd888021e41f332 ================================================ FILE: locales/tr/documents/teamwork-questions-for-adrs/index.md ================================================ ### ADR'yi kim oluşturabilir? Belirli kişiler, belirli roller, belirli ekipler veya belirli departmanlar gibi alanları göz önünde bulundurun; ayrıca bir ADR'yi görevlendirebilecek, yani başka birinin yazacağı bir tane talep eden kişiler, roller, ekipler veya departman olup olmadığını da göz önünde bulundurun. Örnek cevap: Kuruluşumuzda mimari karar kaydı README sayfasını okuyan herhangi bir kişi bir ADR önerebilir, yani kişi onu yazmaya başlayabilir ve ekiple paylaşabilir. ### ADR'yi gündeme getirmeyi ne haklı çıkarır? Kuruluşunuzun ekip çalışma şekilleri, yazılım sistem yapınız, ekipler arası koordinasyon, uzun vadeli sürdürülebilirlik, harici arayüzler, kimden faydalanmak istediğiniz ve benzeri alanları göz önünde bulundurun. Örnek cevap: Gelecekteki geliştiricilerin yaptıklarımızın “nedenini” anlamasını istediğimizde bir ADR oluşturmak istiyoruz. ### ADR'yi yükseltmemeyi ne haklı çıkarır? Mimari ile ilgili olmayan veya minimum riskli veya kendi kendine yeten veya tek geliştirici gibi küçük olan veya standartlar veya politikalar veya belgeler gibi başka bir yerde zaten tamamen kapsanan veya geçici çözümler veya kavram kanıtları veya deneyler gibi geçici olan kararlar gibi alanları göz önünde bulundurun. Örnek cevap: Bir kararın kapsam, zaman, risk ve maliyet açısından sınırlı olduğu veya başka bir yerde zaten kapsandığı durumlarda bir ADR'yi atlamak istiyoruz. ### ADR'nin yaşam döngüsü nedir? Oluşturma süreci, araştırma süreci, karar verme süreci, uygulama süreci ve kullanımdan kaldırma süreci gibi alanları göz önünde bulundurun. ADR'yi bir durumdan diğerine nasıl taşıyacağınız ve bunu paydaşlara nasıl ileteceğiniz gibi ADR yaşam döngüsünü zaman içinde nasıl izleyeceğinizi düşünün. Örnek cevap: Bir ADR'nin beş yaşam döngüsü aşamasına sahip olmasını istiyoruz: Başlatma → Araştırma → Değerlendirme → Uygulama → Sürdürme → Kullanımdan Kaldırma. ### ADR'nin yaşam döngüsü adımları için kriterler nelerdir? Bir ADR için kabul kriterleri gibi alanları göz önünde bulundurun, yani bir yaşam döngüsü adımından diğerine geçmek için yeterince iyi olduğunu nasıl anlarsınız? Sorun açıkça ifade edilmiş mi? Alternatifler düşünüldü mü? Ödünleşimler yeterince anlaşılıp belgelendi mi? Tüm ilgili bağlam yerinde mi? İlgili tüm paydaşlar dahil mi? Tüm geri bildirimler dahil edildi mi? Örnek cevap: Aktif ekip 1) araştırmalarını tamamladığında, 2) değerlendirmelerini tamamladığında, 3) ADR teklifini yorum talebi ve bir haftalık bir zaman kutusu ile paydaşlara yayınladığında, 4) tüm paydaş yorumları dahil edilip ele alındığında paydaşlar tarafından bir ADR'ye oy verilmesini istiyoruz. ### Hangi roller ve sorumluluklar bir ADR ile etkileşime girer? Teklif sahibi, araştırmacı, değerlendirici, gözden geçiren, onaylayan, sürdüren ve benzeri rolleri göz önünde bulundurun. Paydaşlarla iletişim, beklentilerin karşılandığından emin olma, web sitesinde veya intranette paylaşma, çalışmayı periyodik olarak ve özellikle ilgili değişiklikler olduğunda gözden geçirme gibi sorumlulukları göz önünde bulundurun. Örnek cevap: Her ADR'nin her zaman bir birincil irtibat kişisi, ikincil irtibat kişisi ve sorumlu ekibe sahip olmasını istiyoruz; bunlar iletişim, yayınlar, bakım, yılda en az bir kez periyodik inceleme ve gerektiğinde nihai kullanımdan kaldırmadan sorumludur. ### Yönetişim bir ADR ile nasıl etkileşime girer? Kuruluşunuzun çalışma şekilleri, yasal yönler veya insan kaynakları yönleri gibi özel uyumluluk ihtiyaçları, fikir birliği, çatışma ve tırmanmayı nasıl ele almak istediğiniz gibi alanları göz önünde bulundurun. Bir ADR ile ilgili olarak, onu onaylayabilme, oy kullanabilme veya veto edebilme gibi diğerlerinden daha fazla etkiye sahip olabilecek alanlar, kişiler veya ekipler var mı? Örnek cevap: Bir ADR'nin yönetişimi şu öncelik sırasındadır: CEO, CTO, CLO, bir ADR'yi uygulayan ekip, ADD hakkında en bilgili olan ekipteki uzmanlar. ADR'de açıklanmadığı sürece başka hiç kimsenin yönetişimi yoktur. ### Hangi ilkeler bir ADR ile etkileşime girer? Kuruluşunuzun hızlı hareket etme ve yavaş hareket etme, karar birliği ve karar çatışması, risk tercihleri ve güvenlik tercihleri, halka açık tartışma ve özel tartışma ve benzerlerini içeren çalışma şekilleri gibi alanları göz önünde bulundurun. Örnek cevap: Eylem için önyargı, aynı fikirde olmama ve taahhüt etme, kolayca geri döndürülebilir, kolayca izole edilebilir kararlar için %70 tahminlerin yeterince iyi olduğu ve kuruluşumuzun gizlilik sözleşmesinde açıklanan gizli bilgiler haricinde halka açık çalışma şekilleri gibi liderlik ilkelerini kullanıyoruz. ================================================ FILE: locales/tr/documents/what-is-an-architecture-decision-record/.locale-peer-id ================================================ 020ff535ed1a3347a265209291e756b6 ================================================ FILE: locales/tr/documents/what-is-an-architecture-decision-record/index.md ================================================ ## Mimari karar kaydı nedir? **Mimari karar kaydı** (ADR), bağlamı ve sonuçlarıyla birlikte alınan önemli bir mimari kararı yakalayan bir belgedir. **Mimari karar** (AD), önemli bir gereksinimi karşılayan bir yazılım tasarım seçimidir. **Mimari karar günlüğü** (ADL), belirli bir proje (veya kuruluş) için oluşturulan ve sürdürülen tüm ADR'lerin koleksiyonudur. **Mimari açıdan önemli bir gereksinim** (ASR), bir yazılım sisteminin mimarisi üzerinde ölçülebilir bir etkiye sahip olan bir gereksinimdir. Bunların hepsi **mimari bilgi yönetimi** (AKM) konusundadır. Bu belgenin amacı, ADR'lere hızlı bir genel bakış, nasıl oluşturulacakları ve daha fazla bilgi için nereye bakılacağı sağlamaktır. Kısaltmalar: * **AD**: mimari karar * **ADL**: mimari karar günlüğü * **ADR**: mimari karar kaydı * **AKM**: mimari bilgi yönetimi * **ASR**: mimari açıdan önemli gereksinim ================================================ FILE: locales/tr/examples/.locale-peer-id ================================================ ================================================ FILE: locales/tr/examples/4-day-work-week/.locale-peer-id ================================================ fb15d0e84550135e2e7a280693ba5848 ================================================ FILE: locales/tr/examples/4-day-work-week/index.md ================================================ # 4 günlük çalışma haftası için karar kaydı Başlık: 4 Günlük Çalışma Haftasının Uygulanması ## Bağlam ve Sorun Bildirimi Kuruluşumuz 4 günlük çalışma haftasına geçmeyi düşünmektedir. Haftada 5 gün, günde 8 saat olan mevcut çalışma programı, düşük üretkenlik, çalışanların tükenmişliği ve yüksek işten ayrılma oranları ile sonuçlanmıştır. Önerilen değişikliğin amacı, çalışan memnuniyetini, bağlılığını ve elde tutmayı artırmak ve nihayetinde kuruluş performansını iyileştirmektir. ## Karar Önümüzdeki çeyrekten itibaren kuruluş genelindeki tüm çalışanlar için 4 günlük çalışma haftasını uygulamaya karar verdik. ## Gerekçe Karar aşağıdaki faktörlere dayanıyordu: 1. Çalışan geri bildirimi: Çalışanlar arasında yapılan bir anket, daha esnek bir çalışma programı ve daha iyi bir iş-yaşam dengesi arzusunu vurguladı. Katılımcıların çoğunluğu 4 günlük çalışma haftasına ilgi duyduklarını belirtti. 2. Araştırma bulguları: 4 günlük çalışma haftasını uygulayan şirketler üzerine yapılan araştırmalar, çalışan verimliliğinin arttığını, devamsızlığın azaldığını ve iş-yaşam dengesinin iyileştiğini göstermiştir. 3. Rekabet avantajı: 4 günlük çalışma haftası sunmak, potansiyel çalışanlar için cazip bir fayda olabilir ve mevcut yetenekleri elde tutmaya yardımcı olabilir. 4. Kurumsal hedefler: 4 günlük çalışma haftasına geçiş, daha sağlıklı ve daha üretken bir çalışma ortamı yaratma kurumsal hedeflerimizle uyumludur. ## Uygulama Planı 4 günlük çalışma haftasını uygulamak için aşağıdaki adımlar atılacaktır: 1. İletişim: Karar, tüm çalışanlara şirket çapında bir e-posta ve ekip liderleriyle bir toplantı yoluyla iletilecektir. 2. Program: Yeni program, tam zamanlı çalışanlar için Pazartesi'den Perşembe'ye kadar olacak ve yarı zamanlı çalışanlar için esnek program seçenekleri sunulacaktır. Çalışma saatleri günde 10 saate uzatılacaktır. 3. Politika güncellemeleri: İzin politikaları ve yan haklar gibi insan kaynakları politikaları yeni programa uyacak şekilde güncellenecektir. 4. Eğitim: Yöneticiler, yeni program kapsamında ekipleri nasıl yönetecekleri ve çalışan performansını ve üretkenliğini nasıl düzgün bir şekilde izleyecekleri konusunda eğitilecektir. 5. Değerlendirme: Yeni çalışma programı, çalışan memnuniyeti, bağlılığı ve elde tutma üzerindeki etkisini belirlemek için altı ay sonra değerlendirilecektir. ## Beklenen sonuçlar 4 günlük çalışma haftasının uygulanmasının aşağıdaki sonuçları doğurması beklenmektedir: 1. Artan çalışan memnuniyeti, bağlılığı ve elde tutma. 2. Çalışanlar için iyileştirilmiş iş-yaşam dengesi. 3. Artan üretkenlik ve azalan devamsızlık. 4. Daha cazip çalışan yan hakları paketi ve işe alım pazarında rekabet avantajı. ## Sonuç 4 günlük çalışma haftasının uygulanmasının kuruluşumuza ve çalışanlarımıza fayda sağlayacağına inanıyoruz. Bu kararın çalışanlarımız ve genel kurumsal performansımız üzerindeki olumlu etkisini görmeyi dört gözle bekliyoruz. ================================================ FILE: locales/tr/examples/agile-software-development/.locale-peer-id ================================================ a4bc089ce8e95a6dce0fb0845081674a ================================================ FILE: locales/tr/examples/agile-software-development/index.md ================================================ # Çevik yazılım geliştirme için karar kaydı Başlık Çevik Yazılım Geliştirmenin Tanıtımı Tarih: [Tarih Girin] Katılan Ekip Üyeleri: [İsimleri Girin] ## Arka Plan Ekip, üretkenliği artırmak, verimliliği artırmak ve hızla değişen yazılım geliştirme endüstrisine daha iyi uyum sağlamak için Çevik yazılım geliştirme metodolojisini benimsemeyi düşünmektedir. Önemli Noktalar: - Çevik, yinelemeli geliştirmeyi, sık iletişimi ve gereksinimlerde esnekliği vurgular - Çevik, ekip üyeleri arasında daha iyi işbirliğine yol açabilir - Çevik, proje kapsamındaki ve gereksinimlerdeki değişiklikleri öngörmeye ve bunlara yanıt vermeye yardımcı olabilir - Çevik, pazara sunma süresinin kısalmasına ve genel proje sonuçlarının iyileşmesine yol açabilir ## Karar Uzun süren müzakereler ve tartışmalardan sonra Ekip, Çevik yazılım geliştirme metodolojisini benimsemeye karar verdi. ## Gerekçe Çevik'in hızla değişen yazılım geliştirme endüstrisine daha iyi uyum sağlamamıza ve müşterilerimize yüksek kaliteli ürünler sunmamıza yardımcı olacağına inanıyoruz. Çevik'i benimseme kararımız, mevcut iş akışımızın bir değerlendirmesine, sektör uzmanlarıyla yapılan tartışmalara ve uzun vadeli kurumsal hedeflerimize dayanıyordu. ## Eylem Maddeleri - Ekip üyelerinin Çevik metodolojisine aşinalığını değerlendirin ve gerektiğinde gerekli eğitim ve kaynakları sağlayın - Çevik tabanlı proje yönetimi süreçleri ve iş akışları geliştirin ve iletin - Çevik metodolojisinin etkinliğini izlemek için temel performans göstergeleri (KPI'lar) oluşturun - Yeni Çevik metodolojisinin etkinliğini değerlendirmek için KPI'lara yönelik ilerlemeyi izleyin ## Sonuç Çevik yazılım geliştirme metodolojisinin benimsenmesi ekibimiz için önemli bir karardır. Çevik'e geçişimizin daha iyi ürünleri verimli ve etkili bir şekilde sunmamıza yardımcı olacağına inanıyoruz. ================================================ FILE: locales/tr/examples/amazon-web-services/.locale-peer-id ================================================ c4beaa505311198b2b00341fe42c948f ================================================ FILE: locales/tr/examples/amazon-web-services/index.md ================================================ # Amazon Web Services için Mimari Karar Kaydı Başlık: Bulut Altyapısı için Amazon Web Services'i Benimseme ## Karar Çeşitli bulut altyapı platformlarının kapsamlı bir değerlendirmesinden sonra, kuruluşumuzun bulut altyapısı ihtiyaçları için Amazon Web Services'in (AWS) benimsenmesine karar verilmiştir. ## Arka Plan Kuruluşumuz hızla büyüyor ve işimizin taleplerini karşılamak için güvenilir ve ölçeklenebilir bir bulut altyapısına ihtiyacımız var. Bir dizi bulut altyapı sağlayıcısını değerlendirdikten sonra, AWS'nin mevcut ve gelecekteki gereksinimlerimizi karşılamak için en uygun hizmet yelpazesini sunduğu sonucuna varıldı. ## Dikkate Alınan Hususlar Piyasada güvenilir ve verimli olduğu kanıtlanmış çok sayıda bulut altyapı sağlayıcısı bulunmaktadır. Ancak AWS, yalnızca ihtiyaçlarımızı karşılamak için kapsamlı bir hizmet seti sunmakla kalmaz, aynı zamanda geniş bir müşteri tabanına ve başarılı dağıtım geçmişine sahiptir. AWS ayrıca ekibimizin platformla etkili bir şekilde çalışabilmesini sağlamak için geniş bir destek ve eğitim kaynakları yelpazesi sunar. Ayrıca, AWS'nin dünya çapında çeşitli bölgelerde bulunan veri merkezleriyle geniş bir küresel varlığı vardır. Bu, verilerimizin güvende olmasını ve uygulamalarımızın ve hizmetlerimizin yüksek oranda kullanılabilir olmasını sağlar. AWS ayrıca işimiz için kritik olan sağlam bir güvenlik çerçevesine sahiptir. Son olarak, AWS, altyapımızı talebe göre ölçeklendirme esnekliği sunan kullandıkça öde modeli sunar. Bu, yalnızca kullandığımız kadar ücretlendirileceğimiz anlamına gelir, bu da maliyetlerimizi optimize etmemize ve işin diğer alanlarına yatırım yapmamıza olanak tanır. ## Karar Yapılan değerlendirmeler ve AWS'nin sunduğu avantajlar doğrultusunda, bulut altyapısı ihtiyaçlarımız için AWS'nin benimsenmesine karar verilmiştir. ## Sonuçlar AWS'nin benimsenmesi, ekiplerimizin platforma aşina olmalarını ve onu etkili bir şekilde kullanabilmelerini sağlamak için eğitim gerektirebilir. Mevcut altyapımızı AWS platformuna taşımak için bazı başlangıç maliyetleri de olabilir. ## Sahiplik AWS'nin etkin kullanımını ve ilgili risklerin yönetimini sağlama sorumluluğu, bulut altyapı ekibinin yetki alanına girecektir. Ortaya çıkan tüm sorunlar bu ekip tarafından ele alınmalıdır. ## Gözden Geçirme AWS'yi benimseme kararı, ihtiyaçlarımızı karşılamaya devam ettiğinden ve platformun faydalarının tam olarak gerçekleştirildiğinden emin olmak için yıllık olarak gözden geçirilecektir. ================================================ FILE: locales/tr/examples/api-using-json-v-grpc/.locale-peer-id ================================================ 7c91a4cc326aecb7f1a62a6d41b8b4fd ================================================ FILE: locales/tr/examples/api-using-json-v-grpc/index.md ================================================ # Mimari Karar Kaydı: JSON ve gRPC kullanan API ## Durum Kabul edildi ## Bağlam Birden çok istemci tarafından kullanılacak yeni bir hizmet için bir API tasarlıyoruz. API'yi uygulamak için iki seçeneği değerlendiriyoruz: HTTP üzerinden JSON kullanmak veya gRPC kullanmak. HTTP üzerinden JSON, API'ler oluşturmak için yaygın olarak kullanılan bir yaklaşımdır ve birçok programlama dili ve çerçevesi tarafından desteklenir. Bu yaklaşım basit, hafif ve anlaşılması kolaydır, bu da onu birçok proje için iyi bir seçim haline getirir. Ancak, özellikle büyük miktarda veri işlerken diğer seçeneklerden daha az verimli olabilir. öte yandan gRPC, API'ler oluşturmanın daha verimli bir yolunu sunan daha yeni bir teknolojidir. Veri aktarımı için ikili serileştirme kullanır, bu da JSON kullanmaktan daha hızlı ve daha kompakt olabilir. gRPC ayrıca çift yönlü akışı da destekler, bu da onu gerçek zamanlı uygulamalar için iyi bir seçim haline getirir. ## Karar Her iki seçeneğin de artılarını ve eksilerini göz önünde bulundurduktan sonra, API'miz için gRPC kullanmaya karar verdik. HTTP üzerinden JSON daha basit bir seçenek olsa da, gRPC'nin hizmetimiz için daha verimli ve ölçeklenebilir bir çözüm sağlayacağına inanıyoruz. Ayrıca API'mizin büyük miktarda veri işleyeceğini ve gRPC'nin ikili serileştirmesinin bu kullanım durumu için daha verimli olacağını tahmin ediyoruz. Ayrıca, gRPC'nin çift yönlü akış desteğinin gelecekte geliştirebileceğimiz gerçek zamanlı uygulamalar için faydalı olacağına inanıyoruz. ## Sonuçlar gRPC'yi seçerek, API'mizi oluşturmak için HTTP üzerinden JSON kullanmaya kıyasla farklı bir araç ve kitaplık seti kullanmamız gerekecek. Bu, bu teknolojileri öğrenmek ve uygulamak için ek zaman ve çaba gerektirebilir. Ek olarak, API'mizi kullanmak isteyen istemcilerin, HTTP kitaplıkları üzerinden JSON kadar yaygın olarak desteklenmeyebilecek gRPC uyumlu kitaplıkları kullanması gerekecektir. Ancak, gRPC kullanmanın faydalarının bu potansiyel dezavantajlardan daha ağır bastığına ve bu kararın daha verimli ve ölçeklenebilir bir API ile sonuçlanacağından eminiz. ================================================ FILE: locales/tr/examples/authentication-authorization-options/index.md ================================================ # Mimari Karar Kaydı: kimlik doğrulama yetkilendirme seçenekleri Web uygulaması kimlik doğrulaması ve yetkilendirme, uygulamalara ve hizmetlere erişimi güvence altına almada iki önemli kavramdır. Her ikisi de kullanıcıların kimliği ve izinlerin nasıl verildiği ile ilgilenir, ancak farklı yönlere odaklanırlar: - **Kimlik doğrulama**, bir kullanıcının veya sistemin kimliğini doğrulama işlemidir. - **Yetkilendirme**, kimliği doğrulanmış kullanıcının veya sistemin hangi kaynaklara veya eylemlere erişebileceğini belirleme işlemidir. Şimdi, modern web uygulamalarında kimlik doğrulama ve yetkilendirmeyi yönetmek için yaygın olarak kullanılan, bahsettiğiniz belirli protokollere ve teknolojilere dalalım. ### 1. **OAuth (Açık Yetkilendirme)** **OAuth**, yetkilendirme için açık bir standarttır. Bir kullanıcının, kimlik bilgilerini paylaşmadan üçüncü taraf bir uygulamanın kaynaklarına sınırlı erişim vermesine olanak tanır. Anahtar fikir **temsilci erişimidir**. OAuth, kullanıcıların üçüncü taraf bir hizmete (örneğin, Google ile oturum açma) doğrudan kullanıcı adlarını ve şifrelerini vermeden giriş yapabildiği durumlarda sıklıkla kullanılır. - **Akış**: OAuth genellikle, bir yetkilendirme sunucusunun üçüncü taraf uygulamasına bir erişim belirteci verdiği **belirteç tabanlı** bir akışı izler. Bu belirteç, kullanıcının izinlerini temsil eder ve uygulama, bir API'den kullanıcının verilerine veya kaynaklarına erişmek için onu kullanır. - **Örnek**: Bir kullanıcı, Google hesabını kullanarak üçüncü taraf bir uygulamada oturum açar. Google, kullanıcının kimliğini doğrular ve ardından üçüncü taraf uygulamanın bazı Google verilerine (örneğin, Google Takvim) erişmesine izin veren bir belirteç verir. OAuth, kimlik doğrulamayı doğrudan **ele almaz**; erişim izni vermekle ilgilidir. Kimlik doğrulama için OAuth, genellikle **OpenID Connect** gibi diğer protokollerle eşleştirilir. ### 2. **OpenID Connect (OIDC)** **OpenID Connect (OIDC)**, OAuth'un yetkilendirme yeteneklerine kimlik doğrulama ekleyen **OAuth 2.0** üzerine kurulu bir kimlik katmanıdır. Esasen, OpenID Connect, **kullanıcı kimlik doğrulamasını** işlemek için OAuth'u genişletir ve uygulamaların bir kullanıcının kimliğini doğrulaması için standartlaştırılmış bir yol sağlar. - **Akış**: Bir kullanıcı OpenID Connect kullanarak oturum açtığında, üçüncü taraf uygulaması (OAuth erişim belirtecine ek olarak) bir kimlik belirteci talep eder. Kimlik belirteci, kullanıcı hakkında (kullanıcı adı, e-posta ve diğer talepler gibi) bilgiler içerir. Bu, uygulamanın kullanıcının kim olduğunu ve kimliğinin doğrulanıp doğrulanmadığını bilmesini sağlar. - **Örnek**: Google hesabınızı (Google'ın OpenID Connect sağlayıcısı olduğu) kullanarak Slack gibi bir hizmette oturum açmak, OpenID Connect aracılığıyla kimlik doğrulamayı içerirken, OAuth Google kaynaklarınıza erişimi yönetir. OIDC, üçüncü taraf uygulamaların, bu uygulamaların hangi kaynaklara erişebileceği üzerinde ayrıntılı denetime izin verirken **kullanıcıların kimliğini doğrulamayı** kolaylaştırır. ### 3. **SAML (Güvenlik Onaylama İşaretleme Dili)** **SAML**, özellikle **Tek Oturum Açma (SSO)** senaryolarında taraflar arasında kimlik doğrulama ve yetkilendirme verilerini değiştirmek için kullanılan daha eski, XML tabanlı bir standarttır. Öncelikle kurumsal ortamlarda, kullanıcıların bir kez kimlik doğrulaması yapmasına ve kimlik bilgilerini yeniden girmeden birden çok uygulamaya erişmesine olanak sağlamak için kullanılır. - **Akış**: Kullanıcı önce bir kimlik sağlayıcı (IdP) ile kimlik doğrulaması yapar. IdP, kullanıcının kimliğini ve ilgili niteliklerini içeren imzalı bir **SAML onayı** oluşturur. Onay, hizmet sağlayıcıya (SP) gönderilir ve SP, uygulamaya erişimi yetkilendirmek için onu kullanır. - **Örnek**: Bir çalışan, kurumsal portallarına (IdP) giriş yapar ve kimlik bilgilerini yeniden girmeden e-posta, CRM vb. gibi diğer sistemlere otomatik olarak giriş yapar. Kimlik doğrulama işlemi, IdP tarafından gönderilen SAML onayına dayanır. SAML, **kurumsal SSO çözümlerinde** yaygın olarak kullanılır ve kurumsal ortamlardaki web uygulamaları için iyi çalışır, ancak OAuth/OIDC'ye kıyasla daha az mobil uyumludur. ### 4. **WS-Federation (Web Hizmetleri Federasyonu)** **WS-Federation**, özellikle Microsoft tabanlı kurumsal ortamlarda **Tek Oturum Açma (SSO)** için kullanılan başka bir protokoldür. **WS-* (Web Hizmetleri)** belirtim ailesinin bir parçasıdır ve farklı güvenlik alanları (farklı kuruluşlar arasında veya farklı hizmetler arasında gibi) arasında kimlik federasyonuna izin verir. - **Akış**: WS-Federation, **güvenilir bir kimlik sağlayıcının (IdP)** kullanıcıların kimliğini doğrulamasına ve hizmet sağlayıcının yetkilendirme için kullanabileceği belirteçler vermesine olanak tanır. SAML'ye benzer, ancak genellikle Microsoft teknolojilerine büyük ölçüde dayanan senaryolarda kullanılır. - **Örnek**: Bir kullanıcı, Microsoft Azure Active Directory (AD) tarafından barındırılan bir kurumsal uygulamada oturum açar ve kimliği, üçüncü taraf satıcılar tarafından barındırılan uygulamalar da dahil olmak üzere diğer birleşik hizmetlere erişmek için kullanılabilir. WS-Federation, birçok modern web ortamında OAuth2.0 ve OpenID Connect gibi daha yeni protokollerle büyük ölçüde değiştirilmiş olsa da, özellikle Microsoft merkezli işletmelerde eski sistemlerde hala kullanılmaktadır. ### 5. **LDAP (Hafif Dizin Erişim Protokolü)** **LDAP**, genellikle **kullanıcı kimlik bilgilerini depolamak** ve merkezi bir dizinde (genellikle **Dizin Hizmeti** olarak adlandırılır) erişim denetimini yönetmek için kullanılan dizin hizmetlerine erişmek ve bunları yönetmek için kullanılan bir protokoldür. LDAP, özellikle kimlik doğrulama veya yetkilendirme ile ilgili değildir, ancak bu işlemlerde kullanılan kimlik verilerini depolamak ve almak için kullanılır. - **Kimlik Doğrulama**: LDAP, bir uygulamanın kimlik bilgileri (şifreler gibi) için dizin hizmetini sorgulayarak kullanıcıların kimliğini doğrulamasına olanak tanır. - **Yetkilendirme**: Ayrıca kullanıcı rollerini ve izinlerini yöneterek bir kullanıcının belirli kaynaklara erişip erişemeyeceğini belirlemeye yardımcı olur. - **Örnek**: Birçok işletme, özellikle Windows ortamlarında kimlik doğrulama ve yetkilendirme için LDAP tabanlı dizinleri (örneğin, **Active Directory**) kullanır. LDAP, işletmelerin dahili sistemler arasında kullanıcı erişimini yönetmesi için çok önemlidir, ancak modern bir web bağlamında LDAP, daha eksiksiz bir kimlik yönetimi için genellikle SAML veya OAuth gibi diğer protokollerle entegre edilir. ### 6. **Sosyal SSO Sağlayıcıları** **Facebook**, **Google**, **Twitter**, **GitHub** gibi sosyal **Tek Oturum Açma (SSO)** sağlayıcıları, kullanıcıların sosyal medya kimlik bilgilerini kullanarak üçüncü taraf uygulamalarda kimlik doğrulaması yapmasına olanak tanır. Bu, üçüncü taraf hizmetin (örneğin, Google) kimlik sağlayıcısı olduğu bir **OAuth tabanlı kimlik doğrulama** türüdür. - **Akış**: Kullanıcı "Google ile giriş yap" (örneğin) seçeneğine tıklar. Uygulama, kullanıcının (henüz giriş yapmadıysa) giriş yaptığı Google'a yönlendirir. Google daha sonra, kullanıcının kimliğini doğrulamak ve muhtemelen verilerine erişmek için kullanılabilecek bir erişim belirteci veya kimlik belirteci sağlar. - **Örnek**: Birçok uygulama, Google veya Facebook kimlik bilgilerinizi kullanarak giriş yapmanıza olanak tanır. Uygulama, kimliğinizi doğrulamak ve bazı durumlarda belirli sosyal medya verilerine erişmek için arka planda OAuth veya OpenID Connect'i kullanır. Sosyal SSO, kullanıcılar için başka bir kullanıcı adı ve şifre oluşturmak istemeyebilecekleri için sürtünmeyi azalttığı için kullanışlı ve yaygın olarak benimsenen bir kimlik doğrulama yöntemidir. --- ### Farklılıkların Özeti: - **OAuth**: Yetkilendirme için kullanılır, üçüncü taraf uygulamaların kimlik bilgilerini ifşa etmeden kullanıcı verilerine erişmesine olanak tanır. - **OpenID Connect**: Uygulamaların kullanıcı kimliğini doğrulamasına olanak tanıyan kimlik doğrulama sağlamak için OAuth'u genişletir. - **SAML**: Genellikle kurumsal ortamlarda SSO için kullanılan XML tabanlı protokol. - **WS-Federation**: Eski sistemlerde kullanılan kimlik federasyonu için Microsoft'a özgü bir protokol. - **LDAP**: Kullanıcıların kimliğini doğrulamak ve yetkilendirmeyi yönetmek için dizin hizmetlerini sorgulamak için kullanılan bir protokol. - **Sosyal SSO Sağlayıcıları**: Üçüncü taraf uygulamaların sosyal medya kimlik bilgilerini kullanarak kullanıcıların kimliğini doğrulamasına olanak tanıyan OAuth tabanlı sistemler (Google, Facebook gibi). Bu teknolojilerin her birinin kendi güçlü yönleri ve kullanım durumları vardır ve modern uygulamalarda, güvenliğin farklı yönleri için bunların bir kombinasyonunun kullanıldığını görebilirsiniz (örneğin, API erişimi için OAuth/OIDC, kurumsal SSO için SAML). ================================================ FILE: locales/tr/examples/browser-automation-framework-for-e2e-testing-playwright-vs-selenium/index.md ================================================ ## Mimari karar kaydı: E2E testi için tarayıcı otomasyon çerçevesi (Playwright vs Selenium) ### 1. **Bağlam** Uçtan uca (E2E) test boru hattımız için bir tarayıcı otomasyon çerçevesi seçme sürecindeyiz. Bu çerçeve, platformumuzdaki gerçek kullanıcı etkileşimlerini simüle eden testleri çalıştırarak CI/CD süreçlerimizin ayrılmaz bir parçası olacaktır. Özellikle, testler kullanıcı kaydı/girişi, dosya yüklemeleri, pano etkileşimleri ve rapor indirmeleri gibi senaryoları kapsayacaktır. Bir **startup** olarak odak noktamız, hızla yineleme ve gelişme ihtiyacı ile **çevik geliştirmedir**. Ekibimiz ağırlıklı olarak **TypeScript** ve **Python** ile çalışmaktadır ve bu dillerde test yazma yeteneği esastır. Ek olarak, platform **etkileşimli grafikler ve panolar** içerir, bu da otomasyon aracının zengin, dinamik kullanıcı arayüzlerini iyi desteklemesini kritik hale getirir. Bu görev için iki rakip, her birinin kendi güçlü ve zayıf yönleri olan **Playwright** ve **Selenium**'dur. Bu çerçeveleri aşağıda özetlenen özelliklere ve gereksinimlere göre değerlendirmemiz gerekiyor. ### 2. **Dikkate Alınan Seçenekler** - **Playwright** (Microsoft tarafından) - **Selenium** (Selenium Projesi tarafından) ### 3. **Karar Sürücüleri** Kararımızı etkileyen faktörler şunlardır: 1. **Çevik Geliştirme**: Seçilen araç, hızlı ve esnek geliştirme döngülerini sağlamalıdır. 2. **Dil Desteği**: Ekibimiz hem **TypeScript** hem de **Python** için destek gerektirir. 3. **Etkileşimli Kullanıcı Arayüzü Testi**: Etkileşimli grafikleri, panoları ve dinamik öğeleri güvenilir bir şekilde test etme yeteneği esastır. 4. **Çalışma Zamanı Hızı**: Birincil bir endişe olmasa da, CI/CD boru hatlarındaki performans bir düşüncedir. 5. **Ölçeklenebilirlik**: Yakın gelecekte büyük ölçekli ölçeklendirme planlamıyoruz, ancak çözümün gelecekteki büyümeyi kaldırabileceğinden emin olmak istiyoruz. 6. **Geriye Dönük Uyumluluk**: Eski sistemler ve eski tarayıcılarla uyumluluk şu anda projemiz için kritik değildir. 7. **Mobil Test**: Acil bir odak noktası olmasa da, çerçeve mobil duyarlı özellikleri test edebilmeli veya bu tür kullanım durumları için genişletilebilir olmalıdır. 8. **Çoklu Monitör Testi**: Özellikle daha karmaşık kullanıcı iş akışlarını test etmek için ölçeklendiğimizde, çoklu monitör yapılandırmaları için destek ikincil bir gerekliliktir. 9. **Dosya Yükleme Testi**: Çerçeve, test ihtiyaçlarımızın temel bir gereksinimi olan dosya yüklemelerini verimli bir şekilde işlemelidir. ### 4. **Değerlendirme Kriterleri** - **Kullanım Kolaylığı**: Testleri yazmak ve sürdürmek ne kadar kolay? - **Dil Desteği**: Çerçeve, ekibimizin en sık kullandığı iki dil olan TypeScript ve Python'u destekliyor mu? - **Etkileşimli Kullanıcı Arayüzü Testi**: Çerçeve, grafikler, dosya yüklemeleri ve dinamik veriler gibi karmaşık, etkileşimli kullanıcı arayüzlerini ne kadar iyi işliyor? - **CI/CD Entegrasyonu**: Çerçeve, yaygın CI/CD araçları ve hizmetleriyle ne kadar iyi bütünleşiyor? - **Çapraz Tarayıcı Desteği**: Hangi tarayıcılar destekleniyor ve ne kadar iyi performans gösteriyorlar? - **Performans ve Hız**: Testler, özellikle bir CI/CD boru hattında ne kadar hızlı çalışır? - **Ölçeklenebilirlik**: Daha fazla test veya daha karmaşık senaryolar eklendiğinde çerçeve ne kadar iyi ölçeklenebilir? - **Topluluk ve Ekosistem**: Çerçevenin topluluğu ne kadar aktif? Çok sayıda entegrasyon ve uzantı mevcut mu? ### 5. **Dikkate Alınan Hususlar** #### 5.1 **Playwright** ##### **Artıları**: 1. **Yerel Dosya Yüklemeleri için Daha Akıllı API**: Playwright'ın yerel dosyalarla etkileşim kurma ve dosya yüklemeleri gerçekleştirme API'si daha basit ve daha sezgiseldir. Bu, dosya yükleme testini uygulamayı ve sürdürmeyi kolaylaştıracaktır. 2. **Sözdizimi ve Kod Üretimi**: Playwright daha kısa, daha öz bir sözdizimine sahiptir. Bu, daha az standart kodla sonuçlanır, bu da sürdürülebilirliği ve geliştirici verimliliğini artırır. Ek olarak, bu daha kısa sözdizimi, OpenAI kod oluşturma kalitesini artırarak test komut dosyalarını otomatik olarak oluşturmayı kolaylaştırır. 3. **Etkileşimli Kullanıcı Arayüzü Testi**: Playwright, zengin grafikler, karmaşık kullanıcı etkileşimleri ve gerçek zamanlı güncellemeler gibi dinamik, etkileşimli web uygulamalarını test etmede mükemmeldir. WebSockets, WebRTC, gölge DOM'lar ve diğer modern web teknolojilerini çok etkili bir şekilde işler. 4. **Çapraz Tarayıcı Desteği**: Playwright, **Chromium**, **WebKit** ve **Firefox**'u destekler. Bu tarayıcılarda tutarlı bir performansa sahiptir ve bu da test ihtiyaçlarımızın çoğunu karşılamalıdır. 5. **CI/CD Entegrasyonu**: Playwright, modern CI/CD platformlarıyla (GitHub Actions, Jenkins, vb.) sorunsuz bir şekilde bütünleşir. Farklı tarayıcılarda paralel olarak testler çalıştırabilir, test çalışma sürelerini optimize edebilir ve hızlı geliştirme için uygun hale getirebilir. 6. **Hızlı ve Güvenilir**: Playwright, genel olarak, özellikle başsız modda Selenium'dan daha hızlıdır ve eşzamansız web öğeleriyle uğraşırken daha dayanıklıdır. ##### **Eksileri**: 1. **Sınırlı Mobil Test**: Playwright, tarayıcılar için mobil öykünmeyi desteklese de, gerçek mobil test için Selenium'un Appium ile entegrasyonu gibi yerel mobil test yeteneklerinden yoksundur. 2. **Daha Küçük Ekosistem**: Playwright, Selenium'dan hala daha yeni ve daha az yerleşiktir. Hızla büyüyen bir topluluğa ve iyi bir belgelemeye sahip olsa da, Selenium'un sunduğu geniş eklenti ve entegrasyon ekosistemine henüz sahip olmayabilir. 3. **Sınırlı Tarayıcı Desteği**: Playwright, başlıca modern tarayıcıları (Chrome, Safari, Firefox) kapsarken, eski tarayıcılar (örneğin, Internet Explorer) için desteği Selenium kadar sağlam değildir. #### 5.2 **Selenium** ##### **Artıları**: 1. **Daha Uzun Geçmiş ve Olgunluk**: Selenium uzun zamandır var ve kanıtlanmış bir geçmişe sahip. Birçok ekip ve sektörde yaygın olarak kullanılmaktadır ve bu da geniş bir eklenti, entegrasyon ve kaynak ekosistemine yol açmıştır. 2. **Çapraz Tarayıcı ve Çapraz Platform Desteği**: Selenium, **Internet Explorer** dahil olmak üzere **çok çeşitli tarayıcıları** ve sürümlerini destekler ve ayrıca dağıtılmış test için **Docker**, **Selenium Grid** ve **bulut hizmetleri** gibi çeşitli araçlarla entegre edilebilir. 3. **Mobil Test**: Selenium, **Appium** ile entegrasyonu sayesinde, hem Android hem de iOS uygulamaları dahil olmak üzere mobil test için çok daha sağlamdır. Bu, onu mobil öncelikli veya mobil ağırlıklı projelere daha iyi bir seçim haline getirir. 4. **Çoklu Monitör Testi**: Selenium, **birden çok monitör** veya karmaşık çoklu pencere etkileşimleri içeren senaryolar için daha iyi destek sağlar. ##### **Eksileri**: 1. **Karmaşıklık**: Selenium'un API'si daha ayrıntılı ve açıktır. Bu bazı durumlarda bir avantaj olsa da, yazılması ve sürdürülmesi gereken daha fazla kod anlamına gelir, bu da özellikle bir başlangıç ortamında geliştirici çevikliğini azaltabilir. 2. **Performans**: Selenium, özellikle başsız modda Playwright'tan genellikle daha yavaş çalışır. Bu, özellikle test sayısı arttıkça CI/CD boru hatlarını etkileyebilir. 3. **Etkileşimli Kullanıcı Arayüzü Testi**: Selenium, özellikle grafikler ve gerçek zamanlı veri güncellemeleri ile modern, etkileşimli web kullanıcı arayüzlerini test etme konusunda Playwright kadar sorunsuz değildir. Dinamik içerikle güvenilir bir şekilde etkileşim kurmak için daha fazla kurulum ve kullanım gerektirir. ### 6. **Karşılaştırma Özeti** | Özellik | Playwright | Selenium | |---|---|---| | **Kullanım Kolaylığı** | Daha kısa sözdizimi, modern kullanıcı arayüzleri için daha sezgisel | Daha açık, daha fazla standart kod gerektirir | | **Dil Desteği** | TypeScript, Python, JavaScript | TypeScript, Python, Java, Ruby, C# | | **Etkileşimli Kullanıcı Arayüzü Testi** | Dinamik, gerçek zamanlı kullanıcı arayüzleri için mükemmel | Temel kullanıcı arayüzlerini işler, ancak zengin etkileşimler için daha ayrıntılı ve karmaşıktır | | **Dosya Yükleme Testi** | Dosya yüklemeleri için daha akıllı API | Daha ayrıntılı, daha az sezgisel API | | **CI/CD Entegrasyonu** | GitHub Actions, Jenkins ile kolay entegrasyon | Birçok CI aracıyla güçlü entegrasyon | | **Mobil Test** | Sınırlı, yalnızca öykünme | Appium aracılığıyla tam destek | | **Çapraz Tarayıcı Desteği** | Chromium, WebKit, Firefox | Başlıca ve eski tarayıcılarda tam destek | | **Performans** | Hızlı, başsız test için optimize edilmiş | Daha yavaş, özellikle başsız modda | | **Çoklu Monitör Testi** | Sınırlı | Çoklu monitör kurulumları için iyi destek | | **Topluluk ve Ekosistem** | Büyüyen, iyi belgelenmiş | Geniş, olgun, kapsamlı ekosistem | ### 7. **Karar** Gereksinimleri ve ödünleşimleri göz önünde bulundurduktan sonra, **Playwright** mevcut ihtiyaçlarımız için daha iyi bir seçimdir. Yerel dosya yükleme testi için daha akıllı API'si, özlü sözdizimi ve etkileşimli kullanıcı arayüzü testi için güçlü desteği, onu çevik geliştirme döngümüz için ideal bir uyum haline getirir. Hem **TypeScript** hem de **Python**'u desteklemesi ekibimiz için kritik öneme sahiptir ve çerçevenin modern test yaklaşımı, temiz, sürdürülebilir kod yazmamıza olanak tanıyacaktır. **Selenium**, özellikle mobil test, eski tarayıcı desteği ve çoklu monitör kurulumları için harika bir araç olmaya devam ederken, mevcut ihtiyaçlarımıza daha az uygundur. Ayrıntılı olması, daha yavaş performansı ve grafikler gibi dinamik kullanıcı arayüzlerinin daha karmaşık kullanımı, onu bizim kullanım durumumuz için daha az optimal hale getirir. ### 8. **Sonuçlar** - **Acil Eylem**: Kaydolma, oturum açma, dosya yüklemeleri, panolar ve rapor indirmeleri içeren kullanıcı akışlarını test etmeye odaklanarak E2E testimiz için **Playwright**'ı benimseyeceğiz. - **Uzun Vadeli Hususlar**: Gelişen Playwright ekosistemini takip edeceğiz. İhtiyaçlarımız değişirse, özellikle mobil test veya eski tarayıcılar için destek konusunda Selenium'u yeniden ziyaret edebiliriz. - **Eğitim ve Belgeler**: Geliştirme ekiplerinin, özellikle dinamik kullanıcı arayüzlerini ve dosya yüklemelerini işlemek için Playwright'ın API'sine aşina olmaları gerekecektir. - **Geçiş**: Mevcut Selenium testleri (varsa) kademeli olarak Playwright'a geçirilecektir. ### 9. **Gelecekteki Hususlar** ================================================ FILE: locales/tr/examples/chart-library-toolkit-for-data-visualization-using-typescript-and-json/index.md ================================================ # Mimari Karar Kaydı: TypeScript ve JSON kullanarak veri görselleştirme için grafik kitaplığı araç seti **Birincil Amaç:** TypeScript ve JSON kullanarak finansal veriler, bilimsel veriler ve hükümet verilerine odaklanan etkileşimli görselleştirmeler oluşturmak için gelişmiş bir grafik araç takımı seçmek. Kitaplık, sağlam özellikler, esneklik sağlamalı ve açık kaynaklı olmalıdır. ### Bağlam ve Gereksinimler: 1. **Çevik Geliştirme (Yüksek Öncelik)**: Bir başlangıç ​​olarak, hızlı yineleme, prototip oluşturma ve geliştirmede esneklik esastır. Grafik kitaplığı, hızlı geliştirme döngülerine izin vermelidir. 2. **Grafik Türleri (Yüksek Öncelik)**: - **Halka Grafik** - **Radar Grafik** - **Kümeleme Süreci Grafiği** - **Zaman Eksenli Alan Grafiği** - **Mum Grafiği** - **Bülbül Grafiği** - **Coğrafi SVG Haritası** Bu grafik türleri, finansal eğilimler, bilimsel metrikler ve coğrafi bilgiler gibi karmaşık veri kümelerini görselleştirmek için özellikle önemlidir. 3. **Ücretsiz ve Açık Kaynak (Yüksek Öncelik)**: Araç takımı, lisans maliyetlerinden kaçınmak, şeffaflık sağlamak ve özelleştirme için esneklik sunmak için açık kaynaklı olmalıdır. 4. **Düşük Önem Kriterleri**: - **Çalışma Zamanı Hızı**: Performans önemli olsa da, bu karar için en önemli öncelik değildir. - **Ölçeklenebilirlik**: Ölçeklenebilirlik genel olarak önemli olsa da, acil ihtiyaç zamanla büyüyebilecek bir MVP oluşturmaktır. Ölçeklenebilirlik endişeleri daha sonra ele alınabilir. - **Geriye Dönük Uyumluluk**: Kitaplık modern ve aktif olarak sürdürüldüğü sürece, ilk yapı için birincil bir endişe değildir. ### Değerlendirilen Kütüphaneler: 1. **Apache ECharts** 2. **Chart.js** 3. **ApexCharts** 4. **AG Charts** 5. **Highcharts** 6. **Carbon Charts** 7. **Layer Cake** 8. **D3.js** --- ### 1. **Apache ECharts** **Genel Bakış**: Apache ECharts, etkileşimli, özelleştirilebilir görselleştirmeler için güçlü, esnek bir grafik kitaplığıdır. Çok çeşitli grafikleri destekler ve özellikle karmaşık, dinamik görselleştirmelerde güçlüdür. **Güçlü Yönleri**: - **Gelişmiş Etkileşim**: ECharts, yakınlaştırma, kaydırma ve dinamik veri güncellemeleri gibi özellikler sunan etkileşimli grafikler sağlamada mükemmeldir. - **Halka, Radar, Mum, Coğrafi SVG Haritaları**: ECharts, halka, radar, mum ve coğrafi harita görselleştirmeleri de dahil olmak üzere gerekli grafik türlerinin çoğunu destekler. - **Ücretsiz ve Açık Kaynak**: ECharts, bir girişimin bütçeye duyarlı doğasına uyan ve kodu değiştirme özgürlüğü sağlayan açık kaynaklı bir kitaplıktır. - **Esneklik ve Genişletilebilirlik**: Animasyonlar, özel görselleştirmeler ve gelişmiş grafik teknikleri için kapsamlı destekle son derece özelleştirilebilir. **Zayıf Yönleri**: - **Öğrenme Eğrisi**: ECharts, güçlü olmasına rağmen, esnekliği ve kapsamlı API'si nedeniyle daha dik bir öğrenme eğrisine sahip olabilir. - **Belgelendirme Karmaşıklığı**: Belgeler kapsamlıdır ancak yeni başlayan geliştiriciler için bunaltıcı olabilir. **Karar**: ECharts, mum grafikleri, radar grafikleri ve coğrafi haritalar gibi gerekli tüm türleri içeren etkileşimli grafikler desteği nedeniyle proje için son derece uygundur. Açık kaynaklı yapısı, projenin esneklik ve maliyet etkinliği ihtiyacıyla uyumludur. --- ### 2. **Chart.js** **Genel Bakış**: Chart.js, yaygın grafik türleri oluşturmak için basit, kullanımı kolay bir grafik kitaplığıdır. Sadeliği ve entegrasyon kolaylığı ile bilinir. **Güçlü Yönleri**: - **Kullanım Kolaylığı**: Chart.js, minimum öğrenme eğrisi ile kurulumu ve kullanımı çok basittir. - **Açık Kaynak**: Chart.js, maliyetleri düşürmek için kritik olan ücretsiz ve açık kaynaklıdır. - **Yaygın Grafik Türleri**: Birincil ihtiyaçların çoğunu kapsayan halka, alan, radar ve çizgi grafikleri gibi temel grafikleri destekler. **Zayıf Yönleri**: - **Sınırlı Gelişmiş Grafikler**: Chart.js, mum grafikleri, coğrafi SVG haritaları veya kümeleme süreci grafikleri gibi karmaşık grafik türlerini yerel olarak desteklemez. Bu özellikler eklentiler veya özelleştirme yoluyla eklenebilse de, diğer kitaplıklarda olduğu kadar basit değildir. - **Etkileşim**: Chart.js temel etkileşimi (örneğin, araç ipuçları ve üzerine gelme efektleri) desteklese de, ECharts veya D3.js kadar gelişmiş özellikler sunmaz. **Karar**: Chart.js, basit ve hızlı projeler için harikadır, ancak karmaşık grafik türleri desteğinin olmaması, mum grafikleri ve coğrafi haritalar gibi gelişmiş ihtiyaçları olan veri ağırlıklı bir uygulama için uygun değildir. Prototip oluşturmak için iyi bir seçimdir, ancak gerekli grafik türleri için daha gelişmiş araçlar önerilir. --- ### 3. **ApexCharts** **Genel Bakış**: ApexCharts, çeşitli grafik türleri sağlayan ve kullanımı kolay bir API ile etkileşimli görselleştirmelere odaklanan modern bir grafik kitaplığıdır. **Güçlü Yönleri**: - **Etkileşimli Özellikler**: ApexCharts, araç ipuçları, yakınlaştırma, kaydırma ve güncellemeler içeren etkileşimli grafikler sunar. - **Finansal ve Bilimsel Grafikler Desteği**: Mum grafikleri, radar grafikleri ve alan grafikleri de dahil olmak üzere çok çeşitli grafik türlerini destekler. - **Kullanım Kolaylığı**: Basit bir API'ye sahiptir ve bir projeye entegre edilmesi basittir. - **Ücretsiz ve Açık Kaynak**: ApexCharts, birçok kullanım durumu için uygun olan ücretsiz bir açık kaynak sürümü sunar. **Zayıf Yönleri**: - **Karmaşık Özelleştirme**: Birçok özellik sağlarken, özelleştirme seçenekleri son derece karmaşık veya özel grafik ihtiyaçları için ECharts veya D3.js kadar esnek değildir. - **Coğrafi Haritalar**: ApexCharts, bu proje için gerekli olan coğrafi haritaları veya kümeleme süreci grafiklerini yerel olarak desteklemez. **Karar**: ApexCharts, kullanım kolaylığı ve etkileşimi nedeniyle güçlü bir rakiptir, ancak özellikle coğrafi haritalar ve kümeleme grafikleri ihtiyacı olmak üzere belirli gelişmiş grafik türlerinde yetersiz kalmaktadır. Daha basit grafikler için iyi bir seçenektir, ancak bazı gerekli özelliklerden yoksundur. --- ### 4. **AG Charts** **Genel Bakış**: AG Charts, performans ve hassasiyet için tasarlanmış ticari sınıf bir grafik kitaplığıdır. Finansal, bilimsel ve iş panoları oluşturmak için son derece uygundur. **Güçlü Yönleri**: - **Gelişmiş Grafik Türleri**: AG Charts, mum grafikleri, alan grafikleri, radar grafikleri ve daha fazlası dahil olmak üzere birçok gelişmiş grafik türünü destekler. Ayrıca diğer AG-Grid ürünleriyle derin entegrasyon sunar. - **Yüksek Performans**: Özellikle büyük veri kümeleriyle uğraşırken mükemmel performans sunar. - **Etkileşim**: AG Charts, yakınlaştırma, araç ipuçları ve dinamik güncellemeler gibi çeşitli etkileşimli özellikleri destekler. **Zayıf Yönleri**: - **Tamamen Ücretsiz Değil**: AG Charts ücretsiz bir sürüm sunarken, tam özellikli sürüm ücretlidir ve bu da maliyetleri en aza indirmek isteyen yeni başlayanlar için bir engel olabilir. - **Karmaşıklık**: Kitaplık zengin özelliklere sahip olsa da, daha basit projeler için aşırı olabilir ve diğer seçeneklere kıyasla daha fazla kurulum ve yapılandırma gerektirebilir. **Karar**: AG Charts güçlü ve zengin özelliklere sahiptir, ancak ticari yapısı ve maliyet yapısı nedeniyle en uygun olmayabilir. Uygunluğu, bütçenin ücretli sürümleri karşılayıp karşılayamayacağına veya açık kaynaklı alternatiflerin tercih edilip edilmediğine bağlıdır. --- ### 5. **Highcharts** **Genel Bakış**: Highcharts, geniş grafik türü yelpazesi ve güçlü özelleştirme seçenekleriyle bilinen popüler bir grafik kitaplığıdır. **Güçlü Yönleri**: - **Kapsamlı Grafik Türleri**: Highcharts, mum, radar, alan ve coğrafi haritalar da dahil olmak üzere çok çeşitli grafikleri destekler. - **Etkileşimli ve Dinamik**: Highcharts, ayrıntıya inme, yakınlaştırma ve kaydırma gibi zengin etkileşimli özellikler sunar. - **Kullanım Kolaylığı**: Kullanıcı dostu bir API'ye ve iyi bir belgelemeye sahiptir, bu da başlamayı kolaylaştırır. **Zayıf Yönleri**: - **Ticari Lisans**: Highcharts ticari olmayan kullanım için ücretsiz bir sürüm sunarken, ticari lisans pahalıdır ve bu da yeni başlayanlar için önemli bir dezavantaj olabilir. - **Öğrenme Eğrisi**: ECharts kadar dik olmasa da, Highcharts için öğrenme eğrisi yeni başlayanlar için hala zorlayıcı olabilir. **Karar**: Highcharts zengin özelliklere sahip bir kitaplıktır, ancak ticari lisansı onu açık kaynaklı, maliyete duyarlı projeler için daha az uygun hale getirir. Kapsamlı grafik seçenekleri bir artıdır, ancak lisans sorunu bu kullanım durumu için çekiciliğini sınırlar. --- ### 6. **Carbon Charts** **Genel Bakış**: Carbon Charts, görsel olarak çekici ve son derece özelleştirilebilir grafikler oluşturmak için tasarlanmış, IBM tarafından geliştirilmiş bir grafik kitaplığıdır. **Güçlü Yönleri**: - **Özelleştirilebilirlik**: Carbon Charts, grafik görünümünün ve davranışının kapsamlı bir şekilde özelleştirilmesine olanak tanır. - **Açık Kaynak**: Projenin bütçe dostu çözümler gereksinimiyle uyumlu olan ücretsiz ve açık kaynaklıdır. - **Yaygın Grafikler Desteği**: Coğrafi haritalar veya mum grafikleri gibi daha gelişmiş türler için destekten yoksun olmasına rağmen, halka, radar ve alan grafikleri gibi yaygın grafik türlerini destekler. **Zayıf Yönleri**: - **Sınırlı Gelişmiş Grafik Türleri**: Proje için gerekli olan coğrafi haritaları, kümeleme süreci grafiklerini veya mum grafiklerini desteklemez. - **Daha Küçük Ekosistem**: Carbon Charts, ECharts veya Highcharts gibi daha büyük grafik kitaplıklarına kıyasla daha küçük bir topluluğa ve ekosisteme sahiptir. **Karar**: Carbon Charts açık kaynaklı ve özelleştirilebilir, ancak bu proje için gereken daha karmaşık grafik türleri için destekten yoksundur. Daha basit grafik ihtiyaçları için daha uygundur. --- ### 7. **Layer Cake** **Genel Bakış**: Layer Cake, esnek, katmanlı görselleştirmeler oluşturmak için tasarlanmış bir veri görselleştirme kitaplığıdır. **Güçlü Yönleri**: - **Özelleştirilebilir Katmanlar**: Karmaşık görselleştirmeler için güçlü katmanlama seçenekleri sunar. - **Açık Kaynak**: Bütçeye duyarlı projeler için uygun bir seçenek haline getiren ücretsiz ve açık kaynaklıdır. **Zayıf Yönleri**: - **Sınırlı Belgeler**: Layer Cake, kapsamlı belgelere ve topluluk desteğine sahip değildir, bu da daha yerleşik kitaplıklara kıyasla çalışmayı daha zorlaştırır. - **Grafikler İçin Oluşturulmadı**: Layer Cake, grafik olmayan görselleştirmeler için daha uygundur, bu nedenle kullanıma hazır grafik seçenekleri sınırlıdır. **Karar**: Benzersiz görselleştirmeler için ilginç olsa da, Layer Cake mum grafikleri veya radar grafikleri gibi geleneksel grafik gereksinimleri için ideal değildir. Standart grafiklerin kapsamı dışındaki özel görselleştirmeler için daha uygundur. --- ### 8. **D3.js** **Genel Bakış**: D3.js, HTML, SVG ve CSS aracılığıyla veriye dayalı görselleştirmeler oluşturmak için güçlü bir JavaScript kitaplığıdır. **Güçlü Yönleri**: - **Eşsiz Esneklik**: D3.js, neredeyse her tür özel görselleştirme oluşturmaya olanak tanır, bu da onu gelişmiş ve etkileşimli grafikler için son derece güçlü kılar. - **Kapsamlı Özellikler**: Coğrafi haritalar, kümeleme grafikleri ve daha fazlası dahil olmak üzere gerekli tüm grafik türlerini destekler. - **Özelleştirilebilir**: D3.js'deki özelleştirme düzeyi eşsizdir ve geliştiricilerin son derece özel görselleştirmeler oluşturmasına olanak tanır. **Zayıf Yönleri**: - **Dik Öğrenme Eğrisi**: D3.js'nin dik bir öğrenme eğrisi vardır ve diğer kitaplıklara kıyasla entegre edilmesi daha karmaşıktır. - **Zaman Alıcı**: D3.js'de grafikler oluşturmak, özellikle mum veya halka grafikleri gibi yaygın grafikler için zaman alıcı olabilir. **Karar**: D3.js, gelişmiş, özelleştirilmiş grafikler için inanılmaz derecede güçlüdür, ancak dik öğrenme eğrisi ve geliştirme süresi nedeniyle birçok tipik kullanım durumu için aşırıdır. Diğer grafik kitaplıklarının gerekli özelleştirme düzeyini sağlamadığı durumlar için en iyisidir. --- ### Sonuç Kitaplıkları projenin ihtiyaçlarına göre değerlendirdikten sonra, **Apache ECharts** en iyi seçenek olarak öne çıkıyor. Coğrafi haritalar, mum grafikleri ve kümeleme grafikleri de dahil olmak üzere gerekli tüm grafikleri destekler. Açık kaynaklı, zengin özelliklere sahip ve son derece etkileşimlidir, bu da projenin hedefleriyle mükemmel bir şekilde uyumludur. **D3.js** en fazla esnekliği sunarken, karmaşıklığı ve zaman yatırımı, hızlı bir şekilde yineleme yapmak isteyen bir başlangıç ​​için daha az ideal hale getirir. **ApexCharts** ve **Chart.js**, daha basit projeler için iyi alternatiflerdir, ancak gelişmiş grafik türleri için destekten yoksundurlar. ================================================ FILE: locales/tr/examples/choosing-a-database-technology/.locale-peer-id ================================================ ee24129d8750e5ceebb9b4ff7b3cfb1a ================================================ FILE: locales/tr/examples/choosing-a-database-technology/index.md ================================================ # Mimari Karar Kaydı: Bir Veritabanı Teknolojisi Seçimi ## Durum Kabul edildi ## Bağlam Verileri ölçeklenebilir ve performanslı bir şekilde depolamayı ve almayı gerektiren yeni bir uygulama tasarlıyoruz. Yaygın olarak kullanılan üç tür veritabanı teknolojisi belirledik: ilişkisel veritabanları, belge veritabanları ve olay veritabanları. İlişkisel veritabanları, verileri sabit şemalara sahip tablolarda depolar ve katı veri bütünlüğü kısıtlamaları uygular. Karmaşık veri ilişkileri ve işlemleri gerektiren uygulamalar için uygundurlar. Örnekler arasında MySQL, PostgreSQL ve Oracle bulunur. Belge veritabanları, verileri JSON benzeri belgelerde depolar ve şemasızdır. Esnek veri modelleri ve yatay ölçeklendirme gerektiren uygulamalar için çok uygundurlar. Örnekler arasında MongoDB, Couchbase ve Amazon DynamoDB bulunur. Olay veritabanları, verileri bir dizi olay olarak depolar ve verilerdeki her değişikliği yakalar. Denetim, olay kaynağı oluşturma ve karmaşık veri işleme gerektiren uygulamalar için uygundurlar. Örnekler arasında Apache Kafka, Apache Pulsar ve AWS Kinesis bulunur. Karar Uygulamamızın gereksinimlerini ve kısıtlamalarını dikkatlice değerlendirdikten sonra, bir belge veritabanı kullanmaya karar verdik. ## Gerekçe Bir belge veritabanı seçtik çünkü: 1. Uygulamamız, zamanla gelişebilecek esnek bir veri modeli gerektirir. Belge veritabanları, verileri şemasız bir biçimde depolamamıza olanak tanır, bu da veritabanı şemasını değiştirmek zorunda kalmadan yeni alanlar ekleyebileceğimiz veya mevcut belgelerin yapısını değiştirebileceğimiz anlamına gelir. 2. Uygulamamızın büyük hacimli veri ve trafiği işlemek için yatay olarak ölçeklenmesi gerekir. Belge veritabanları, verileri birden çok sunucuya dağıtmamızı ve yüksek okuma ve yazma verimini işlememizi sağlayan parçalama ve çoğaltma için yerleşik destek sağlar. 3. Uygulamamız hızlı ve verimli veri alımı gerektirir. Belge veritabanları, verileri hızlı ve verimli bir şekilde almamızı sağlayan güçlü dizinleme ve sorgulama yetenekleri sağlar. 4. Uygulamamız karmaşık işlemler veya veri ilişkileri gerektirmez. İlişkisel veritabanları, veri bütünlüğü kısıtlamalarını uygulamada ve karmaşık işlemleri işlemede mükemmel olsa da, uygulamamızın bu tür gereksinimleri yoktur. Belge veritabanları, kullanım durumumuz için yeterli tutarlılık ve dayanıklılık garantisi sağlayabilir. ## Sonuçlar Bir belge veritabanı seçerek, kullanmayı seçtiğimiz belirli teknolojiyi öğrenmeye ve anlamaya yatırım yapmamız gerekecek. Ek olarak, performansı ve ölçeklenebilirliği en üst düzeye çıkarmak için uygulamamızın veri modelinin belge veritabanının veri modeliyle iyi bir şekilde eşleştiğinden emin olmamız gerekecektir. Ancak, bir belge veritabanı kullanmanın faydalarının maliyetlerden daha ağır bastığına ve uygulamamızın gereksinimleri ve kısıtlamaları için en uygun olduğuna inanıyoruz. ================================================ FILE: locales/tr/examples/continuous-integration/.locale-peer-id ================================================ 45cdbd2e37d773b7e0592a142fd5de30 ================================================ FILE: locales/tr/examples/continuous-integration/index.md ================================================ # Sürekli entegrasyon için Karar Kaydı Başlık: Sürekli Entegrasyonu Uygulama Kararı ## Bağlam Şirket, manuel test, derleme süreçleri ve dağıtımlar sonucunda geliştirme süreciyle ilgili zorluklar yaşamaktadır. Bu durum, yazılımın kalitesi ve teslimatında sık sık gecikmelere, hatalara ve tutarsızlıklara yol açmıştır. ## Karar Geliştirme sürecinde yaşanan zorluklara bir çözüm olarak sürekli entegrasyonu uygulamak. ## Gerekçe Sürekli entegrasyon, kod değişikliklerini teslimat ortamına zamanında ve verimli bir şekilde otomatik olarak derleyecek, test edecek ve dağıtacaktır. Yazılımın kararlılığına müdahale etmeden yeni özelliklerin kod tabanına entegrasyonunu sağlayacaktır. Sürekli entegrasyon, yazılımın kalitesini ve teslimatını artıracak, hataları çözmek için geçen süreyi azaltacak ve paydaş memnuniyetini artıracaktır. ## Sonuçlar Olumlu: - Yazılımın kalitesi ve teslimatının iyileştirilmesi - Otomasyon yoluyla zaman ve maliyet tasarrufu - Geliştirme ekibi içinde gelişmiş işbirliği ve entegrasyon Olumsuz: - Teknolojiyi uygulamakla ilişkili başlangıç maliyetleri - Sürekli entegrasyonu uygulamak için gereken insanlara, araçlara ve süreçlere ön yatırım - Uygulama sırasında teknik zorlukların potansiyel riski. ## Sonuç Sürekli entegrasyonu uygulamanın faydaları, yatırım maliyetlerinden ve potansiyel risklerden daha ağır basmaktadır. Bu nedenle, sürekli entegrasyonu uygulama kararı onaylanmıştır. ================================================ FILE: locales/tr/examples/css-framework/.locale-peer-id ================================================ 694d2d4235299f058990c1cc470af15e ================================================ FILE: locales/tr/examples/css-framework/index.md ================================================ # Mimari Karar Kaydı: CSS çerçevesi İçindekiler: - [Özet](#özet) - [Sorun](#sorun) - [Karar](#karar) - [Durum](#durum) - [Ayrıntılar](#ayrıntılar) - [Varsayımlar](#varsayımlar) - [Kısıtlamalar](#kısıtlamalar) - [Pozisyonlar](#pozisyonlar) - [Argüman](#argüman) - [Etkiler](#etkiler) - [İlgili](#ilgili) - [İlgili kararlar](#ilgili-kararlar) - [İlgili gereksinimler](#ilgili-gereksinimler) - [İlgili eserler](#ilgili-eserler) - [İlgili ilkeler](#ilgili-ilkeler) - [Notlar](#notlar) ## Özet ### Sorun Web uygulamalarımızı oluşturmak için bir CSS çerçevesi kullanmak istiyoruz: * Kullanıcı deneyiminin tüm popüler tarayıcılarda ve ekran boyutlarında hızlı ve güvenilir olmasını istiyoruz. * Tasarım, düzen, kullanıcı arayüzü/kullanıcı deneyimi vb. konularda hızlı yineleme istiyoruz. * Özellikle mobil cihazlardaki gibi daha küçük ekranlar, 4K geniş ekranlardaki gibi daha büyük ekranlar ve döndürülebilir ekranlar gibi dinamik ekranlar için duyarlı uygulamalar istiyoruz. ### Karar Bulma'ya karar verildi. ### Durum Bulma'ya karar verildi. Yeni CSS çerçevesi seçenekleri geldikçe onlara açığız. ## Ayrıntılar ### Varsayımlar Modern, hızlı, güvenilir, duyarlı vb. web uygulamaları oluşturmak istiyoruz. Tipik modern web uygulamaları, çeşitli nedenlerle jQuery kullanımını azaltıyor/kaldırıyor: * Modern JavaScript, jQuery'nin sağladığı birçok yeteneği aşamalı olarak kullanıma sunuyor, bu nedenle jQuery'ye daha az ihtiyaç duyuluyor ve belirli uygulamaları sağlayan daha iyi/daha hızlı/daha küçük modüller var * jQuery'nin geniş yaklaşımı, modern JavaScript çerçeveleri (ör. React, Vue, Svelte) için bir anti-desen olan doğrudan DOM manipülasyonu yapmaktır. * jQuery, iki kez yüklenirse kendi kendine müdahale eder, vb. ### Kısıtlamalar jQuery kullanan bir CSS çerçevesi seçersek, jQuery'yi içe aktarmak zorunda kalırız. Örneğin, Semantic UI jQuery kullanır ve Tachyons kullanmaz. Minimal bir CSS çerçevesi seçersek, şimdi veya yakında isteyebileceğimiz çerçeve bileşenlerinden vazgeçeriz. Örneğin, Semantic UI bir resim karuseli sağlar ve Tachyons sağlamaz. ### Pozisyonlar Hiçbir çerçeve kullanmamayı düşündük. Bu, özellikle CSS ızgarası projemiz için ihtiyacımız olanın çoğunu sağladığı için hala uygulanabilir görünüyor. Hızlı bir kısa liste üçlemesi kullanarak birçok CSS çerçevesini değerlendirdik: Bootstrap, Bulma, Foundation, Materialize, Semantic UI, Tachyons, vb. Daha derinlemesine inceleme için iki seçimimiz Semantic UI (en anlamsal yaklaşıma sahip olduğu için) ve Bulma (istediğimiz bileşenleri sağlayan en hafif yaklaşıma sahip olduğu için). Semantic UI'yi düşündük. Bu, projemiz için istediğimiz sekmeler, ızgaralar, düğmeler vb. dahil olmak üzere birçok bileşen sağlar. Semantic UI ile iki şekilde bir pilot uygulama yaptık: tipik CDN dosyalarını kullanarak ve NPM depolarını kullanarak. Statik bir HTML sayfasında Semantic UI ile başarı elde ettik, ancak bir JavaScript SPA oluşturmak için zaman kutumuz içinde başarı elde edemedik (öncelikle jQuery yükleme sorunları nedeniyle). Diğer kodlayıcıların, sahip olduğumuz aynı nedenlerle Semantic UI geliştiricilerinden jQuery içermeyen bir sürüm oluşturmalarını istediğini keşfettik. Diğer kodlayıcılar uzun yıllardır jQuery içermeyen bir sürüm talep ediyorlardı, ancak geliştiriciler hayır dedi ve herhangi bir jQuery içermeyen sürümün yazılmasının çok zor olacağını belirtti, örneğin ~"Semantic UI projesinin jQuery kullanan 22.000'den fazla temas noktası var". Anlamsal örnek: ```html
Alfa Bravo
``` Bulma'yı düşündük. Bulma, çok sayıda gelişmiş bileşene sahip olmasa da, Semantic UI'ye benzer birçok yeteneğe sahiptir. Bulma, jQuery'siz gibi modern tekniklerle oluşturulmuştur. Bulma'nın, bazılarını kullanmak isteyebileceğimiz bazı üçüncü taraf bileşenleri vardır. Bulma ile örnek: ```html
``` ### Argüman Yukarıdaki gibi. Özellikle, Semantic UI, hem teknoloji (yani çok sayıda jQuery temas noktası) hem de liderlik (yani jQuery'siz, bir yol haritası denemek veya sürekli iyileştirme veya bağış toplama vb. yerine kesin bir hayırdı) açısından bir uyarı bayrağına sahip görünüyor. ### Etkiler İyi bir jQuery olmayan CSS çerçevesi bulursak, bu genellikle genel olarak yararlı ve iyidir. ## İlgili ### İlgili kararlar Seçtiğimiz CSS çerçevesi test edilebilirliği etkileyebilir. ### İlgili gereksinimler Tamamen modern bir uygulamayı hızlı bir şekilde göndermek istiyoruz. Eski çerçeveler (özellikle Semantic UI) üzerinde eski bağımlılıkları (özellikle jQuery) kullanarak zaman harcamak istemiyoruz. ### İlgili eserler CSS'yi kullanacak tüm tipik HTML'yi etkiler. ### İlgili ilkeler Kolayca geri döndürülebilir. Hız ihtiyacı. ## Notlar Buraya herhangi bir not ekleyin. ================================================ FILE: locales/tr/examples/docker-swarm-container-orchestration/.locale-peer-id ================================================ 3d27355877340537b28efb2bae3a6907 ================================================ FILE: locales/tr/examples/docker-swarm-container-orchestration/index.md ================================================ # Mimari Karar Kaydı: Docker Swarm Konteyner Orkestrasyonu Karar Numarası: 001 Karar Veren: [Adınız veya pozisyonunuz] Tarih: [Karar tarihi] ## Bağlam Mikro hizmet tabanlı mimarimizi yönetmek için farklı konteyner orkestrasyon araçlarını değerlendiriyoruz. Kubernetes, Docker Swarm ve Mesosphere DC/OS gibi farklı çözümleri değerlendirdik. Ancak, basitliği, Docker ile entegrasyonu ve yerleşik yük dengelemesi nedeniyle Docker Swarm'a odaklanmaya karar verdik. ## Karar Konteyner orkestrasyon aracımız olarak Docker Swarm'ı kullanmaya karar verdik. Docker Swarm, bir düğüm kümesi genelinde konteynerli uygulamaları yönetmek için basit ve sezgisel bir yol sağlar. Ayrıca mevcut Docker tabanlı iş akışlarımızı ve altyapımızı kullanmamıza olanak tanır. Docker Swarm ile uygulamalarımızı kolayca dağıtabilir, ölçeklendirebilir ve yönetebiliriz, tüm bunları yerleşik yük dengelemesinden yararlanarak yaparız. ## Faydaları - **Basitlik:** Docker Swarm, Docker ile aynı prensipleri takip eder, bu nedenle yeni bir teknoloji öğrenmeye gerek yoktur. Docker'a aşina olan geliştiriciler için öğrenme eğrisi nispeten sığdır. - **Entegrasyon:** Docker Swarm, Docker Compose gibi Docker araçlarıyla sorunsuz bir şekilde bütünleşir, bu da tüm konteynerlerimizi ve hizmetlerimizi tek bir yerden yönetmeyi kolaylaştırır. - **Yük dengeleme:** Docker Swarm, uygulamalarımızın her zaman kullanılabilir olmasını ve küme genelinde eşit şekilde dağıtılmasını sağlayan yerleşik yük dengelemesi sağlar. - **Ölçeklenebilirlik:** Docker Swarm, kümeden düğümleri ekleyerek veya kaldırarak uygulamalarımızı yatay olarak ölçeklendirmeyi kolaylaştırır. - **Yüksek kullanılabilirlik:** Docker Swarm, hizmetlerimizi düğümler arasında otomatik olarak dağıtarak, düğüm arızası durumunda yüksek kullanılabilirlik sağlar. ## Riskler - **Sınırlı işlevsellik:** Docker Swarm, Kubernetes veya Mesosphere DC/OS'ta bulunan otomatik ölçeklendirme veya kendi kendini iyileştirme gibi bazı gelişmiş özelliklerden yoksun olabilir. - **Docker merkezli:** Docker Swarm, Docker ile sıkı bir şekilde bağlıdır, bu da Docker tabanlı çözümlerden uzaklaşmamız gerekirse esnekliğimizi sınırlayabilir. - **Olgunlaşmamışlık:** Docker Swarm hala nispeten yeni bir teknolojidir ve bazı kararlılık sorunları veya belgelerde boşluklar olabilir. ## Alternatifler - **Kubernetes:** Kubernetes, en yaygın kullanılan konteyner orkestrasyon platformudur ve gelişmiş özellikler ve daha olgun bir ekosistem sağlar. Ancak, daha dik bir öğrenme eğrisine sahiptir ve ihtiyaçlarımız için aşırı olabilir. - **Mesosphere DC/OS:** Mesosphere DC/OS, çoklu bulut desteği ve yerel büyük veri ve yapay zeka platformu yetenekleri gibi gelişmiş özellikler sağlayan güçlü bir araçtır. Ancak, uygulamak için önemli uzmanlık gerektirir ve gereksinimlerimiz için çok karmaşık olabilir. ## Sonuç Dikkatli bir değerlendirmeden sonra, konteyner orkestrasyon aracımız olarak Docker Swarm'ı kullanmaya karar verdik. Docker Swarm, konteynerli uygulamalarımızı yönetmek için ihtiyaç duyduğumuz basitliği, entegrasyonu ve yerleşik yük dengelemesini sağlar. Bazı gelişmiş özelliklerden yoksun olsa da, Docker Swarm'ın faydalarının mevcut gereksinimlerimiz için risklerinden daha ağır bastığına inanıyoruz.
Kredi: Bu sayfa ChatGPT tarafından oluşturulmuş, ardından netlik ve biçim için düzenlenmiştir.
================================================ FILE: locales/tr/examples/environment-variable-configuration/.locale-peer-id ================================================ 46b0910941ab1812cda52b34baca5798 ================================================ FILE: locales/tr/examples/environment-variable-configuration/index.md ================================================ # Ortam değişkeni yapılandırması İçindekiler: * [Özet](#özet) * [Sorun](#sorun) * [Karar](#karar) * [Durum](#durum) * [Ayrıntılar](#ayrıntılar) * [Varsayımlar](#varsayımlar) * [Kısıtlamalar](#kısıtlamalar) * [Pozisyonlar](#pozisyonlar) * [Argüman](#argüman) * [Etkiler](#etkiler) * [İlgili](#ilgili) * [İlgili kararlar](#ilgili-kararlar) * [İlgili gereksinimler](#ilgili-gereksinimler) * [İlgili eserler](#ilgili-eserler) * [İlgili ilkeler](#ilgili-ilkeler) * [Notlar](#notlar) ## Özet ### Sorun Uygulamalarımızın, dağıtım ortamına bağlı olarak farklı davranabilmesi için yapıtlar/ikili dosyalar/kaynak kodunun ötesinde yapılandırılabilir olmasını istiyoruz. * Bunu başarmak için ortam değişkeni yapılandırmasını kullanmak istiyoruz. * Yapılandırmayı sürüm kontrolü yapabileceğimiz dosyaları kullanarak yönetmek istiyoruz. * Nelerin yapılandırılabileceği ve ilgili varsayılanlar gibi bazı geliştirici deneyimi ergonomisi sağlamak istiyoruz. ### Karar İlgili varsayılan dosya ve şema dosyası ile .env dosyalarına karar verildi. ### Durum Karar verildi. Ortaya çıkan yeni yetenekleri değerlendirmeye açığız. ## Ayrıntılar ### Varsayımlar Uygulama kodunu ve ortam kodunu ayırmayı tercih ediyoruz. Uygulamanın geliştirme ortamı, test ortamı, demo ortamı, üretim ortamı vb. gibi farklı ortamlarda farklı çalışması gerektiğini varsayıyoruz. "12 faktörlü uygulama" endüstri uygulamasını ve hatta daha da ilgili olan "15 faktörlü uygulama" uygulamasını tercih ediyoruz. Önceki projelerimizin çoğu, bir `.env` dosyası veya benzeri `.env` dizini kuralını kullanmıştır. Bunları sürüm kontrolünden uzak tutmak ve bunun yerine bunları dağıtmak, sürümlemek ve yönetmek için başka bir yol kullanmak tipik bir uygulamadır. ### Kısıtlamalar Gizli bilgileri kaynak kod yönetim (SCM) sürüm kontrol sistemimizden (VCS) uzak tutmak istiyoruz. Popüler yazılım çerçeveleri ve kütüphaneleriyle uyumluluğu hedeflemek istiyoruz. Örneğin, Node'un ortam değişkeni yapılandırmasını okumak için "dotenv" adlı bir modülü vardır. ### Pozisyonlar Birkaç yaklaşımı değerlendirdik: * Yapılandırmayı `config.js` dosyası gibi uygulamada depolayın. * Yapılandırmayı `.env` dosyası gibi ortamda depolayın. * Yapılandırmayı lisans sunucusu gibi bilinen bir konumdan alın. ### Argüman .env dosyası yaklaşımını seçtik çünkü: * Uzmanlar da dahil olmak üzere popülerdir. * Ekiplerimizin birçok projede defalarca başarıyla kullandığı `.env` dosyaları modelini takip eder. * Basittir. Özellikle, bir lisans sunucusu yaklaşımına kıyasla denetim yeteneklerinin eksikliği gibi gördüğümüz önemli ödünleşimlerle şimdilik sorun yaşamıyoruz. ### Etkiler Ortam değişkeni yapılandırmasını genelden herhangi bir gizli bilgi yönetiminden ayırmanın bir yolunu bulmamız gerekiyor. ## İlgili ### İlgili kararlar Tüm uygulamalarımızın bu yaklaşımı kullanmasını bekliyoruz. İkili dosyada veya kaynak kodda sabit kodlama gibi daha az yetenekli bir yaklaşım kullanan uygulamalarımızı yükseltmeyi planlayacağız. Lisans sunucusu gibi daha yetenekli bir yaklaşım kullanan uygulamalarımızı olduğu gibi tutacağız. ### İlgili gereksinimler Dosyalar için kancalar, testler ve sürekli entegrasyon dahil olmak üzere devops yetenekleri ekleyeceğiz. Bu karar hakkında tüm geliştirici ekip arkadaşlarını eğitmemiz gerekiyor. ### İlgili eserler Dağıttığımız her alanın kendi .env dosyasına ve ilgili dosyalara ihtiyacı olacaktır. ### İlgili ilkeler Kolayca geri döndürülebilir. ## Notlar Örnek `.env` dosyası: ```env NAME=Alice Anderson EMAIL=alice@example.com ``` Örnek `.env.defaults` dosyası: ```env NAME=Joe Doe EMAIL=joe@example.com ``` Sadece anahtarları içeren örnek `.env.schema` dosyası: ```env NAME EMAIL ``` ================================================ FILE: locales/tr/examples/go-programming-language/.locale-peer-id ================================================ 77c69ad4fd10a2dc47f3f7a6dcbbef68 ================================================ FILE: locales/tr/examples/go-programming-language/index.md ================================================ # Mimari Karar Kaydı: Go programlama dili Başlık: Go Programlama Dilinin Benimsenmesi Durum: Kabul Edildi ## Bağlam Kuruluşumuz web uygulamaları geliştirmek için ağırlıklı olarak Java programlama dilini kullanmaktadır. Ancak, Java'nın ayrıntılı yapısı ve bazı çerçevelerin karmaşıklığı nedeniyle bazı zorluklar yaşamaktayız. Ayrıca, ekibimiz daha verimli ve sağlam bir geliştirme için modern programlama dillerini keşfetmeye ilgi göstermiştir. Araştırma yaptıktan sonra, Go'yu Java ile karşılaştığımız sorunlara potansiyel bir çözüm olarak belirledik. ## Karar İleriye dönük olarak web uygulamaları geliştirmek için Go programlama dilini benimseyeceğiz. ## Gerekçe 1. **Basitlik ve okunabilirlik:** Go, basitliği ve özlü sözdizimi ile bilinir. Bu, kod okumayı ve yazmayı kolaylaştırarak geliştirme sürecimizin karmaşıklığını azaltır. 2. **Yüksek performans ve ölçeklenebilirlik:** Go, sunucuda yerel olarak çalışan makine koduna derlenir. Bu, Java gibi yorumlanan dillere kıyasla daha hızlı yürütme süreleri ve daha iyi performans sağlar. Ek olarak, Go'nun eşzamanlılık modeli birden çok isteği aynı anda işleyerek onu yüksek oranda ölçeklenebilir hale getirir. 3. **Güçlü topluluk desteği:** Go, yıllar içinde büyümesine katkıda bulunan canlı bir geliştirici topluluğuna sahiptir. Bu, başlamamıza ve sağlam uygulamalar oluşturmamıza yardımcı olacak çok sayıda kaynak, kütüphane ve çerçeve olduğu anlamına gelir. 4. **Esneklik:** Go hem ön uç hem de arka uç geliştirme için kullanılabilir. Bu, geliştirme projelerimiz için her iki alandaki avantajlarından yararlanabileceğimiz anlamına gelir. ## Etkiler 1. **Eğitim:** Geliştiricilerimizin Go programlama dilini ve inceliklerini öğrenmek için eğitim almaları gerekecektir. 2. **Deneyim:** Java'dan Go'ya geçerken bazı zorluklarla karşılaşabiliriz. Geliştiricilerimizin yeni dile hakim olmaları biraz zaman alabilir. 3. **Araçlar:** Go'ya özgü yeni araçlar ve çerçeveler benimsememiz gerekecektir. Ancak, bu değişikliğin etkisini en aza indirmek için mevcut altyapımızı kullanabiliriz. 4. **Satıcıya bağımlılık:** Go açık kaynaklı bir programlama dilidir ve herhangi bir satıcıya veya hizmet sağlayıcıya bağlı kalmayacağız. ## Sonuç Go programlama dilinin benimsenmesi, geliştirme sürecimizi iyileştirmemize ve sağlam uygulamalar oluşturmamıza yardımcı olacaktır. Bu geçişi desteklemek için eğitim ve araçlara kaynak yatırımı yapmamız gerekecek, ancak bu kararın faydalarının maliyetlerinden daha ağır bastığına inanıyoruz.
Kredi: Bu sayfa ChatGPT tarafından oluşturulmuş, ardından netlik ve biçim için düzenlenmiştir.
================================================ FILE: locales/tr/examples/google-cloud-platform/.locale-peer-id ================================================ 819cd06503cb318caf8f90fcff244b84 ================================================ FILE: locales/tr/examples/google-cloud-platform/index.md ================================================ # Google Cloud Platform için Mimari Karar Kaydı ## Bağlam Google Cloud Platform (GCP), bilgi işlem, depolama ve ağ çözümleri dahil olmak üzere çeşitli bulut hizmetleri sunan önde gelen bir bulut bilişim platformudur. Bu ADR, kuruluşumuz için GCP tabanlı bir altyapı geliştirmek ve uygulamak için alınan mimari kararları belgelemeyi amaçlamaktadır. ## Karar Kuruluşumuz, uygulamamız için bulut altyapısı olarak Google Cloud Platform'u kullanmaya karar vermiştir. Bu kararın birincil değerlendirmeleri şunlardır: - Maliyet etkinliği - Ölçeklenebilirlik - Güvenilirlik - Esneklik ## Seçimler Gereksinimlerimizi karşılamak için GCP'den aşağıdaki hizmetler seçilmiştir: - Sanal makineler ve bilgi işlem kaynakları için Compute Engine - Nesne depolama ve dosya barındırma için Cloud Storage - Yönetilen veritabanı hizmeti için Cloud SQL - Uygulama geliştirme ve barındırma için Firebase ## Gerekçe - Maliyet Etkinliği: Google Cloud Platform, diğer bulut platformlarına kıyasla oldukça uygun maliyetlidir ve bütçe kısıtlamaları olan kuruluşlar için cazip bir seçenek haline getirir. - Ölçeklenebilirlik: GCP'nin kolayca ölçeklenebilen altyapısı, her türlü trafiği gerçek zamanlı olarak işlemeyi sağlar. - Güvenilirlik: GCP'nin yönetilen hizmetleri, kaynakların ve verilerin yüksek kullanılabilirliğini sağlayan otomatik yedeklemeler ve olağanüstü durum kurtarma yetenekleri ile yüksek güvenilirlik sunar. - Esneklik: Platform, yapay zeka, veri analizi ve IoT gibi farklı alanlarda çeşitli araçlar ve hizmetler sunarak oldukça çok yönlüdür. ## Sonuçlar Google Cloud Platform'a geçiş, ekiplerimizi GCP hizmetleri konusunda eğitmeyi, uygulamayı seçilen hizmetlerle uyumlu olacak şekilde yeniden tasarlamayı ve GCP hizmetlerini desteklemek için altyapı kodunu güncellemeyi gerektirecektir. Ancak, geçiş tamamlandıktan sonra, uygulamamızı barındırmak için yüksek oranda ölçeklenebilir, güvenilir ve uygun maliyetli bir altyapıya sahip olmamız beklenmektedir. Ayrıca, GCP'de kaynak sağlama maliyetlerini yönetmemiz gerekecektir. ## Sonuç Google Cloud Platform, maliyet etkinliği, ölçeklenebilirliği, güvenilirliği ve esnekliği nedeniyle bulut altyapımız için mükemmel bir seçimdir. Seçilen hizmetleri kullanarak, uygulamamız için yüksek oranda kullanılabilir ve sağlam bir altyapı sağlayabiliriz. ================================================ FILE: locales/tr/examples/high-trust-teamwork/.locale-peer-id ================================================ 912115918de8642859827f500f4aca23 ================================================ FILE: locales/tr/examples/high-trust-teamwork/index.md ================================================ # Yüksek Güvenli Ekip Çalışması için Karar Kaydı Tarih: [Tarih Girin] Katılımcılar: [Katılımcıların İsimlerini Girin] Karar Ulaşımı: [Oybirliği/Çoğunluk kararı/Bireysel Karar] ## Karar Açıklaması Yüksek Güvenli Ekip Çalışmasını ekibimizin ve organizasyon kültürümüzün temel değeri ve inancı olarak benimseme kararı. ## Değerlendirilen Alternatifler Düşük güvenli veya güvensiz ekip çalışması gibi alternatif ekip çalışması yaklaşımlarını ve bilişsel çeşitlilik ekipleri, merkezi karar alma ekipleri ve çevik ekipler gibi diğer çerçeveleri değerlendirdik. ## Faydaları ve Riskleri Yüksek güvenli ekip çalışmasının faydaları arasında gelişmiş işbirliği, daha iyi karar alma, artan motivasyon ve katılım, daha yüksek iş memnuniyeti ve elde tutma oranları ile gelişmiş inovasyon ve yaratıcılık yer almaktadır. Yüksek güvenli ekip çalışmasıyla ilişkili riskler arasında, yanlış iletişimler veya yüksek güven ilkelerine uymama nedeniyle güven ihlalleri, çatışmalar ve yanlış anlaşılmalar potansiyeli bulunmaktadır. ## Karar Sonucu Yüksek güvenli ekip çalışmasını ekibimizin ve organizasyon kültürümüzün temel değeri ve inancı olarak benimseme konusunda oybirliğiyle anlaşıldı. Şeffaflık, dürüstlük, bütünlük ve saygı yoluyla güven inşa etmenin ve sürdürmenin önemini kabul ettik ve bu yaklaşımın olumlu ve ödüllendirici bir çalışma ortamı oluşturmamıza yardımcı olacağını fark ettik. ## Eylem Maddeleri Yüksek güvenli ekip çalışmasını uygulamak için aşağıdaki adımları atacağız: 1. Yüksek güven ilkelerini ve uygulamalarını tanımlayın ve bunları tüm ekip üyelerine iletin 2. Ekibi ilerleme, zorluklar ve fırsatlar hakkında güncel tutmak için düzenli geri bildirim mekanizmaları ve iletişim kanalları oluşturun 3. Yüksek güvenli ekip çalışması eğitimlerine katılın ve ekip oluşturma etkinliklerine aktif olarak katılın 4. Yüksek güven ilkelerini eylemde gösteren davranışları teşvik edin ve tanıyın 5. Potansiyel güven ihlallerini, çatışmaları veya yanlış anlaşılmaları ele almak için bir plan geliştirin ve bu tür durumları etkili bir şekilde ele almak için bir sürece sahip olun. ================================================ FILE: locales/tr/examples/index.md ================================================ # Karar kaydı örnekleri * [CSS çerçevesi](css-framework) * [Ortam değişkeni yapılandırması](environment-variable-configuration) * [Metrikler, monitörler, uyarılar](metrics-monitors-alerts) * [Microsoft Azure DevOps](microsoft-azure-devops) * [Monorepo ve multirepo karşılaştırması](monorepo-vs-multirepo) * [Programlama dilleri](programming-languages) * [Gizli bilgi depolama](secrets-storage) * [REST API için snake_case ve camelCase karşılaştırması](snake-case-v-camelcase-for-a-rest-api) * [Zaman damgası biçimi](timestamp-format) ChatGPT örnekleri: * [JSON ve gRPC kullanan API](api-using-json-v-grpc) * [Veritabanı teknolojisi seçimi](choosing-a-database-technology) Belirli programlama dilleri: * [Go programlama dili](go-programming-language) * [Rust programlama dili](rust-programming-language) * [Java programlama dili](java-programming-language) * [Python programlama dili](python-programming-language) Belirli veritabanları: * [MySQL veritabanı](mysql-database) * [PostgreSQL veritabanı](postgresql-database) Belirli konteyner orkestrasyon: * [Docker Swarm konteyner orkestrasyonu](docker-swarm-container-orchestration) * [Kubernetes konteyner orkestrasyonu](kubernetes-container-orchestration) Belirli web çerçeveleri, kütüphaneler ve stiller: * [React ön uç JavaScript kütüphanesi](react-front-end-javascript-library) * [Ruby on Rails çerçevesi](ruby-on-rails-framework) * [Svelte ön uç JavaScript kütüphanesi](svelte-front-end-javascript-library) * [SvelteKit çerçevesi](sveltekit-framework) * [Tailwind CSS](tailwind-css) * [Vue ön uç JavaScript kütüphanesi](vue-front-end-javascript-library) ================================================ FILE: locales/tr/examples/java-programming-language/.locale-peer-id ================================================ 984e1e50927d81ec862d5899cd3cb077 ================================================ FILE: locales/tr/examples/java-programming-language/index.md ================================================ # Mimari Karar Kaydı: Java programlama dili Başlık: Proje için Java Programlama Dilini Seçme Karar: Birden çok programlama dilini değerlendirdikten sonra, projemiz için Java kullanmaya karar verdik. ### Arka Plan Birden çok işletim sisteminde çalışabilen web tabanlı bir uygulama oluşturmayı amaçladık. Projemiz, güçlü güvenlik özellikleri sağlayabilen, eşzamanlılığı yönetebilen, büyük kod tabanlarını destekleyebilen ve gelecekteki büyüme gereksinimlerimizi karşılayabilecek kadar çok yönlü bir dil gerektiriyordu. Java'ya karar vermeden önce, güçlü yönlerini ve sınırlamalarını göz önünde bulundurarak birkaç dili değerlendirdik. ### Dikkate Alınan Hususlar 1. **Güvenlik:** Java, iyi tanımlanmış güvenlik politikaları ve erişim kontrolü aracılığıyla mükemmel güvenlik özellikleri sağlar. Ayrıca, kötü amaçlı yazılımların bir sistemde çalışmasını önlemeye yardımcı olan bayt kodu doğrulama gibi özellikleri de içerir. 2. **Eşzamanlılık:** Java, uygulamaların birden çok görevi aynı anda gerçekleştirmesine olanak tanıyan çoklu iş parçacığı desteğine sahiptir. Bu özellik, Java'yı birden çok özellik ve işlevselliğe sahip büyük, karmaşık uygulamalar geliştirmek için mükemmel bir seçim haline getirir. 3. **Büyük kod tabanları:** Java, nesne yönelimli programlamayı destekler, bu da onu büyük kod tabanları geliştirmek için uygun bir seçim haline getirir. Modüler yapısı ve kapsülleme ve soyutlama desenlerinin kullanımı, yazılım geliştirme sürecinin kolaylığını daha da artırır. 4. **Çok yönlülük:** Java çok yönlüdür ve geniş bir kütüphane ve çerçeve yelpazesi kullanma yeteneği sağlar, bu da onu hem web tabanlı hem de kurumsal düzeydeki uygulamalar için mükemmel bir seçim haline getirir. ### Karar Sonucu Güvenlik özellikleri, eşzamanlılık desteği, büyük kod tabanlarını yönetme yeteneği ve çok yönlülüğü göz önünde bulundurarak projemiz için Java programlama dilini kullanmaya karar verdik. Bu karar, proje gereksinimlerimizle uyumludur ve Java'yı seçmenin başarısını sağlayacağına inanıyoruz. ### Sonuçlar 1. Java deneyimi olan ve onu yetkin bir şekilde kullanabilen geliştiricilere ihtiyacımız olacak. 2. Dilde yazılan herhangi bir kod, Java Sanal Makinesi (JVM) ile uyumlu olmalıdır. 3. Yeni özellikler, işlevler veya çerçeveler eklemek bazı zorluklar yaratabilir. 4. Java'daki büyük, karmaşık projelerin geliştirilmesi daha fazla zaman ve kaynak gerektirebilir.
Kredi: Bu sayfa ChatGPT tarafından oluşturulmuş, ardından netlik ve biçim için düzenlenmiştir.
================================================ FILE: locales/tr/examples/kubernetes-container-orchestration/.locale-peer-id ================================================ cb3edecf9181c9c28bbbbc5d323ec733 ================================================ FILE: locales/tr/examples/kubernetes-container-orchestration/index.md ================================================ # Mimari Karar Kaydı: Kubernetes konteyner orkestrasyonu ## Problem Bildirimi Büyüyen bulut tabanlı uygulama portföyümüz için bir konteyner orkestrasyon platformu seçmemiz gerekiyor. Mevcut eski platform dağıtımımız çok yavaş ve büyüyen ihtiyaçlarımıza ayak uyduracak kadar çevik değil. Çeviklikten veya kullanım kolaylığından ödün vermeden hizmetlerimizi mümkün olan en verimli şekilde ölçeklendirmemizi sağlayacak bir sistem arıyoruz. ## Değerlendirilen Alternatifler 1. Docker Swarm 2. Kubernetes 3. Apache Mesos ## Alınan Karar Her bir konteyner orkestrasyon platformunun kapsamlı bir analizini yaptıktan sonra, kurumsal ihtiyaçlarımız için en iyi seçenek olarak Kubernetes'i benimsemeye karar verdik. Kubernetes'i seçme nedenlerimiz şunlardır: 1. **Ölçeklenebilirlik:** Kubernetes'in benzersiz tasarımı, uygulamaları ölçeklendirmek için mükemmeldir ve ölçeklenebilirlik gereksinimlerimiz zamanla geliştikçe, Kubernetes bu değişiklikleri sorunsuz bir şekilde karşılayacak yerleşik yeteneğe sahiptir. 2. **Merkezi Olmayan Mimari:** Kubernetes'in ana-işçi topolojisi, tek bir hata noktasının olmamasını sağlayan merkezi olmayan bir mimariyi garanti eder. 3. **Topluluk Desteği:** Kubernetes, en büyük ve en aktif açık kaynak topluluğuna sahiptir, bu da yardım almamızı ve kaynak bulmamızı kolaylaştıran çok sayıda katkıda bulunan, geliştirici ve satıcı olduğu anlamına gelir. 4. **Ekosistem Desteği:** Kubernetes, çeşitli üçüncü taraf araçları, konteyner kayıt defterleri, CI/CD boru hatları, veri depolama ve daha fazlasıyla entegrasyonları olan büyüyen bir ekosisteme sahiptir. Bu nedenle, mevcut ve yakın gelecek için konteyner orkestrasyon platformumuz olarak Kubernetes'i benimsemeye karar verdik.
Kredi: Bu sayfa ChatGPT tarafından oluşturulmuş, ardından netlik ve biçim için düzenlenmiştir.
================================================ FILE: locales/tr/examples/metrics-monitors-alerts/.locale-peer-id ================================================ d97e71af7770a8cfefb718b2ffd28062 ================================================ FILE: locales/tr/examples/metrics-monitors-alerts/index.md ================================================ # Metrikler, monitörler, uyarılar İçindekiler: * [Özet](#özet) * [Sorun](#sorun) * [Karar](#karar) * [Durum](#durum) * [Ayrıntılar](#ayrıntılar) * [Varsayımlar](#varsayımlar) * [Kısıtlamalar](#kısıtlamalar) * [Pozisyonlar](#pozisyonlar) * [Argüman](#argüman) * [Etkiler](#etkiler) * [İlgili](#ilgili) * [İlgili kararlar](#ilgili-kararlar) * [İlgili gereksinimler](#ilgili-gereksinimler) * [İlgili eserler](#ilgili-eserler) * [İlgili ilkeler](#ilgili-ilkeler) * [Notlar](#notlar) * [Serbest biçimli metin mesajları ve yapılandırılmış olay mesajları](#serbest-biçimli-metin-mesajları-ve-yapılandırılmış-olay-mesajları) * [Graylog daha kolay](#graylog-daha-kolay) * [Prometheus biraz ayar gerektirir](#prometheus-biraz-ayar-gerektirir) * [AWS hizmetleri karışıktır](#aws-hizmetleri-karışıktır) * [Kafka](#kafka) * [Loki](#loki) * [Prometheus + alertmanager + Rollbar + Graylog + Grafana](#prometheus--alertmanager--rollbar--graylog--grafana) * [Thanos](#thanos) * [Prometheus HA](#prometheus-ha) * [Datadog + PagerDuty + Threat Stack](#datadog--pagerduty--threat-stack) * [Zabbix](#zabbix) * [Outlyer](#outlyer) * [Nagios + Nagiosgraph](#nagios--nagiosgraph) * [Prometheus + Grafana + AlertManager](#prometheus--grafana--alertmanager) * [DataDog + Sentry + PagerDuty.](#datadog--sentry--pagerduty) * [Sensu + Graphite + ELK](#sensu--graphite--elk) * [Prometheus + Alertmanager](#prometheus--alertmanager) * [Sensu + Grafana + Graylog + Kibana + NewRelic.](#sensu--grafana--graylog--kibana--newrelic) * [Prometheus + Circonus](#prometheus--circonus) * [icinga2 + VictorOps + NewRelic + Sentry + Slack](#icinga2--victorops--newrelic--sentry--slack) * [AppDynamics + Papertrail + PagerDuty + Healthchecks.io + Stackdriver](#appdynamics--papertrail--pagerduty--healthchecksio--stackdriver) * [icinga2 + elasticsearch](#icinga2--elasticsearch) * [DataDog + New Relic + ELK + EFK + Sentry + Alertmanager + VictorOps](#datadog--new-relic--elk--efk--sentry--alertmanager--victorops) * [Wavefront + Scalyr + PagerDuty + Stackstorm + Slack](#wavefront--scalyr--pagerduty--stackstorm--slack) * [Telegraf + Prometheus + InfluxDB + Grafana](#telegraf--prometheus--influxdb--grafana) * [Sematext + Logagent + Experience](#sematext--logagent--experience) * [Azure Monitor/Analytics + OpsGenie](#azure-monitoranalytics--opsgenie) * [Prometheus + Alertmanager + Grafana + Splunk + PagerDuty](#prometheus--alertmanager--grafana--splunk--pagerduty) * [Telegraf + Prometheus + Grafana + Alertmanager](#telegraf--prometheus--grafana--alertmanager) * [Prometheus + Grafana + Cloudwatch + sentry + kibana + elasticsearch](#prometheus--grafana--cloudwatch--sentry--kibana--elasticsearch) * [PagerDuty + Monitis](#pagerduty--monitis) * [Prometheus + Grafana + Bosun](#prometheus--grafana--bosun) * [Azure Monitor/Analytics/Insights/Dashboards](#azure-monitoranalyticsinsightsdashboards) * [Grafana + Monitis + OpsGenie + Slack](#grafana--monitis--opsgenie--slack) * [Checkly + AppOptics + Cloudwatch + Heroku + Pagerduty + Papertrail](#checkly--appoptics--cloudwatch--heroku--pagerduty--papertrail) * [Instana + Logz.io + slack](#instana--logzio--slack) * [SignalFX + Splunk + PagerDuty + Slack](#signalfx--splunk--pagerduty--slack) * [ELK + Prometheus + Grafana](#elk--prometheus--grafana) * [Datadog + Prometheus + Grafana](#datadog--prometheus--grafana) * [Nagios + ELK](#nagios--elk) * [Datadog vs. Site24x7 + StatusCake + PagerDuty + SumoLogic + Slack](#datadog-vs-site24x7--statuscake--pagerduty--sumologic--slack) * [Prometheus + AlertManager + Grafana + Stackdriver](#prometheus--alertmanager--grafana--stackdriver) * [Zabbix](#zabbix) ## Özet ### Sorun Uygulamalarımızın ne kadar iyi çalıştığını ve bir sorun olduğunda bilmek istediğimiz için metrikler, monitörler ve uyarılar kullanmak istiyoruz. ### Karar WIP. ### Durum Bilgi toplama. Spektrumun olası uçlarından başlıyoruz: en çok önerilen eski ücretsiz araç (Nagios) ve en çok önerilen yeni ücretli araç (New Relic). ## Ayrıntılar ### Varsayımlar Modern, hızlı, güvenilir, duyarlı vb. web uygulamaları oluşturmak istiyoruz. İnşa etmek yerine satın almak istiyoruz. ### Kısıtlamalar Devops boru hattımız ve dağıtım bulutlarımızla iyi çalışan araçlar istiyoruz. ### Pozisyonlar Şu anda pozisyonları araştırıyoruz. * AlertManager * AppDynamics * AppOptics * Azure Monitor/Analytics/Insights/Dashboards * Bosun * Checkly * Circonus * Cloudwatch * EFK * ELK * Grafana * Grafana * Graphite * Graylog * Healthchecks.io * Heroku * icinga2 * InfluxDB * Instana * Kafka * Logagent * Logz.io * Loki * Monitis * Nagios * Nagios * Nagiosgraph * NewRelic * OpsGenie * Outlyer * PagerDuty * Pagerduty * PagerDuty * Papertrail * Prometheus * Rollbar * Scalyr * Sematext Metrikler, Loglar, Deneyim, İzleme * Sensu * SignalFX * Slack * Splunk * Stackdriver * Stackstorm * Telegraf * Telegraf * Thanos * VictorOps * Wavefront * Zabbix ### Argüman Şimdiye kadar Nagios ve New Relic spektrumun uç noktalarıdır. Nagios en eski, en basit, ücretsiz, uygulanabilir araçtır. New Relic en yeni özelliklere sahip, en eksiksiz, ücretli, uygulanabilir araçtır. Bunların değerlendirmeleriyle başlayacağız. Gerektiğinde, spektruma geçeceğiz. Şimdiye kadar Zabbix en iyi önerilere sahiptir ve en eksiksiz yetenekleri sunar. Şimdiye kadar ELK, açık kaynaklı, satın almaktan daha iyi bir popülerliğe sahiptir. Şimdiye kadar Prometheus + Graphana en iyi popülerliğe sahiptir. ### Etkiler YAPILACAK. ## İlgili ### İlgili kararlar Seçimler test edilebilirliği, telemetriyi ve müşteri hizmetleri, site güvenilirliği mühendisliği vb. gibi diğer sistemleri etkileyecektir. ### İlgili gereksinimler YAPILACAK. ### İlgili eserler YAPILACAK. ### İlgili ilkeler Kolayca geri döndürülebilir. Hız ihtiyacı. ## Notlar Oldukça iyi bir açık kaynak yığını şunlardır: * Metrikler ve metriklere dayalı uyarılar için Prometheus * Metrikleri görüntülemek için Grafana * Loglar ve yapılandırılmış olaylar için Elasticsearch/Logstash/Kibana (ELK) * Mobil bildirimler için Pushover ### Serbest biçimli metin mesajları ve yapılandırılmış olay mesajları Serbest biçimli metin mesajları: örneğin, /var/log/messages içinde bulabileceğiniz rastgele şeyler ve uygulama tarafından kasıtlı olarak oluşturulan bir şey. Mesajlar, bellek dışı veya donanım hataları gibi kutuda meydana gelen diğer şeyleri tanımlamak için yararlıdır, ancak çok fazla gereksiz bilgi içerir. Yapılandırılmış olay mesajları: uygulama tarafından, sabit veya dinamik bir dizi öznitelikle oluşturulur, örneğin bir HTTP isteği günlüğü, bir muhasebe günlüğü, bir kullanıcı girişi. Genel olarak konuşursak, her istek hakkında özniteliklere göre ayrıntılı olarak inceleyebileceğiniz bir şekilde ayrıntıları günlüğe kaydetmek güzeldir. Bu nedenle, her şeye örneğin bir kullanıcı kimliği veya oturum kimliği eklemek izlemenizi sağlar. Açık izleme de elbette iyidir. Bunun için ELK kullanmak, bir tür fakir adamın https://www.honeycomb.io/ sürümüdür. ### Graylog daha kolay Deneyimlerime göre Graylog'u başlatmak daha kolay. ### Prometheus biraz ayar gerektirir Genel olarak metrikler için Prometheus'tan memnunum. Uyarılar biraz ayar gerektirir, ancak oldukça iyidir. Uygulamanıza bağlıdır. Bence son kullanıcıya görünen koşullar hakkında uyarı vermek en iyisidir, temel nedenler hakkında değil. Örneğin, sayfa yükleme süresi iyidir, saniyedeki istek sayısı değildir. Ancak saniyedeki sıfır istek, bir şeylerin yanlış olduğunu gösterir. Bir hizmetin avantajı, kutudan çıktığı gibi ek zeka sunmalarıdır. Genel olarak Datadog'u severim. Çok fazla veriniz varsa hizmetler korkutucu derecede pahalı olabilir ve bazen bulut dostu olmayan fiyatlandırma modellerine sahip olabilirler, örneğin örnek başına ücretlendirme, örnekler dinamik olduğunda. Her isteğin ücretli bir kullanıcıdan geldiği hizmetler ile reklamla ilgili olanlar arasında da bir fark vardır, bu nedenle isteklerin yalnızca küçük bir yüzdesi size para kazandırır. Çok fazla veriniz olabilir ve o kadar da bütçeniz olmayabilir. Günde 1 milyar istek alan bazı hizmetler üzerinde çalışıyorum, bu nedenle kendi izleme ve günlük kaydımızı barındırmak mantıklı. Hacimleriniz daha düşükse, barındırılan hizmetler daha kolaydır. ### AWS hizmetleri karışıktır AWS hizmetleriyle ilgili deneyimim karışıktı. Elasticsearch hizmetleri kararsızdı, bu yüzden bunun için kendi örneklerimizi çalıştırıyoruz. CloudWatch metrikleri pahalıdır, bu yüzden genellikle bunları uygulama yerine "altyapı" düzeyindeki metrikler için kullanırız, yani AWS'nin örnek üzerinde çalışan yazılımdan daha iyi bilebileceği sağlıkla ilgili metrikler. CloudWatch Logları yavaş güncellenebilir ve çok fazla meta veriye sahip değildir. ELK çalıştırmak buna yardımcı olur. Gerçek zamanlı verilere gerçekten ihtiyacım varsa, loglar için Kafka'yı taşıma olarak kullanmak daha iyidir. Bu, Logstash tarafından oldukça iyi desteklenir. Bir Kafka kümesini yönetmek cesaret isteyen bir iştir, ancak çok fazla açıkta boru hattı vardır. ### Kafka Yorum: Kafka bazen çok zor olabilir veya Kafka kaya gibi sağlam olabilir ve her şeyi birbirine bağladığını neredeyse unutursunuz. Yorum: Kafka sağlamdı, ancak onu çalıştırmak şaşırtıcı derecede çok işti. Bunu ilişkisel bir veritabanı gibi düşünüyorum, ancak yalnızca "fiziksel" katmanda, örneğin tablo alanları, dosyalar ve bölümler üzerinde çalışıyorsunuz. Başlangıçta yönetim yardımcı programlarının yetersiz olduğu ve örneğin bir tüketici grubunu sıfırlamak için programlar yazmak zorunda kaldığımız zamanlar oldu. http://howfuckedismydatabase.com/nosql/ Yorum: Kafka'yı günlük mesajları için bir "arabellek" ve birden çok sunucudan gelen veriler üzerinde gerçek zamanlı akış işleme yapabileceğimiz bir yer olarak kullanıyoruz. Bir DDOS saldırısı alırsak, verileri birden çok örnekte analiz etmenin bir yoluna ihtiyacımız var. Sunuculardan doğrudan ELK'ye günlük kaydı yapıyorsak, yük Elasticsearch kümesini patlatabilir. Yorum: Kafka bizim için iyidir çünkü bir DDOS saldırısı alırsak, verileri birden çok örnekte analiz etmenin bir yoluna ihtiyacımız var. Sunuculardan doğrudan ELK'ye günlük kaydı yapıyorsak, yük Elasticsearch kümesini patlatabilir. Yorum: Kafka daha az iş yapar ve daha verimlidir, bu nedenle yükü daha iyi kaldırabilir. Ve Kafka işini sıraya alır ve yeniden deneriz. Ve Kafka'nın aşırı yüklenmesi, Elasticsearch zorlanıyorsa olacağı gibi, Kibana ile etkileşimli çalışma yapmaya çalışan kullanıcıları etkilemez. Yorum: Akış işleme çoğunlukla kötüye kullanımı arar, örneğin tüm küme genelinde tek bir IP'den çok fazla trafik ve ardından bloğu tüm küme genelinde paylaşır. Yorum: logstash-output-kafka eklentisi şu anda oldukça güvenilmez. GitHub sorunlar sayfasındaki birkaç sorundan etkilendim, bunlar asla düzeltilmiyor gibi görünüyor. Onu kullanmaktan, uygulamalarımızdan doğrudan Kafka'ya göndermeye geçmek istiyorum. Yorum: Artık yapılandırılmış olayları doğrudan uygulamadan Kafka'ya gönderiyoruz. Ana motivasyon, günlük verilerine daha az dokunmak ve diski birden çok kez okuma ve yazmaktan kaçınmaktı. Yüksek hacimli sistemlerde, günlük kaydı uygulamanın kendisinden daha fazla iş alabilir. journald'nin günlükleri doğrudan bir C programından da göndermesini sağlamayı düşünüyorum. ### Loki Loki'yi yakından takip edin. Henüz hazır değil ama hazır olduğunda bu yığında daha iyi bir uyum olmasını bekliyorum. Loki, grafana laboratuvarları tarafından oluşturulan bir günlük toplayıcıdır, Prometheus ile benzer bir kazıma ve etiket sözdizimi kullanır. ### Prometheus + alertmanager + Rollbar + Graylog + Grafana Metrikler için Prometheus + alertmanager. <3 Prometheus. Günlük kaydı/hata raporlama için Rollbar/Graylog (burada bazı çakışmalar var; küçük bir hizmetin muhtemelen ikisine de ihtiyacı yoktur). Şu anda, uyarılar sadece ilgili tarafların bildirimlerini açtığı birkaç Slack kanalından birine gidiyor. Eğer daha ciddi bir nöbetçi olsaydık, PagerDuty/VictorOps/vb. gibi yerlere giderlerdi. Grafikler ve gösterge tabloları için Grafana. Ayrıca, yaklaşan günlük kaydı tesislerinin Graylog'u gereksiz kılıp kılmayacağını görmek için sabırsızlanıyorum. ### Thanos HA kurulumumuz için Thanos'u ön uç olarak kullanıyoruz. HA çiftlerini nasıl tekilleştireceğini biliyor. Şu anda 6 aylık yerel Prometheus verilerini tutuyoruz. Bu bizim için oldukça iyi çalışıyor. Ancak uzun vadeli veri depolama için Thanos kurulumumuza kova depolamayı devreye alma sürecindeyim. Teorik olarak, GCS depolama, şu anda kullandığımız GCE standart kalıcı diskten yaklaşık %30 daha ucuz olacaktır. Şu anda Prometheus verilerini yedeklemiyoruz. Veriler, uyarılar için yeterli olmanın ötesinde bizim için gerçekten önemli değil. Genel filo dağıtımımız yıldan yıla o kadar çok değişiyor ki, birkaç aydan eski geçmiş veriler o kadar da ilginç değil. Yıllık birkaç temel istatistiğe sahip olmak ilginç olabilir, bir çekirdek istatistik kayıt kuralları seti kurabilir ve bunları Federasyon ile depolayabilir veya sadece Thanos'un halletmesine izin verebilirim. EDİT: Küçük bir uyarı, ben bir Prometheus geliştiricisiyim. ### Prometheus HA Prometheus'ta HA, birden çok popper çalıştırdığınızda çoğaltma ile yapılır, birden çok popper'ı sorgulamanın ve verileri tekilleştirmenin yolları vardır. Ölçeklendirme, ağı belirleyerek ve farklı Prometheus'ların ağın farklı kısımlarını sorgulamasıyla yapılır. Uzun vadeli depolama, Prometheus'un güçlü yanı değildir, ancak influxes veya timescaledb (teknik olarak HA onay işaretini de yapar) gibi bir şeye aktarılır. Bununla ilgili okuduğum makale https://blog.timescale.com/prometheus-ha-postgresql-8de68d19b6f5?gi=7df160f10e07 Uzun vadeli şeyleri henüz denemedim, çünkü hala sadece deney yapıyorum ve kısa vadeli grafikler için kullanıyorum, librenms ise ağımı uzun vadeli olarak izliyor. ### Datadog + PagerDuty + Threat Stack Datadog (PagerDuty ile) ve Threat Stack kullanıyoruz ve daha mutlu olamazdık. DD ile ilgili tek şikayetim, metrik depolamanın nispeten yüksek maliyeti. ### Zabbix Zabbix, neredeyse her şeyi izlemek için özel komut dosyalarıyla. Sorunsuz çalışıyor. ### Outlyer Outlyer kullanıyorum, ancak burada çalıştığımı ve kendi ürünümüzü kullanmanın bir zorunluluk olduğunu belirtmeliyim. Hala Graylog, Sentry ve Statuscake'i geliştirmem gerekiyor. Önyargılı gelebilir, ancak Nagios ve diğer izleme sistemlerini dahili olarak başarıyla çalıştırdıktan sonra, herhangi bir yeni işte barındırılan bir çözüm satın alıp bu acıdan kurtulurdum. ### Nagios + Nagiosgraph Tüm izleme ve uyarılar için Nagios kullanıyoruz. Uyarılar e-posta (uyarılar ve kritik bildirimler) ve sesli uygulama bildirimleri (kritik uyarılar için) aracılığıyla gerçekleşir. Nagiosgraph görselleştirmeler için kullanılır. Bu kurulum, ortamımızda neler olup bittiği hakkında bizi kapsamlı bir şekilde bilgilendirmede çok etkili oldu. Yaklaşık 110 kritik sunucuyu ve yaklaşık 760 veri noktasını çalıştırıyor ve izliyoruz ve bu izleme sistemi yedi yılı aşkın süredir yerinde. Bir noktada günlükleri Graylog veya ELk ile de toplamak istiyorum. ### Prometheus + Grafana + AlertManager Prometheus + Grafana + AlertManager, harika Prometheus Operator helm grafiği aracılığıyla. ELK'nin GKE'deki mütevazı minimum 3 maksimum 5 düğümümüz için çok ağır olduğunu fark ettiğimiz için günlük hala LogDNA huş ağacı planına gidiyor. ### DataDog + Sentry + PagerDuty. Nagios, Icinga, Zabbix, ELK, Greylog2, Influx ve diğer birçok araç dahil olmak üzere her türlü yazılımı kullanarak kendi izleme çözümlerimi çalıştırırdım, ancak gerçek şu ki, kendi izleme altyapınızı çalıştırmak için çok fazla çaba harcamak gerekiyor, özellikle de başkalarına bu kadar düşük ücretlerle yaptırabiliyorken! İzleme altyapısını çalıştırmak için başkalarına ödeme yapmak, müşterilerimin izlemeyi izlemek yerine platformlarını çalıştırmaya odaklanmalarını sağlar, bu da platformlarının kararlılığından elde ettikleri değerin Hizmet Olarak İzleme maliyetlerinden çok daha ağır bastığı anlamına gelir. ### Sensu + Graphite + ELK Şirketim kendi kendine barındırılan şeylere çok düşkün. Sensu -> PagerDuty Graphite/Grafana ELK (Elasticsearch, Logstash, Kibana) ### Prometheus + Alertmanager Uyarılar için Prometheus + Alertmanager, ekibim basit izlemenin iyi izleme olduğuna inanıyor. Günlük kaydı ve izleme gibi diğer sistemler, nöbetçi bir uyarı aldığında teşhis için zengin bağlam sağlayacaktır, ancak bunlara asla uyarı oluşturmayız. ### Sensu + Grafana + Graylog + Kibana + NewRelic. Sensu, grafana, graylog, kibana, newrelic. ### Prometheus + Circonus Prometheus enstrümanlı hizmetler => Circonus analizi ve görselleştirme ### icinga2 + VictorOps + NewRelic + Sentry + Slack Aşağıdaki hizmetleri kullanıyoruz: İzleme için icinga2 ve uyarılar için VictorOps Hizmetin ayrıntılı izlenmesi için NewRelic Hizmette hata izleme için Sentry Slack/E-posta, NewRelic veya icinga2'den tetiklenen uyarıların bir parçasıdır. ### AppDynamics + Papertrail + PagerDuty + Healthchecks.io + Stackdriver AppDynamics Papertrail PagerDuty Healthchecks.io Stackdriver ### icinga2 + elasticsearch Analiz için elasticsearch entegrasyonlu icinga2 ve grafikler için graphite+grafana entegrasyonu. icinga2'deki kuralları uygulama esnekliği sayesinde, geliştiriciler yalnızca bildirim aldıkları hizmetleri görebilirler. ve icinga2 director aracılığıyla, programcılar kendi kontrollerini (her birkaç günde bir yaparlar - 100 kontrol dışarı, 100 kontrol içeri) büyük ölçekte sıfır sorunla kolayca tanımlayabilirler. ### DataDog + New Relic + ELK + EFK + Sentry + Alertmanager + VictorOps Şu anda sahip olduklarımız: Metrikler için DataDog Uygulama izleme için New Relic Loglar için ELK (Elastic Search + Logstash + Kibana) İstisnaları günlüğe kaydetmek için Sentry (kendi kendine barındırılan) Uyarılar için E-postalar + Slack + VictorOps (önem derecesine göre) Sahip olmak istediklerimiz: Metrikler için Prometheus (görselleştirme için Grafana) Uygulama izleme için New Relic (muhtemelen Elastic Search APM) Loglama için EFK (elastic search + fluentd + kibana). Muhtemelen, Grafana'dan Loki, buraya geldiğimizde üretime hazır olacaktır. İstisnalar için Sentry Uyarılar için Alertmanager + e-posta + VictorOps ### Wavefront + Scalyr + PagerDuty + Stackstorm + Slack Wavefront + Scalyr + PagerDuty + Stackstorm + Slack (Yasal Uyarı: VMware'de çalışır) ### Telegraf + Prometheus + InfluxDB + Grafana CPU, Disk, Bellek ve Ağ gibi sunucu metrikleri için Telegraf. Ağ cihazlarımızın SNMP izlemesi için de Telegraf kullanıyoruz. Uygulama metrikleri için Prometheus. Prometheus'un kazıdığı uygulamamıza sağlık kontrolleri kodluyoruz. Zaman serisi depolama için InfluxDB. Telegraf verilerimizin gönderildiği yer burası. Gösterge tabloları ve uyarılar için Grafana. Uyarı motoru süper sağlam değil, ancak işini yapıyor. Ayrıca Slack'e uyarılar gönderiyoruz. Şu anda merkezi bir günlük kaydı çözümüm yok. ELK güçlü ama kurulumu ve yönetimi zor ve incelemeye değer yeterince yakın ücretsiz alternatif bilmiyorum. ### Sematext + Logagent + Experience Metrikler, loglar, izler ve yakında gerçek kullanıcı izlemesi için Sematext. Bence N farklı araç/hizmet kullanmaktan daha basit/ucuz. Log gönderimi için rsyslog kullanıyorduk ve sonra Logagent'a geçtik. Ön uç çökme raporlaması için Sentry kullanıyoruz, ancak kısa süre içinde Experience'a geçeceğiz. Yasal Uyarı: Ben bir Sematextan'ım. ### Azure Monitor/Analytics + OpsGenie Keşke Log Analytics'in daha iyi bir arayüzü olsaydı. Splunk'tan uzaklaşıyoruz, ki bu çok daha kolay gezinilebilirdi. ### Prometheus + Alertmanager + Grafana + Splunk + PagerDuty Prometheus, Alertmanager, Grafana, Splunk, PagerDuty Kendi bildirim sisteminizi çalıştırmak gerçekten istemezsiniz. Güvenlik ekibiniz Splunk'u tercih etmiyorsa Splunk'ı ELK ile değiştirebilirsiniz. ### Telegraf + Prometheus + Grafana + Alertmanager Toplayıcı olarak Telegraf, izleme ve uyarılar için Prometheus + Alertmanager, kritik uyarılar için slack kanalları ve pagerduty ile entegre. Ana bilgisayar metrikleri görselleştirmesi için Grafana. ### Prometheus + Grafana + Cloudwatch + sentry + kibana + elasticsearch Metrikler + uyarılar için Prometheus Prometheus gösterge tabloları için Grafana Cloudwatch izleme Prometheus örnekleri İstisna izleme için sentry kibana + elasticsearch graylog toplu/cron işleri için prometheus Push Gateway SOP https://github.com/rapidloop/sop, 1 Prometheus örneğinden diğerine metrikleri "itmek/iletmek" için müşteriler Prometheus istemcilerini kullanır. İstemci tarafında opencensus.io kullanmaya çalışıyoruz. ### PagerDuty + Monitis PagerDuty + Monitis. Ayrıca bazı hizmetlerin sağlığını test etmek için bazı özel Azure İşlevleri. Bu yıl Prometheus ve Grafana'yı tanıtmayı düşünüyoruz. ### Prometheus + Grafana + Bosun Zaman serisi verilerini depolamak için Prometheus. Görselleştirme için Grafana. Uyarı yönetimi için Bosun. ### Azure Monitor/Analytics/Insights/Dashboards Sadece Azure mağazası, Azure Monitor, Log Analytics, App Insights, Azure Gösterge Tabloları + Pager Duty ### Grafana + Monitis + OpsGenie + Slack Kubernetes'teki konteyner hizmetlerini Prometheus aracılığıyla izlemek için Grafana Web API'leri ve web uygulamaları için uçtan uca hizmet izleme için Monitis Uyarı yönetimi için OpsGenie Sistemlerimizden durum bilgisi almak için Slack ### Checkly + AppOptics + Cloudwatch + Heroku + Pagerduty + Papertrail Uzun süredir (dev)ops mühendisiyim. Nagios ile büyüdüm. Başlangıç ​​SaaS'ım https://checklyhq.com hakkındaki görüşlerinizi almak isterim. Oldukça derinlemesine uyarılarla API izleme ve site işlem izleme yapıyoruz. Checkly'yi, API alanındaki aktif / sentetik izlemenin biraz sınırlı (ve pahalı) olması nedeniyle başlattım. Tarayıcı tabanlı / betik tabanlı izleme daha da tescilli ve pahalıdır. Puppeteer kullanıyoruz ve fiyatları mümkün olduğunca düşük tutuyoruz. İzleme yığınımız: Checkly (kendi ürünümüzü kullanıyoruz...) AppOptics (özel grafikleme) SMS mesajları için AWS Cloudwatch ve SNS. yerleşik Heroku uyarısı. Pagerduty Papertrail ### Instana + Logz.io + slack Instana, altyapı sorunları veya performans düşüşleri hakkında slack'te bizi uyarır ve uygulama katmanından belirli bir hacimde hata düzeyi günlükleri hakkında slack'te uyarı vermek için logz.io'yu yapılandırdık. ### SignalFX + Splunk + PagerDuty + Slack Şu anda kullandıklarımız: SignalFX, Splunk, PagerDuty ve Slack. SignalFX'in destek ekibi süper arkadaş canlısı ve duyarlı olsa da, SignalFX'in büyük bir hayranı değilim. Splunk'ı seviyorum (ödeyebilirseniz değer), PagerDuty ve Slack. Eskiden TICK yığınını kullanırdım, burada C'nin çoğu aslında G idi, yani Grafana idi, ancak Chronograf'ı da biraz kullandım. Bu harikaydı ama yönetmesi zordu. Klasik SaaS ve kendi kendine barındırma ikilemi. DataDog, New Relic, Graylog, ELK ve BugSnag kullandım. DataDog ve New Relic'i çok seviyorum, Graylog oldukça iyi. Ancak büyük bir ELK hayranı değilim. BugSnag güzel, aslında hata/istisna izlemenin birçok durumda tam günlük izleme için oldukça iyi bir yedek olduğunu düşünüyorum. ### ELK + Prometheus + Grafana Diğerleri gibi, loglar için ELK ve diğer her şey için Prometheus+Grafana kullanıyoruz. Bu kurulumu sürdürmek, ara sıra veri kaybetme izni verirseniz kolaydır. Örneğin, Elasticsearch veritabanımız bir sorun yaşarsa (ki bu bizim için ne yazık ki her 2-3 ayda bir olur) HA ile uğraşmayız ve bunun yerine verileri boşaltıp hayatımıza devam ederiz. HA veya uzun vadeli saklama kesinlikle gerekiyorsa, iyi şanslar. ### Datadog + Prometheus + Grafana Buraya geldiğimde izleme ve uyarı olmadığı için Datadog'u aylık olarak kurdum. Sadece birkaç sitemiz 5 dakikada bir çalışma süresi için izleniyordu. Datadog kurulumu en kolay olanıdır. Diğer tüm sorunları giderdiğimde Prometheus+Grafana'ya geçeceğim. Henüz günlük yönetimi konusunda %100 karar vermedim. ### Nagios + ELK Desteklediğimiz 100'den fazla ürünümüz var. Şirket içi için çoğunlukla Nagios ve ELK kullanıyoruz. Bulut için DataDog'dan NewRelic'e geçiş yapıyoruz. ### Datadog vs. Site24x7 + StatusCake + PagerDuty + SumoLogic + Slack Eskiden datadog kullanıyorduk ama ihtiyaçlarımız için çok pahalı olduğunu gördük. Yanlış anlamayın, harika ama çok büyük bir maliyeti var. Site24x7.com'u yıllık abonelikle DD'nin 2-3 aylık maliyetine kurabildik. İzleme yığınımız: Site24x7 - APM, Harici URL izleme, SMTP posta akışı izleme, ssl süre sonları ve süreç izleme. StatusCake - URL izleme ve onay için - Site24x7 bir şeyi kaçırırsa (ki kaçırmaz) bizim yedeğimizdir, ancak SC ihtiyaçlarımız için harici bağlantı noktası ve hizmet izleme için daha esnektir. Her iki araç da PagerDuty'ye yükselir ve ardından Slack'te yükseltmelerimizi alırız. SumoLogic - günlük izleme için (harika bir araç ama ihtiyaçlarımız için biraz karmaşık) Slack'ten bir uyarıyı onaylayabilir veya düzeltebiliriz. Daha sonra, site24x7 otomasyonlarının çoğu, 'BedOps' dediğimiz commando.io'ya bağlanır - burada bir uyarı tetiklendiğinde, durumu düzeltmek için birkaç komut dosyası veya otomasyon başlatırız (zamanın %99'unda otomasyon + komut dosyalarımız bizi beladan uzak tutar) Otomasyonlar başarısız olursa veya düzeltilmesi gereken kapsam dışı bir şey varsa, KB'mizde dahili çalışma kitaplarımız vardır. ### Prometheus + AlertManager + Grafana + Stackdriver GKE kümelerimizde ve VM'lerimizde metrikler için Prometheus (Operatör) / AlertManager / Grafana. Google Stackdriver for Logs (varsayılan olarak dahil olduğu ve aktif olduğu ve şu anda ihtiyaçlarımız için yeterli olduğu için). ### Zabbix Her şey için Zabbix. Ek yazılıma gerek yok. ================================================ FILE: locales/tr/examples/microsoft-azure-cloud-infrastructure/.locale-peer-id ================================================ 4dce71df0db78d050f86e1a2cc4cb9d1 ================================================ FILE: locales/tr/examples/microsoft-azure-cloud-infrastructure/index.md ================================================ # Mimari Karar Kaydı: Microsoft Azure bulut altyapısı" Karar Başlığı: Kuruluşumuz için bulut altyapısı olarak Microsoft Azure'u benimseme Karar Veren: Bilgi İşlem Direktörü Tarih: 2021-10-15 Durum: Onaylandı ## Arka Plan Kuruluş, geleneksel şirket içi altyapıdan bulut altyapısına geçmeyi planlamaktadır. Bunu başarmak için kuruluş, Amazon Web Services (AWS), Google Cloud Platform (GCP), Microsoft Azure ve IBM Cloud gibi birden çok bulut hizmeti sağlayıcısını değerlendirmiştir. Her sağlayıcının kendi özellik, fayda ve fiyatlandırma yapısı vardır. Ayrıntılı bir analizden sonra, Microsoft Azure'un kuruluşumuz için en uygun seçenek olduğu sonucuna varılmıştır. ## Karar Kuruluşumuz için bulut altyapısı olarak Microsoft Azure'u benimseyin. ## Gerekçe Microsoft Azure'u benimseme nedenleri şunlardır: 1. Kapsamlı Hizmetler: Azure, hizmet olarak altyapı (IaaS) ile hizmet olarak yazılım (SaaS) ve hizmet olarak platform (PaaS) arasında eksiksiz bir bulut hizmetleri yelpazesi sunar. Bu, depolama, bilgi işlem, ağ ve analiz gibi kuruluşun gereksinimlerini çözmek için Azure hizmetlerinden yararlanmamızı sağlar. 2. Ölçeklenebilirlik ve Esneklik: Azure ile kaynakları iş gereksinimlerimize göre kolayca ölçeklendirebilir veya azaltabiliriz. Azure ayrıca işletim sistemi, programlama dili ve çerçeveleri seçmede esneklik sunar. 3. Güvenlik ve Uyumluluk: Azure, ISO, SOC, HIPAA ve PCI DSS gibi çeşitli endüstri standartlarına uyumlu olduğu için yüksek düzeyde güvenlik ve uyumluluk sunar. Azure ayrıca ağ güvenlik grupları, güvenlik duvarları ve DDoS koruması gibi gelişmiş güvenlik özellikleri sağlar. 4. Hibrit Bulut: Azure, kuruluşların şirket içi altyapılarını Azure ile bağlamalarını sağlayan sorunsuz bir hibrit bulut deneyimi sunar. Bu, iş yüklerini buluta taşımamızı kolaylaştırır ve verileri nerede depolayacağımızı seçme esnekliği sağlar. 5. Maliyet etkinliği: Azure, kullandıkça öde fiyatlandırma modeli sunar, bu da yalnızca kullanılan kaynaklar için ödeme yaptığımız anlamına gelir. Bu, geleneksel şirket içi altyapıya kıyasla maliyet tasarrufu yapmamıza yardımcı olur. ## Sonuç Kuruluşumuz için bulut altyapısı olarak Microsoft Azure'u benimsemek, iş gereksinimlerimizle uyumludur ve ölçeklenebilirlik, esneklik, güvenlik ve maliyet etkinliği gibi çeşitli faydalar sunar. Bu nedenle, Azure'u bulut altyapımız olarak benimsemeniz önerilir. ================================================ FILE: locales/tr/examples/microsoft-azure-devops/.locale-peer-id ================================================ e1e84e31e7b1463322b083fd2983fe1a ================================================ FILE: locales/tr/examples/microsoft-azure-devops/index.md ================================================ # Microsoft Azure DevOps İçindekiler: * [Özet](#özet) * [Sorun](#sorun) * [Karar](#karar) * [Durum](#durum) * [Ayrıntılar](#ayrıntılar) * [Varsayımlar](#varsayımlar) * [Kısıtlamalar](#kısıtlamalar) * [Pozisyonlar](#pozisyonlar) * [Argüman](#argüman) * [Etkiler](#etkiler) * [İlgili](#ilgili) * [İlgili kararlar](#ilgili-kararlar) * [İlgili gereksinimler](#ilgili-gereksinimler) * [İlgili eserler](#ilgili-eserler) * [İlgili ilkeler](#ilgili-ilkeler) * [Notlar](#notlar) * [Microsoft Devops CI: Tatmin Edici Olmayan Bir Macera](#microsoft-devops-ci-tatmin-edici-olmayan-bir-macera) * [Hacker News tartışma öne çıkanları](#hacker-news-tartışma-öne-çıkanları) * [Windows Geliştirme MVP](#windows-geliştirme-mvp) * [Edward Thomson (Azure PM) özeti](#edward-thomson-azure-pm-özeti) ## Özet ### Sorun Projelerimizi oluşturmak, entegre etmek, dağıtmak ve barındırmak için devops kullanmak istiyoruz. Microsoft Azure DevOps'u değerlendiriyoruz. * Devops kurulumu (örneğin yapılandırma) ve sürekli kullanım (örneğin hızlı derleme süreleri) için geliştirici deneyiminin hızlı ve güvenilir olmasını istiyoruz. * Proje uygulamalarını, veritabanlarını vb. barındırmak için Microsoft Azure'u bir bütün olarak kullanmayı düşünmek istiyoruz. ### Karar Microsoft Azure DevOps'a karşı karar verildi. ### Durum Karar verildi. Yeni önemli bilgiler geldiğinde/gelirse yeniden değerlendirmeye açığız. ## Ayrıntılar ### Varsayımlar Accelerate kitabındaki gibi tüm olağan devops varsayımları. * Hızlı derlemeler önemli bir yardımdır. Bu, geri bildirim döngülerini hızlandırır. * Alternatif satıcılardan parçaları değiştirebiliriz, yani daha yüksek hızlı derleme sunucularımızı getirmek veya kendi sürüm kontrol sistemimizi seçmek veya kendi kendine barındırılan sürekli entegrasyon sunucusuyla koordine etmek isteyebiliriz. * Geliştirici deneyimi için ve dolayısıyla tutarlılık, netlik, güvenlik ve öğrenme eğrisinin kolaylığı gibi hassas alanlar için kolaylaştırılmış kullanılabilirlik önemli bir yardımdır. * Herhangi bir şey bozulduğunda veya sorunlu olduğunda, sorunu bildirmek için etkili bir yol istiyoruz. Bu, özellikle güvenlikle ilgili sorunlar için önemlidir. ### Kısıtlamalar Bilinen bir kısıtlama yok. Azure, harici araçlarla iyi çalışmaya yönelik yayınlanmış bir taahhüde sahiptir. ### Pozisyonlar Microsoft Azure Devops'u mevcut AWS'ye karşı kullanmayı düşündük. Azure DevOps, Azure Pipelines, Azure Repo ve Terraform aracılığıyla yeni sunucu başlatma ile denemeler yaptık. Microsoft temsilcilerinden destek alma konusunda denemeler yaptık. Bloglardan ve Hacker News'ten akranlardan bilgi topladık. ### Argüman Azure DevOps mükemmel bir teklif seti reklamı yapıyor, ancak bunlar ayakta durmuyor, birlikte iyi çalışmıyor ve destek zayıf. İlk elden deneyimimiz: * Azure kurulumu, bazıları Microsoft hesaplarıyla çakışan, bazıları çakışmayan kullanıcı arayüzlerinin bir karmaşasıdır. Örneğin, bir Azure oturum açma, bir Microsoft.com oturum açma, bir Live.com oturum açma vb. vardır ve hepsi aynı anda devrededir. * Kurulum sırasında küçük bir güvenlik sorunuyla karşılaştık ve çözüm bulamadık. Birçok Microsoft temsilcisine birçok yolla bildirmeye çalıştık, ancak başarılı olamadık. Microsoft güvenliğine başarıyla bildirdik, ancak düzeltilmeyeceği yanıtını aldık. * Belgeler genellikle yanlış veya güncel değil. Bunun en azından bir kısmı Microsoft'un zayıf arama motorundan ve bir kısmı da yetersiz SEO'dan kaynaklanmaktadır. * Terraform kurulumu iyi belgelenmiştir ve çalışır. Ancak, Microsoft'un Terraform kurulum örnekleri aracılığıyla zincirleme yapmak için satıcılarla iş ilişkileri kurması nedeniyle Terraform desteği AWS'ye kıyasla zayıftır. Akran deneyimlerimiz: * Kendi kör değerlendirmemizi yaptıktan sonra, akran deneyimlerini aradık. Bulduklarımız deneyimlerimizi doğruladı. * Akranlar, derleme süreleriyle ilgili ek sorunlar ve kendi derleme sunucunuzu getirme sorunları bildirdi. Bu sorunlar, kullanıcı arayüzü sorunlarından önemli ölçüde daha ciddidir, çünkü derleme yapmak bir derleme boru hattının temel amacıdır ve günde birçok kez yapmayı bekleriz. * Azure ekip arkadaşlarının tartışma alanlarına mükemmel katılımını bulduk. Microsoft'a bunun için teşekkür ederiz. Özellikle Edward Thomson, Azure PM ve kodlayıcı, katılımı, doğrudanlığı ve teknik açıklamaları nedeniyle bizi çok etkiledi. ### Etkiler Microsoft Azure DevOps'u seçmek, Azure'u seçmemekten daha pahalı (~3 kat) zaman ve maliyet açısından daha pahalı olma olasılığı yüksek görünüyor. ## İlgili ### İlgili kararlar Azure DevOps'u seçersek, Azure Repo, Azure Pipeline vb. dahil olmak üzere birçok ilgili teklif vardır. Azure Devops'u seçersek, bu, daha fazla Azure yeteneği kullanmayı kolaylaştırabilir veya diğer satıcıların yeteneklerini kullanmayı zorlaştırabilir. Microsoft'un geliştirici deneyiminde büyük adımlar attığına inanıyoruz ve Microsoft'un geliştirici araçlarını (örneğin GitHub) ve bağımlılıklarını (örneğin Citus) büyük ölçüde satın aldığını görüyoruz. Azure DevOps'u seçersek, Microsoft satın alma tekliflerini seçmeye vurgu yapmak isteyebiliriz ve potansiyel doku reddi, örneğin personel devir riski nedeniyle satın alma tekliflerine daha dikkatli/değerlendirmeyle yaklaşmak isteyebiliriz. ### İlgili gereksinimler Derleme sürelerinin çok hızlı olmasını istiyoruz. Bunun için yüksek bir prim ödemeyi kabul ediyoruz. Bunun nedeni, çok hızlı yineleme yapmak istememizdir. Güvenilirliğin çok yüksek olmasını istiyoruz. Bunun için yüksek bir prim ödemeyi kabul ediyoruz. Bunun nedeni, finansal işlemler, gizli işlemler vb. dahil olmak üzere yüksek değerli kullanım durumlarını test etmemizdir. En iyi 4 devops KPI'mız, hızlı derlemeler ve yüksek güvenilirlik gerektiren ortalama kurtarma süresini içerir. ### İlgili eserler Derleme sisteminin, Artifactory gibi diğer sistemlerde kullanıma uygun yapıtlar üretmesini istiyoruz. ### İlgili ilkeler Kolayca geri döndürülebilir. Azure DevOps'u AWS ile paralel olarak değerlendirebiliriz. ## Notlar ### Microsoft Devops CI: Tatmin Edici Olmayan Bir Macera https://toxicbakery.github.io/vsts-devops/microsoft-devops-ci/ Blog yazısı. "Bir yazılım geliştiricisi olarak, kaliteli ürünleri hızlı ve ucuza inşa etmenin ne kadar zor olduğunu ilk elden biliyorum. Bu, bazen doğru yaptığımız, bazen de Obama dönemi sağlık hizmetleri hükümet sitesine benzer bir şeye dönüşen bir sanat formudur. Ortaya çıkan ürün üzerindeki kontrol seviyemiz değişir ve başarısızlığın suçu genellikle karar alma hiyerarşisindeki yanlış kişilere düşer. Microsoft'un Azure DevOps (eski adıyla Visual Studio Team Services), açıkça iyi niyetlere rağmen, kötü kararların ve kötü uygulamanın mükemmel bir fırtınasıdır." ### Hacker News tartışma öne çıkanları https://news.ycombinator.com/item?id=18983586 "İşimde Azure DevOps'u yoğun bir şekilde kullanıyoruz ve GitHub, Gitlab, kendi kendine barındırılan çözümler, Jenkins, TeamCity... kullandıktan sonra Azure DevOps son sırada yer alıyor." "Kullanıcı arayüzü her yerde korkunç derecede hantal. Benim için en kötüsü çekme istekleri. Bir çekme isteği üzerinde insanlarla çalışmak inanılmaz derecede zor. Size "belirli" bir sorunu bile gösteremem - bizim için her yerde bozuk." "Azure Devops sevmek istediğim bir şey. Kullanıcı arayüzü sürekli değişiyor, ancak yıllardır var olan temel hataları düzeltmiyor." "Araçlar iyi entegre değil, kullanıcı arayüzü gerçekten yavaş, favori depolarım için aktif çekme istekleri, derlemeler, yayınlar vb. için bir gösterge paneli görünümü yok. Derleme/Dağıtım süreleri inanılmaz derecede yavaş." "Azure Boards'u (İş Öğeleri, Panolar, İş Listeleri vb.) da kullanmaya çalıştık. Ah! Tamamen kopuk fikirlerin bir kullanıcı arayüzü karmaşası. Bir şeyi iyi uygulamak yerine, iki düzine şeyi korkunç bir şekilde uyguladılar." ### Windows Geliştirme MVP Windows Geliştirme MVP olarak buradayım. Bu sorunlar hakkında daha yüksek sesle konuşmadığım için sorumluluğun bir kısmını üstlenmem gerektiğini hissediyorum. Ancak şunu söylemeliyim ki, UX sorunları hakkında "şaşırmış" olmanız beni hayal kırıklığına uğrattı. İnsanlarınıza UX'in korkunç olduğunu (örneğin lansman öncesinden beri) söylüyordum ve sürekli "biliyoruz, düzeltiyoruz" yanıtını alıyordum. Geri bildirimi resmileştirmeye başlayacağım ve boru hatlarından geçireceğim, takipte kalın. Ayrıca yerel (Bellevue) olarak da buradayım, nispeten basit oss .net/wpf/uwp uygulamamızı boru hattına sokmaya çalışmak isterim. Sanırım ikimiz için de göz açıcı olacaktır. Bazı örnekler: * Alt modüller içeren bir git deposuyla bir boru hattı oluşturamazsınız. * Bazı özel araçlar için PATH'i düzenlemenin imkansız olduğunu gördüm. * Yeni Boru Hattı deneyimi pek mantıklı değil, yeni kullanıcılar etrafa tıklayarak sonunda yanlış Belgelere ulaşacaklar. ### Edward Thomson (Azure PM) özeti Çekme isteklerinizi birleştiren kodu ben yazdım. Microsoft'ta Azure DevOps için Program Yöneticisi; daha önce GitHub, Microsoft, SourceGear'da sürüm kontrol araçları üzerinde yazılım mühendisiydi. https://www.edwardthomson.com/ libgit2'nin ortak bakımcısı. https://libgit2.github.io Git hakkında Podcast olan All Things Git'in ortak sunucusu. https://www.allthingsgit.com/ Geliştirme araçları hakkında bir bülten olan Developer Tools Weekly'nin küratörü. https://developertoolsweekly.com/ ================================================ FILE: locales/tr/examples/monorepo-vs-multirepo/.locale-peer-id ================================================ b52cc745a00570dede6cd309dd35d7ac ================================================ FILE: locales/tr/examples/monorepo-vs-multirepo/index.md ================================================ # Monorepo vs multirepo Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes) ## Summary ### Issue Our project involves developing three major categories of software: * Front-end GUIs * Middleware services * Back-end servers When we develop, our source code management (SCM) version control system (VCS) is git. We need to choose how we use git to organize our code. The top-level choice is to organize as a "monorepo" or "polyrepo" or "hybrid": * Monorepo means we put all pieces into one big repo * Polyrepo means we put each piece in its own repo * Hybrid means some mix of monorepo and polyrepo For more please see https://github.com/joelparkerhenderson/monorepo-vs-polyrepo ### Decision Monorepo when an organization/team/project is relatively small, and rapid iteration is higher priority than sustaining stability. Polyrepo when an organization/team/project is relatively large, and sustaining stability is higher priority than rapid iteration. ### Status Decided. Open to revisiting if/when new tooling becomes available for managing monorepos and/or polyrepos. ## Details ### Assumptions All the code that we're developing is for one organization's offerings, and not for the general public. I.e. the Broker-Dealer isn't aiming to have anything like general public volunteer developers. ### Constraints Constraints are well-documented at https://github.com/joelparkerhenderson/monorepo-vs-polyrepo ### Positions We considered monorepos in the style of Google, Facebook, etc. We think any monorepo scaling issues are so far in the future that we will be able to leverage the same practices as Google and Facebook, by the time we need them. We considered polyrepos in the style of typical Git open source projects, such as Google Android, Facebook React, etc. We think these are the best choice for general public participation (e.g. anyone in the world can work on the code) and individual availability (e.g. the project is used on its own, without any other pieces). ### Argument When an organization/team/project is relatively small, we choose monorepo, because rapid iteration is significantly higher in priority than sustaining stability When an organization/team/project is relatively large, we choose polyrepo, because sustaining stability is significantly higher in priority than rapid iteration. ### Implications If there's an existing pipeline for CI+CD, then we may need to adjust it for testing multiple projects within one repo. CI+CD could take more time for a full build for a monorepo, because CI+CD could build all the projects in the monorepo. If an organization/team/project grows, then a monorepo will have scaling issues. Monorepo scaling issues may make it increasing valuable to transition to a polyrepo. Transition from monorepo to polyrepo is a significant devops task, and will need to be planned, managed, and programmed. ## Related ### Related decisions We will create decisions for related tooling to manage monorepos (e.g. Google Bazel) and polyrepos (e.g. Lyft Refactorator). ### Related requirements We need to develop the CI+CD pipeline to work well with git. ### Related artifacts We expect the repo organization to have related artifacts for provisioning, configuration management, testing, and similar devops areas. ### Related principles Easily reversible. If the monorepo doesn't work in practice, or isn't wanted by leadership, it's simple to change to polyrepo. Customer Obsession. We value getting the project in the hands of customers, and we believe that a monoreop can get us there faster than a polyrepo, and also help us iterate faster. Think big. Google and Facebook are very strong advocates for monorepos over polyrepos, because all the core offerings can be developed/tested/deployed in concert. ## Notes Add any notes here. ================================================ FILE: locales/tr/examples/mysql-database/.locale-peer-id ================================================ 4f4246ee263e7d47d7533ed048c2c7ef ================================================ FILE: locales/tr/examples/mysql-database/index.md ================================================ # Architecture Decision Record: MySQL database Title: Choosing MySQL as Database Management System for Project X ## Context and Problem Statement We need to decide on which database management system (DBMS) to use for Project X. The database will be used to store and manage large amounts of data from multiple sources. We need a DBMS that can handle transactions, offer scalability, and provide high reliability and security. Among various options available, we are considering MySQL as a possible choice. ## Decision Considerations - Ease of use and maintenance - Community support and resources - Performance and scalability - Security and reliability - Cost and licensing - Compatibility with our technology stack ## Considered Options - MySQL - PostgreSQL - Oracle - Microsoft SQL Server - MongoDB ## Decision Outcome After evaluating the above options based on our decision considerations, we have decided to choose MySQL as our DBMS for Project X. MySQL is a popular open-source system with a strong development community and a large pool of resources for problem-solving and knowledge sharing. It is well-known for its excellent performance and scalability capabilities, making it ideal for handling vast amounts of data with high levels of efficiency. The platform is secure, reliable, and has a wide range of features that are essential for our project, including ACID compliance for transactions, flexible data model, and support for various programming languages and frameworks. MySQL is also compatible with the majority of our technology stack, including our web development framework, hosting solutions, and other essential tools. Plus, its cost and licensing terms are competitive compared to other proprietary systems like Oracle and Microsoft SQL Server. ## Consequences We anticipate the following outcomes and consequences of our decision: ### Positive - **High performance and scalability:** MySQL offers exceptional performance and scalability capabilities, making it ideal for handling large amounts of data efficiently. - **Secure and reliable:** MySQL provides excellent security features and reliability, which is essential for managing critical data. - **Wide community support:** MySQL has a vast community and various online resources, making it easier to seek help and solve problems. - **Compatibility:** MySQL is compatible with our technology stack and programming languages, streamlining our development process. ### Negative - **Learning curve:** There might be a learning curve for the development team, especially those not experienced with MySQL and SQL databases. - **Limitations:** MySQL may have some limitations when it comes to handling certain data types and complex data models, requiring careful development and optimization. ## Conclusion Based on the available data and our decision considerations, we believe that MySQL is the right choice for our database management system for Project X. MySQL offers high-performance, reliability, security, and scalability capabilities and is widely compatible with our technology stack. The development team will need to get familiar with using MySQL, but the available community support and resources should help in the process.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/tr/examples/postgresql-database/.locale-peer-id ================================================ 4ea514a9c996ef7af8eca37ec2b96d69 ================================================ FILE: locales/tr/examples/postgresql-database/index.md ================================================ # Architecture Decision Record: PostgreSQL database Title: Use of PostgreSQL Database ## Context Our organization is currently evaluating options for the most suitable database management system to be used in our upcoming project. We have narrowed our search down to two options – PostgreSQL and MySQL. After careful consideration, we have decided to use PostgreSQL due to its advanced features and performance capabilities. ## Decision We will use PostgreSQL as the preferred database management system for our organization's upcoming project. ## Justification After analyzing and comparing the features of both PostgreSQL and MySQL, we have come to the conclusion that PostgreSQL is the better option because of the following reasons: 1. **Advanced features:** PostgreSQL has a wide range of advanced features like JSON support, full-text search, and spatial data management, which are essential for our project. 2. **Performance:** PostgreSQL has a proven track record of excellent performance capabilities, which will ensure that our project runs smoothly without any performance issues. 3. **Community support:** PostgreSQL has a large and active community that provides regular updates and support, making it easier to resolve any issues that arise during the project development phase. 4. **Scalability:** PostgreSQL is highly scalable, and it can handle large amounts of data with ease, which will be essential for our project. 5. **Security:** PostgreSQL has a robust security mechanism that will ensure that our project data is secure at all times, and it meets all our organization's security requirements. ## Alternatives The other option that we considered was MySQL. MySQL is also a highly capable database management system, but it lacks some of the advanced features that PostgreSQL offers, and its performance capacity is not as good as that of PostgreSQL. ## Conclusion Based on our analysis, we have decided to use PostgreSQL as the preferred database management system for our upcoming project. This decision has been made after careful consideration, and we believe that it will help us achieve our project goals efficiently and effectively.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/tr/examples/programming-code-editors/.locale-peer-id ================================================ 8aec4ce83bd164e7b2945f37c052a6d1 ================================================ FILE: locales/tr/examples/programming-code-editors/index.md ================================================ # Architecture Decision Record: Programming Code Editors ## Context Programming code editors are an essential tool for developers to write and edit code. There are numerous code editors available, each with its own set of features, advantages, and disadvantages. The purpose of this ADR is to document the architectural decisions made for programming code editors. ## Priorities The architecture for programming code editors should prioritize the following: * **Modularity**: The code editor should be designed in a modular way, allowing developers to customize and extend it as needed. This allows for a flexible architecture that can adapt to the needs of different developers and teams. * **Performance**: The code editor should be performant and responsive, allowing developers to work efficiently without being slowed down by the tool they are using. * **User Interface**: The user interface should be intuitive and easy to use, allowing developers to focus on their code rather than struggling with the editor. * **Extensibility**: The code editor should be designed to allow for easy extension with third-party plugins and integrations. * **Compatibility**: The code editor should be compatible with a wide range of programming languages and technologies, making it a useful tool for a broad range of developers. ## Decision Based on these priorities, the architecture for programming code editors should be designed with the following components: * **Core**: This component provides the basic functionality of the code editor, such as syntax highlighting, text editing, and file management. * **UI**: This component provides the user interface for the code editor, including menus, toolbars, and keyboard shortcuts. * **Plugins**: This component allows developers to extend the functionality of the code editor by installing third-party plugins. Plugins can provide additional features, such as code completion, linting, or debugging. * **Integrations**: This component allows the code editor to integrate with other tools and technologies, such as version control systems, build systems, or debugging tools. ## Rationale The modularity of the code editor allows developers to customize and extend it as needed. This is important because different developers and teams have different needs and workflows, and a flexible architecture can accommodate these differences. * **Performance**: crucial because developers need to be able to work efficiently without being slowed down by their tools. A performant code editor is essential for productivity and can help developers maintain their focus and concentration. * **UI**: important because it allows developers to focus on their code rather than struggling with the editor. This can lead to better productivity and less frustration for developers. * **Extensibility**: powerful because it allows the code editor to be adapted to different needs and workflows. Third-party plugins and integrations can provide additional features and capabilities that are not included in the core editor. * **Compatibility**: valuable because it allows the code editor to be used with a wide range of programming languages and technologies. This makes the editor a more useful tool for a broad range of developers. The core, plugins, integrations, and UI components provide a clear separation of concerns and allow for a modular architecture that can be easily extended and customized. This architecture is flexible, performant, and compatible with a wide range of programming languages and technologies, making it a useful tool for developers. ================================================ FILE: locales/tr/examples/programming-languages/.locale-peer-id ================================================ 1984c4f82b0b1364c6a3fae147697337 ================================================ FILE: locales/tr/examples/programming-languages/index.md ================================================ # Programming languages Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes) ## Summary ### Issue We need to choose programming languages for our software. We have two major needs: a front-end programming language suitable for web applications, and a back-end programming language suitable for server applications. ### Decision We are choosing TypeScript for the front-end. We are choosing Rust for the back-end. ### Status Decided. We are open to new alternatives as they arise. ## Details ### Assumptions The front-end applications are typical: * Typical users and interactions * Typical browsers and systems * Typical developments and deployments The front-end applications is likely to evolve quickly: * We want to ensure fast easy developments, deployments, iterations, etc. * We value provability, such as type safety, and we are fine doing a bit more work to achieve it. * We do not need legacy compatibility. The back-end applications are higher-than-typical: * Higher-than-typical goals for quality, especially provability, reliability, security, etc. * Higher-than-typical goals for near-real-time, i.e. we do not want pauses due to virtual machine garbage collection. * Higher-than-typical goals for functional programming, especially for parallelization, multi-core processing, and memory safety. We accept lower compile-time speeds in favor of compile-time safety and runtime speeds. ### Constraints We have a strong constraint on languages that are usable with major cloud provider services for functions, such as Amazon Lambda. ### Positions We considered these languages: * C * C++ * Clojure * Elixir * Erlang * Elm * Flow * Go * Haskell * Java * JavaScript * Kotlin * Python * Ruby * Rust * TypeScript ### Argument Summary per language: * C: rejected because of low safety; Rust can do nearly everything better. * C++: rejected because it's a mess; Rust can do nearly everything better. * Clojure: excellent modeling; best Lisp approximation; great runtime on the JVM. * Elixir: excellent runtime including deployability and concurrency; excellent developer experience; relatively small ecosystem. * Erlang: excellent runtime including deployability and concurrency; challenging developer experience; relatively small ecosystem. * Elm: looks very promising; IBM is publishing major case studies with good results; smaller ecosystem. * Flow: interesting improvement over JavaScript; however; developers are moving away from it. * Go: excellent developer experience; excellent concurrency; but a track record of bad decisions that cripple the language. * Haskell: best functional language; smaller developer community; hasn't achieved enough published production successes. * Java: excellent runtime; excellent ecosystem; sub-par developer experience. * JavaScript: most popular language ever; most widespread ecosystem. * Kotlin: fixes so much of Java; excellent backing by JetBrains; good published cases of porting from Java to Kotlin. * Python: most popular language for systems administration; great analytics tooling; good web frameworks; but abandoned by Google in favor of Go. * Ruby: best developer experience ever; best web frameworks; nicest community; but very slow; somewhat hard to package. * Rust: best new language; zero-abstraction emphasis; concurrency emphasis; however relatively small ecosystem; and has deliberate limits on some kinds of compiler accelerations e.g. direct memory access needs to be explicitly unsafe. * TypeScript: adds types to JavaScript; great transpiler; growing developer emphasis on porting from JavaScript to TypeScript; strong backing from Microsoft. We decided that VMs have a set of tradeoffs that we do not need right now, such as additional complexity that provides runtime capabilities. We believe that our core decision is driven by two cross-cutting concerns: * For fastest runtime speed and tightest system access, we would choose JavaScript and C. * For close-to-fastest runtime speed and close-to-tightest system access, we choose TypeScript and Rust. Honorable mentions go to the VM languages and web frameworks that we would choose if we wanted a VM language: * Clojure and Luminus * Java and Spring * Elixir and Phoenix ### Implications Front-end developers will need to learn TypeScript. This is likely an easy learning curve if the developer's primary experience is using JavaScript. Back-end developers will need to learn Rust. This is likely a moderate learning curve if the developer's primary experience is using C/C++, and a hard learning curve if the developer's primary experience is using Java, Python, Ruby, or similar memory-managed languages. TypeScript and Rust are both relatively new. This means that many tools do not yet have documentation for these languages. For example, the devops pipeline will need to be set up for these languages, and so far, none of the devops tools that we are evaluating have default examples for these languages. Compile times for TypeScript and Rust are quite slow. Some of this may be due to the newness of the languages. We may want to look at how to mitigate slow compile times, such as by compile-on-demand, compile-concurrency, etc. IDE support for these languages is not yet ubiquitous and not yet first-class. For example, JetBrains sells the PyCharm IDE for first-class support for Python, but does not sell and IDE with first-class support for Rust; instead, JetBrains can use a Rust plug-in that provides perhaps 80% of Rust language support vis a vis Python language support. ## Related ### Related decisions We will aim toward ecosystem choices that align with these languages. For example, we want to choose an IDE that has good capabilities for these languages. For example, for our front-end web framework, we are more-likley to decide on a framework that tends to aim toward TypeScript (e.g. Vue) than a framework that tends to aim toward plain JavaScript (e.g. React). ### Related requirements Our entire toolchain must support these languages. ### Related artifacts We expect we may export some secrets to environment variables. ### Related principles Measure twice, build once. We are prioritizing some safety over some speed. Runtime is more valuable than compile time. We are prioritizing customer usage over developer usage. ## Notes Any notes here. ================================================ FILE: locales/tr/examples/python-django-framework/.locale-peer-id ================================================ b8f60539494aed8b17e1b8969ae2f10b ================================================ FILE: locales/tr/examples/python-django-framework/index.md ================================================ # Architecture Decision Record for Python Django Framework Decision Date: 2021-07-15 Status: Accepted ## Context Our organization is planning to develop a web application that manages customer data. We have chosen Python as the programming language and are considering Django as the web framework for the development of the application. ## Decision We have decided to use the Django web framework for the development of the web application. Django provides a robust set of tools and features for building web applications quickly and efficiently. ## Factors Some of the factors that influenced our decision include: 1. Object-Relational Mapping (ORM): Django has a built-in ORM that allows us to interact with the database without writing SQL queries. This makes it easier to develop the application and maintain it in the long run. 2. MVC framework: Django follows a Model-View-Controller (MVC) architecture, making it easier to separate the business logic and presentation layers of the application. 3. Scalability: Django is known for its scalability capabilities, making it an excellent choice for developing large-scale applications. 4. Security: Django has built-in security features, such as protection against common web attacks like cross-site scripting (XSS) and SQL injection. 5. Community Support: Django has a large and active community that provides support and contributes to the development of the framework. ## Alternatives Considered We considered other web frameworks such as Flask and Pyramid. However, we found that Django is a more mature and well-established framework with a robust set of features. We also discussed developing the application without a web framework and using libraries like SQLAlchemy and Flask-RESTful. However, we found that Django offers broader functionality, making it a better choice for a complete web application. ## Consequences The adoption of Django will lead to the following consequences: 1. Easier to develop and maintain the application due to Django’s built-in tools and features. 2. Separation of business logic and presentation layer, leading to more organized and easier to maintain code. 3. Scalability and robustness of the application. 4. Built-in security features that help protect the application against common web attacks. 5. Access to a large and active community for support. We understand that Django has a steeper learning curve than other frameworks, but we find that it is worth the investment for the long-term benefits it provides. ## Conclusion Based on the factors considered, we have decided to use the Django web framework for the development of the web application. We believe that Django’s features, community support, and scalability capabilities make it the best choice for building a complete web application. We will train our developers to use Django to ensure that the framework is used effectively and efficiently. ================================================ FILE: locales/tr/examples/python-programming-language/.locale-peer-id ================================================ 42fd8a00f5f37e2f2a9c4a3f2fd61356 ================================================ FILE: locales/tr/examples/python-programming-language/index.md ================================================ # Architecture Decision Record: Python programming language ## Context We need to decide on whether to use Python as a programming language for our project. Our project involves data analysis, machine learning, and web development. ## Decision We have decided to use Python as our primary programming language for our project. ## Rationale Python is a versatile programming language that is widely used in the areas of data analysis, machine learning, and web development. It is an interpreted language, which means that it does not need to be compiled, and it has an easy-to-read and understand syntax. Other important factors for our decision include the following: 1. **Availability of libraries:** Python has a huge collection of libraries and frameworks, such as NumPy, Pandas, and Scikit-learn, which makes it easier for developers to implement machine learning algorithms and data analysis. 2. **Community support:** Python has a large and active community of developers who contribute to its development and provide support and guidance on various forums and websites. This makes it easier for beginners to find help and learn the language. 3. **Scalability:** Python is scalable, which means that it can handle large datasets and complex applications. It can also be used for rapid prototyping or building small applications with minimal effort, making it easier for us to start our project and iterate quickly. 4. **Flexibility:** Python can be used for various types of projects, including web development, scientific computing, machine learning, etc. It is also compatible with other programming languages, such as Java and C++, which makes it easier to integrate with other systems. ## Consequences There are some potential consequences to using Python as our programming language, such as: 1. **Performance:** Python can be slower than compiled languages like C++ when it comes to executing certain algorithms, but this can be mitigated by using optimized libraries or writing critical code in C++ and interfacing with it using Python. 2. **Learning curve:** While Python has an easy-to-learn syntax, it can be challenging to learn the best practices for writing efficient and scalable code. This can be overcome by following conventions, using frameworks and libraries, and seeking guidance from experienced developers. 3. **Version compatibility:** Different versions of Python can have different syntax and capabilities, which can make it difficult to maintain and update projects. It is important to choose a version of Python that is widely supported and compatible with our project requirements. ## Conclusion After considering the pros and cons of using Python as our programming language, we have decided that it is the best choice for our project. We believe that it will provide us with the most flexibility, availability of libraries, and community support, while also being scalable and adaptable to our changing needs.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/tr/examples/react-front-end-javascript-library/.locale-peer-id ================================================ 9eadfd943b9e3d2404a28e8ad14d3076 ================================================ FILE: locales/tr/examples/react-front-end-javascript-library/index.md ================================================ # Architecture Decision Record: React Front-End JavaScript Library ## Context We need to choose a front-end JavaScript library for our application to develop a responsive and interactive user interface. ## Option Considered 1. React 2. Vue 3. Svelte ## Decision We will use React as our front-end JavaScript library. ## Rationale 1. **Component-Based Architecture:** React provides a component-based architecture that allows us to break down the UI into small reusable components. This helps improve the modularity of our code and makes it easier to maintain, scale, and update the application. 2. **Declarative programming:** React uses a declarative style of programming that makes our code more intuitive and easier to read. It also provides a virtual DOM, which allows our code to run faster and more efficiently. 3. **Large Community:** React has a large and active community, and it is one of the most popular front-end libraries. This means that there are a lot of resources, tools, and libraries available that can help us develop our application faster and more efficiently. 4. **Better performance:** React uses a one-way data flow, which helps simplify the application logic and makes it more efficient. It also provides server-side rendering, which helps improve the performance and SEO of our application. 5. **Flexibility:** React can be used with other libraries and frameworks, which gives us the freedom to choose the best technology stack that suits our project's requirements. ## Consequences 1. **Learning Curve:** React has a learning curve, and it may take some time for developers who are new to React to get up to speed. 2. **Build Tools:** React requires additional build tools such as Babel and Webpack, which may add complexity to the development process. 3. **Browser compatibility:** React has compatibility issues with older browsers since it uses ES6 features that are not supported in older browsers. 4. Steep learning curve: It may take time for developers who are not familiar with React to learn how to use it efficiently, which may lead to slower development times. ## Conclusion We have decided to use React for our application's front-end JavaScript library. Although it may have a learning curve, the benefits that React provides, such as its component-based architecture, declarative style of programming, better performance, flexibility, and large community, outweigh the potential drawbacks.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/tr/examples/ruby-on-rails-framework/.locale-peer-id ================================================ b107a749a966e10cc337420370e34063 ================================================ FILE: locales/tr/examples/ruby-on-rails-framework/index.md ================================================ # Architecture Decision Record: Ruby on Rails Framework ## Context - The organization is developing a web application with complex business logic and multiple integrations with third-party services. - The team has experience in building web applications with Ruby on Rails. - There is a need to choose a web framework that promotes rapid development, scalability, and maintainability. ## Decision - Use Ruby on Rails as the framework for developing the web application. ## Justification - Ruby on Rails is a mature, stable, and widely adopted web framework that has proven its effectiveness in building complex web applications. - The framework follows the Model-View-Controller (MVC) architecture pattern, which promotes separation of concerns and enhances code reusability and maintainability. - Rails provides many built-in features, such as ActiveRecord for database interactions and ActionMailer for email management, which can save development time and simplify code. - The framework has a large and active community, with many reusable modules and plugins available to enhance functionality and resolve common problems. - Ruby on Rails supports Test-Driven Development (TDD) and Behavior-Driven Development (BDD), which enables developers to write automated tests for their code, ensuring that it works as expected and reducing bugs and regressions. - Ruby is a high-level language that promotes developer productivity and code readability, and acts as a powerful glue language for integrating with a wide range of third-party services and APIs. ## Consequences - The team needs to ensure that the web application's architecture and design follow Rails conventions and best practices to maximize the benefits of the framework. - Developers need to have a good understanding of the Ruby language and the Rails framework, although the Rails documentation and community can provide guidance and support. - There may be a learning curve for developers who are new to Ruby and Rails, although the benefits of the framework can justify the investment in training and onboarding. - The team needs to monitor the application's performance and scalability, and may need to fine-tune database queries and optimize caching to handle large amounts of data and traffic.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/tr/examples/rust-programming-language/.locale-peer-id ================================================ d21b58847a2e92716ef2f68b44156564 ================================================ FILE: locales/tr/examples/rust-programming-language/index.md ================================================ # Architecture Decision Record: Rust programming language Decision Number: AR-001 Decision Title: Adoption of Rust programming language Date: December 1, 2021 Status: Accepted ### Problem Statement As we continue to develop software applications, we have observed that it is increasingly challenging to mitigate potential security vulnerabilities and prevent runtime errors. With the existing programming languages, such as C and C++, we continue to experience issues such as buffer overflows, memory leaks, and undefined behavior leading to applications' crashes. We require a programming language that provides memory safety guarantees and is efficient enough to support performance-critical applications. ### Considerations Several programming languages are designed to address the existing problems. Among them, Rust programming language has gained significant attention from the developers' community due to its unique design features. Considerations include; 1. Memory safety and security 2. Performance and efficiency 3. Community support and adoption 4. Learning curve 5. Tools and ecosystem 6. Compatibility with existing software systems. ### Constraints Adopting a new programming language requires retraining developers, which takes time and resources. Integrating the language into the existing development workflow may be a challenge. We must ensure compatibility with the existing systems and avoid breaking changes to maintain continuity. ### Implementation 1. Our development team will undergo training to learn and familiarize themselves with the Rust programming language. 2. We will create a new project using Rust on a trial basis to evaluate its compatibility and suitability for our development purposes. 3. We will gradually migrate existing systems written in C and C++ to Rust. 4. We will collaborate with the Rust community to explore the available tools and libraries that can enhance our development workflow. 5. We will monitor the performance of Rust and compare it to the performance of the existing programming languages regularly. 6. We will adopt a long-term approach that balances the costs of training, integration, and potential benefits of using Rust. ### Rationale We have adopted Rust due to its unique features designed to provide memory safety and security guarantees while maintaining performance and efficiency. Rust's robust type system, borrow checker, and memory safety concepts make it highly suitable for developing performance-critical and safety-critical applications. Moreover, Rust has a significant community of developers, enabling us to access a wide range of tools, libraries, and ecosystem that support our development workflow. Although Rust comes with a learning curve, we believe the benefits of adopting Rust outweigh the costs and provide an excellent opportunity for continued growth and innovation. ### Consequences 1. The adoption of Rust will require a significant investment in time and resources to train developers and integrate the language into the existing development workflow. 2. Adopting Rust may cause some degree of compatibility issues with existing systems, requiring refactoring, and modifications. 3. Rust's adoption may increase the number of developers who can contribute to our project by attracting Rust developers who want to work on exciting projects. 4. The adoption could lead to improved performance, efficiency, and safety as compared to the existing languages. 5. Finally, adopting Rust comes with the potential benefit of reducing security vulnerabilities in our applications.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/tr/examples/secrets-storage/.locale-peer-id ================================================ 8123c8089cda027baecab9c034e947c6 ================================================ FILE: locales/tr/examples/secrets-storage/index.md ================================================ # Secrets storage Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes) * [Vault by HashiCorp](#vault-by-hashicorp) * [LastPass](#lastpass) * [Bitwarden](#bitwarden) * [EnvKey](#envkey) * [Confidant by Lyft](#confidant-by-lyft) * [Devolutions Password Server](#devolutions-password-server) * [Secret Server by Thycotic](#secret-server-by-thycotic) ## Summary ### Issue We need to store secrets, such as passwords, private keys, authentication tokens, etc. Some of the secrets are user-oriented. For example, our developer wants to be able to use their mobile phone to look up a password to a service. Some of the secrets are system-oriented. For example, our continuous delivery pipeline needs to be able to look up the credentials for our cloud hosting. ### Decision Bitwarden for user-oriented secrets Vault by HashiCorp for system-oriented secrets. ### Status Decided. We are open to new alternatives as they arise. ## Details ### Assumptions For this purpose, and our current state, we value user-oriented convenience, such as usable mobile apps. * We want to ensure fast easy access on the go, such as for a developer doing on-call system reliability engineering. * We want to be able to share some secrets among selected people, such as a team. We are not trying to solve for single-provider, such as storing all secrets exclusively on Amazon or Azure or Google. We do not want ad-hoc approaches such as "remember it" or "write it on a note" or "figure out your own way to store it". Our security model for this purpose is fine with using well-respected COTS vendors, such as SaaS password management tools. ### Constraints Right now we want something that is easy i.e. no need to write code, no need to install servers, no need to make a major commitment, no need to standardize everyone. ### Positions We considered: 1. User-oriented off-the-self password managers: LastPass, 1Password, Bitwarden, Dashlane, KeePass, pass, GPG, etc. 2. System-oriented COTS password managers: AWS KMS, Vault by HashiCorp, EnvKy, Secret Server by Thycotic, Devolutions Password Server, Confidant by Lyft. 3. Sharing-oriented approaches: using a shared Google document, or shared Slack channel, or shared network folder, etc. 4. Low-tech ad-hoc approaches, such as remembering, writing a note, or relying on each user to figure out their own approach. ### Argument Bitwarden, LastPass, 1Password, and Dashlane all are commercial off-the-shelf products. * Similar kinds of features for users, teams, organizations, etc. * Desktop capability for Windows and Mac, and mobile capability for Android and iOS. * Browser extensions for Chrome and Firefox, for automatic form fill in, etc. Bitwarden has two advantages over the others: * Bitwarden is open source, which means the security can be peer reviewed and also the company is widely-appreciated by security-oriented developers. * Anecdotes by software workers describe a significant preference for Bitwarden over the others. A typical good example writeup: https://jcs.org/2017/11/17/bitwarden A typical side-by-side voting site: https://stackshare.io/stackups/bitwarden-vs-dashlane We defer KeyPass, pass, GPG, etc. because there's additional complexity. All of these look like fine solutions for technical users. GPG looks especially good for technical users who want cross-system command-oriented capabilities. We defer KMS because it has single-provider lock-in. We choose Vault for system-oriented needs, because the reviews are amazingly positive, and because HashiCorp has an excellent track record fup top-quality software and support. We veto the approaches of sharing approaches such as via shared documents, shared channels, shared network folders, etc. These do not provide the security qualities that we want. We veto the ad-hoc low-tech approaches, because we all agree it's not a long-term path forward. ### Implications Developers may need to track secrets in two places: Bitwarden for user-oriented access, and Vault for system-oriented access. ## Related ### Related decisions The decision of which CI/CD server must include proof of capability for accessing secrets. We will need to decide how to managea the secrets, in terms of policies, rotations, organizations, etc. ### Related requirements The secrets will have related requirements for compliance, auditing, and HR onboarding/offboarding. ### Related artifacts We expect we may export some secrets to environment variables. ### Related principles Easily reversible. Easily parallel i.e. it's easy to use a variety of password managers. Cheap to try i.e. there's a free trial and no commitment. ## Notes Evaluation notes here. The notes are all public comments on various devops discussion boards. ### Vault by HashiCorp Vault is exactly what you want here. Don't just throw Vault into production though, stand it up in a test environment first, because HashiCorp's documentation can be pretty lacking even if their products are amazing. Very steep learning curve and is not trivial to stand up. The initial setup is a bit of a pain. It's well worth it though, and the community will support it will enough for you to get by. Horrid docs but there are lots of guides online of people setting it up and if you put a few of them together you will have a working setup. Initial setup took fiddling with their helm charts (vault and consul). While technically you can use lots of other back-ends, I really really don't recommend it. The back-end/consul can be teeny tiny if you don't have a ton of data to store. Definitely get comfortable/familiar with using the CLI, because the GUI is more like a proof-of-concept/advertisement portal for their enterprise edition. The fact that you cannot just "fill it up" is a pain. For example if you have 5 fields you need to manually add each field for each item. So it's not like you pre-define fields for a specific category, and fill those fields for all the items in that category, it's more like "you generate everything every time", which (in my mind) is a pain in the ass. You may want to also look at goldfish as a UI for on top of vault. Makes it rather nice to get your team on board with it. They also have a demo. 1. Set up consul. 2. Set up vault pointing to consul. 3. Set up goldfish pointing to vault. 3. Setup some cron job to run consul snapshot for backups. ### LastPass LastPass Teams. We use it, has custom templates, ACL, nothing missing IMO. I implemented LastPass at my org and give it a C+/B-. The biggest issue lately is a lack of reliability. In the past 90 days there have been multiple hours where vaults were forced into offline mode. This isn't ideal for my org due to having, literally, 4,000+ passwords stored across 20+ shared folders. As you can imagine with that many passwords at least a few get updated or added daily. We have a DR plan if issues last more than an hour or two: a script signs and encrypts a CSV dump of vault every night that can be imported into keepass. LastPass has had unreported blips of degraded service: login 'works' but doesn't pull sites, random features broken in the admin panel, and not properly sharing keys for new top level shared folders. I have a specific 'key push'/backup user that is in every group. Usually logging in as that user will fix any key sharing issues but not when the service is degraded despite what the status page says... For integration it can be easy if you have proper ACLs with a least privileged model e.g. if a user has read & write and read only on an entry or folder they only get read only permissions. Unfortunately my org's ACLs are not the best so I ended up using the JSON provisioning API and ~500 lines of python due to the dependent nature of our hundreds of ACLs not mapping well to the least privileged model. I ended up getting all ACLs a user was in and do a dependency walk of sorts. If your ACL or group structure is already built with a least privileged structure in mind the AD/LDAP sync tool for Windows will work well. Reach out to their sales team and they can hook you up with a longer Enterprise trial. Be sure you fully understand its limitations before pulling the trigger. We had a good number of growing pains but aside from outages or impairments on the server side it's been incredibly smooth. ### Bitwarden Bitwarden has a nice tooling around it (WebUI, CLI, Mobile, Desktop). Self-hosted and fairly easy to setup. Fairly good documentation and recommended tool by PrivacyTools. ### EnvKey https://www.envkey.com/ Is a saas. Really easy to implement, integrate and manage. Features: * Protect API keys and credentials. * Keep configuration in sync everywhere. * Smart, end-to-end encrypted configuration and secrets management. * Prevent insecure sharing and config sprawl. * Integrate in minutes. Capabilities: * Manage configuration and access levels for all your apps, environments, and teams in one place. * Configure any development or server environment with just a single environment variable. Pros: * Good home page. * Clear value prop. * Visually excellent web app. * Superior example data e.g. Algolia, AWS, Datadog, GitHub, Stripe, etc. * Spoke with the founder for 30m about the company, UI, etc. Dane sounds well-informed, honest about the pros/cons, and a viable partner. * The company is essentially a typical Y Combinator company, with 1 founder. Raised $120K in 2018-01. * Focus is on getting to enterprise features, esp. moving from EnvKey cloud-hosting to either on-prem or BYOC. * Potential path forward starting with EnvKey for ease of use, then later (or in parallel) adding Vault. ### Confidant by Lyft https://lyft.github.io/confidant/ Confidant is a open source secret management service that provides user-friendly storage and access to secrets in a secure way, from the developers at Lyft. KMS Authentication: Confidant solves the authentication chicken and egg problem by using AWS KMS and IAM to allow IAM roles to generate secure authentication tokens that can be verified by Confidant. Confidant also manages KMS grants for your IAM roles, which allows the IAM roles to generate tokens that can be used for service-to-service authentication, or to pass encrypted messages between services. At-rest encryption of versioned secrets: Confidant stores secrets in an append-only way in DynamoDB, generating a unique KMS data key for every revision of every secret, using Fernet symmetric authenticated cryptography. A user-friendly web interface for managing secrets: Confidant provides an AngularJS web interface that allows end-users to easily manage secrets, the mappings of secrets to services and the history of changes. ### Devolutions Password Server https://server.devolutions.net/ Secure, manage, and monitor access to privileged accounts and sessions. A comprehensive, highly-secured password vault that lets you control access to your privileged accounts, while also improving overall network visibility for sysadmins and providing a seamless experience for end users. Features: centralized organization password vault, user-specific private vault, password manager, credential injection, Active Directory integration, role-based access control, two-factor authentication, enterprise ready, IP restrictions, management capabilities, automated password generator, mobile app access, password history, access reports, email alerts. * supports data encryption * supports multiple Authentication schemes including LDAP, O365, and Local users WITH support for MFA from multiple sources * multiple repositories/vaults with fine-grained access controls for multiple teams * modern Web UI * private credential and connection vaults for personal creds/connections * mobile apps for IOS/Android * audit logs for each entry, who/what/when with an optional prompt for why they're accessing * customizable templates (though they support hundreds of connection types natively) * tons more features and a Windows/Mac thick client (Remote Desktop Manager) that you can sync to that greatly expands the options...one-click connections * pricing isn't all that bad - up to 15 users is $500 a year for the password server ### Secret Server by Thycotic https://thycotic.com/products/secret-server/ On-premise version features: * Total control over your end-to-end security systems and infrastructure * Deploy software within your on-premise data center or your own virtual private cloud instance * Meet legal and regulatory obligations that require all data and systems to reside on premise Cloud version features: * Software-as-a-service model lets you sign up and start right away * Elastic scalability as you grow * Controls and redundancy delivered by Azure with 99.9% uptime SLA User feedback: * We used to use that product. It was so easily bypassed and the rules only work for smart people. Lazy or dumb users can easily screw it up in a team area. Prices are negotiable when you talk to them. * You can run it using SQL express and an Win 7box. * Cheap. ================================================ FILE: locales/tr/examples/snake-case-v-camelcase-for-a-rest-api/.locale-peer-id ================================================ 56bcc02899f133bd74208e58e020ad3a ================================================ FILE: locales/tr/examples/snake-case-v-camelcase-for-a-rest-api/index.md ================================================ # Architecture Decision Record: snake_case v. camelCase for a REST API? Decision: snake_case naming convention will be used for REST API endpoints Status: Accepted ## Context In naming conventions for REST APIs, there are two popular formats: snake_case and camelCase. The snake_case format is where each word in the name is separated by underscores, whereas camelCase is where the first word of the name is in lower case, and the subsequent words have their first letter capitalized. This decision will determine which naming convention should be used for a REST API. ## Decision Drivers - Consistency with existing naming conventions in the project - Readability and clarity for anyone who may be working on the API - Alignment with industry best practices for REST API naming conventions - Ease of implementation and maintenance ## Decision The snake_case naming convention will be used for REST API endpoints. This choice is driven by the following factors: 1. **Consistency**: The project already uses snake_case naming convention for all endpoints, and it would be beneficial to maintain this convention to ensure consistency across the entire project. 2. **Readability and clarity**: The snake_case convention is more readable and easier to understand. The underscores provide a clear separation between words, making it easier to parse and understand the meaning of the name. 3. **Alignment with industry best practices**: The snake_case convention is widely used in the industry and is considered to be a best practice for REST APIs, making it a good choice for the project. 4. **Ease of implementation and maintenance**: Keeping with the existing naming convention is easier to implement and maintain as all existing code and documentation would need to be updated if a new convention was chosen. ## Consequences There are potential consequences of this decision. * If any new team members joining the project are unfamiliar with snake_case naming convention, it could lead to confusion and mistakes in development. However, since snake_case is a widely-used convention, such a risk is minimal. * If other tools or frameworks are used in the project that are heavily based on camelCase convention, it may require extra effort to convert between naming conventions. However, it is not a significant concern since the project has standardized on the snake_case convention. Overall, the decision to use snake_case naming convention for REST API endpoints results in a consistent, readable, and industry-standard approach while being easy to implement and maintain.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/tr/examples/svelte-components/index.md ================================================ # Architecture Decision Record (ADR) for Svelte Components ## Context We are selecting a Svelte UI component library to provide full features for: - **Tables** - **Charts** - **Lists** - **Grids** - **Gantt charts** The goal is to choose a library that balances ease of integration, full feature support, performance, and long-term maintainability. The options under consideration are: 1. **SVAR** 2. **Carbon** 3. **Flowbite** 4. **SkeletonUI** 5. **MeltUI** 6. **SvelteUI** 7. **shadcn-svelte** ## Options Analysis ### 1. **SVAR** - **Overview**: SVAR is a modern, feature-rich component library for Svelte, with a focus on design systems and enterprise-ready components. - **Pros**: - Full-featured components, including tables, forms, and charts. - High customization options with built-in theme support. - Built-in support for accessibility and responsiveness. - Well-documented with community contributions. - **Cons**: - It might be heavier compared to other simpler libraries. - Limited support for specific components like Gantt charts and advanced grids. - **Best For**: Enterprise-level applications where a full-featured design system is necessary. - **Table/Chart Support**: Moderate to good. - **Grid/Gantt Support**: Minimal. ### 2. **Carbon** - **Overview**: Carbon Design System is an open-source design system from IBM, offering a robust set of UI components. - **Pros**: - High-quality, polished design with extensive documentation. - Very accessible and responsive. - Large component library, including grids, tables, and form controls. - **Cons**: - Not focused on Svelte, so integration can be cumbersome. - Could require additional customization for full Svelte compatibility. - No out-of-the-box support for advanced components like Gantt charts or complex charts. - **Best For**: Large-scale projects requiring a consistent, polished UI. - **Table/Chart Support**: Good (with charting library integrations). - **Grid/Gantt Support**: Good (Grid support available, but no Gantt charts). ### 3. **Flowbite** - **Overview**: Flowbite is a component library that’s built with Tailwind CSS, offering various components and UI elements. - **Pros**: - Tailwind CSS-based, which makes it easy to customize. - Easy to integrate and use with Svelte. - Provides rich components like tables, charts, and UI controls. - **Cons**: - Lacks advanced features (e.g., Gantt charts or complex grids). - Doesn’t have native charting components; relies on external libraries. - **Best For**: Projects requiring quick development with a focus on Tailwind CSS integration. - **Table/Chart Support**: Good (requires integration with third-party chart libraries). - **Grid/Gantt Support**: Minimal. ### 4. **SkeletonUI** - **Overview**: SkeletonUI is a lightweight component library for Svelte, focusing on simplicity and minimalism. - **Pros**: - Extremely lightweight and fast. - Simple and intuitive API. - Good for small projects or where performance is critical. - **Cons**: - Very few components are included, so it's not feature-rich. - Lacks advanced table/grid/chart/Gantt components. - Limited community support and less comprehensive documentation. - **Best For**: Projects that require lightweight components with minimal overhead. - **Table/Chart Support**: Minimal. - **Grid/Gantt Support**: Minimal. ### 5. **MeltUI** - **Overview**: MeltUI is a collection of accessible UI components for Svelte, focusing on simplicity and composability. - **Pros**: - Lightweight and fully customizable. - Good accessibility features out-of-the-box. - Modern and minimalistic design. - **Cons**: - Less feature-rich compared to other libraries. - Lacks advanced grid and table components. - No Gantt charts or complex charting options. - **Best For**: Minimalistic designs that prioritize accessibility and performance. - **Table/Chart Support**: Minimal. - **Grid/Gantt Support**: Minimal. ### 6. **SvelteUI** - **Overview**: SvelteUI is a comprehensive and customizable UI component library for Svelte, designed for building modern web apps with elegant UI. - **Pros**: - Comprehensive set of components, including tables, grids, charts, and forms. - Provides both light and dark mode support. - Highly customizable and easy to extend. - Built-in integrations for charting libraries like `chart.js` or `d3.js`. - **Cons**: - Can be heavier than simpler component libraries. - Requires some setup to integrate external libraries for more complex features like Gantt charts. - **Best For**: Projects needing a comprehensive, customizable set of components. - **Table/Chart Support**: Excellent (charting libraries supported). - **Grid/Gantt Support**: Good (Grid components available; Gantt needs external integration). ### 7. **shadcn-svelte** - **Overview**: A Svelte version of ShadCN, which focuses on utility-first design and provides modern, styled components. - **Pros**: - Utility-first design, built on top of Tailwind CSS, making it easy to customize. - Rich set of components and fully styled out-of-the-box. - Easy to integrate with other libraries. - **Cons**: - Not as feature-complete as some others in terms of advanced UI elements. - Lacks built-in support for tables, charts, or grids. - No out-of-the-box support for Gantt charts. - **Best For**: Small-to-medium projects requiring a utility-first, customizable approach. - **Table/Chart Support**: Minimal. - **Grid/Gantt Support**: Minimal. ## Decision ### Recommended Option: **SvelteUI** - **Rationale**: SvelteUI offers a well-rounded, comprehensive suite of components that cater to the need for tables, charts, grids, and forms. It’s highly customizable, integrates well with other charting libraries (like `chart.js` and `d3.js`), and has a good balance of lightweight performance and feature richness. While it may not provide out-of-the-box Gantt chart support, it can be easily extended with third-party integrations, making it ideal for a full-featured, scalable solution. - **Pros**: - Excellent table and chart support. - Full grid and layout components. - Customizable and integrates well with external charting libraries. - Good community and documentation. - **Cons**: - Heavier than some other minimalist libraries. - Needs external integration for complex charts like Gantt charts. ### Alternative: **Flowbite** or **Carbon** (for larger enterprise projects) - If a polished, Tailwind-based, or more consistent design system is required, **Flowbite** (with Tailwind CSS) or **Carbon** (for enterprise-grade solutions) may be suitable alternatives. However, they may require extra effort for integrations with more complex charts and components. ## Conclusion The best fit for your requirements (full features for tables, charts, lists, grids, Gantt) is **SvelteUI**, followed by **Flowbite** and **Carbon** depending on the project needs and design preferences. ================================================ FILE: locales/tr/examples/svelte-front-end-javascript-library/.locale-peer-id ================================================ bdca98499db7dd51eeb5add1ca5ec974 ================================================ FILE: locales/tr/examples/svelte-front-end-javascript-library/index.md ================================================ # Architecture Decision Record: Svelte Front-end JavaScript Library Status: Accepted ## Context We are developing a web application using a modern front-end JavaScript framework. We want to choose a library that is lightweight, fast, and easy to use. We have evaluated several libraries, including React, Vue, and Angular. We have also heard about Svelte, which claims to be a new kind of lightweight framework. We need to evaluate Svelte and decide whether it is a good fit for our application. ## Decision After considering the benefits and drawbacks of each library, we have decided to use Svelte as our front-end JavaScript library for the following reasons: 1. **Lightweight:** Svelte is one of the lightest libraries available, which will help us keep our application size small and improve page load times. 2. **Fast:** Svelte is known for its fast rendering speed, which will make our application feel responsive and snappy. 3. **Easy to use:** Svelte's syntax is simple and easy to understand, which will make it easier for our team to adopt it and write clean code. 4. **Optimized for UI rendering:** Svelte is optimized for rendering UI components, which will make it easier for us to create dynamic and reusable UI elements. 5. **Good documentation and community support:** Svelte has a growing community and good documentation, which will help us get started quickly and resolve any issues that arise. ## Alternatives We considered React, Vue, and Angular, but decided against them for the following reasons: 1. **React:** While React has a large user base and a wealth of libraries and resources, it can be complex and difficult to learn, especially for beginners. 2. **Vue:** Vue is a lightweight library that is easy to learn and use, but it may not be as fast or optimized as Svelte. 3. **Angular:** Angular is a comprehensive framework that offers many features and tools, but it can be heavy and complex, and may require more maintenance than Svelte. ## Consequences Using Svelte as our front-end JavaScript library will have the following consequences: 1. Our application will be lightweight and fast, which will improve user experience and engagement. 2. Our team will need to learn a new library, but the syntax of Svelte is simple and easy to understand, so the learning curve should be manageable. 3. Svelte is still a relatively new library, so we may encounter some issues that are not well documented or supported by the community. 4. The community of Svelte users is growing, so we may see more third-party libraries and resources become available in the future that can be used to supplement the core library. ## Conclusion Based on our evaluation, we have decided to use Svelte as our front-end JavaScript library for our web application. We believe that Svelte's lightweight and fast nature, ease of use, and optimized UI rendering make it the best choice for our needs. We will continue to monitor the development of Svelte and its community and make modifications to our choice if needed.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/tr/examples/sveltekit-framework/.locale-peer-id ================================================ 0bc6820a0b59edb03d91948dcfcd6cd0 ================================================ FILE: locales/tr/examples/sveltekit-framework/index.md ================================================ # Architecture Decision Record: SvelteKit framework * Date: [Current Date] * Status: [proposed, approved, rejected, deprecated] ## Context We are building a new web application that requires a scalable and efficient front-end architecture. After conducting a thorough analysis of various front-end frameworks, we have chosen SvelteKit as our preferred framework. ## Decision We have decided to implement the SvelteKit front-end architecture for our web application. SvelteKit provides an advanced front-end development system that is fast, efficient, and flexible. It can be used for optimizing large and small applications. ## Rationale SvelteKit is a new and comprehensive front-end solution that offers an array of features such as server-side rendering, hot reloading, simplified configuration, and many more. It enables us to create high-quality front-end architecture that can handle the largest applications with ease. SvelteKit's component-based architecture enables us to develop reusable and scalable UI components that can be integrated seamlessly between different projects. The framework offers excellent support for TypeScript, allowing us to create clean and structured code that is easy to maintain. In addition, SvelteKit provides an easy-to-use document management system that allows us to track all of our project's architectural decisions and changes. ## Alternatives Considered We have evaluated several alternatives, such as React, Vue, Angular, and Next.js, but with its features, ease of use, and robustness, SvelteKit was the clear choice for our project. ## Consequences Implementing SvelteKit front-end architecture will provide enhanced user experience, performance, and flexibility. We can achieve better productivity through the framework’s simpler configurations, component-based architecture, and modularity. As a result, our project can be more efficient and stable. ## Conclusion We decided to implement the SvelteKit front-end architecture to achieve a modern, scalable, and efficient web application with the features and modularity we need. With its excellent support for TypeScript, server-side rendering, and simplification of configurations, we feel that SvelteKit is the best choice for our project.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/tr/examples/tailwind-css/.locale-peer-id ================================================ 496e7846025a0701822dc65ca71180a5 ================================================ FILE: locales/tr/examples/tailwind-css/index.md ================================================ # Architecture Decision Record: Tailwind CSS Decision: Use Tailwind CSS as the CSS framework to style a user interface. ## What is Tailwind CSS? Tailwind is a utility-first CSS framework that allows for rapid development and customization of user interfaces. It is designed to be highly customizable and allows developers to write leaner and more efficient CSS. This framework provides a set of pre-defined classes to style the UI very fast. ## Context We are building a web application for a client that requires a responsive and customizable user interface. The client has asked for consistent and modern styling. The development team has experience using custom CSS but wants to explore CSS frameworks that can save time and effort. We are looking for a framework that is easy to use, customizable, and has a large community for support. ## Decision Drivers - **Easy to use:** We want a framework that is simple to learn and can be integrated into our development workflow. - **Customizable:** We want a framework that can be customized to match the client's brand guidelines and theme. - **Large community support:** We want a framework that has an active community of developers and designers that can provide help and resources when needed. - **Time-saving:** We want a framework that can save time and effort in styling the UI. ## Considered Options - **Bootstrap:** A popular CSS framework with a lot of pre-built components and a large community of developers. - **Foundation:** Another popular CSS framework that was designed for mobile-first development. - **Materialize:** A CSS framework based on Google's Material Design language with pre-built components for UI development. - **Tailwind CSS:** A utility-first CSS framework with a focus on customization and efficiency. ## Decision Outcome After considering the options, we decided to use Tailwind CSS for the following reasons: - **Easy to use:** Tailwind's approach is simple and easy to understand. Its utility classes make building a UI faster. - **Customizable:** Tailwind allows for customization by providing a set of configuration files that allow developers to modify the framework's default styles with ease. - **Large community support:** Tailwind has a very active community of developers and designers that are consistently creating new resources, plugins, and tools. - **Time-saving:** Tailwind can save time, enabling developers to focus on other areas of the project. We will use Tailwind CSS's utility classes to build the UI for our project. The development team will use its atomic and modular design system to write efficient and scalable CSS code. We will leverage Tailwind's pre-built templates and visual components to speed up the development process while utilizing custom styles to match the branding and theme of the client.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/tr/examples/timestamp-format/.locale-peer-id ================================================ 9374af360cb954bffd75c8518a93b25d ================================================ FILE: locales/tr/examples/timestamp-format/index.md ================================================ # Timestamp format Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes) ## Summary ### Issue We want to be able to track when things happen by using timestamps and by using a consistent timestamp format that works well across all our systems and third-party systems. We interact with systems that have different timestamp formats: * JSON messages do not have a native timestamp format, so we need to choose how to convert a timestamp to a string, and convert a string to a timestamp, i.e. how to serialize/deserialize. * Some applications are set to use local time, rather than UTC time. This can be convenient for projects that must adjust to local time, such as projects that trigger events that are based on local time. * Some systems have different time precision needs and capabilities, such as using a time resolution of seconds vs. milliseconds vs. nanoseconds. For example, the Linux operating system `date` command uses a default time precision of seconds, whereas the Nasdaq stock exchange wants a default time precision of nanoseconds. ### Decision We choose the timestamp standard format ISO 8601 with nanosecond precision, specifically "YYYY-MM-DDTHH:MM:SS.NNNNNNNNNZ". The format shows the year, month, day, hour, minute, second, nanoseconds, and Zulu time zone a.k.a. UTC, GMT. ### Status Decided. ## Details ### Assumptions We need to handle these timestamp text strings, to convert from a timestamp to a string (a.k.a. serialize) and convert from a string to a timestamp (a.k.a. deserialize). We want a format that is generally easy to use, easy to convert, and easy for a person to read. We want compatibility with a wide range of external systems that we cannot control, such as analytics systems, database systems, financial systems. ### Constraints Some systems have time precision limitations. For example, the macOS operating system `date` command can print time precision in seconds, but not in nanoseconds. ### Positions We considered a range of options: * Unix epoch i.e. one incrementing number. * Terse text format "YYYYMMDDTHHMMSSNNNNNNNNN". * Using a local time zone vs. the UTC time zone. ### Argument For typical use, we value easy to read/write by humans, more than raw speed/size. For typical use, we want a format that works fine in machine systems, and also works well manually, such as writing sample data, reading JSON output, grepping a log file, etc. For atypical use, such as high performance computing, we expect we'll want to optimize any text format we choose by converting the text to a faster format, such as a programming language's built-in date object type. So the text format doesn't matter much for HPC. ### Implications Our various text systems and time systems will converge on this format. ## Related ### Related decisions We may want a fast/easy way to also track time deltas a.k.a. durations. These are easy with Unix epoch timestamps. ### Related requirements We may want to adjust our decision e.g. if we have a related requirement for a specific kind of logging message stamp, such as for Splunk, Sumo, ELK, etc. ### Related artifacts Language formatters and parsers: * [date-fns: Modern JavaScript date utility library](https://date-fns.org/) * [Crono: date and time library for Rust](https://github.com/chronotope/chron) Rosetta Code examples: * [System time](https://www.rosettacode.org/wiki/System_time) * [Data format](https://www.rosettacode.org/wiki/Date_format) * [Show the epoch](https://www.rosettacode.org/wiki/Show_the_epoch) SixArm examples: * [now_string](https://github.com/SixArm/rosetta_code/tree/master/tasks/now_string) ### Related principles Easily reversible. We can change pretty easily to a different format, such as Unix epoch. Defer premature optimization. For typical use we don't care much about a handful of extra characters such as a format that uses dashes and colons. ## Notes Add notes here. ================================================ FILE: locales/tr/examples/vue-front-end-javascript-library/.locale-peer-id ================================================ b43f7e984abc2ba89f2738c3e63203aa ================================================ FILE: locales/tr/examples/vue-front-end-javascript-library/index.md ================================================ # Architecture Decision Record: Vue front-end JavaScript library Date: [Date of decision] Status: [Draft/Final/Postponed/Cancelled] Subject: Architecture Decision Record for Vue front-end JavaScript library ## Context Our web application requires a front-end JavaScript library to provide dynamic and responsive user interfaces. We have evaluated several popular libraries that include React, Angular, and Vue. Based on the evaluation, we have decided to use the Vue library as the primary front-end library for our web application. ## Decision We have decided to adopt the Vue front-end JavaScript library based on the following factors: 1. **Lightweight:** Vue is a lightweight library that offers functionality similar to that of React and Angular but with a smaller code footprint. 2. **Easy to learn:** Vue has a simple and intuitive API that makes it easy to learn and use. 3. **Flexibility:** Vue is a flexible library that works well with other libraries or frameworks to provide different functionalities. 4. **Performance:** Vue provides excellent performance with fast rendering and minimal overhead. 5. **Strong community:** Vue has a growing and strong community that offers support and resources to the users. ## Consequences The decision to use Vue as the primary front-end JavaScript library will have the following consequences: 1. Development and maintenance will be faster and easier because of the simplicity and flexibility of Vue. 2. Team members who are new to Vue can easily learn and use it because of its simple and intuitive API. 3. Integration with other libraries or frameworks will be easier because of the flexibility of Vue. 4. The application will have better performance and responsiveness with faster rendering and minimal overhead. 5. The team will have access to a growing and strong community that offers support and resources for Vue. ## Conclusion Based on the evaluation and the above factors, we have decided to use Vue as the primary front-end JavaScript library for our web application. This decision will provide us with the benefits of simplicity, flexibility, performance, and support from a growing and strong community.
Credit: this page is generated by ChatGPT, then edited for clarity and format.
================================================ FILE: locales/tr/examples/web-application-framework-batteries-included-full-stack-for-a-startup-product/index.md ================================================ # Architecture Decision Record: web application framework, batteries included, full stack, for a startup product **Primary Objective:** To build a web application for paying customers to sign in, upload files, process data, and view reports, focusing on agile development, full-stack functionality, and strong compatibility with AI/ML tools, especially Project Jupyter notebooks. ### Context and Requirements: 1. **Agile Development (High Priority)**: As a startup, we need rapid iteration and flexibility. Agile practices, such as quick prototyping, iterative development, and adaptability to change, are key to our development cycle. 2. **Full-Stack Framework (High Priority)**: We aim to minimize overhead by selecting a framework that can handle both backend and frontend efficiently, reducing the need for separate front-end frameworks. 3. **Compatibility with AI/ML Tools (High Priority)**: The ability to integrate easily with data analysis tools like Jupyter notebooks and Python's data science ecosystem (NumPy, Pandas, TensorFlow, etc.) is essential. This would facilitate efficient data processing and reporting. 4. **Low Importance Criteria**: - **Runtime Speed**: While performance is relevant, it is not the most critical factor at the start since we are more concerned with development speed and feature completeness. - **Scalability**: We anticipate growth, but scalability concerns can be addressed later, and this is not a primary requirement right now. - **Backwards Compatibility**: We are focusing on current technologies and are not heavily concerned about backward compatibility with legacy systems. ### Frameworks Evaluated: 1. **Django (Python)** 2. **Ruby on Rails (Ruby)** 3. **Phoenix (Elixir)** 4. **Loco (Rust)** --- ### 1. **Django (Python)** **Overview**: Django is a high-level web framework for Python that promotes rapid development and clean, pragmatic design. It is known for its “batteries included” philosophy, meaning it includes many features such as authentication, routing, ORM, and form handling right out of the box. **Strengths**: - **Full-Stack**: Django is a comprehensive, full-stack framework that can handle both backend and frontend needs with integrated features (e.g., templating engine, admin interface). - **Agile Development**: Django's well-defined structure and conventions allow for rapid development and adaptability, crucial for a startup environment. The framework comes with excellent documentation and a rich ecosystem of third-party packages, which accelerates development. - **AI/ML Integration**: Python's ecosystem is unmatched when it comes to data science and machine learning. Django, being Python-based, integrates seamlessly with tools like Jupyter notebooks, Pandas, NumPy, TensorFlow, and scikit-learn. - **Community and Ecosystem**: Django has an extensive community, robust documentation, and a wide range of plugins and extensions, which significantly speeds up development and troubleshooting. **Weaknesses**: - **Runtime Speed**: Python tends to be slower compared to languages like Rust or Elixir. However, for this use case, where performance is not the primary concern, this may not be a dealbreaker. - **Scalability**: While Django is highly scalable, there might be challenges at the very high scale without careful optimization (e.g., when handling heavy concurrent requests). However, Django can still be scaled effectively using load balancing and caching techniques. **Verdict**: Django aligns well with the requirements for agile development, full-stack support, and AI/ML compatibility. Its Python integration offers seamless access to the data science tools and libraries necessary for the application. --- ### 2. **Ruby on Rails (Ruby)** **Overview**: Ruby on Rails (RoR) is a mature, full-stack web application framework known for its convention-over-configuration approach, which facilitates rapid development. **Strengths**: - **Full-Stack**: RoR comes with built-in tools for both backend and frontend development (e.g., views, templates, scaffolding), and its rich library of gems allows quick implementation of various features. - **Agile Development**: Ruby on Rails is particularly known for its fast iteration cycles, which is advantageous for startups looking to quickly iterate on features. RoR supports test-driven development (TDD) and has an established ecosystem for agile workflows. - **Community and Ecosystem**: RoR has a well-established, strong community and a wide array of gems that can speed up development. - **Ease of Use**: Rails has a very developer-friendly syntax and is known for making tasks such as database migrations, model-view-controller (MVC) architecture, and route handling quick and simple. **Weaknesses**: - **Performance**: Ruby tends to have slower runtime performance compared to Python or Elixir. While RoR can scale with the right infrastructure, Ruby’s performance might become a bottleneck for applications that require heavy real-time processing or high concurrent traffic. - **AI/ML Integration**: Although Ruby has some machine learning libraries, it is not as widely adopted in the AI/ML community as Python. Integration with tools like Jupyter notebooks is not as seamless, making Python a stronger choice for data-heavy applications. **Verdict**: While Ruby on Rails excels in agile development and rapid prototyping, it falls short in terms of AI/ML compatibility compared to Python (Django). It’s a viable choice for startups that prioritize fast iteration over deep data analysis integration. --- ### 3. **Phoenix (Elixir)** **Overview**: Phoenix is a web framework built with Elixir, a functional programming language designed for scalability and concurrency. Phoenix leverages the Erlang VM, which is known for handling massive concurrency and fault-tolerant systems. **Strengths**: - **Scalability and Performance**: Phoenix shines in scalability and handling high concurrency. It is built on the Erlang VM, which can support thousands (or even millions) of concurrent connections, making it a strong candidate for applications requiring real-time data processing or high-volume traffic. - **Full-Stack**: Phoenix includes everything needed to build both the backend and frontend of an application. It supports live views for interactive UI updates and includes a templating engine. - **Agile Development**: Phoenix is highly modular, allowing for rapid iteration on features. It is well-suited for startups that need to move quickly. - **AI/ML Compatibility**: While Elixir has emerging machine learning libraries, it is not as widely supported for AI/ML tasks as Python. Integrating with tools like Jupyter notebooks would require workarounds, as Elixir’s ecosystem for data science is not as mature as Python’s. **Weaknesses**: - **AI/ML Ecosystem**: Elixir is not the primary language used in data science or machine learning, and the ecosystem is not as mature as Python’s. Thus, integration with tools like Jupyter notebooks or popular AI libraries (TensorFlow, PyTorch) will be cumbersome. - **Learning Curve**: If the team is unfamiliar with functional programming and Elixir, there might be a steeper learning curve. **Verdict**: Phoenix is an excellent choice if scalability and concurrency are a primary concern. However, given the priority on AI/ML compatibility, Phoenix may not be the best fit due to Elixir's limited ecosystem in this space. --- ### 4. **Loco (Rust)** **Overview**: Loco is a web framework built with Rust, a systems programming language known for its performance, memory safety, and concurrency. Rust is increasingly popular for building high-performance applications. **Strengths**: - **Performance**: Rust’s primary strength lies in its high performance and memory safety, making it an excellent choice for applications requiring low-level control or extremely high performance. - **Concurrency**: Rust’s ownership system ensures memory safety while allowing safe concurrent programming, making it ideal for systems that need to scale efficiently and handle parallelism. **Weaknesses**: - **Full-Stack Development**: Loco, while promising, is not as mature as the other frameworks in terms of providing a complete full-stack solution. It is more suitable for backend development, and the front-end ecosystem around Rust is still emerging. - **Agile Development**: Developing with Rust can be slower compared to higher-level languages like Python or Ruby due to its lower-level nature and steeper learning curve. - **AI/ML Ecosystem**: Rust does not have the same extensive ecosystem for AI/ML as Python. While there are growing libraries in Rust for numerical computing, they are far less mature than Python’s offerings, such as Jupyter notebooks or machine learning frameworks. **Verdict**: While Rust and its framework Loco offer exceptional performance, the lack of full-stack support, agile development benefits, and AI/ML ecosystem make it less ideal for this specific use case. It is more suited for performance-critical applications rather than rapid web development with integrated data science tools. --- ### Conclusion After evaluating the options based on the project’s requirements, **Django (Python)** is the most suitable choice. It offers the following advantages: - **Full-Stack Capabilities**: Django is a full-stack framework that integrates both backend and frontend development. - **Agile Development**: The framework is well-suited to rapid prototyping and iteration, which is essential for a startup environment. - **AI/ML Compatibility**: Python is the leading language in AI/ML, and Django’s compatibility with libraries like Jupyter notebooks ensures smooth integration for data analysis and processing. - **Community and Ecosystem**: Django’s strong community support and extensive library ecosystem provide numerous tools to accelerate development. While **Ruby on Rails** is also a strong contender for agile development, its limited AI/ML support makes it less ideal for this specific use case. **Phoenix (Elixir)** and **Loco (Rust)**, though excellent for scalability and performance, fall short in terms of AI/ML integration and full-stack development. Therefore, Django is the recommended framework for this project. ================================================ FILE: locales/tr/examples/work-from-home/.locale-peer-id ================================================ 0a53cbdf9f479da77ad7e0a6128275a9 ================================================ FILE: locales/tr/examples/work-from-home/index.md ================================================ # Decision record for work from home Title: Employees can work from home Decision Maker: Management Team Decision Date: July 1, 2021 ## Background Due to the ongoing COVID-19 pandemic, many employees have been working remotely from home. This arrangement has provided benefits such as increased flexibility, improved work-life balance and a decrease in the spread of the virus. Furthermore, numerous employees have expressed that they would like to continue working from home even after the pandemic has ended. ## Decision After weighing the pros and cons of allowing employees to work from home, the management team has decided to implement a permanent work from home policy for eligible employees. The policy applies to all full-time employees who can effectively perform their duties from home and have demonstrated success working remotely during the pandemic. Eligible employees can choose to work from home up to three days per week, while in-office work will be required for the remaining two days. To ensure effective communication and collaboration, regular check-ins with team members and managers will be required. Additionally, employees will be provided with the necessary equipment and resources to perform their duties effectively from home. The implementation of this policy will be reviewed and revisited regularly to ensure that it continues to benefit both the employees and the company. ## Reasoning The decision to continue allowing employees to work from home is based on several factors, including employee work-life balance, greater flexibility and freedom, improved productivity, and less exposure to the risk of infection. By implementing a flexible work model, the company can attract and retain top talent while also providing a positive company culture. ## Implications The implementation of the permanent work from home policy will have several implications, including the need for ongoing communication and coordination among team members, adjusting work processes and protocols to accommodate a remote workforce, and ensuring that all employees have access to the necessary equipment, tools and resources. ## Conclusion The decision to implement a permanent work from home policy is in line with the company's values of promoting a healthy work-life balance, supporting employee well-being and promoting a positive company culture. We believe that this decision will enable our organization to be more agile and better suited to adapt to changing business needs while improving employee satisfaction and productivity. ================================================ FILE: locales/tr/templates/.locale-peer-id ================================================ 70f1f9b3530831bc891a6e9b9b0d27de ================================================ FILE: locales/tr/templates/decision-record-template-by-arc42/LICENSE.md ================================================ # LICENSE Source: License: License: ================================================ FILE: locales/tr/templates/decision-record-template-by-arc42/index.md ================================================ # arc42 tarafından karar kaydı şablonu ## 1. Giriş ve Hedefler Gereksinimlerin kısa açıklaması, itici güçler, gereksinimlerin özeti (veya özet). Ana paydaşlar için en yüksek önceliğe sahip mimari için en önemli üç (maksimum beş) kalite hedefi. Mimari ile ilgili beklentileri olan önemli paydaşların tablosu. ## 1.1 Gereksinimler Genel Bakışı ### İçerik İşlevsel gereksinimlerin, itici güçlerin, gereksinimlerin özeti (veya özet) kısa açıklaması. (Umarız var olan) gereksinim belgelerine bağlantılar ve nerede bulunacağı bilgisi. ### Motivasyon Son kullanıcıların bakış açısından, bir sistem bir iş faaliyetini desteklemeyi iyileştirmek ve/veya kaliteyi artırmak için oluşturulur veya değiştirilir. ### Biçim Kısa metinsel açıklama, muhtemelen tablo kullanım durumu formatında. Gereksinim belgeleri varsa, bu genel bakış bu belgelere başvurmalıdır. Bu alıntıları mümkün olduğunca kısa tutun. Bu belgenin okunabilirliğini gereksinim belgeleriyle olası fazlalıkla dengeleyin. ## 1.2 Kalite hedefleri ### İçerik Ana paydaşlar için en yüksek öneme sahip mimari için en önemli üç (maksimum beş) kalite hedefi. Mimari için gerçekten kalite hedeflerini kastediyoruz. Bunları proje hedefleriyle karıştırmayın. Bunlar mutlaka aynı değildir. ISO 25010 standardı ilgi çekici olası konuların güzel bir genel bakışını sağlar. ### Motivasyon En önemli paydaşlarınızın kalite hedeflerini bilmelisiniz, çünkü bunlar temel mimari kararları etkileyecektir. Bu kaliteler hakkında çok somut olduğunuzdan emin olun, moda sözcüklerden kaçının. Bir mimar olarak işinizin kalitesinin nasıl değerlendirileceğini bilmiyorsanız … ### Biçim En önemli kalite hedeflerini ve somut senaryoları içeren, önceliklere göre sıralanmış bir tablo. ## 1.3 Paydaş ### İçerik Sistemin paydaşlarının açık genel bakışı, yani tüm kişiler, roller veya kuruluşlar: - mimariyi bilmeli - mimariye ikna edilmeli - mimari veya kodla çalışmak zorunda - işleri için mimari belgelerine ihtiyaç duyar - sistem veya geliştirilmesi hakkında kararlar almak zorunda ### Motivasyon Sistemin geliştirilmesinde yer alan veya sistemden etkilenen tüm tarafları bilmelisiniz. Aksi takdirde, geliştirme sürecinde daha sonra kötü sürprizlerle karşılaşabilirsiniz. Bu paydaşlar çalışmanızın ve sonuçlarının kapsamını ve ayrıntı düzeyini belirler. ### Biçim Rol adları, kişi adları ve mimari ve belgeleriyle ilgili beklentileri içeren tablo. ## 2. Kısıtlamalar Tasarım ve uygulama kararlarında veya ilgili süreçlerle ilgili kararlarda ekipleri kısıtlayan her şey. Bazen bireysel sistemlerin ötesine geçebilir ve tüm kuruluşlar ve şirketler için geçerli olabilir. ### İçerik Yazılım mimarlarını tasarım ve uygulama kararlarında veya geliştirme süreci hakkındaki kararlarda özgürlüklerinde kısıtlayan herhangi bir gereksinim. Bu kısıtlamalar bazen bireysel sistemlerin ötesine geçer ve tüm kuruluşlar ve şirketler için geçerlidir. ### Motivasyon Mimarlar, tasarım kararlarında nerede özgür olduklarını ve nerede kısıtlamalara uymaları gerektiğini tam olarak bilmelidir. Kısıtlamalarla her zaman uğraşılmalıdır; yine de pazarlığa açık olabilirler. ### Biçim Açıklamalarla basit kısıtlama tabloları. Gerekirse bunları teknik kısıtlamalar, organizasyonel ve politik kısıtlamalar ve kurallar (örn. programlama veya sürümleme yönergeleri, belgeleme veya adlandırma kuralları) olarak alt bölümlere ayırabilirsiniz. ## 3. Bağlam ve Kapsam Sisteminizi (harici) iletişim ortaklarından (komşu sistemler ve kullanıcılar) sınırlar. Harici arayüzleri belirtir. İş/alan perspektifinden (her zaman) veya teknik perspektiften (isteğe bağlı) gösterilir. ### İçerik Sistem kapsamı ve bağlamı - adından da anlaşılacağı gibi - sisteminizi (yani kapsamınız) tüm iletişim ortaklarından (komşu sistemler ve kullanıcılar, yani sisteminizin bağlamı) sınırlar. Böylece harici arayüzleri belirtir. Gerekirse, iş bağlamını (alana özgü girdiler ve çıktılar) teknik bağlamdan (kanallar, protokoller, donanım) ayırt edin. ### Motivasyon İletişim ortaklarına alan arayüzleri ve teknik arayüzler sisteminizin en kritik yönleri arasındadır. Bunları tamamen anladığınızdan emin olun. ### Biçim - Çeşitli bağlam diyagramları - İletişim ortaklarının ve arayüzlerinin listeleri. ## 3.1 İş bağlamı ### İçerik Alana özgü girdiler ve çıktılar veya arayüzlerin açıklamalarıyla tüm iletişim ortaklarının (kullanıcılar, BT sistemleri, …) belirtimi. İsteğe bağlı olarak alana özgü formatlar veya iletişim protokolleri ekleyebilirsiniz. ### Motivasyon Tüm paydaşlar, sistemin çevresiyle hangi verilerin değiş tokuş edildiğini anlamalıdır. ### Biçim Sistemi kara kutu olarak gösteren ve iletişim ortaklarına alan arayüzlerini belirten her türlü diyagram. Alternatif olarak (veya ek olarak) bir tablo kullanabilirsiniz. Tablonun başlığı sisteminizin adıdır, üç sütun iletişim ortağının adını, girdileri ve çıktıları içerir. ## 3.2 Teknik bağlam ### İçerik Sisteminizi çevresine bağlayan teknik arayüzler (kanallar ve iletim ortamları). Ek olarak, alana özgü girdi/çıktının kanallara eşlenmesi, yani hangi I/O'nun hangi kanalı kullandığının açıklaması. ### Motivasyon Birçok paydaş, sistem ve bağlamı arasındaki teknik arayüzlere dayalı mimari kararlar alır. Özellikle altyapı veya donanım tasarımcıları bu teknik arayüzlere karar verir. ### Biçim Örneğin, komşu sistemlere kanalları açıklayan UML dağıtım diyagramı, kanallar ve girdi/çıktı arasındaki ilişkileri gösteren bir eşleme tablosuyla birlikte. ## 4. Çözüm Stratejisi Mimariyi şekillendiren temel kararların ve çözüm stratejilerinin özeti. Teknoloji, üst düzey ayrıştırma, en önemli kalite hedeflerine ulaşma yaklaşımları ve ilgili organizasyonel kararları içerebilir. ### İçerik Sistemin mimarisini şekillendiren temel kararların ve çözüm stratejilerinin kısa bir özeti ve açıklaması. Bunlar şunları içerir: - teknoloji kararları - sistemin üst düzey ayrıştırılması hakkındaki kararlar, örn. mimari kalıp veya tasarım kalıbı kullanımı - temel kalite hedeflerine nasıl ulaşılacağına dair kararlar - ilgili organizasyonel kararlar, örn. bir geliştirme süreci seçmek veya belirli görevleri üçüncü taraflara devretmek. ### Motivasyon Bu kararlar mimariniz için temel taşlarını oluşturur. Birçok diğer ayrıntılı karar veya uygulama kuralı için temeldir. ### Biçim Bu temel kararların açıklamasını kısa tutun. Problem tanımınıza, kalite hedeflerinize ve temel kısıtlamalara dayanarak neye karar verdiğinizi ve neden bu şekilde karar verdiğinizi motive edin. Aşağıdaki bölümlerdeki ayrıntılara bakın (yapısal ayrıntılar için bölüm 5, kesişen kavramlar için bölüm 8). Çözüm yaklaşımlarının bir listesini veya bir tablo kullanabilirsiniz. ## 5. Yapı Taşı Görünümü Sistemin statik ayrıştırması, kaynak kodun soyutlamaları, uygun ayrıntı düzeyine kadar beyaz kutuların (siyah kutular içeren) hiyerarşisi olarak gösterilir. ### İçerik Yapı taşı görünümü, sistemin yapı taşlarına (modüller, bileşenler, alt sistemler, sınıflar, arayüzler, paketler, kütüphaneler, çerçeveler, katmanlar, bölümler, seviyeler, fonksiyonlar, makrolar, işlemler, veri yapıları, …) statik ayrıştırmasını ve bunların bağımlılıklarını (ilişkiler, ilişkilendirmeler, …) gösterir. Bu görünüm her mimari belgeleme için zorunludur. Bir ev analojisinde bu kat planıdır. ### Motivasyon Yapısını soyutlama yoluyla anlaşılır hale getirerek kaynak kodunuzun genel bakışını koruyun. Bu, paydaşlarınızla uygulama ayrıntılarını açıklamadan soyut bir düzeyde iletişim kurmanıza olanak tanır. ### Biçim Yapı taşı görünümü, siyah kutuların ve beyaz kutuların (aşağıdaki şekle bakın) ve açıklamalarının hiyerarşik bir koleksiyonudur. ## 5.1 Beyaz Kutu Genel Sistem Burada, aşağıdaki beyaz kutu şablonunu kullanarak genel sistemin ayrıştırmasını açıklarsınız. Şunları içerir: - bir genel bakış diyagramı - ayrıştırma için bir motivasyon - içerilen yapı taşlarının siyah kutu açıklamaları. Bunlar için alternatifler sunuyoruz: - tüm içerilen yapı taşlarının ve arayüzlerinin kısa ve pragmatik bir genel bakışı için bir tablo kullanın - siyah kutu şablonuna göre yapı taşlarının siyah kutu açıklamalarının bir listesini kullanın (aşağıya bakın). Araç seçiminize bağlı olarak bu liste alt bölümler (metin dosyalarında), alt sayfalar (Wiki'de) veya iç içe öğeler (modelleme aracında) olabilir. - (isteğe bağlı:) bir yapı taşının siyah kutu şablonlarında açıklanmayan, ancak beyaz kutuyu anlamak için çok önemli olan önemli arayüzler. Arayüzleri belirtmenin pek çok yolu olduğundan, onlar için belirli bir şablon sağlamıyoruz. En iyi durumda örnekler veya basit imzalarla yetineceksiniz. ## 5.2 Seviye 2 Burada, seviye 1'den (bazı) yapı taşlarının iç yapısını beyaz kutular olarak belirtebilirsiniz. Sisteminizin hangi yapı taşlarının böyle ayrıntılı bir açıklamayı haklı kılacak kadar önemli olduğuna karar vermelisiniz. Lütfen tamlık yerine alaka düzeyini tercih edin. Önemli, şaşırtıcı, riskli, karmaşık veya değişken yapı taşlarını belirtin. Sisteminizin normal, basit, sıkıcı veya standartlaştırılmış kısımlarını atlayın. ### 5.2.1 Yapı taşı 1 için Beyaz Kutu Yapı taşı 1'in iç yapısını belirtir. Beyaz kutu şablonunu kullanın (yukarıya bakın). ## 6. Çalışma Zamanı Görünümü Önemli kullanım durumlarını veya özellikleri, kritik harici arayüzlerdeki etkileşimleri, işletim ve yönetim artı hata ve istisna davranışını kapsayan senaryolar olarak yapı taşlarının davranışı. ### İçerik Çalışma zamanı görünümü, sistemin yapı taşlarının somut davranışını ve etkileşimlerini aşağıdaki alanlardan senaryolar şeklinde açıklar: - önemli kullanım durumları veya özellikler: yapı taşları bunları nasıl yürütür? - kritik harici arayüzlerdeki etkileşimler: yapı taşları kullanıcılar ve komşu sistemlerle nasıl işbirliği yapar? - işletim ve yönetim: başlatma, başlangıç, durdurma - hata ve istisna senaryoları Not: Olası senaryoların (diziler, iş akışları) seçimi için ana kriter mimari alaka düzeyleridir. Çok sayıda senaryo tanımlamak önemli değildir. Bunun yerine temsili bir seçim belgelemelisiniz. ### Motivasyon Sisteminizdeki yapı taşlarının (örneklerinin) çalışma zamanında işlerini nasıl yaptığını ve nasıl iletişim kurduğunu anlamalısınız. Mimarinizi statik modelleri (yapı taşı görünümü, dağıtım görünümü) okumaya ve anlamaya daha az istekli veya yetenekli paydaşlara iletmek için belgelerinizde esas olarak senaryoları yakalayacaksınız. ### Biçim Senaryoları tanımlamak için birçok gösterim vardır, örn. - adımların numaralandırılmış listesi (doğal dilde) - aktivite diyagramları veya akış şemaları - sıra diyagramları - BPMN veya EPC'ler (olay süreç zincirleri) - durum makineleri - vb. ## 6.n Çalışma Zamanı Senaryosu n (1, 2, 3, vb.) Senaryonun çalışma zamanı diyagramını veya metinsel açıklamasını ekleyin. Bu diyagramda gösterilen yapı taşı örnekleri arasındaki etkileşimlerin dikkat çekici yönlerinin açıklamasını ekleyin. ## 7. Dağıtım Görünümü Ortamlar, bilgisayarlar, işlemciler, topolojilerle teknik altyapı. (Yazılım) yapı taşlarının altyapı öğelerine eşlenmesi. ### İçerik Dağıtım görünümü şunları açıklar: - sisteminizi yürütmek için kullanılan teknik altyapı, coğrafi konumlar, ortamlar, bilgisayarlar, işlemciler, kanallar ve ağ topolojileri gibi altyapı öğeleri ve diğer altyapı öğeleri ile - (yazılım) yapı taşlarının bu altyapı öğelerine eşlenmesi. Sistemler genellikle farklı ortamlarda yürütülür, örn. geliştirme ortamı, test ortamı, üretim ortamı. Bu gibi durumlarda tüm ilgili ortamları belgelemelisiniz. Özellikle yazılımınız birden fazla bilgisayar, işlemci, sunucu veya konteyner ile dağıtılmış bir sistem olarak yürütüldüğünde veya kendi donanım işlemcilerinizi ve çiplerinizi tasarlayıp oluşturduğunuzda dağıtım görünümünü belgeleyin. Yazılım perspektifinden, altyapının yapı taşlarınızın dağıtımını göstermek için gereken öğelerini yakalamak yeterlidir. Donanım mimarları bunun ötesine geçebilir ve ihtiyaç duydukları herhangi bir ayrıntı düzeyinde altyapıyı tanımlayabilir. ### Motivasyon Yazılım donanım olmadan çalışmaz. Bu temel altyapı sisteminizi ve/veya bazı kesişen kavramları etkileyebilir ve etkileyecektir. Bu nedenle, altyapıyı bilmeniz gerekir. ### Biçim Belki en üst düzey dağıtım diyagramı zaten bölüm 3.2'de kendi altyapınızla TEK bir siyah kutu olarak teknik bağlam olarak yer almaktadır. Bu bölümde ek dağıtım diyagramları kullanarak bu siyah kutuya yakınlaşacaksınız. - UML bu görünümü ifade etmek için dağıtım diyagramları sunar. Altyapınız daha karmaşıksa, muhtemelen iç içe diyagramlarla kullanın. - (Donanım) paydaşlarınız UML dağıtım diyagramı yerine diğer tür diyagramları tercih ediyorsa, altyapının düğümlerini ve kanallarını gösterebilen herhangi bir türü kullanmalarına izin verin. ## 7.1 Altyapı Seviyesi 1 Açıklayın (genellikle diyagramlar, tablolar ve metin kombinasyonunda): - sisteminizin birden çok konuma, ortama, bilgisayara, işlemciye dağılımı, vb. ve aralarındaki fiziksel bağlantılar - bu dağıtım yapısı için önemli gerekçe veya motivasyon - altyapının kalite ve/veya performans özellikleri - yazılım eserlerinin (yapı taşları) altyapı öğelerine eşlenmesi Birden fazla ortam veya alternatif dağıtımlar için lütfen arc42'nin bu bölümünü tüm ilgili ortamlar için kopyalayın. ** ## 7.2 Altyapı Seviyesi 2 Burada altyapı seviyesi 1'den (bazı) altyapı öğelerinin iç yapısını ekleyebilirsiniz. Lütfen her seçili öğe için seviye 1'den yapıyı kopyalayın. ## 8. Kesişen Kavramlar Sistemin birden çok bölümünde (→ kesişen) ilgili genel, temel düzenlemeler ve çözüm yaklaşımları. Kavramlar genellikle birden çok yapı taşıyla ilişkilidir. Alan modelleri, mimari kalıplar ve stiller, belirli teknoloji kullanım kuralları ve uygulama kuralları gibi farklı konuları içerir. ### İçerik Bu bölüm kesişen kavramları (uygulamalar, kalıplar, düzenlemeler veya çözüm fikirleri) açıklar. Bu tür kavramlar genellikle birden çok yapı taşıyla ilişkilidir. Birçok farklı konu içerebilirler. ### Motivasyon Kavramlar, mimarinin kavramsal bütünlüğü (tutarlılık, homojenlik) için temel oluşturur. Bu nedenle, sisteminizin iç niteliklerine ulaşmak için önemli bir katkıdır. Bu, bu tür kavramların uyumlu bir belirtimi için şablonda sağladığımız yerdir. Bu kavramların çoğu yapı taşlarınızdan birkaçını etkiler veya birkaçıyla ilişkilidir. ### Biçim Biçim değişebilir: - herhangi bir yapıya sahip kavram belgeleri - özellikle teknik kavramlar için örnek uygulamalar - mimari görünümlerin gösterimlerini kullanan kesişen model alıntıları veya senaryolar ### Bu bölümün yapısı Sisteminiz için yalnızca en çok ihtiyaç duyulan konuları seçin ve bu bölümde her birine seviye-2 başlığı atayın (örn. 8.1, 8.2 vb). - Yukarıda belirtilen diyagramın tüm konularını kapsamaya ÇALIŞMAYIN. ### Arka Plan Sistemlerdeki bazı konular genellikle birden çok yapı taşı, donanım öğesi veya geliştirme sürecini ilgilendirir. Bu tür kesişen konuları, bunları ilgili yapı taşları, donanım öğeleri veya geliştirme süreçlerinin açıklamasında tekrarlamak yerine merkezi bir konumda iletmek veya belgelemek daha kolay olabilir. Belirli kavramlar bir sistemin tüm öğelerini ilgilendirebilir, diğerleri yalnızca birkaçıyla ilgili olabilir. ## 9. Mimari Kararlar Gerekçeler dahil önemli, pahalı, kritik, büyük ölçekli veya riskli mimari kararlar. ### İçerik Gerekçeler dahil önemli, pahalı, büyük ölçekli veya riskli mimari kararlar. "Kararlar" ile verilen kriterlere dayalı bir alternatif seçmeyi kastediyoruz. Bir mimari kararın burada bu merkezi bölümde mi yoksa yerel olarak mı (örn. bir yapı taşının beyaz kutu şablonunda) belgelenmesi gerektiğine karar vermek için yargınızı kullanın. Tekrarlanan metinlerden kaçının. Mimarinizin en önemli kararlarını zaten yakaladığınız bölüm 4'e bakın. ### Motivasyon Sisteminizin paydaşları kararlarınızı anlayabilmeli ve takip edebilmelidir. ### Biçim - Her önemli karar için ADR (mimari karar kaydı) - önem ve sonuçlara göre sıralanmış liste veya tablo veya - karar başına ayrı bölümler şeklinde daha ayrıntılı ### Arka Plan (ADR'ler hakkında) Daha küçük belgeleme parçalarının okunması, oluşturulması ve bakımı daha kolaydır. Mimari kararlar söz konusu olduğunda, geliştirme ekipleri genellikle: - kararı bilecektir, örn. kaynak kodunda görünür olduğu için, ama - bu kararın arkasındaki motivasyonu kaçıracaktır (bkz. Nygard 2011) Bu nedenle, birkaç önemli kararı motivasyonları ve gerekçeleriyle birlikte belgelemelisiniz. ### Kararlar hakkındaki önerimiz Yapı, kalite karakteristikleri, önemli (özellikle harici) bağımlılıklar ve arayüzler veya yapım tekniklerini etkileyen mimari açıdan önemli kararların bir koleksiyonunu tutun (bu öneri için Michael Nygard'a teşekkürler). ## 10. Kalite Gereksinimleri Üst düzey genel bakış sağlamak için kalite ağacıyla birlikte senaryolar olarak kalite gereksinimleri. En önemli kalite hedefleri bölüm 1.2'de (kalite hedefleri) açıklanmış olmalıdır. ### İçerik Bu bölüm tüm ilgili kalite gereksinimlerini içerir. Bu gereksinimlerin en önemlileri zaten bölüm 1.2'de (kalite hedefleri) açıklanmıştır, bu nedenle burada yalnızca atıfta bulunulmalıdır. Bu bölüm 10'da ayrıca tam olarak başarılamadığında yüksek riskler oluşturmayacak daha az öneme sahip kalite gereksinimlerini de yakalamalısınız (ancak olması güzel olabilir). ### Motivasyon Kalite gereksinimleri mimari kararları çok etkileyeceğinden, paydaşlarınız için hangi niteliklerin gerçekten önemli olduğunu spesifik ve ölçülebilir bir şekilde bilmelisiniz. ### Daha Fazla Bilgi https://quality.arc42.org adresindeki kapsamlı Q42 kalite modeline bakın. ## 10.1 Kalite Gereksinimleri Genel Bakışı ### İçerik Kalite gereksinimlerinin bir genel bakışı veya özeti. ### Motivasyon Genellikle düzinelerce (hatta yüzlerce) ayrıntılı kalite gereksinimle karşılaşırız. Bu genel bakış bölümünde, örneğin kategorileri veya konuları (ISO 25010:2023 veya Q42 tarafından önerildiği gibi) açıklayarak özetlemeye çalışmalısınız. Bu özet açıklamalar zaten yeterince kesin, spesifik ve ölçülebilirse, bölüm 10.2'yi atlayabilirsiniz. ### Biçim Her satırın bir kategori veya konu ve kalite gereksiniminin kısa bir açıklamasını içerdiği basit bir tablo kullanın. Alternatif olarak, bu kalite gereksinimlerini yapılandırmak için bir zihin haritası kullanabilirsiniz. Literatürde, genel "kalite" terimini kök olarak koyan ve "kalite" teriminin ağaç benzeri bir iyileştirmesini kullanan kalite nitelik ağacı fikri de tanımlanmıştır. [Bass+21] bu amaç için "Kalite Niteliği Fayda Ağacı" terimini tanıttı. ## 10.2 Kalite Senaryoları ### İçerik Kalite senaryoları kalite gereksinimlerini somutlaştırır ve bunların yerine getirilip getirilmediğine (kabul kriterleri anlamında) karar vermeye izin verir. Senaryolarınızın spesifik ve ölçülebilir olduğundan emin olun. İki tür senaryo özellikle yararlıdır: - Kullanım senaryoları (uygulama senaryoları veya kullanım durumu senaryoları olarak da adlandırılır), sistemin belirli bir uyarana çalışma zamanı tepkisini tanımlar. Bu ayrıca sistemin verimliliğini veya performansını tanımlayan senaryoları da içerir. Örnek: Sistem, bir kullanıcının isteğine bir saniye içinde tepki verir. - Değişiklik senaryoları, sistemin veya yakın çevresinin bir değişikliğinin veya uzantısının istenen etkisini tanımlar. Örnek: Ek işlevsellik uygulanır veya bir kalite niteliği için gereksinimler değişir ve değişikliğin çabası veya süresi ölçülür. ### Biçim Ayrıntılı senaryolar için tipik bilgiler şunları içerir: Kısa biçimde (Q42 modelinde tercih edilir): - Bağlam/Arka Plan: Ne tür bir sistem veya bileşen, ortam veya durum nedir? - Kaynak/Uyaran: Kim veya ne bir davranışı, tepkiyi veya eylemi başlatır veya tetikler. - Metrik/Kabul Kriterleri: Bir ölçüm veya metrik içeren bir yanıt Senaryoların uzun biçimi (SEI ve [Bass+21] tarafından tercih edilir) daha ayrıntılıdır ve aşağıdaki bilgileri içerir: - Senaryo Kimliği: Senaryo için benzersiz bir tanımlayıcı. - Senaryo Adı: Senaryo için kısa, açıklayıcı bir ad. - Kaynak: Senaryoyu başlatan varlık (kullanıcı, sistem veya olay). - Uyaran: Sistemin ele alması gereken tetikleyici olay veya koşul. - Ortam: Sistemin uyaranı deneyimlediği işletimsel bağlam veya koşul. - Eser: Uyarandan etkilenen sistemin yapı taşları veya diğer öğeleri. - Yanıt: Sistemin uyarana tepki olarak sergilediği sonuç veya davranış. - Yanıt Ölçümü: Sistemin yanıtının değerlendirildiği kriter veya metrik. ### Ayrıca bakınız Ocak 2023'ten bu yana, arc42 kalite gereksinimlerini #flexible, #efficient, #usable, #operable, #testable, #secure, #safe, #reliable gibi hashtag'ler veya etiketlerle etiketlemeyi öneren pragmatik bir kalite modeli sağlamaktadır. ## 11. Riskler ve Teknik Borç Bilinen teknik riskler veya teknik borç. Sistem içinde veya çevresinde hangi potansiyel sorunlar var? Geliştirme ekibi ne konusunda mutsuz hissediyor? ### İçerik Önceliğe göre sıralanmış tanımlanmış teknik risklerin veya teknik borçların listesi ### Motivasyon "Risk yönetimi yetişkinler için proje yönetimidir" (Tim Lister, Atlantic Systems Guild.) Bu, yönetim paydaşları (örn. proje yöneticileri, ürün sahipleri) tarafından genel risk analizi ve ölçüm planlamasının bir parçası olarak ihtiyaç duyulacak olan mimarideki risklerin ve teknik borçların sistematik tespiti ve değerlendirmesi için mottonuz olmalıdır. ### Biçim Riskleri en aza indirmek, azaltmak veya önlemek veya teknik borçları azaltmak için önerilen önlemleri muhtemelen içeren risklerin ve/veya teknik borçların listesi. ================================================ FILE: locales/tr/templates/decision-record-template-by-edgex/.locale-peer-id ================================================ 01939db0c341e9092c344d904065da12 ================================================ FILE: locales/tr/templates/decision-record-template-by-edgex/LICENSE.md ================================================ # LICENSE Source: https://docs.edgexfoundry.org/2.3/design/adr/template/ License: https://github.com/edgexfoundry/edgex-go/blob/main/LICENSE ================================================ FILE: locales/tr/templates/decision-record-template-by-edgex/index.md ================================================ # Mimari Karar Kaydı (ADR) şablonu Bu, EdgeX Foundry ADR için bir şablondur. Kaynak: https://docs.edgexfoundry.org/2.3/design/adr/template/ ### Gönderenler ADR gönderenlerini listeleyin. Biçim: - Ad (Kuruluş) ## Değişiklik Günlüğü Belgedeki değişiklikleri, durum, tarih ve PR URL'si dahil olmak üzere listeleyin. Durum şunlardan biridir: beklemede, onaylandı, değiştirildi, kullanımdan kaldırıldı. Tarih ISO 8601 (YYYY-AA-GG) biçiminde bir dizedir. PR, fark, katkıda bulunanlar ve inceleyenler gibi bilgiler dahil değişikliği gönderen pull request'tir. Biçim: - \[ADR'nin durumu, örn. onaylandı, değiştirildi, vb.\]\(pull request URL'si\) YYYY-AA-GG ## Başvurulan Kullanım Durumu/Durumları Tüm ilgili kullanım durumu / gereksinim belgelerini listeleyin. ADR en az bir ilgili, onaylanmış kullanım durumu gerektirir. Biçim: - \[Kullanım Durumu Adı\]\(URL\) ADR bir kullanım durumunun tüm gereksinimlerini karşılamıyorsa açıklama ekleyin. ## Bağlam Açıklayın: - tasarımın mimari açıdan nasıl önemli olduğu - bir ADR'yi gerektiren (basit bir sorun ve PR ile düzeltme yerine) - üst düzey tasarım yaklaşımı (ayrıntılar aşağıdaki önerilen tasarımda açıklanmıştır) ## Önerilen Tasarım Tasarımın ayrıntıları (mümkün olduğunca uygulamaya girmeden). Taslak: - etkilenecek (değiştirilecek) hizmetler/modüller - eklenecek yeni hizmetler/modüller - model ve DTO etkisi (değişiklikler/eklemeler/kaldırmalar) - API etkisi (değişiklikler/eklemeler/kaldırmalar) - genel yapılandırma etkisi (yeni bölümlerin oluşturulması, değişiklikler/eklemeler/kaldırmalar) - devops etkisi ## Değerlendirmeler ADR'nin tartışmasında ortaya çıkan alternatifleri, endişeleri, yan veya ilgili sorunları, soruları belgeleyin. Bunların çözülüp çözülmediğini veya nasıl yatıştırıldığını belirtin. ## Karar Üzerinde anlaşmaya varılan önemli uygulama ayrıntılarını, uyarıları, gelecekteki değerlendirmeleri, kalan veya ertelenen tasarım sorunlarını belgeleyin. Önerilen tasarım tarafından karşılanmayan gereksinimlerin herhangi bir bölümünü belgeleyin. ## Diğer İlgili ADR'ler İlgili ADR'leri listeleyin - örneğin bir özelliğin alt bileşeni için tasarım kararı, bu tasarım sonucunda kullanımdan kaldırılan bir tasarım vb. Biçim: - \[ADR Başlığı\]\(URL\) - İlgi ## Referanslar Ek referansları listeleyin. Biçim: - \[Başlık\]\(URL\) ================================================ FILE: locales/tr/templates/decision-record-template-by-gareth-morgan/README.md ================================================ index.md ================================================ FILE: locales/tr/templates/decision-record-template-by-gareth-morgan/index.md ================================================ # [000] Başlık *Kolay referans ve kataloglama için her ADR'ye bir numara atayın* \ *NOT: Tüm italik metin ipuçları sağlar ve üretim için kaldırılmalıdır* ## Durum - TASLAK / AKTİF / [000] tarafından KULLANIMDAN KALDIRILDI / [000]'IN YERİNİ ALDI ## Bağlam *Bu ADR'nin ele almayı amaçladığı sorunu/sorunları ve sorunların neden var olduğunu kısaca açıklayın.* ## Kararlaştırılan Yaklaşım *Alınmış / alınacak mimari açıdan önemli kararı ayrıntılandırın ve Bağlam bölümünde özetlenen sorunları nasıl ele aldığını açıklayın.* ## Sonuçlar *Bu kararın sistemin mimari karakteristikleri ve işlevsel gereksinimleri üzerindeki etkisi nedir?* ## Yönetişim *Bu kararın sonuçları nasıl izlenecek?* \ *Bu karara uyum nasıl sağlanacak?* ## Seçenek Analizi *Uygulanabilirse, bu belgede alınan karara ulaşmak için gerçekleştirilen herhangi bir değiş tokuş analizini dahil edin veya bağlantı verin.* ### Anahtar *İsteğe bağlı: Paydaşlara olumlu ve olumsuz değiş tokuşları hızlıca fark etmelerine yardımcı olabilecek görsel yardımcılar sağlayın - örneğin olumlu veya olumsuz ön ekleri olan basit trafik ışığı vurgulamaları.* Yeşil arka plan iyi bir uyumu gösterir, sarı ile kötüleşir, kırmızı en kötü uyumdur. \ \+ olumlu etkili bir yorumu gösterir \ \- olumsuz etkili bir yorumu gösterir ### Üst Düzey Genel Bakış *Her seçenek problem bağlamına bir bakışta ne kadar iyi uyuyor?*
Özet Seçenek 1 Seçenek 2 Seçenek 3
Uygulama Kolaylığı + Çok kolay - Zor - Uzman bilgisi gerektiren büyük uygulama
Zaman Çizelgeleri + Çok hızlı - Oldukça yavaş - Çok yavaş
Stratejik Değer - Stratejik değer yok, tamamen taktiksel + Müşteri katılım deneyimini biraz iyileştirir + Yaklaşan birleşme için ideal
### İşlevsel Gereksinimler *Her potansiyel seçenek istenen işlevsel gereksinimlere ne kadar iyi uyuyor?*
Senaryo Seçenek 1 Seçenek 2 Seçenek 3
Senaryo 1
Senaryo 2
Senaryo 3
*İsteğe bağlı: Bilinen gelecek senaryoları kapsamak için satır / başka bir tablo ekleyin.* ### İşlevsel Olmayan Gereksinimler *Her potansiyel seçenek istenen mimari karakteristiklere ne kadar iyi uyuyor? Not: 'Mimari Karakteristikler' daha uygun bir başlık olurdu, ancak bunu iş alanınız için tanıdık dile uyarlayın.*
Mimari
Karakteristik		 Seçenek 1 Seçenek 2 Seçenek 3
Ölçeklenebilirlik
Performans
Kullanılabilirlik
*İsteğe bağlı: İşiniz / ürününüz için geçerli olan mimari karakteristiklerin tanımlarını ekleyin veya bağlantı verin.* ================================================ FILE: locales/tr/templates/decision-record-template-by-gig-cymru-nhs-wales/index.md ================================================ # {Başlığınız Buraya} !!! info **Durum**: { Önerildi | İnceleniyor | Kabul Edildi | Reddedildi | Yerini Aldı | Kullanımdan Kaldırıldı } **Güncellendi**: {YYYY-AA-GG} ## Özet {Bu, ADR'nizin 'yönetici özeti' veya 'asansör konuşmasıdır'. Birkaç özlü cümlede (genellikle 2-4), bu ADR'nin ele aldığı temel sorunu, soruyu veya fırsatı açıkça belirtin. Alınan karara veya odak alanına kısa bir ipucu ekleyin. Amaç, okuyucuların bu ADR'nin ne hakkında olduğunu hızlıca anlamalarına ve belgenin tamamını okumaya gerek kalmadan kendileri için uygun olup olmadığına karar vermelerine yardımcı olmaktır. Bunu teknik bir makalenin özeti veya ana konuya çok kısa bir giriş olarak düşünün.} ## Etkenler {Bu bölüm bu kararın neden **şimdi** alındığını açıklar. Bu mimari kararı gerektiren birincil motivasyonları, ihtiyaçları veya sorunları açıkça ifade edin. Temel nedenleri ve baskıları düşünün.} * {örn. ... gerektiren yeni bir özellik/yetenek geliştiriyoruz} * {örn. Performansı iyileştirmemiz, erişilebilirliği artırmamız, borcu temizlememiz gerekiyor...} * {örn. Kullanıcılardan gelen geri bildirimler ... öneriyor} * {örn. Mevcut yaklaşım bu sınırlamaları getiriyor...} ## Seçenekler {Burada değerlendirdiğiniz farklı seçenekleri listelersiniz. Gerçeklere bağlı kalın ve görüşlerden kaçının, sonraki bölüm analizi kapsar. Kısa bir açıklama, ilgili belgelere veya örneklere bağlantılar ekleyin. Sonuçta seçilmemiş olsalar bile, araştırdığınız tüm önemli alternatifleri dahil edin. Amaç, değerlendirmeye dalmadan önce okuyuculara her alternatif hakkında açık, tarafsız bir anlayış sağlamaktır.} ### {Seçenek 1 Başlığı} {Seçeneği açıklayın, bir özet sağlayın, gerçekleri listeleyin, bağlantılar verin vb.} ### {Seçenek n Başlığı} ... ## Seçenek Analizi {Burada *Seçenekler* bölümünde sunulan her seçeneği eleştirel olarak değerlendirirsiniz. Her seçenek için avantajları, dezavantajları ve diğer ilgili değerlendirmeler veya değiş tokuşların dengeli bir görünümünü sağlayın. Spesifik olun ve mümkünse noktalarınızı *Etkenler*e geri bağlayın. Şu gibi yönleri düşünün: * Maliyet (geliştirme, operasyonel, lisanslama) * Karmaşıklık (uygulama, bakım, öğrenme eğrisi) * Riskler (teknik, operasyonel, güvenlik) * Mimari ilkeler veya mevcut standartlarla uyum * Performans, ölçeklenebilirlik, kullanılabilirlik, bakım kolaylığı, güvenlik vb. üzerindeki etki Gerektiği kadar Artı/Eksi/Diğer ifadesi ekleyin. } ### {Seçenek 1 Değerlendirmesi} * Artı: {Bu seçeneğin belirli bir avantajı veya faydası.} * Eksi: {Bu seçenekle ilişkili belirli bir dezavantaj, risk veya maliyet.} * Diğer: {Kesinlikle artı veya eksi olmayan ilgili bir nokta.} ### {Seçenek n Değerlendirmesi} ... ## Öneri {Burada nihai kararı açıkça belirtir ve seçilen seçeneği açıkça adlandırırsınız. Bu seçeneğin **neden** seçildiğini ayrıntılı olarak açıklayın. Seçilen seçeneğin *Etkenler*i en iyi nasıl ele aldığını ve temel gereksinimleri karşıladığını veya belirtilen sorunu çözdüğünü açıkça ifade etmelisiniz.} ### Sonuçlar {Bu bölüm **isteğe bağlıdır**.} {Artık bir karar alındığına göre, hem olumlu hem de olumsuz beklenen sonuçlar ve etkiler nelerdir? Bu karar alınarak hangi bilinen sınırlamalar, maliyetler veya riskler kabul ediliyor? Bu karar farklı paydaşları, diğer sistemleri, geliştirme uygulamalarını, operasyonel prosedürleri veya kullanıcı deneyimini nasıl etkileyecek?} * Artı: {Bu karardan beklenen belirli bir olumlu sonuç veya fayda.} * Eksi: {Bu karardan kaynaklanan belirli bir kabul edilen dezavantaj, maliyet veya risk.} * Diğer: {Kesinlikle artı veya eksi olmayan bir sonuç.} ### Onay {Bu bölüm **isteğe bağlıdır**.} {Bu kararın uygulanmasının nasıl doğrulanacağını ve devam eden uyumun nasıl sağlanacağını özetleyin. Bu, kararın sadece teorik olmadığını, aktif olarak uygulamaya konulacağını ve izleneceğini göstermeye yardımcı olur. Kararın doğru şekilde uygulandığını nasıl kontrol edeceksiniz? (örn. kod incelemeleri, belirli testler, gösteriler, akran değerlendirmesi). Bu karara bağlılık zaman içinde nasıl sürdürülecek? (örn. otomatik kontroller, periyodik denetimler, ekip yönergelerinde güncellemeler, eğitim). Kararın amaçlanan olumlu sonuçları elde ettiğini gösterecek belirli metrikler veya göstergeler var mı? (örn. performans kıyaslamaları, benimseme oranları, belirli hatalarda azalma, kullanıcı geri bildirim puanları). Bunu denetlemekten kim sorumlu ve karar izlenmezse ne olur?} ## Daha Fazla Bilgi {Bu bölüm **isteğe bağlıdır**.} {Bu bölümü, kararı destekleyen, bağlam ekleyen veya gelecekteki eylemleri yönlendiren ek bilgiler sağlamak için kullanın. Diğer kararlara ve kaynaklara bağlantılar da burada görünebilir. Karar alma sürecine kimlerin dahil olduğunu ve uzlaşmaya nasıl/varılıp varılmadığını kısaca not edebilirsiniz. Ayrıca gelecekte bu kararın yeniden değerlendirilmesini tetikleyebilecek bir zaman çerçevesi veya belirli olaylar önermek isteyebilirsiniz.} ================================================ FILE: locales/tr/templates/decision-record-template-by-jeff-tyree-and-art-akerman/.locale-peer-id ================================================ f4ca0a94124a91279e1929ea23ab864d ================================================ FILE: locales/tr/templates/decision-record-template-by-jeff-tyree-and-art-akerman/LICENSE-WIP.md ================================================ # LICENSE WIP ```email From:Joel Parker Henderson To:Help@computer.org Subject:License question for Architecture Decision Records Date:Monday, September 08, 2025 06:39 Hello, I'm seeking your copyright/permission person or team please. I'm an individual who maintains an education resource that includes one of your magazine articles, I'm seeking your guidance please on how to ask for permission to use the information and how to credit it the way your authors wish. The education resource is a summary introduction called "Architecture Decision Record" and it gathers a dozen or so architecture decision record templates into one place. The intended audience is software developers such as myself. There's no profit of any kind. The purpose is to help discussions among software developer peers. The project URL is: https://github.com/joelparkerhenderson/architecture-decision-record/ The item by your authors is: https://github.com/joelparkerhenderson/architecture-decision-record/tree/main/locales/en/templates/decision-record-template-by-jeff-tyree-and-art-akerman What are options for next steps please? Best, Joel -- (CONTACT INFO) ``` ================================================ FILE: locales/tr/templates/decision-record-template-by-jeff-tyree-and-art-akerman/index.md ================================================ # Jeff Tyree ve Art Akerman tarafından karar kaydı şablonu Bu, ["Architecture Decisions: Demystifying Architecture" (Jeff Tyree ve Art Akerman, Capital One Financial)](https://www.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf) makalesinde yayınlanan mimari karar açıklama şablonudur. * **Sorun**: Ele aldığınız mimari tasarım sorununu açıklayın, bu sorunu neden şimdi ele aldığınız konusunda hiçbir soru bırakmayın. Minimalist bir yaklaşım izleyerek, yalnızca yaşam döngüsünün çeşitli noktalarında ele alınması gereken sorunları belgeleyin. * **Karar**: Mimarinin yönünü açıkça belirtin—yani seçtiğiniz pozisyonu. * **Durum**: Kararın durumu, beklemede, karara bağlandı veya onaylandı gibi. * **Grup**: Karar setini düzenlemeye yardımcı olmak için entegrasyon, sunum, veri vb. gibi basit bir gruplama kullanabilirsiniz. Ayrıca, olay, takvim ve konum gibi daha soyut kategoriler içeren John Kyaruzi ve Jan van Katwijk'inkiler gibi daha sofistike bir mimari ontoloji de kullanabilirsiniz. Örneğin, bu ontolojiyi kullanarak, sistemin bilgi gerektirdiği olaylarla ilgili kararları olay altında gruplandırırsınız. * **Varsayımlar**: Kararı aldığınız ortamdaki temel varsayımları açıkça tanımlayın—maliyet, program, teknoloji vb. Çevresel kısıtlamaların (kabul edilmiş teknoloji standartları, kurumsal mimari, yaygın olarak kullanılan kalıplar vb. gibi) değerlendirdiğiniz alternatifleri sınırlayabileceğini unutmayın. * **Kısıtlamalar**: Seçilen alternatifin (kararın) ortama getirebileceği ek kısıtlamaları yakalayın. * **Pozisyonlar**: Değerlendirdiğiniz pozisyonları (uygulanabilir seçenekler veya alternatifler) listeleyin. Bunlar genellikle uzun açıklamalar, bazen modeller ve diyagramlar bile gerektirir. Bu kapsamlı bir liste değildir. Ancak, son bir inceleme sırasında "Bunu düşündünüz mü...?" sorusunu duymak istemezsiniz; bu, güvenilirlik kaybına ve diğer mimari kararların sorgulanmasına yol açar. Bu bölüm ayrıca başkalarının fikirlerini duyduğunuzdan emin olmanıza yardımcı olur; diğer görüşleri açıkça belirtmek, savunucularını kararınıza dahil etmenize yardımcı olur. * **Argüman**: Uygulama maliyeti, toplam sahip olma maliyeti, pazara çıkış süresi ve gerekli geliştirme kaynaklarının kullanılabilirliği gibi öğeler dahil olmak üzere neden bir pozisyon seçtiğinizi özetleyin. Bu muhtemelen kararın kendisi kadar önemlidir. * **Etkiler**: REMAP metamodelinin gösterdiği gibi, bir karar birçok etkiyle birlikte gelir. Örneğin, bir karar başka kararlar alma ihtiyacı doğurabilir, yeni gereksinimler oluşturabilir veya mevcut gereksinimleri değiştirebilir; ortama ek kısıtlamalar koyabilir; müşterilerle kapsam veya program yeniden müzakere etmeyi gerektirebilir; veya ek personel eğitimi gerektirebilir. Kararınızın etkilerini açıkça anlamak ve belirtmek, destek kazanmada ve mimari uygulama için bir yol haritası oluşturmada çok etkili olabilir. * **İlgili kararlar**: Birçok kararın birbiriyle ilişkili olduğu açıktır; bunları burada listeleyebilirsiniz. Ancak, pratikte bir izlenebilirlik matrisi, karar ağaçları veya metamodellerin daha yararlı olduğunu bulduk. Metamodeller, karmaşık ilişkileri diyagramatik olarak göstermek için yararlıdır (Rose modelleri gibi). * **İlgili gereksinimler**: Kararlar iş odaklı olmalıdır. Hesap verebilirliği göstermek için, kararlarınızı açıkça hedefler veya gereksinimlerle eşleştirin. Bu ilgili gereksinimleri burada listeleyebilirsiniz, ancak bir izlenebilirlik matrisine başvurmanın daha uygun olduğunu bulduk. Her mimari kararın her gereksinimi karşılamaya katkısını değerlendirebilir ve ardından gerekliliğin tüm kararlar arasında ne kadar iyi karşılandığını değerlendirebilirsiniz. Bir karar bir gereksinimi karşılamaya katkıda bulunmuyorsa, o kararı almayın. * **İlgili eserler**: Bu kararın etkilediği ilgili mimari, tasarım veya kapsam belgelerini listeleyin. * **İlgili ilkeler**: Kuruluşun üzerinde anlaşılmış bir ilke seti varsa, kararın bunlardan bir veya daha fazlasıyla tutarlı olduğundan emin olun. Bu, etki alanları veya sistemler arasında uyum sağlamaya yardımcı olur. * **Notlar**: Karar verme süreci haftalar sürebileceğinden, sosyalleştirme sürecinde ekibin tartıştığı notları ve sorunları yakalamayı yararlı bulduk. ================================================ FILE: locales/tr/templates/decision-record-template-by-michael-nygard/.locale-peer-id ================================================ b1e90e6556c1c8f1e2eb3ac22c8c5077 ================================================ FILE: locales/tr/templates/decision-record-template-by-michael-nygard/LICENSE.md ================================================ # LICENSE This content comes from this URL: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions The content site says this: [CC0](https://creativecommons.org/publicdomain/zero/1.0/). To the extent possible under law, Cognitect, a Nu Holdings, Ltd. company. has waived all copyright and related or neighboring rights to "Documenting Architecture Decisions". This work is published from: United States. ================================================ FILE: locales/tr/templates/decision-record-template-by-michael-nygard/index.md ================================================ # Michael Nygard tarafından karar kaydı şablonu Bu, [Documenting architecture decisions - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) makalesindeki şablondur. ADR dosyalarını yönetmek için [adr-tools](https://github.com/npryce/adr-tools) kullanabilirsiniz. Her ADR dosyasında şu bölümleri yazın: # Başlık ## Durum Durum nedir, örneğin önerilen, kabul edildi, reddedildi, kullanımdan kaldırıldı, yerini aldı vb.? ## Bağlam Bu kararı veya değişikliği motive eden gördüğümüz sorun nedir? ## Karar Önerdiğimiz ve/veya yaptığımız değişiklik nedir? ## Sonuçlar Bu değişiklik nedeniyle ne daha kolay veya daha zor hale gelir? ================================================ FILE: locales/tr/templates/decision-record-template-for-alexandrian-pattern/.locale-peer-id ================================================ f33e4eb0409f956de201b791749dc9aa ================================================ FILE: locales/tr/templates/decision-record-template-for-alexandrian-pattern/index.md ================================================ # Aleksandriyen desen için karar kaydı şablonu ## Giriş * Önsöz (Özet) * Tartışma (Bağlam) * Çözüm (Karar) * Sonuçlar (Sonuçlar) ## Ayrıntılar ## * Önsöz (Özet) * Özetlemek için ifade: * (kullanım durumu) bağlamında
(endişe) ile karşı karşıya kalarak
(seçenek) için karar verdik
(kalite) elde etmek için
(dezavantaj) kabul ederek. * Tartışma (Bağlam) * Oyundaki güçleri (teknik, politik, sosyal, proje) açıklar. * Bu, çözmeye çalıştığımız sorunu anlatan hikayedir. * Çözüm * Kararın sorunu nasıl çözeceğini açıklar. * Sonuçlar * Kararın uzun vadeli sonuçlarını açıklar. * İşe yaradı mı, yaramadı mı, değiştirildi mi, yükseltildi mi, vb. ================================================ FILE: locales/tr/templates/decision-record-template-for-business-case/.locale-peer-id ================================================ f6d1fb662640a00f4c66c586233dead9 ================================================ FILE: locales/tr/templates/decision-record-template-for-business-case/index.md ================================================ # İş durumu için karar kaydı şablonu Bu ADR şablonu, kriterler, adaylar ve maliyetler dahil olmak üzere bir karar için iş durumu oluşturmayı vurgular. ## Üst düzey * Başlık * Durum * Değerlendirme kriterleri * Değerlendirilecek adaylar * Her adayın araştırması ve analizi * Kriterleri karşılar/karşılamaz ve neden * Maliyet analizi * SWOT analizi * Görüşler ve geri bildirimler * Öneri ## Alt düzey derinlemesine inceleme **Başlık**: * Kısa, şimdiki zaman emir kipi ifade, 50 karakterden az, git commit mesajı gibi. **Durum**: * Önerilen, kabul edildi, reddedildi, kullanımdan kaldırıldı, yerini aldı vb. durumlarından biri. **Değerlendirme kriterleri**: * Özet: neyi keşfetmeye çalıştığımızı ve nedenini kısaca açıklayın. * Ayrıntılar **Değerlendirilecek adaylar**: * Özet: adayları nasıl keşfettiğimizi kısaca açıklayın ve herhangi bir aykırı değere dikkat çekin. * Tüm adayları ve ilgili seçenekleri listeleyin; potansiyel çözümler olarak neyi değerlendiriyoruz? * Ayrıntılar **Her adayın araştırması ve analizi**: * Özet: araştırma yöntemlerini kısaca açıklayın ve kalıplara, kümelere ve aykırı değerlere dikkat çekin. * Kriterleri karşılar/karşılamaz ve neden * Özet * Ayrıntılar * Maliyet analizi * Özet * Örnekler * Lisanslama, sözleşme anlaşmaları ve yasal taahhütler gibi * Eğitim, beceri geliştirme ve değişiklik yönetimi gibi * İşletim, destek ve bakım gibi * Ölçüm, bant genişliği ve CPU kullanımı gibi * SWOT analizi * Özet * Güçlü yönler * Zayıf yönler * Fırsatlar * Tehditler * İç görüşler ve geri bildirimler * Özet * Örnekler * Ekip tarafından, ideal olarak gerçek kişi tarafından yazılmış * Diğer paydaşlardan * Kalite nitelikleri diğer adıyla çapraz fonksiyonel gereksinimler * Dış görüşler ve geri bildirimler * Özet * Görüşü kim sağlıyor? * Değerlendirdiğiniz diğer adaylar neler? * Ne oluşturuyorsunuz? * Örnekler * B2B veya B2C * dışa dönük veya yalnızca çalışan * masaüstü veya mobil * pilot veya üretim * monolit veya mikroservisler * Adayları nasıl değerlendirdiniz? * Kazananı neden seçtiniz? * O zamandan beri ne oluyor? * Örnekler * Kazanan nasıl performans gösteriyor? * Gerçek dünya üretim kullanıcı trafiğinin yüzde kaçı kazanan üzerinden akıyor? * Sürekli teslim boru hatları, içerik yönetim sistemleri, analitik ve metrikler vb. gibi ne tür entegrasyonlar söz konusu? * Şimdi bildiklerinizi bilerek, insanlara farklı ne yapmalarını tavsiye ederdiniz? * Anekdotlar **Öneri**: * Özet * Ayrıntılar ================================================ FILE: locales/tr/templates/decision-record-template-of-the-madr-project/.locale-peer-id ================================================ 0a9f88e5cda952db0a82d071f585d090 ================================================ FILE: locales/tr/templates/decision-record-template-of-the-madr-project/LICENSE.md ================================================ # LICENSE Source: https://github.com/adr/madr/ License: https://github.com/adr/madr/blob/develop/LICENSE Code: MIT OR CC0-1.0 ================================================ FILE: locales/tr/templates/decision-record-template-of-the-madr-project/index.md ================================================ # [çözülen sorunun ve çözümün kısa başlığı] * Durum: [önerilen | reddedildi | kabul edildi | kullanımdan kaldırıldı | … | [ADR-0005](0005-example.md) tarafından yerini aldı] * Karar vericiler: [karara dahil olan herkesi listeleyin] * Tarih: [kararın son güncellendiği tarih YYYY-AA-GG] Teknik Hikaye: [açıklama | bilet/sorun URL'si] ## Bağlam ve Problem Tanımı [Bağlamı ve problem tanımını açıklayın, örn. iki üç cümle kullanarak serbest biçimde. Sorunu bir soru şeklinde ifade etmek isteyebilirsiniz.] ## Karar Etkenleri * [etken 1, örn. bir güç, karşılaşılan endişe, …] * [etken 2, örn. bir güç, karşılaşılan endişe, …] * … ## Değerlendirilen Seçenekler * [seçenek 1] * [seçenek 2] * [seçenek 3] * … ## Karar Sonucu Seçilen seçenek: "[seçenek 1]", çünkü [gerekçe. örn. k.o. kriteri karar etkenini karşılayan tek seçenek | güç güçünü çözen | … | en iyi sonucu veren (aşağıya bakın)]. ### Olumlu Sonuçlar * [örn. kalite niteliği memnuniyetinin iyileştirilmesi, takip kararları gerekli, …] * … ### Olumsuz Sonuçlar * [örn. kalite niteliğinden ödün verme, takip kararları gerekli, …] * … ## Seçeneklerin Artıları ve Eksileri ### [seçenek 1] [örnek | açıklama | daha fazla bilgi için işaretçi | …] * İyi, çünkü [argüman a] * İyi, çünkü [argüman b] * Kötü, çünkü [argüman c] * … ### [seçenek 2] [örnek | açıklama | daha fazla bilgi için işaretçi | …] * İyi, çünkü [argüman a] * İyi, çünkü [argüman b] * Kötü, çünkü [argüman c] * … ### [seçenek 3] [örnek | açıklama | daha fazla bilgi için işaretçi | …] * İyi, çünkü [argüman a] * İyi, çünkü [argüman b] * Kötü, çünkü [argüman c] * … ## Bağlantılar * [Bağlantı türü] [ADR'ye bağlantı] * … ================================================ FILE: locales/tr/templates/decision-record-template-using-planguage/.locale-peer-id ================================================ bb37e19df57d398b0704d6bd30ee6e6d ================================================ FILE: locales/tr/templates/decision-record-template-using-planguage/index.md ================================================ # Planguage kullanan karar kaydı şablonu Bkz. https://www.iaria.org/conferences2012/filesICCGI12/Tutorial%20Specifying%20Effective%20Non-func.pdf ## Planguage nedir? Planguage, şu anahtar kelimeleri kullanan bir planlama dilidir: * Etiket: Benzersiz, kalıcı bir tanımlayıcı * Özet: Gereksinim veya ele alınan alanın kısa bir özeti * Gereksinim: Gereksinimin kendisini ayrıntılandıran metin * Gerekçe: Gereksinimi haklı kılan akıl yürütme * Öncelik: Bir öncelik beyanı ve kaynak talebi * Paydaşlar: Gereksinimden maddi olarak etkilenen taraflar * Durum: Gereksinimin durumu (taslak, incelendi, taahhüt edildi, vb.) * Sahip: Gereksinimin uygulanmasından sorumlu kişi * Yazar: Gereksinimi yazan kişi * Revizyon: Beyan için bir sürüm numarası * Tarih: En son revizyonun tarihi * Varsayımlar: Şimdi veya daha sonra doğru değilse sorunlara neden olabilecek herhangi bir şey * Riskler: Arıza, gecikme veya diğer olumsuz etkilere neden olabilecek herhangi bir şey * Tanımlı: Bir terimin tanımı (bir sözlük kullanmak daha iyidir) ================================================ FILE: locales/tr/templates/index.md ================================================ # Karar kaydı şablonları * [Jeff Tyree ve Art Akerman tarafından karar kaydı şablonu](decision-record-template-by-jeff-tyree-and-art-akerman) * [Michael Nygard tarafından karar kaydı şablonu](decision-record-template-by-michael-nygard) * [EdgeX tarafından karar kaydı şablonu](decision-record-template-by-edgex) * [arc42 tarafından karar kaydı şablonu](decision-record-template-by-arc42) * [Aleksandriyen desen için karar kaydı şablonu](decision-record-template-for-alexandrian-pattern) * [İş durumu için karar kaydı şablonu](decision-record-template-for-business-case) * [MADR Projesi karar kaydı şablonu](decision-record-template-of-the-madr-project) * [Planguage kullanan karar kaydı şablonu](decision-record-template-using-planguage) * [Gareth Morgan tarafından karar kaydı şablonu](decision-record-template-by-gareth-morgan) * [GIG Cymru NHS Wales tarafından karar kaydı şablonu](decision-record-template-by-gig-cymru-nhs-wales)