2 ms·

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 markd

by 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

by jph 2y ago

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