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: docs/adr/adr_0011.md
+34-34Lines changed: 34 additions & 34 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,14 +39,14 @@ This manual action may include making changes to scan definitions, or to systems
39
39
It sees the entire _secureCodeBox_ as **one large piece of software with many components** that are all equally important to the overall compatibility, and where all components are (usually) updated in lockstep.
40
40
As illustration, here are a few examples and what kind of release they would require:
| A scanner changes how it is parameterized | Major |
45
+
| A scanner removes data from its output or makes other changes affecting the findings| Major |
46
+
| The SCB makes changes to the findings format of one scanner (e.g., renaming a key) | Major |
47
+
| The SCB makes breaking changes to the CRDs (renaming or removing fields) | Major |
48
+
| The SCB makes backwards-compatible changes to the CRDs (adding new fields) | Minor |
49
+
| The SCB fixes a small bug in the operator or a scanner | Patch |
50
50
51
51
#### Advantages
52
52
1.**MAJOR versions indicate that manual action may be required to keep existing workflows running** and that the users should read the changelog. However, it may turn out that the breaking change does not apply to the users' environment (e.g., because they are not using a specific scanner), in which case no manual action may be required.
@@ -68,14 +68,14 @@ This approach sees the _secureCodeBox_ as **a platform with independent componen
68
68
The MAJOR version number indicates compatibility between the operator and scanners, while MINOR version changes can still be breaking to some users (in which case this will be denoted prominently at the top of the release notes).
69
69
As illustration, here are a few examples and what kind of release they would require:
| A scanner changes how it is parameterized | Minor |
74
+
| A scanner removes data from its output or makes other changes affecting the findings| Minor |
75
+
| The SCB makes changes to the findings format of one scanner (e.g., renaming a key) | Minor |
76
+
| The SCB makes breaking changes to the CRDs (renaming or removing fields) | Major |
77
+
| The SCB makes backwards-compatible changes to the CRDs (adding new fields) | Minor |
78
+
| The SCB fixes a small bug in the operator or a scanner | Patch |
79
79
80
80
#### Advantages
81
81
1.**MAJOR versions indicate that a joint upgrade of operator and scanners is required,** which is highly relevant in environments where operator and scanners are maintained by different teams (we know that these environments exist, and want to support them). This obviates the need for a detailed compatibility matrix between scanner and operator versions.
@@ -89,13 +89,13 @@ As illustration, here are a few examples and what kind of release they would req
89
89
A different variant of the previous option would be to prefix the version number with an ARCHITECTURE (ARCH) number, so the final versioning would be ARCH.MAJOR.MINOR.PATCH. In that case, the table would look like this:
| A scanner changes how it is parameterized | Major |
94
+
| A scanner removes data from its output or makes other changes affecting the findings| Major |
95
+
| The SCB makes changes to the findings format of one scanner (e.g., renaming a key) | Major |
96
+
| The SCB makes breaking changes to the CRDs (renaming or removing fields) | Arch |
97
+
| The SCB makes backwards-compatible changes to the CRDs (adding new fields) | Minor |
98
+
| The SCB fixes a small bug in the operator or a scanner | Patch |
99
99
100
100
This could be considered "playing tricks" (by just adding a digit and relabeling the meaning of the positions) and would deviate from semver, but would allow us to use the ARCH number to denote operator compatibility, while the MAJOR version denotes scanner compatibility, the MINOR indicates feature additions, and the PATCH indicates bugfixes.
101
101
@@ -114,8 +114,8 @@ We will thus not consider this proposal in greater detail here.
114
114
115
115
### Option 5: SemVer With Major Version Indicating Operator Compatibility + Included Version of "Embedded Dependency"
116
116
117
-
(Based on Suggestion by @EndPositive: https://github.com/secureCodeBox/secureCodeBox/pull/936#issuecomment-1016480293)
118
-
This option expands on option 2, but adds an additional the version of embedded dependencies (primarily of scanner) in the build metadata section of the semver version (See: https://semver.org/#spec-item-10).
117
+
(Based on [Suggestion by @EndPositive](https://github.com/secureCodeBox/secureCodeBox/pull/936#issuecomment-1016480293))
118
+
This option expands on option 2, but adds an additional version of embedded dependencies (primarily of scanner) in the [build metadata section of the semver version](https://semver.org/#spec-item-10).
119
119
120
120
**Example Version Numbers:**
121
121
@@ -131,15 +131,15 @@ Currently undecided:
131
131
- e.g. embedded version / version range of supported DefectDojo version in build meta
132
132
- might not be necessary / possible for every hook. And thus make the hook versioning schema inconsistent
| A scanner changes how it is parameterized | Major |
137
+
| A scanner removes data from its output or makes other changes affecting the findings| Major |
138
+
| The SCB makes changes to the findings format of one scanner (e.g., renaming a key) | Major |
139
+
| The SCB makes breaking changes to the CRDs (renaming or removing fields) | Arch |
140
+
| The SCB makes backwards-compatible changes to the CRDs (adding new fields) | Minor |
141
+
| The SCB fixes a small bug in the operator or a scanner | Patch |
142
+
| A scanner changes its own version | Updated Build Meta |
143
143
144
144
This makes the proposal still not completely Semver compliant as the command line flags of the scanner can still break in minor releases, but these can be easily detected as the user will notice that the version number of the scanner has jumped a major release.
0 commit comments