diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 571b6b8..40ca9d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to adr.github.io -To improve this page, head to , edit `index.md` or `_tabs/*.md`, and submit a pull request. +To improve this page, head to , edit `_posts/*.md`, and submit a pull request. See [Chirpy's Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/) post for information on possible styling. The [source](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/_posts/2019-08-08-text-and-typography.md?plain=1) shows the respective Markdown source. diff --git a/_config.yml b/_config.yml index b9e8c42..2a38266 100644 --- a/_config.yml +++ b/_config.yml @@ -150,7 +150,7 @@ pwa: deny_paths: # - "/example" # URLs match `/example/*` will not be cached by the PWA -# paginate: 10 +paginate: 10 # The base URL of your site baseurl: "" @@ -171,7 +171,7 @@ kramdown: collections: tabs: - output: true + output: false sort_by: order defaults: @@ -184,7 +184,7 @@ defaults: toc: true # Display TOC column in posts. # DO NOT modify the following parameter unless you are confident enough # to update the code of all other post links in this project. - permalink: /posts/:title/ + permalink: :title/ - scope: path: _drafts values: diff --git a/_data/share.yml b/_data/share.yml index 6f97568..b2ff94a 100644 --- a/_data/share.yml +++ b/_data/share.yml @@ -2,48 +2,36 @@ # Icons from platforms: - - type: Twitter - icon: "fa-brands fa-square-x-twitter" - link: "https://twitter.com/intent/tweet?text=TITLE&url=URL" - - - type: Facebook - icon: "fab fa-facebook-square" - link: "https://www.facebook.com/sharer/sharer.php?title=TITLE&u=URL" - - - type: Telegram - icon: "fab fa-telegram" - link: "https://t.me/share/url?url=URL&text=TITLE" - # Uncomment below if you need to. # - # - type: Linkedin - # icon: "fab fa-linkedin" - # link: "https://www.linkedin.com/sharing/share-offsite/?url=URL" + - type: Linkedin + icon: "fab fa-linkedin" + link: "https://www.linkedin.com/sharing/share-offsite/?url=URL" # # - type: Weibo # icon: "fab fa-weibo" # link: "https://service.weibo.com/share/share.php?title=TITLE&url=URL" # - # - type: Mastodon - # icon: "fa-brands fa-mastodon" - # # See: https://github.com/justinribeiro/share-to-mastodon#properties - # instances: - # - label: mastodon.social - # link: "https://mastodon.social/" - # - label: mastodon.online - # link: "https://mastodon.online/" - # - label: fosstodon.org - # link: "https://fosstodon.org/" + - type: Mastodon + icon: "fa-brands fa-mastodon" + # # See: https://github.com/justinribeiro/share-to-mastodon#properties + instances: + # - label: mastodon.social + # link: "https://mastodon.social/" + # - label: mastodon.online + # link: "https://mastodon.online/" + - label: fosstodon.org + link: "https://fosstodon.org/" # - label: photog.social # link: "https://photog.social/" # - # - type: Bluesky - # icon: "fa-brands fa-bluesky" - # link: "https://bsky.app/intent/compose?text=TITLE%20URL" + - type: Bluesky + icon: "fa-brands fa-bluesky" + link: "https://bsky.app/intent/compose?text=TITLE%20URL" # - # - type: Reddit - # icon: "fa-brands fa-square-reddit" - # link: "https://www.reddit.com/submit?url=URL&title=TITLE" + - type: Reddit + icon: "fa-brands fa-square-reddit" + link: "https://www.reddit.com/submit?url=URL&title=TITLE" # # - type: Threads # icon: "fa-brands fa-square-threads" diff --git a/index.md b/_posts/2024-10-26-adrs.md similarity index 97% rename from index.md rename to _posts/2024-10-26-adrs.md index c052803..627926e 100644 --- a/index.md +++ b/_posts/2024-10-26-adrs.md @@ -1,10 +1,10 @@ --- -layout: default +title: Architectural Decision Records (ADRs) +pin: true mermaid: true +toc: true --- -# Architectural Decision Records (ADRs) - ## Motivation and Definitions An [Architectural Decision (AD)](https://en.wikipedia.org/wiki/Architectural_decision) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. @@ -19,8 +19,6 @@ The aim of the [GitHub adr organization](https://github.com/adr) is to: 2. Strengthen the tooling around ADRs, in support of agile practices as well as iterative and incremental engineering processes. 3. Provide pointers to public knowledge in the context of AKM and ADRs. -The repository for the Website of the ADR organization is [https://github.com/adr/adr.github.io](https://github.com/adr/adr.github.io). - ## ADRs in the Media - The [Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record) at Microsoft Ignite features ADRs and this website (10/11/2024). diff --git a/_posts/2024-10-27-ad-practices.md b/_posts/2024-10-27-ad-practices.md new file mode 100644 index 0000000..c8d8e66 --- /dev/null +++ b/_posts/2024-10-27-ad-practices.md @@ -0,0 +1,40 @@ +--- +title: AD Practices +toc: true +--- + +> The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them. +{: .prompt-info } + +[Timing Architectural Decisions](https://ozimmer.ch/assets/presos/ZIO-ITARCKeynoteTADv101p.pdf), a presentation given at the annual Swedish IT architect conference ITARC features many of the practices collected on this page. + +## AD Making + +The [Design Practice Repository](https://socadk.github.io/design-practice-repository/) on GitHub and the [Design Practice Reference](https://leanpub.com/dpr), a corresponding LeanPub e-Book, feature an AD making and capturing activity, which is positioned as one of the essential activities in DPR. + +[Decision-making ADRs: weightings are a work-around](https://jacquiread.com/posts/2024-09-11-decision-making-adrs-weightings-are-a-workaround/) is a blog post by Jacqui Read that offers some tips on how to make better architectural decisions. + +## Good ADRs --- and How to Get to Them + +### Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template: + +1. [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html), suggesting five criteria abbreviated as START. +2. [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html) +3. [How to create ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html) collects good practices and anti-patterns. +4. [The Markdown ADR (MADR) Template Explained and Distilled](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html) +5. [A Definition of Done for Architectural Decision Making](https://www.ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html) proposes five criteria and a checklist to decide when it is time to set the status of a single decision to "done": evidence, criteria and alternatives, agreement, documentation, and realization/review plan. Here, we focus on the 'D' in *ecADR*. +6. Context, background and examples of good and bad justifications can be found in [this blog post](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html). +7. [How to review ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html) has good practices, anti-patterns, review check list +8. [An Adoption Model for Architectural Decision Making and Capturing](https://ozimmer.ch/practices/2023/04/21/ADAdoptionModel.html) + +Most of the material referenced above is also available on [Medium](https://medium.com/olzzio/tagged/adr). + +### Third-party articles + +- [Documenting Architecture Decisions](https://www.fabian-keller.de/blog/documenting-architecture-decisions), blog post by Fabian Kleiser +- More will be featured in future versions of this page, suggestions are welcome! +- *to be continued* + +## From Architectural Decisions to Design/Any Decisions + +[From Architectural Decisions to Design Decisions](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and [ADR = Any Decision Record?](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) are two blog posts proposing to extend the scope of ADRs. diff --git a/_posts/2024-10-28-adr-tooling.md b/_posts/2024-10-28-adr-tooling.md new file mode 100644 index 0000000..b1f3a7c --- /dev/null +++ b/_posts/2024-10-28-adr-tooling.md @@ -0,0 +1,63 @@ +--- +title: Decision Capturing Tools +toc: true +--- + +> The following lists are rather inclusive and sorted alphabetically. +> Please find out about the status and the maturity of the list entries for yourself by following the links. +> We are happy to include more candidate assets here. +{: .prompt-info } + +## Tooling to create and maintain decision files + +### Any template + +- [dotnet-adr](https://github.com/endjin/dotnet-adr) - A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR). + +### MADR template + +| Name | MADR Version | Comment | +| ----------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| [adr-log](https://github.com/adr/adr-log?tab=readme-ov-file#adr-log-) | 2.1.2 | CLI to keep an `index.md` file updated with all ADRs | +| [ADR Manager](https://adr.github.io/adr-manager/) | 2.1.2 | Web-based UI connecting to GitHub to directly edit ADRs in a form-based way | +| [ADR Manager VS Code Extension](https://github.com/adr/vscode-adr-manager) | 2.1.2 | Visual Studio Code (VS Code) extension | +| [Backstage ADR plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) | 2.1.2 and 3.x | plugin to explore and search ADRs within a backstage based developer portal. Search at scale across mutliple orgs/repos | +| [Hugo Markdown ADR Tools](https://github.com/butonic/adr-tools) | 2.1.2. | CLI to create and update ADRs | +| [Log4brains](https://github.com/thomvaill/log4brains) | 2.1.2 without numbers in the filename | Supports both nice rendering of ADRs and creation of ADRs in a command line. | +| [pyadr](https://github.com/opinionated-digital-center/pyadr) | 2.1.2 | CLI to help with an ADR process lifecycle (proposal/acceptance/rejection/deprecation/superseding) | + +### Nygard template + +- [adr-tools](https://github.com/npryce/adr-tools) - bash scripts to manage ADRs in the [Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html). [example](https://github.com/npryce/adr-tools/blob/master/doc/adr/0002-implement-as-shell-scripts.md). + - Ansible script to install adr-tools: [ansible-adr-tools](https://github.com/escalate/ansible-adr-tools) + - C# rewrite: [adr-cli](https://github.com/GingerTommy/adr-cli) + - Go rewrite: [adr](https://github.com/marouni/adr) + - Java rewrite: [adr-j](https://github.com/adoble/adr-j) + - ESM Node.js port: [adr-tools](https://github.com/meza/adr-tools) + - Node.js rewrite: [adr](https://github.com/phodal/adr) + - PHP version: [phpadr](https://github.com/globtec/phpadr) + - Powershell module: [adr-ps](https://github.com/rdagumampan/adr-ps) + - Python rewrite: [adr-tools-python](https://pypi.org/project/adr-tools-python/) + - Another Powershell module: [ArchitectureDecisionRecords](https://github.com/ajoberstar/ArchitectureDecisionRecords) + - Rust rewrite: [adrs](https://github.com/joshrotenberg/adrs) +- [adr-viewer](https://github.com/mrwilson/adr-viewer) - python application to generate a website from a set of ADRs. +- [architectural-decision](https://github.com/cspray/architectural-decision): PHP library to create ADRs using PHP8 Attributes. +- [Loqbooq](https://loqbooq.app): Commerical Web App with Slack integration to record ADR-inspired decision logs +- [Talo](https://github.com/canpolat/talo): CLI (and dotnet tool) to manage and export ADRs, RFCs and custom software design document types. + +## Tooling close to the code + +- [(Java) Embedded Architectural Decision Records](https://github.com/adr/e-adr#embedded-architectural-decision-records), which shows how a distributed AD log can be embedded in Java Code via ADR annotations. + +## Tooling related to architecture management + +- [ArchUnit](https://github.com/TNG/ArchUnit): unit tests for architecture +- [docToolchain](https://doctoolchain.github.io/docToolchain/): docToolchain is an implementation of the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) approach for software architecture plus some additional automation. +- [Structurizr](https://www.structurizr.com/): Structurizr is a collection of tooling to help you visualise, document and explore your software architecture using the [C4 model](https://c4model.com/). + +## Interesting, but unmaintained tooling + +- [adr-log](https://github.com/adr/adr-log): Generates an architectural decision log out of MADRs. +- [ADMentor](https://github.com/IFS-HSR/ADMentor) Architectural Decision Modeling Add-In for [Sparx Enterprise Architect](https://www.sparxsystems.de/uml/neweditions/) +- [eadlsync](https://adr.github.io/eadlsync/): Synchronizes embedded architectural decision records with a repository of architectural decisions. +- [SE Repo](https://github.com/adr/serepo): Software Engineering Repository. A repository for versioning software engineering artifacts, which can be architectural decisions, patterns, and others. diff --git a/_tabs/ad-practices.md b/_tabs/ad-practices.md index 9f1341c..04cadf7 100644 --- a/_tabs/ad-practices.md +++ b/_tabs/ad-practices.md @@ -1,41 +1,5 @@ --- icon: fas fa-check-circle -order: 1 +order: 2 title: AD Practices --- - -> The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them. -{: .prompt-info } - -[Timing Architectural Decisions](https://ozimmer.ch/assets/presos/ZIO-ITARCKeynoteTADv101p.pdf), a presentation given at the annual Swedish IT architect conference ITARC features many of the practices collected on this page. - -## AD Making - -The [Design Practice Repository](https://socadk.github.io/design-practice-repository/) on GitHub and the [Design Practice Reference](https://leanpub.com/dpr), a corresponding LeanPub e-Book, feature an AD making and capturing activity, which is positioned as one of the essential activities in DPR. - -[Decision-making ADRs: weightings are a work-around](https://jacquiread.com/posts/2024-09-11-decision-making-adrs-weightings-are-a-workaround/) is a blog post by Jacqui Read that offers some tips on how to make better architectural decisions. - -## Good ADRs --- and How to Get to Them - -### Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template: - -1. [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html), suggesting five criteria abbreviated as START. -2. [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html) -3. [How to create ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html) collects good practices and anti-patterns. -4. [The Markdown ADR (MADR) Template Explained and Distilled](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html) -5. [A Definition of Done for Architectural Decision Making](https://www.ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html) proposes five criteria and a checklist to decide when it is time to set the status of a single decision to "done": evidence, criteria and alternatives, agreement, documentation, and realization/review plan. Here, we focus on the 'D' in *ecADR*. -6. Context, background and examples of good and bad justifications can be found in [this blog post](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html). -7. [How to review ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html) has good practices, anti-patterns, review check list -8. [An Adoption Model for Architectural Decision Making and Capturing](https://ozimmer.ch/practices/2023/04/21/ADAdoptionModel.html) - -Most of the material referenced above is also available on [Medium](https://medium.com/olzzio/tagged/adr). - -### Third-party articles - -- [Documenting Architecture Decisions](https://www.fabian-keller.de/blog/documenting-architecture-decisions), blog post by Fabian Kleiser -- More will be featured in future versions of this page, suggestions are welcome! -- *to be continued* - -## From Architectural Decisions to Design/Any Decisions - -[From Architectural Decisions to Design Decisions](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and [ADR = Any Decision Record?](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) are two blog posts proposing to extend the scope of ADRs. diff --git a/_tabs/adr-tooling.md b/_tabs/adr-tooling.md index 65e1e3b..5781307 100644 --- a/_tabs/adr-tooling.md +++ b/_tabs/adr-tooling.md @@ -1,64 +1,5 @@ --- icon: fas fa-briefcase -order: 4 +order: 3 title: Decision Capturing Tools --- - -> The following lists are rather inclusive and sorted alphabetically. -> Please find out about the status and the maturity of the list entries for yourself by following the links. -> We are happy to include more candidate assets here. -{: .prompt-info } - -## Tooling to create and maintain decision files - -### Any template - -- [dotnet-adr](https://github.com/endjin/dotnet-adr) - A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR). - -### MADR template - -| Name | MADR Version | Comment | -| ----------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| [adr-log](https://github.com/adr/adr-log?tab=readme-ov-file#adr-log-) | 2.1.2 | CLI to keep an `index.md` file updated with all ADRs | -| [ADR Manager](https://adr.github.io/adr-manager/) | 2.1.2 | Web-based UI connecting to GitHub to directly edit ADRs in a form-based way | -| [ADR Manager VS Code Extension](https://github.com/adr/vscode-adr-manager) | 2.1.2 | Visual Studio Code (VS Code) extension | -| [Backstage ADR plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) | 2.1.2 and 3.x | plugin to explore and search ADRs within a backstage based developer portal. Search at scale across mutliple orgs/repos | -| [Hugo Markdown ADR Tools](https://github.com/butonic/adr-tools) | 2.1.2. | CLI to create and update ADRs | -| [Log4brains](https://github.com/thomvaill/log4brains) | 2.1.2 without numbers in the filename | Supports both nice rendering of ADRs and creation of ADRs in a command line. | -| [pyadr](https://github.com/opinionated-digital-center/pyadr) | 2.1.2 | CLI to help with an ADR process lifecycle (proposal/acceptance/rejection/deprecation/superseding) | - -### Nygard template - -- [adr-tools](https://github.com/npryce/adr-tools) - bash scripts to manage ADRs in the [Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html). [example](https://github.com/npryce/adr-tools/blob/master/doc/adr/0002-implement-as-shell-scripts.md). - - Ansible script to install adr-tools: [ansible-adr-tools](https://github.com/escalate/ansible-adr-tools) - - C# rewrite: [adr-cli](https://github.com/GingerTommy/adr-cli) - - Go rewrite: [adr](https://github.com/marouni/adr) - - Java rewrite: [adr-j](https://github.com/adoble/adr-j) - - ESM Node.js port: [adr-tools](https://github.com/meza/adr-tools) - - Node.js rewrite: [adr](https://github.com/phodal/adr) - - PHP version: [phpadr](https://github.com/globtec/phpadr) - - Powershell module: [adr-ps](https://github.com/rdagumampan/adr-ps) - - Python rewrite: [adr-tools-python](https://pypi.org/project/adr-tools-python/) - - Another Powershell module: [ArchitectureDecisionRecords](https://github.com/ajoberstar/ArchitectureDecisionRecords) - - Rust rewrite: [adrs](https://github.com/joshrotenberg/adrs) -- [adr-viewer](https://github.com/mrwilson/adr-viewer) - python application to generate a website from a set of ADRs. -- [architectural-decision](https://github.com/cspray/architectural-decision): PHP library to create ADRs using PHP8 Attributes. -- [Loqbooq](https://loqbooq.app): Commerical Web App with Slack integration to record ADR-inspired decision logs -- [Talo](https://github.com/canpolat/talo): CLI (and dotnet tool) to manage and export ADRs, RFCs and custom software design document types. - -## Tooling close to the code - -- [(Java) Embedded Architectural Decision Records](https://github.com/adr/e-adr#embedded-architectural-decision-records), which shows how a distributed AD log can be embedded in Java Code via ADR annotations. - -## Tooling related to architecture management - -- [ArchUnit](https://github.com/TNG/ArchUnit): unit tests for architecture -- [docToolchain](https://doctoolchain.github.io/docToolchain/): docToolchain is an implementation of the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) approach for software architecture plus some additional automation. -- [Structurizr](https://www.structurizr.com/): Structurizr is a collection of tooling to help you visualise, document and explore your software architecture using the [C4 model](https://c4model.com/). - -## Interesting, but unmaintained tooling - -- [adr-log](https://github.com/adr/adr-log): Generates an architectural decision log out of MADRs. -- [ADMentor](https://github.com/IFS-HSR/ADMentor) Architectural Decision Modeling Add-In for [Sparx Enterprise Architect](https://www.sparxsystems.de/uml/neweditions/) -- [eadlsync](https://adr.github.io/eadlsync/): Synchronizes embedded architectural decision records with a repository of architectural decisions. -- [SE Repo](https://github.com/adr/serepo): Software Engineering Repository. A repository for versioning software engineering artifacts, which can be architectural decisions, patterns, and others. diff --git a/_tabs/adrs.md b/_tabs/adrs.md new file mode 100644 index 0000000..b8e00d9 --- /dev/null +++ b/_tabs/adrs.md @@ -0,0 +1,5 @@ +--- +icon: fas fa-info +order: 1 +title: About ADRs +--- diff --git a/index.html b/index.html new file mode 100644 index 0000000..1357b08 --- /dev/null +++ b/index.html @@ -0,0 +1,4 @@ +--- +layout: home +# Index page +---