@snyk/sweater-comb - npm Package Compare versions

Comparing version 0.3.1 to 0.3.2

docs/standards.md

@@ -69,3 +69,3 @@ # Snyk API Standards
 
-Schema properties use **camel case** names.
+Schema properties use **snake case** names.
 
@@ -72,0 +72,0 @@ ### Operation IDs

docs/version.md

@@ -21,8 +21,4 @@ # Versioning
 
-### Releases can only increase in stability (or sunset by newer releases)
+A change in stability also requires a new resource version date. Retroactive releases suddenly showing up at a higher stability can introduce unexpected breaking changes in the API.
 
-A resource version can be "promoted" to greater stability. For example, you may decide that you're ready to commit an experimental version to beta-quality, or what was in beta, is now ready for general availability.
-
-However, you "can't go back". If you find that it's "back to the drawing board" with a resource version, then a new version needs to be created at that later point in time — you can't lower the stability of an already-released version!
-
 ## Versioning resources
@@ -41,3 +37,3 @@
 
-The version date must be the day that the resource version was originally introduced.
+The version date must be the day that the resource version is made available.
 
@@ -59,3 +55,3 @@ Versions must not be released or requested at a future date.
     - It will be available for at least **30 days** after a subsequent resource version *of equal or greater stability* is published, after which it may be removed.
-    - During its availability, it may be revised with incompatible and breaking changes.
+    - During its availability, it must not be revised with incompatible and breaking changes.
     - May be distributed as a limited tech preview.
@@ -73,14 +69,32 @@ - `beta`
 
-### Increasing stability of a release
+### Promoting stability of a resource over time
 
-A release version may be promoted to a greater stability, retroactively. For example:
+To promote a more stable version of a resource, release a new version with the desired stability commitment, on the date it is made available.
 
-- Resource version `2021-06-04~wip` is first introduced into a service on June 4, 2021.
-- It is shortly promoted to `2021-06-04~experimental`. The stability level is updated in-place.
-- Several weeks later, it is considered stable enough to promote to `2021-06-04~beta`.
+Other versions of the resource must continue to remain available through [deprecation and sunset](#deprecation-sunset).
 
-### Deprecation and Sunset
+These resource versions may share some common implementation. However, requests and responses at each version must conform to each respective OpenAPI specification.
 
-When a new version of a resource is released, it deprecates any existing version of the resource at the same stability level. A version is considered **deprecated** until it is past the mandatory duration of availability for its stability level (as defined above), after which, it may be **sunset** — removed and no longer available.
+#### Don't rewrite version history
 
+Resource versions MUST NOT be modified in-place retroactively with a stability increase. Instead, release a new version with the higher stability, dated according to its availability.
+
+A version's stability cannot be modified in-place because this effectively rewrites API history. If a past API version suddenly becomes more stable, this can change the resolved version consumers interact with, with unexpected results.
+
+An example of how this can cause problems:
+
+- A version is released at 2021-06-04~experimental
+- It gets modified in-place to increase stability, eventually becoming 2021-06-04~ga.
+- Another version starts at 2021-08-12~experimental.
+- A client evaluates the API at version 2021-10-01~ga. This resolves to
+  2021-06-04~ga. It works well so the client pins on this version (2021-10-01).
+- 2021-08-12~experimental gets modified in-place to 2021-08-12~ga on 2021-10-15.
+- The above client requests for 2021-10-01~ga now suddenly resolve to a surprise GA version that wasn't there before: 2021-08-12~ga. Unfortunately, it's a breaking change...
+
+If the 2021-08-12~experimental promotion to GA was dated when it actually took place (2021-10-15), the client would not have been broken by the newer change.
+
+### <a id="deprecation-sunset"></a>Deprecation and Sunset
+
+When a new version of a resource is released, it deprecates any prior versions of the resource at equal or lower stability. A version is considered to be in this **deprecated** state until it is past the mandatory duration of availability for its stability level (as defined above), after which, it may be **sunset** — removed and no longer available.
+
 ## Resource versioning in projects
@@ -87,0 +101,0 @@

package.json

 {
   "name": "@snyk/sweater-comb",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Snyk API linting rules",
@@ -5,0 +5,0 @@ "main": "apinext.yaml",

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

456980

increased by1.6%

Number of package files

70

increased by2.94%

Lines of code

1505

increased by4.73%

Number of medium supply chain risk alerts

0

decreased by-100%

No dependency changes