[#68] Ensure compatibility of different API versions with each other.

Update linters.

Signed-off-by: Ori Bruk <o.bruk@yadro.com>

.forgejo/workflows/pre-commit.yaml

@@ -10,6 +10,8 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
       - name: Install deps
         run: |
           apt update

.pre-commit-config.yaml

@@ -22,3 +22,13 @@ repos:
         entry: make fmt
         language: system
         pass_filenames: false
+      - id: make-check-version
+        name: Run make check-version
+        entry: make check-version
+        language: system
+        pass_filenames: false
+      - id: make-compatibility
+        name: Run make compatibility
+        entry: make compatibility
+        language: system
+        pass_filenames: false

CHANGELOG.md

@@ -2,8 +2,14 @@
 
 ## [3.0] - 2024-10-08 - Potanin Glacier
 
+### Added
+- Version compatibility information
+- Linter for checking version update
+- Linter for checking json files for version compatibility
+
 ### Changed
 - Proto package path
+- Versioning (semver like 2.14.0 to milestone with patch like 3.0)
 
 ### Removed
 - Proto options for all languages

CONTRIBUTING.md

@@ -53,6 +53,13 @@ changes. Maybe you will find it convenient to name branch in the
 $ git checkout -b feature/123-something_awesome
 ```
 
+### Maintain version compatibility
+After your code changes, make sure
+
+- Increment the milestone version or patch version in case of bug fixes [Version information](version.json).
+- To add information about compatibility with previous versions of the api for the new code
+  [Compatibility files](compatibility).
+
 ### Test your changes
 After your code changes, make sure
 

Makefile

@@ -1,9 +1,11 @@
 #!/usr/bin/make -f
 SHELL=bash
 
+VERSION_CHECK_BRANCH ?=$(shell git describe --tags --match "version-check*" 2>/dev/null || echo "remotes/origin/master")
+
 include help.mk
 
-.PHONY: doc fmt pre-commit unpre-commit pre-commit-run
+.PHONY: doc fmt check-version compatibility pre-commit unpre-commit pre-commit-run
 
 # Regenerate documentation for proto files:
 doc:
@@ -22,6 +24,55 @@ fmt:
 		clang-format -i $$f; \
 	done
 
+# Run version update check in version.json file
+check-version:
+	@protoChanges=$$(git diff --name-only $(VERSION_CHECK_BRANCH) | grep '**/*.proto'); \
+	version=$$(git show $(VERSION_CHECK_BRANCH):version.json); \
+	if [ -z "$$version" ] || [ -z "$$protoChanges" ]; then \
+		exit; \
+	fi; \
+	masterMilestone=$$(jq -n --argjson data "$$version" '$$data.milestone'); \
+	masterPatch=$$(jq -n --argjson data "$$version" '$$data.patch'); \
+	milestone=$$(jq -r '.milestone' version.json); \
+	patch=$$(jq -r '.patch' version.json); \
+	if [ "$$masterMilestone" -eq "$$milestone" -a "$$masterPatch" -eq "$$patch" ]; then \
+		echo "⇒ You need to update the api version in the version.json file"; \
+		exit 1; \
+	fi; \
+	if [ "$$masterMilestone" -gt "$$milestone" ]; then \
+		echo "⇒ The milestone cannot be decrement in the version.json file"; \
+		exit 1; \
+	fi; \
+	if [ "$$masterMilestone" -eq "$$milestone" -a "$$masterPatch" -gt "$$patch" ]; then \
+		echo "⇒ The patch cannot be decrement without milestone increment in the version.json file"; \
+		exit 1; \
+	fi; \
+	if [ "$$masterMilestone" -lt "$$milestone" -a "$$patch" -ne 0 ]; then \
+		echo "⇒ The patch should be 0 after milestone increment in the version.json file"; \
+		exit 1; \
+	fi
+
+# Run a compatibility information check
+# Checks that the files that describe compatibility in the compatibility package
+# have the current version information added in the version.json file.
+# Description of logic:
+# 1. Determine the current API version from the version.json file;
+# 2. Find all JSON files with compatibility descriptions in the compatibility package;
+# 3. For each such file, we define all the described rpc methods;
+# 4. For each rpc method in each compatibility file, we check that the updated version information is present.
+compatibility:
+	@version=$$(jq -r '.milestone' version.json).$$(jq -r '.patch' version.json); \
+	conflicts=0; \
+	for f in `ls compatibility/*.json`; do \
+		for rpc in $$(jq -r '.[] | to_entries | .[].key' $$f); do \
+			if $$(jq -r '.[].'$$rpc' | has("v'$$version'") | not' $$f); then \
+				echo "⇒ No compatibility information found for version" $$version "in file" $$f "for rpc" $$rpc; \
+				conflicts=$$(($conflicts+1)); \
+			fi \
+  		done \
+	done; \
+	exit $$conflicts;
+
 # Activate pre-commit hooks
 pre-commit:
 	pre-commit install --hook-type pre-commit

compatibility/accounting.json

@@ -0,0 +1,9 @@
+{
+  "compatibilityInfo": {
+    "Balance": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    }
+  }
+}

compatibility/apemanager.json

@@ -0,0 +1,19 @@
+{
+  "compatibilityInfo": {
+    "AddChain": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "RemoveChain": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "ListChains": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    }
+  }
+}

compatibility/container.json

@@ -0,0 +1,24 @@
+{
+  "compatibilityInfo": {
+    "Put": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "Delete": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "Get": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "List": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    }
+  }
+}

compatibility/netmap.json

@@ -0,0 +1,19 @@
+{
+  "compatibilityInfo": {
+    "LocalNodeInfo": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "NetworkInfo": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "NetmapSnapshot": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    }
+  }
+}

compatibility/object.json

@@ -0,0 +1,49 @@
+{
+  "compatibilityInfo": {
+    "Get": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "Put": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "Delete": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "Head": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "Search": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "GetRange": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "GetRangeHash": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "PutSingle": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    },
+    "Patch": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    }
+  }
+}

compatibility/session.json

@@ -0,0 +1,9 @@
+{
+  "compatibilityInfo": {
+    "Create": {
+      "v3.0": {
+        "compatibility": "SUPPORTED"
+      }
+    }
+  }
+}

doc/release_instructions.md

@@ -3,15 +3,17 @@
 This documents outlines the frostfs-api release process and can be used as a TODO
 list for a new release.
 
+## Pre-release actions
+
+Increment the milestone version or patch version in case of bug fixes.
+To add information about compatibility with previous versions of the api for the new code.
+This must be run:
+* `make doc`
+
 ## Pre-release checks
 
 This should run successfully:
-* `make lint`
-
-## Pre-release actions
-
-This must be run:
-* `make doc`
+* `make pre-commit-run`
 
 ## Writing CHANGELOG
 
@@ -30,13 +32,13 @@ Release commit summary should follow the template:
 `Release v<Version> - <Codename island> (<Hangeul>, <Hanja>)`, e.g.:
 
 ```
-Release v2.9.0 - Anmyeondo (안면도, 安眠島)
+Release v3.0 - Anmyeondo (안면도, 安眠島)
 ```
 
 ## Tag the release
 
-Use `vX.Y.Z` tag following the semantic versioning standard. For pre-release
-versions use `vX.Y.Z-rc.N` scheme.
+Use `vX.Y` tag (milestone version with patch). For pre-release
+versions use `vX.Y-rc.N` scheme.
 
 ## Push changes and release tag to Github
 
@@ -45,7 +47,7 @@ that releasing requires admin privileges for the project), both the `master`
 branch update and tag must be pushed simultaneously like this:
 
 ```
-$ git push origin master v2.7.0
+$ git push origin master v2.7
 ```
 
 ## Make a proper Github release
@@ -58,5 +60,5 @@ releases.
 
 ## Post-release actions
 
-* Close corresponding X.Y.Z Github milestone
+* Close corresponding X.Y Github milestone
 * Make announcements in Matrix and Discord channels

version.json

@@ -0,0 +1,5 @@
+{
+  "milestone": 3,
+  "patch": 0,
+  "date": "2024-10-08"
+}