You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: any-decision-record-template.md
+25-10Lines changed: 25 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,16 @@
1
-
# Decision Title - ADR-XXX: ADR (Any Decision Record) Template
1
+
# ADR-XXX: ADR (Any Decision Record) Template
2
2
3
-
-[Decision Title - ADR-XXX: ADR (Any Decision Record) Template](#decision-title---adr-xxx-adr-any-decision-record-template)
3
+
>|||
4
+
>| ------------ | --- |
5
+
>| Date |`dd/mm/YYYY`_when the decision was last updated_|
6
+
>| Status |`RFC by dd/mm/YYYY, Proposed, In Discussion, Pending Approval, Withdrawn, Rejected, Accepted, Deprecated, ..., Superseded by ADR-XXX or Supersedes ADR-XXX`|
7
+
>| Deciders |`Tech Radar, Engineering, Architecture, Solution Assurance, Clinical Assurance, Technical Review and Governance, Information Governance, Cyber Security, Live Services Board,` ... |
-`Deciders`: List all the key decision makers and state whether it is an internal decision or it requires additional endorsement or approval of an external group or governing body like `Tech Radar | Engineering | Architecture | Solution Assurance | Clinical Assurance | Technical Review and Governance | Information Governance | Cyber Security | Live Services Board` or any other
Describe the context and the problem statement. Is there a relationship to other decisions previously made? Are there any dependencies and/or constraints within which the decision will be made? Do these need to be reviewed or validated? Please, note that environmental limitations or restrictions such as accepted technology standards, commonly recognised and used patterns, engineering and architecture principles, organisation policies, governance and so on, may as an effect narrow down the choices. This should also be explicitly documented, as this is a point-in-time decision with the intention of being able to articulate it clearly and justify it later.
@@ -34,20 +40,24 @@ List the decision drivers that motivate this change or course of action. This ma
34
40
35
41
### Options
36
42
37
-
Consider a comprehensive set of alternative options.
43
+
Consider a comprehensive set of alternative options; provide weighting if applicable.
38
44
39
45
### Outcome
40
46
41
-
State the decision outcome as a result of taking into account all of the above.
47
+
State the decision outcome as a result of taking into account all of the above. Is it a reversible or irreversible decision?
42
48
43
49
### Rationale
44
50
45
51
Provide a rationale for the decision that is based on weighing the options to ensure that the same questions are not going to be asked again and again unless the decision needs to be superseded.
46
52
53
+
For non-trivial decisions a comparison table can be useful for the reviewer. Decision criteria down one side, options across the top. You'll likely find decision criteria come from the Drivers section above. Effort can be an important driving factor. You may have an intuitive feel for this, but reviewers will not. T-shirt sizing the effort for each option may help communicate.
54
+
47
55
## Consequences
48
56
49
57
Describe the resulting context, after applying the decision. All the identified consequences should be listed here, not just the positive ones. Any decision comes with many implications. For example, it may introduce a need to make other decisions as an effect of cross-cutting concerns; it may impact structural or operational characteristics of the software, and influence non-functional requirements; as a result, some things may become easier or more difficult to do because of this change. What are the trade-offs?
50
58
59
+
What are the conditions under which this decision no longer applies or becomes irrelevant?
60
+
51
61
## Compliance
52
62
53
63
Establish how the success is going to be measured. Once implemented, the effect might lend itself to be measured, therefore if appropriate a set of criteria for success could be established. Compliance checks of the decision can be manual or automated using a fitness function. If it is the latter this section can then specify how that fitness function would be implemented and whether there are any other changes to the codebase needed to measure this decision for compliance.
@@ -58,6 +68,11 @@ Include any links to existing epics, decisions, dependencies, risks, and policie
58
68
59
69
It is important that if the decision is sub-optimal or the choice is tactical or misaligned with the strategic directions the risk related to it is identified and clearly articulated. As a result of that, the expectation is that a [Tech Debt](./tech-debt.md) record is going to be created on the backlog.
60
70
71
+
## Actions
72
+
73
+
-[x] name, date by, action
74
+
-[ ] name, date by, action
75
+
61
76
## Tags
62
77
63
-
`#availability|#security|#resilience|#scalability|#maintainability|#accessibility|…` these tags are intended to be operational, structural or cross-cutting architecture characteristics to link to related decisions.
78
+
`#availability|#scalability|#elasticity|#performance|#reliability|#resilience|#maintainability|#testability|#deployability|#modularity|#simplicity|#security|#data|#cost|#usability|#accessibility|…` these tags are intended to be operational, structural or cross-cutting architecture characteristics to link to related decisions.
Copy file name to clipboardExpand all lines: patterns/everything-as-code.md
+24-16Lines changed: 24 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,25 +36,33 @@ Many teams consider code which has been written [as a pair](https://martinfowler
36
36
Robert Fink provides an excellent description of the [motivation and practice of code reviews](https://medium.com/palantir/code-review-best-practices-19e02780015f). Some key points from this and other sources ([Google](https://google.github.io/eng-practices/review/reviewer/), [SmartBear](https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/), [Atlassian](https://www.atlassian.com/agile/software-development/code-reviews)) are:
37
37
38
38
#### Egalitarian
39
-
* With the right (basic) training, anyone in the team can review anyone else's code with no hierarchy.
40
-
* Everyone's code must be reviewed, no matter how experienced they are.
39
+
40
+
* With the right (basic) training, anyone in the team can review anyone else's code with no hierarchy.
41
+
* Everyone's code must be reviewed, no matter how experienced they are.
42
+
41
43
#### Small
42
-
* Code reviews should be relatively small as it is hard to review very large changes effectively.
43
-
* This is one reason to break stories down as small as practical and to implement each incrementally, ensuring no single change is too large to be reviewed well.
44
+
45
+
* Code reviews should be relatively small as it is hard to review very large changes effectively.
46
+
* This is one reason to break stories down as small as practical and to implement each incrementally, ensuring no single change is too large to be reviewed well.
47
+
44
48
#### Meets user needs
49
+
45
50
While effective testing is the best way to detect bugs or non-functional problems, code review plays an important role in spotting _potential_ issues:
46
-
* Does the code look like it will meet the acceptance criteria, or are there obvious errors or omissions?
47
-
* Does it handle edge cases?
51
+
52
+
* Does the code look like it will meet the acceptance criteria, or are there obvious errors or omissions?
53
+
* Does it handle edge cases?
54
+
48
55
#### Of high quality
49
-
* Is the code clear and simple?
50
-
* Is the code layout and structure consistent with agreed style and other code? (please see [enforce code formatting](enforce-code-formatting.md))
51
-
* Would it easily allow future modification to meet slightly different needs, e.g. ten times the required data size or throughput?
52
-
* Have the non-functional requirements been considered (performance, scalability, robustness, etc)?
53
-
* Are common security issues guarded against (e.g. [OWASP Top 10](https://owasp.org/www-project-top-ten/))? Including:
54
-
* Is any new input data being treated as potentially hostile?
55
-
* Is any data potentially leaking from the system by mistake, for example sensitive data recorded in log files?
56
-
* Are there secrets in the code?
57
-
* For further reading, please see the [OWASP Code Review Guide](https://owasp.org/www-pdf-archive/OWASP_Code_Review_Guide_v2.pdf)
56
+
57
+
* Is the code clear and simple?
58
+
* Is the code layout and structure consistent with agreed style and other code? (please see [enforce code formatting](enforce-code-formatting.md))
59
+
* Would it easily allow future modification to meet slightly different needs, e.g. ten times the required data size or throughput?
60
+
* Have the non-functional requirements been considered (performance, scalability, robustness, etc)?
61
+
* Are common security issues guarded against (e.g. [OWASP Top 10](https://owasp.org/www-project-top-ten/))? Including:
62
+
* Is any new input data being treated as potentially hostile?
63
+
* Is any data potentially leaking from the system by mistake, for example sensitive data recorded in log files?
64
+
* Are there secrets in the code?
65
+
* For further reading, please see the [OWASP Code Review Guide](https://owasp.org/www-pdf-archive/OWASP_Code_Review_Guide_v2.pdf)
58
66
59
67
Note: automated scans and tests can help to identity a lot of these quality issues (please see [Quality Checks](../quality-checks.md)) but no automated scan is perfect, so both code reviews and automated checks are essential.
60
68
@@ -67,4 +75,4 @@ Note: automated scans and tests can help to identity a lot of these quality issu
67
75
68
76
## Further reading
69
77
70
-
*[Clean Code: A Handbook of Agile Software Craftsmanship](https://learning.oreilly.com/library/view/clean-code-a/9780136083238/)
78
+
*[Clean Code: A Handbook of Agile Software Craftsmanship](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
0 commit comments