5 ms·

Architecture retrospectives sound like a good idea but don't seem to be "the key" because in practice they fail too often. Retrospectives look backwards, and m

by jph 2y ago

Architecture retrospectives sound like a good idea but don't seem to be "the key" because in practice they fail too often. Retrospectives look backwards, and most teams aren't wired that way. And unlike sprint retrospectives, architecture retrospectives turn up issues that are unrealistic/impossible to adjust in real time. Instead, try lightweight architectural decision records, during the selection process, at the start, when things are easiest to change, and can be the most flexible. When teams try ADRs in practice, teamwork goes up, choices get better, and implementations get more realistic. And if someone later on wants to do a retrospective, then the key predictive information is right there in the ADR. https://github.com/joelparkerhenderson/architecture-decision-record/ https://github.com/joelparkerhenderson/architecture-decision...

101011 2y ago
thank you for sharing this! I'd seen formats similar to this but I'd never seen what the format itself is called. very helpful to see it clearly described - I think I'll try to give this a go with our teams
westurner 2y ago
Is there already a good way to link an ADR Architectural Decision Record with Threat Modeling primitives and considerations? "Because component_a doesn't support OAuth", "Because component_b doesn't supported signed cookies" Threat Model: https://en.wikipedia.org/wiki/Threat_model https://en.wikipedia.org/wiki/Threat_model GH topic: threat-modeling: https://github.com/topics/threat-modeling https://github.com/topics/threat-modeling Real and hypothetical architectural security issues can be linked to CWE Common Weakness Enumeration URLs. SBOM tools help to inventory components and versions in an existing architecture and to JOIN with vuln databases that publish in OSV OpenSSF Vulnerability Format, which is useful for CloudFuzz, too.
- jph 2y ago
  Good question. Yes there are a variety of ways that help. 1. If the team favors lightweight markdown, then add a markdown section for Threat Modeling and markdown links to references. Some teams favor doing this for more kinds of analysis, such as business analysis (e.g. SWOT) and environment analysis (e.g. PESTLE) and risk analysis (e.g. RAID). 2. If the team favors metrics systems, then consider trying a Jupyter notebook. I haven't personally tried this. Teams anecdotally tell me these can be excellent for showing probable effects. 3. If the team is required to use existing tooling such as tracking systems, such as for auditing and compliance, then consider writing the ADR within the tracking system and linking to it internally.
  - westurner 2y ago
    > 1. Add clickable URL links to the reference material for whichever types of analyses. > 2. Jupyter Notebooks often omit test assertions that would be expected of a Python module with an associated tests/ directory. With e.g. ipytest, you can run specific unit tests in notebook input cells (instead of testing the whole notebook). There are various ways to template and/or parametrize notebooks; copy the template.ipynb and include the date/time in the filename__2024-01-01.ipynb, copy a template git repo and modify, jupyterlab_templates, papermill > 3. [...] consider writing the ADR within the tracking system and linking to it internally +1. A "meta issue" or an epic includes multiple other issues. If you reference an issue as a list item in GFM GitHub-Flavored Markdown, GitHub will auto-embed the current issue title and closed/open status: - https://github.com/python/cpython/issues/1 - python/cpython#1 This without the leading `- ` doesn't get the card embed though: https://github.com/python/cpython/issues/1 Whereas this form with hand-copied issue titles, non-obfuscated URLs you don't need to hover over to read, and - [ ] markdown checkboxes works with all issue trackers: - [ ] "Issue title" https://github.com/python/cpython/issues/1 - [x] "Issue title" https://github.com/python/cpython/issues/2
wodenokoto 2y ago
> Architectural Retrospectives differ from Architectural Reviews by focusing not on evaluating and improving the architecture itself, but on examining and improving how the team went about creating the architecture. I don't think the purpose on a retrospective on product A is to improve product A, but to improve how product B gets built.

by jph 2y ago

101011 2y ago

thank you for sharing this! I'd seen formats similar to this but I'd never seen what the format itself is called. very helpful to see it clearly described - I think I'll try to give this a go with our teams

westurner 2y ago

Is there already a good way to link an ADR Architectural Decision Record with Threat Modeling primitives and considerations? "Because component_a doesn't support OAuth", "Because component_b doesn't supported signed cookies" Threat Model: https://en.wikipedia.org/wiki/Threat_model https://en.wikipedia.org/wiki/Threat_model GH topic: threat-modeling: https://github.com/topics/threat-modeling https://github.com/topics/threat-modeling Real and hypothetical architectural security issues can be linked to CWE Common Weakness Enumeration URLs. SBOM tools help to inventory components and versions in an existing architecture and to JOIN with vuln databases that publish in OSV OpenSSF Vulnerability Format, which is useful for CloudFuzz, too.

jph 2y ago
Good question. Yes there are a variety of ways that help. 1. If the team favors lightweight markdown, then add a markdown section for Threat Modeling and markdown links to references. Some teams favor doing this for more kinds of analysis, such as business analysis (e.g. SWOT) and environment analysis (e.g. PESTLE) and risk analysis (e.g. RAID). 2. If the team favors metrics systems, then consider trying a Jupyter notebook. I haven't personally tried this. Teams anecdotally tell me these can be excellent for showing probable effects. 3. If the team is required to use existing tooling such as tracking systems, such as for auditing and compliance, then consider writing the ADR within the tracking system and linking to it internally.
- westurner 2y ago
  > 1. Add clickable URL links to the reference material for whichever types of analyses. > 2. Jupyter Notebooks often omit test assertions that would be expected of a Python module with an associated tests/ directory. With e.g. ipytest, you can run specific unit tests in notebook input cells (instead of testing the whole notebook). There are various ways to template and/or parametrize notebooks; copy the template.ipynb and include the date/time in the filename__2024-01-01.ipynb, copy a template git repo and modify, jupyterlab_templates, papermill > 3. [...] consider writing the ADR within the tracking system and linking to it internally +1. A "meta issue" or an epic includes multiple other issues. If you reference an issue as a list item in GFM GitHub-Flavored Markdown, GitHub will auto-embed the current issue title and closed/open status: - https://github.com/python/cpython/issues/1 - python/cpython#1 This without the leading `- ` doesn't get the card embed though: https://github.com/python/cpython/issues/1 Whereas this form with hand-copied issue titles, non-obfuscated URLs you don't need to hover over to read, and - [ ] markdown checkboxes works with all issue trackers: - [ ] "Issue title" https://github.com/python/cpython/issues/1 - [x] "Issue title" https://github.com/python/cpython/issues/2

wodenokoto 2y ago

> Architectural Retrospectives differ from Architectural Reviews by focusing not on evaluating and improving the architecture itself, but on examining and improving how the team went about creating the architecture. I don't think the purpose on a retrospective on product A is to improve product A, but to improve how product B gets built.