Skip to content

Commit 43e8725

Browse files
author
Reuven Harrison
authored
improve-deprecation-messages (#284)
* first set of improvements * getDeperacationDays * fix ExtensionsDiff empty checks * centralized check-breaking config * update breaking-changes doc
1 parent cbec540 commit 43e8725

24 files changed

Lines changed: 281 additions & 227 deletions

‎BREAKING-CHANGES-EXAMPLES.md‎

Lines changed: 34 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,17 @@
22
These examples are automatically generated from unit tests.
33
## Examples of breaking changes
44
[adding a new required property in request body is breaking](checker/checker_breaking_property_test.go?plain=1#L352)
5-
[adding a pattern to a schema is breaking for recursive properties](checker/checker_breaking_test.go?plain=1#L469)
6-
[adding a pattern to a schema is breaking](checker/checker_breaking_test.go?plain=1#L453)
7-
[adding a required request body is breaking](checker/checker_breaking_test.go?plain=1#L61)
5+
[adding a pattern to a schema is breaking for recursive properties](checker/checker_breaking_test.go?plain=1#L473)
6+
[adding a pattern to a schema is breaking](checker/checker_breaking_test.go?plain=1#L457)
7+
[adding a required request body is breaking](checker/checker_breaking_test.go?plain=1#L65)
88
[changing a request body to enum is breaking](checker/checker_breaking_property_test.go?plain=1#L122)
99
[changing a request body type and changing it to enum simultaneously is breaking](checker/checker_breaking_property_test.go?plain=1#L152)
1010
[changing a request property to not nullable is breaking](checker/checker_breaking_property_test.go?plain=1#L232)
1111
[changing a required property in response body to optional and also deleting it is breaking](checker/checker_breaking_property_test.go?plain=1#L280)
1212
[changing a response body to nullable is breaking](checker/checker_breaking_property_test.go?plain=1#L216)
1313
[changing a response property to nullable is breaking](checker/checker_breaking_property_test.go?plain=1#L248)
1414
[changing an embedded response property to nullable is breaking](checker/checker_breaking_property_test.go?plain=1#L264)
15-
[changing an existing header param from optional to required is breaking](checker/checker_breaking_test.go?plain=1#L183)
15+
[changing an existing header param from optional to required is breaking](checker/checker_breaking_test.go?plain=1#L187)
1616
[changing an existing header param to enum is breaking](checker/checker_breaking_property_test.go?plain=1#L184)
1717
[changing an existing property in request body anyOf to required is breaking](checker/checker_breaking_property_test.go?plain=1#L627)
1818
[changing an existing property in request body items to required is breaking](checker/checker_breaking_property_test.go?plain=1#L611)
@@ -22,48 +22,49 @@ These examples are automatically generated from unit tests.
2222
[changing an existing property in request header to required is breaking](checker/checker_breaking_property_test.go?plain=1#L56)
2323
[changing an existing property in response body to optional is breaking](checker/checker_breaking_property_test.go?plain=1#L106)
2424
[changing an existing property under another property in request body to required is breaking](checker/checker_breaking_property_test.go?plain=1#L643)
25-
[changing an existing request body from optional to required is breaking](checker/checker_breaking_test.go?plain=1#L78)
25+
[changing an existing request body from optional to required is breaking](checker/checker_breaking_test.go?plain=1#L82)
2626
[changing an existing required property in response body to not-write-only is breaking](checker/checker_breaking_property_test.go?plain=1#L576)
27-
[changing an existing response header from required to optional is breaking](checker/checker_breaking_test.go?plain=1#L207)
27+
[changing an existing response header from required to optional is breaking](checker/checker_breaking_test.go?plain=1#L211)
2828
[changing max length in request from nil to any value is breaking](checker/checker_breaking_min_max_test.go?plain=1#L110)
2929
[changing max length in response from any value to nil is breaking](checker/checker_breaking_min_max_test.go?plain=1#L160)
30-
[deleting a media-type from response is breaking](checker/checker_breaking_test.go?plain=1#L423)
31-
[deleting a path is breaking](checker/checker_breaking_test.go?plain=1#L39)
30+
[deleting a media-type from response is breaking](checker/checker_breaking_test.go?plain=1#L427)
31+
[deleting a path is breaking](checker/checker_breaking_test.go?plain=1#L43)
3232
[deleting a path with some operations having sunset date in the future is breaking](checker/checker_deprecation_test.go?plain=1#L273)
3333
[deleting a required property in request is breaking with warn](checker/checker_breaking_property_test.go?plain=1#L368)
3434
[deleting a required property in response body is breaking](checker/checker_breaking_property_test.go?plain=1#L416)
3535
[deleting a required property under AllOf in response body is breaking](checker/checker_breaking_property_test.go?plain=1#L446)
3636
[deleting a required property within another property in request is breaking with warn](checker/checker_breaking_property_test.go?plain=1#L385)
37-
[deleting an enum value is breaking](checker/checker_breaking_test.go?plain=1#L99)
37+
[deleting an enum value is breaking](checker/checker_breaking_test.go?plain=1#L103)
3838
[deleting an operation before sunset date is breaking](checker/checker_deprecation_test.go?plain=1#L35)
39-
[deleting an operation is breaking](checker/checker_breaking_test.go?plain=1#L46)
39+
[deleting an operation is breaking](checker/checker_breaking_test.go?plain=1#L50)
4040
[deleting an operation without sunset date is breaking](checker/checker_deprecation_test.go?plain=1#L52)
41+
[deleting sunset header for a deprecated endpoint is breaking](checker/checker_deprecation_test.go?plain=1#L290)
4142
[deprecating an operation with a deprecation policy and sunset date before required deprecation period is breaking](checker/checker_deprecation_test.go?plain=1#L218)
4243
[deprecating an operation with a deprecation policy but without specifying sunset date is breaking](checker/checker_deprecation_test.go?plain=1#L84)
4344
[increasing max length in response is breaking](checker/checker_breaking_min_max_test.go?plain=1#L93)
4445
[increasing min items in request is breaking](checker/checker_breaking_min_max_test.go?plain=1#L236)
45-
[modifying a pattern in a schema is breaking](checker/checker_breaking_test.go?plain=1#L485)
46-
[modifying a pattern in request parameter is breaking](checker/checker_breaking_test.go?plain=1#L501)
47-
[modifying the default value of an optional request parameter is breaking](checker/checker_breaking_test.go?plain=1#L531)
48-
[new required header param is breaking](checker/checker_breaking_test.go?plain=1#L167)
49-
[new required path param is breaking](checker/checker_breaking_test.go?plain=1#L151)
46+
[modifying a pattern in a schema is breaking](checker/checker_breaking_test.go?plain=1#L489)
47+
[modifying a pattern in request parameter is breaking](checker/checker_breaking_test.go?plain=1#L505)
48+
[modifying the default value of an optional request parameter is breaking](checker/checker_breaking_test.go?plain=1#L535)
49+
[new required header param is breaking](checker/checker_breaking_test.go?plain=1#L171)
50+
[new required path param is breaking](checker/checker_breaking_test.go?plain=1#L155)
5051
[new required property in request header is breaking](checker/checker_breaking_property_test.go?plain=1#L17)
5152
[reducing max in request is breaking](checker/checker_breaking_min_max_test.go?plain=1#L264)
5253
[reducing max length in request is breaking](checker/checker_breaking_min_max_test.go?plain=1#L12)
5354
[reducing min items in response is breaking](checker/checker_breaking_min_max_test.go?plain=1#L220)
5455
[reducing min length in response is breaking](checker/checker_breaking_min_max_test.go?plain=1#L62)
55-
[removing an existing optional response header is breaking as warn](checker/checker_breaking_test.go?plain=1#L404)
56-
[removing an existing required response header is breaking as error](checker/checker_breaking_test.go?plain=1#L223)
57-
[removing an existing response with non-successful status is breaking (optional)](checker/checker_breaking_test.go?plain=1#L260)
58-
[removing an existing response with successful status is breaking](checker/checker_breaking_test.go?plain=1#L242)
59-
[removing an schema object from components is breaking (optional)](checker/checker_breaking_test.go?plain=1#L586)
56+
[removing an existing optional response header is breaking as warn](checker/checker_breaking_test.go?plain=1#L408)
57+
[removing an existing required response header is breaking as error](checker/checker_breaking_test.go?plain=1#L227)
58+
[removing an existing response with non-successful status is breaking (optional)](checker/checker_breaking_test.go?plain=1#L264)
59+
[removing an existing response with successful status is breaking](checker/checker_breaking_test.go?plain=1#L246)
60+
[removing an schema object from components is breaking (optional)](checker/checker_breaking_test.go?plain=1#L590)
6061
[removing the path without a deprecation policy and without specifying sunset date is breaking if some APIs are not alpha stability level](checker/checker_deprecation_test.go?plain=1#L137)
6162
[removing the path without a deprecation policy and without specifying sunset date is breaking if some APIs are not draft stability level](checker/checker_deprecation_test.go?plain=1#L191)
62-
[removing/updating a property enum in response is breaking (optional)](checker/checker_breaking_test.go?plain=1#L318)
63-
[removing/updating a tag is breaking (optional)](checker/checker_breaking_test.go?plain=1#L335)
64-
[removing/updating an enum in request body is breaking (optional)](checker/checker_breaking_test.go?plain=1#L296)
65-
[removing/updating an operation id is breaking (optional)](checker/checker_breaking_test.go?plain=1#L278)
66-
[setting the default value of an optional request parameter is breaking](checker/checker_breaking_test.go?plain=1#L549)
63+
[removing/updating a property enum in response is breaking (optional)](checker/checker_breaking_test.go?plain=1#L322)
64+
[removing/updating a tag is breaking (optional)](checker/checker_breaking_test.go?plain=1#L339)
65+
[removing/updating an enum in request body is breaking (optional)](checker/checker_breaking_test.go?plain=1#L300)
66+
[removing/updating an operation id is breaking (optional)](checker/checker_breaking_test.go?plain=1#L282)
67+
[setting the default value of an optional request parameter is breaking](checker/checker_breaking_test.go?plain=1#L553)
6768

6869
## Examples of non-breaking changes
6970
[adding a media-type to response is not breaking](checker/checker_not_breaking_test.go?plain=1#L166)
@@ -95,7 +96,7 @@ These examples are automatically generated from unit tests.
9596
[changing servers is not breaking](checker/checker_not_breaking_test.go?plain=1#L234)
9697
[deleting a non-required non-write-only property in response body is not breaking](checker/checker_breaking_property_test.go?plain=1#L531)
9798
[deleting a path after sunset date of all contained operations is not breaking](checker/checker_deprecation_test.go?plain=1#L258)
98-
[deleting a pattern from a schema is not breaking](checker/checker_breaking_test.go?plain=1#L439)
99+
[deleting a pattern from a schema is not breaking](checker/checker_breaking_test.go?plain=1#L443)
99100
[deleting a required write-only property in response body is not breaking](checker/checker_breaking_property_test.go?plain=1#L514)
100101
[deleting a tag is not breaking](checker/checker_not_breaking_test.go?plain=1#L54)
101102
[deleting an operation after sunset date is not breaking](checker/checker_deprecation_test.go?plain=1#L69)
@@ -107,8 +108,8 @@ These examples are automatically generated from unit tests.
107108
[deprecating an operation without a deprecation policy and without specifying sunset date is not breaking](checker/checker_deprecation_test.go?plain=1#L103)
108109
[increasing max length in request is not breaking](checker/checker_breaking_min_max_test.go?plain=1#L76)
109110
[increasing min items in response is not breaking](checker/checker_breaking_min_max_test.go?plain=1#L250)
110-
[modifying a pattern to ".*" in a schema is not breaking](checker/checker_breaking_test.go?plain=1#L517)
111-
[modifying the default value of a required request parameter is not breaking](checker/checker_breaking_test.go?plain=1#L567)
111+
[modifying a pattern to ".*" in a schema is not breaking](checker/checker_breaking_test.go?plain=1#L521)
112+
[modifying the default value of a required request parameter is not breaking](checker/checker_breaking_test.go?plain=1#L571)
112113
[new optional header param is not breaking](checker/checker_not_breaking_test.go?plain=1#L102)
113114
[new optional property in request header is not breaking](checker/checker_breaking_property_test.go?plain=1#L38)
114115
[new required response header param is not breaking](checker/checker_not_breaking_test.go?plain=1#L134)
@@ -117,14 +118,14 @@ These examples are automatically generated from unit tests.
117118
[reducing max length in response is not breaking](checker/checker_breaking_min_max_test.go?plain=1#L31)
118119
[reducing min items in request is not breaking](checker/checker_breaking_min_max_test.go?plain=1#L206)
119120
[reducing min length in request is not breaking](checker/checker_breaking_min_max_test.go?plain=1#L48)
120-
[removing an existing response with error status is not breaking](checker/checker_breaking_test.go?plain=1#L388)
121-
[removing an existing response with unparseable status is not breaking](checker/checker_breaking_test.go?plain=1#L372)
121+
[removing an existing response with error status is not breaking](checker/checker_breaking_test.go?plain=1#L392)
122+
[removing an existing response with unparseable status is not breaking](checker/checker_breaking_test.go?plain=1#L376)
122123
[removing the path without a deprecation policy and without specifying sunset date is not breaking for alpha level](checker/checker_deprecation_test.go?plain=1#L118)
123124
[removing the path without a deprecation policy and without specifying sunset date is not breaking for draft level](checker/checker_deprecation_test.go?plain=1#L172)
124-
[renaming a path parameter is not breaking](checker/checker_breaking_test.go?plain=1#L131)
125+
[renaming a path parameter is not breaking](checker/checker_breaking_test.go?plain=1#L135)
125126

126127
## Examples of info-level changes for changelog
127128
[deprecating an operation with sunset greater than min](checker/checker_not_breaking_test.go?plain=1#L180)
128129
[new paths or path operations](checker/check-api-added_test.go?plain=1#L11)
129-
[path operations that became deprecated](checker/checker_deprecation_test.go?plain=1#L307)
130-
[path operations that were re-activated](checker/checker_deprecation_test.go?plain=1#L327)
130+
[path operations that became deprecated](checker/checker_deprecation_test.go?plain=1#L324)
131+
[path operations that were re-activated](checker/checker_deprecation_test.go?plain=1#L344)

‎checker/check-api-added_test.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ func TestApiAdded_DetectsNewPathsAndNewOperations(t *testing.T) {
1616
s2, err := open("../data/new_endpoints/revision.yaml")
1717
require.NoError(t, err)
1818

19-
d, osm, err := diff.GetWithOperationsSourcesMap(&diff.Config{}, s1, s2)
19+
d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
2020
require.NoError(t, err)
2121

2222
errs := checker.CheckBackwardCompatibility(checker.GetAllChecks(), d, osm)
@@ -40,7 +40,7 @@ func TestApiAdded_DetectsModifiedPathsWithPathParam(t *testing.T) {
4040
s2, err := open("../data/new_endpoints/revision_with_path_param.yaml")
4141
require.NoError(t, err)
4242

43-
d, osm, err := diff.GetWithOperationsSourcesMap(&diff.Config{}, s1, s2)
43+
d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
4444
require.NoError(t, err)
4545

4646
errs := checker.CheckBackwardCompatibility(checker.GetAllChecks(), d, osm)

‎checker/check-api-deprecation.go‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,12 @@ func APIDeprecationCheck(diffReport *diff.Diff, operationsSources *diff.Operatio
4040
continue
4141
}
4242

43-
date, err := diff.GetSunsetDate(op.Extensions)
43+
rawDate, date, err := diff.GetSunsetDate(op.Extensions)
4444
if err != nil {
4545
result = append(result, BackwardCompatibilityError{
4646
Id: "api-deprecated-sunset-parse",
4747
Level: ERR,
48-
Text: config.i18n("api-deprecated-sunset-parse"),
48+
Text: fmt.Sprintf(config.i18n("api-deprecated-sunset-parse"), rawDate, err),
4949
Operation: operation,
5050
OperationId: op.OperationID,
5151
Path: path,
@@ -55,7 +55,6 @@ func APIDeprecationCheck(diffReport *diff.Diff, operationsSources *diff.Operatio
5555
}
5656

5757
days := date.DaysSince(civil.DateOf(time.Now()))
58-
deprecationDays := config.MinSunsetStableDays
5958

6059
stability, err := getStabilityLevel(op.Extensions)
6160
if err != nil {
@@ -70,9 +69,8 @@ func APIDeprecationCheck(diffReport *diff.Diff, operationsSources *diff.Operatio
7069
})
7170
continue
7271
}
73-
if stability == "beta" {
74-
deprecationDays = config.MinSunsetBetaDays
75-
}
72+
73+
deprecationDays := getDeperacationDays(config, stability)
7674

7775
if days < deprecationDays {
7876
result = append(result, BackwardCompatibilityError{

‎checker/check-api-removed.go‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,13 +33,13 @@ func APIRemovedCheck(diffReport *diff.Diff, operationsSources *diff.OperationsSo
3333
})
3434
continue
3535
}
36-
date, err := diff.GetSunsetDate(op.Extensions)
36+
rawDate, date, err := diff.GetSunsetDate(op.Extensions)
3737
if err != nil {
3838
source := "original_source=" + (*operationsSources)[op]
3939
result = append(result, BackwardCompatibilityError{
4040
Id: "api-path-sunset-parse",
4141
Level: ERR,
42-
Text: "api path sunset date can't be parsed",
42+
Text: fmt.Sprintf(config.i18n("api-deprecated-sunset-parse"), rawDate, err),
4343
Operation: operation,
4444
OperationId: op.OperationID,
4545
Path: path,
@@ -81,13 +81,13 @@ func APIRemovedCheck(diffReport *diff.Diff, operationsSources *diff.OperationsSo
8181
})
8282
continue
8383
}
84-
date, err := diff.GetSunsetDate(op.Extensions)
84+
rawDate, date, err := diff.GetSunsetDate(op.Extensions)
8585
if err != nil {
8686
source := (*operationsSources)[op]
8787
result = append(result, BackwardCompatibilityError{
88-
Id: "api-sunset-parse",
88+
Id: "api-path-sunset-parse",
8989
Level: ERR,
90-
Text: "api sunset date can't be parsed",
90+
Text: fmt.Sprintf(config.i18n("api-deprecated-sunset-parse"), rawDate, err),
9191
Operation: operation,
9292
OperationId: op.OperationID,
9393
Path: path,

0 commit comments

Comments
 (0)