[prdoc] Optional SemVer bumps and Docs (#3441)

Changes:
- Add an optional `bump` field to the crates in a prdoc.
- Explain the cargo semver interpretation for <1 versions in the release
doc.

---------

Signed-off-by: Oliver Tale-Yazdi <[email protected]>

Author: ggwpez

docs/RELEASE.md

@@ -18,10 +18,16 @@ Rococo. To easily refer to a release, it shall be named by its date in the form
 
 ## Crate
 
-We try to follow [SemVer 2.0.0](https://semver.org/) as best as possible for versioning our crates. SemVer requires a
-piece of software to first declare a public API. The public API of the Polkadot SDK is hereby declared as the sum of all
-crates' public APIs.
+We try to follow [SemVer 2.0.0](https://semver.org/) as best as possible for versioning our crates. The definitions of
+`major`, `minor` and `patch` version for Rust crates are slightly altered from their standard for pre `1.0.0` versions.
+Quoting [rust-lang.org](https://doc.rust-lang.org/cargo/reference/semver.html):  
 
+>Initial development releases starting with “0.y.z” can treat changes in “y” as a major release, and “z” as a minor
+release. “0.0.z” releases are always major changes. This is because Cargo uses the convention that only changes in the
+left-most non-zero component are considered incompatible.
+
+SemVer requires a piece of software to first declare a public API. The public API of the Polkadot SDK
+is hereby declared as the sum of all crates' public APIs.
 
 Inductively, the public API of our library crates is declared as all public items that are neither:
 - Inside a `__private` module

prdoc/schema_user.json

@@ -3,9 +3,8 @@
     "$id": "https://raw.githubusercontent.com/paritytech/prdoc/master/prdoc_schema_user.json",
     "version": {
       "major": 1,
-      "minor": 0,
-      "patch": 0,
-      "timestamp": 20230817152351
+      "minor": 1,
+      "patch": 0
     },
     "title": "Polkadot SDK PRDoc Schema",
     "description": "JSON Schema definition for the Polkadot SDK PR documentation",
@@ -125,10 +124,16 @@
           "name": {
             "type": "string"
           },
+          "bump": {
+            "$ref": "#/$defs/semver_bump"
+          },
           "note": {
             "type": "string"
           }
-        }
+        },
+        "required": [
+          "name"
+        ]
       },
       "migration_db": {
         "type": "object",
@@ -165,6 +170,26 @@
           "description"
         ]
       },
+      "semver_bump": {
+        "description": "The type of bump to apply to the crate version according to Cargo SemVer: https://doc.rust-lang.org/cargo/reference/semver.html. Please check docs/RELEASE.md for more information.",
+        "oneOf": [
+          {
+            "const": "major",
+            "title": "Major",
+            "description": "A bump to the leftmost non-zero digit of the version number."
+          },
+          {
+            "const": "minor",
+            "title": "Minor",
+            "description": "A bump to the second leftmost non-zero digit of the version number."
+          },
+          {
+            "const": "patch",
+            "title": "Patch",
+            "description": "A bump to the third leftmost non-zero digit of the version number."
+          }
+        ]
+      },
       "doc": {
         "type": "object",
         "description": "You have the the option to provide different description of your PR for different audiences.",