Skip to content

Commit eaeb976

Browse files
committed
Incorporate some of the feedback from review
Signed-off-by: Max Maass <max.maass@iteratec.com>
1 parent 29c04a3 commit eaeb976

1 file changed

Lines changed: 34 additions & 34 deletions

File tree

docs/adr/adr_0011.md

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -39,14 +39,14 @@ This manual action may include making changes to scan definitions, or to systems
3939
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.
4040
As illustration, here are a few examples and what kind of release they would require:
4141

42-
| Action |Version |
43-
|------------------------------------------------------------------------------------|--------|
44-
| A scanner changes how it is parameterized | Major |
45-
| A scanner changes what data it returns | 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 |
42+
| Action |Version |
43+
|--------------------------------------------------------------------------------------|--------|
44+
| 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 |
5050

5151
#### Advantages
5252
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
6868
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).
6969
As illustration, here are a few examples and what kind of release they would require:
7070

71-
| Action |Version |
72-
|------------------------------------------------------------------------------------|--------|
73-
| A scanner changes how it is parameterized | Minor |
74-
| A scanner changes what data it returns | 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 |
71+
| Action |Version |
72+
|--------------------------------------------------------------------------------------|--------|
73+
| 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 |
7979

8080
#### Advantages
8181
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
8989
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:
9090

9191
| Action |Version |
92-
|------------------------------------------------------------------------------------|--------|
93-
| A scanner changes how it is parameterized | Major |
94-
| A scanner changes what data it returns | 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 |
92+
|--------------------------------------------------------------------------------------|--------|
93+
| 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 |
9999

100100
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.
101101

@@ -114,8 +114,8 @@ We will thus not consider this proposal in greater detail here.
114114

115115
### Option 5: SemVer With Major Version Indicating Operator Compatibility + Included Version of "Embedded Dependency"
116116

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).
119119

120120
**Example Version Numbers:**
121121

@@ -131,15 +131,15 @@ Currently undecided:
131131
- e.g. embedded version / version range of supported DefectDojo version in build meta
132132
- might not be necessary / possible for every hook. And thus make the hook versioning schema inconsistent
133133

134-
| Action |Version |
135-
|------------------------------------------------------------------------------------|---------------------|
136-
| A scanner changes how it is parameterized | Major |
137-
| A scanner changes what data it returns | 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 |
134+
| Action |Version |
135+
|--------------------------------------------------------------------------------------|---------------------|
136+
| 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 |
143143

144144
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.
145145

0 commit comments

Comments
 (0)