diff --git a/docs/getting_started/UpgradingDatamodel.md b/docs/getting_started/UpgradingDatamodel.md index c07e2bd27..90628d789 100644 --- a/docs/getting_started/UpgradingDatamodel.md +++ b/docs/getting_started/UpgradingDatamodel.md @@ -32,49 +32,26 @@ $ nexus datamodel build --name orgchart --force=false --prev-spec-dir= -:eyes: Show example +Show example -1. Edit the root.go file in your datamodel. -2. Add an optional field called `AdditionalField` (field with `omitempty` tag) in the node - ```shell - cat <<< '--- root.go.orig 2023-01-05 04:22:07.475996737 -0800 - +++ root.go 2023-01-17 05:41:07.993795597 -0800 - @@ -25,7 +25,8 @@ +1. Add an optional field called `Location` (field with `omitempty` tag) in the node + ``` type Leader struct { // Tags "Root" as a node in datamodel graph nexus.Node - - Name string - - Designation string - - DirectReports Manager `nexus:"children"` - + Name string - + Designation string - + DirectReports Manager `nexus:"children"` - + AdditionalField string `json:"additionalField,omitempty"` + Name string + Designation string + DirectReports Manager `nexus:"children"` + + Location string `json:"location,omitempty"` } - ' | patch root.go --ignore-whitespace - ``` - - -3. Rebuild your datamodel +2. Rebuild your datamodel ``` nexus datamodel build --name orgchart ``` @@ -86,10 +63,9 @@ These are considered non-breaking or backward compatible changes: ##### 2. Modify the existing REST API URIs
-:eyes: Show example +Show example -1. Edit the root.go file in your datamodel. -2. Remove the GET URI from the spec +1. Remove the GET URI from the spec ```shell var LeaderRestAPISpec = nexus.RestAPISpec{ Uris: []nexus.RestURIs{ @@ -105,17 +81,10 @@ These are considered non-breaking or backward compatible changes: nexus.Node Name string Designation string DirectReports Manager `nexus:"children"` + Location string `json:"location,omitempty"` } - ' | patch root.go --ignore-whitespace - ``` - - -3. Rebuild your datamodel +2. Rebuild your datamodel ``` nexus datamodel build --name orgchart ``` @@ -127,9 +96,9 @@ These are considered non-breaking or backward compatible changes: ##### 3. Modify the existing REST APIs annotation
-:eyes: Show example +Show example -1. Edit the root.go file and modify the nexus-rest-api-gen annotation spec +1. Modify the `nexus-rest-api-gen` annotation spec from `LeaderRestAPISpec` to `NewLeaderRestAPISpec` ```shell var NewLeaderRestAPISpec = nexus.RestAPISpec{ @@ -141,20 +110,13 @@ These are considered non-breaking or backward compatible changes: }, } - // nexus-rest-api-gen:NewLeaderRestAPISpec <==== + // nexus-rest-api-gen:NewLeaderRestAPISpec <== type Leader struct { nexus.Node Name string Designation string DirectReports Manager `nexus:"children"` + Location string `json:"location,omitempty"` } - ' | patch root.go --ignore-whitespace - ``` - - 2. Rebuild your datamodel ``` @@ -165,41 +127,27 @@ These are considered non-breaking or backward compatible changes:
-And these would be considered breaking changes: +## What is considered a backward incompatible change? -##### 1. Add a new field in the nexus node +##### 1. Add a required field in the nexus node
-:eyes: Show example +Show example -1. Edit the root.go file in your datamodel. -2. Add a new field called `AdditionalField` in the nexus node - ```shell - cat <<< '--- root.go.orig 2023-01-05 04:22:07.475996737 -0800 - +++ root.go 2023-01-17 05:41:07.993795597 -0800 - @@ -25,7 +25,8 @@ +1. Add a required field called `AdditionalField` in the existing nexus node + ``` type Leader struct { // Tags "Root" as a node in datamodel graph nexus.Node - - Name string - - Designation string - - DirectReports Manager `nexus:"children"` - + Name string - + Designation int - + DirectReports Manager `nexus:"children"` - + AdditionalField string + Name string + Designation int + DirectReports Manager `nexus:"children"` + Location string `json:"location,omitempty"` + + AdditionalField string } - ' | patch root.go --ignore-whitespace - ``` - - -3. Build your datamodel again +2. Rebuild the datamodel ``` nexus datamodel build --name orgchart ``` @@ -219,44 +167,32 @@ And these would be considered breaking changes: time="2023-01-24T12:21:56+05:30" level=error msg="\t > \n" time="2023-01-24T12:21:56+05:30" level=error msg="\t > \n" -4. Use the `—force=true` flag to ignore any build failures and obtain successful code generation. +3. Use the `—force=true` flag to ignore any build failures and obtain successful code generation. ``` nexus datamodel build --name orgchart --force=true ```
-##### 2. Remove a field from the nexus node +##### 2. Remove a required field from the nexus node
-:eyes: Show example +Show example -1. Edit the root.go file in your datamodel. -2. Remove a field called `Designation` from the `Leader` node - ```shell - cat <<< '--- root.go.orig 2023-01-05 04:22:07.475996737 -0800 - +++ root.go 2023-01-17 05:41:07.993795597 -0800 - @@ -25,7 +25,8 @@ +1. Remove a required field called `AdditionalField` from the `Leader` node + ``` type Leader struct { // Tags "Root" as a node in datamodel graph nexus.Node - - Name string - - Designation string - - DirectReports Manager `nexus:"children"` - + Name string - + DirectReports Manager `nexus:"children"` + Name string + Designation int + DirectReports Manager `nexus:"children"` + Location string `json:"location,omitempty"` + - AdditionalField string } - ' | patch root.go --ignore-whitespace - ``` - - -3. Build your datamodel again +2. Rebuild the datamodel ``` nexus datamodel build --name orgchart ``` @@ -270,21 +206,21 @@ And these would be considered breaking changes: time="2023-01-24T14:08:00+05:30" level=error msg="\t > spec changes: \n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > /spec/versions/name=v1/schema/openAPIV3Schema/properties/spec/properties\n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > - one field removed:\n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > designation:\n" + time="2023-01-24T14:08:00+05:30" level=error msg="\t > additionalField:\n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > type: string\n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > /spec/versions/name=v1/schema/openAPIV3Schema/properties/spec/required\n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > - one required field removed:\n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > - designation\n" + time="2023-01-24T14:08:00+05:30" level=error msg="\t > - additionalField\n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" -4. Use the `—force=true` flag to ignore any build failures and obtain successful code generation. +3. Use the `—force=true` flag to ignore any build failures and obtain successful code generation. ``` nexus datamodel build --name orgchart --force=true ``` @@ -294,34 +230,21 @@ And these would be considered breaking changes: ##### 3. Remove an optional field from the nexus node (field with "omitempty" tag )
-:eyes: Show example +Show example -1. Edit the root.go file in your datamodel. -2. Remove an optional field called `Designation` from the `Leader` node - ```shell - cat <<< '--- root.go.orig 2023-01-05 04:22:07.475996737 -0800 - +++ root.go 2023-01-17 05:41:07.993795597 -0800 - @@ -25,7 +25,8 @@ +1. Remove an optional field called `Location` from the `Leader` node + ``` type Leader struct { // Tags "Root" as a node in datamodel graph nexus.Node - - Name string - - Designation string `json:"additionalField,omitempty"` - - DirectReports Manager `nexus:"children"` - + Name string - + DirectReports Manager `nexus:"children"` + Name string + Designation int + DirectReports Manager `nexus:"children"` + - Location string `json:"location,omitempty"` } - ' | patch root.go --ignore-whitespace - ``` - - -3. Build your datamodel again +2. Rebuild the datamodel ``` nexus datamodel build --name orgchart ``` @@ -330,89 +253,22 @@ And these would be considered breaking changes: ``` panic: Error occurred when checking datamodel compatibility: datamodel upgrade failed due to incompatible datamodel changes: \n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > detected changes in model stored in leaders.root.orgchart.org\n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > spec changes: \n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > /spec/versions/name=v1/schema/openAPIV3Schema/properties/spec/properties\n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > - one field removed:\n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > designation:\n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > type: string\n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > /spec/versions/name=v1/schema/openAPIV3Schema/properties/spec/required\n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > - one required field removed:\n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > - designation\n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" - time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n" - -4. Use the `—force=true` flag to ignore any build failures and obtain successful code generation. + time="2023-01-24T20:56:26+05:30" level=error msg="\t > detected changes in model stored in leaders.root.orgchart.org\n" + time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n" + time="2023-01-24T20:56:26+05:30" level=error msg="\t > spec changes: \n" + time="2023-01-24T20:56:26+05:30" level=error msg="\t > /spec/versions/name=v1/schema/openAPIV3Schema/properties/spec/properties\n" + time="2023-01-24T20:56:26+05:30" level=error msg="\t > - one field removed:\n" + time="2023-01-24T20:56:26+05:30" level=error msg="\t > location:\n" + time="2023-01-24T20:56:26+05:30" level=error msg="\t > type: string\n" + time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n" + time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n" + time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n" + time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n" + time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n" + +3. Use the `—force=true` flag to ignore any build failures and obtain successful code generation. ``` nexus datamodel build --name orgchart --force=true ```
- - - - -## Trying the example - -This workflow will walk you through the steps to upgrade your applocal datamodel. - -* [Pre-requisites](UpgradingDatamodel.md#pre-requisites) -* [Upgrading](UpgradingDatamodel.md#Upgrading) - -### Pre-requisites -1. This workflow requires Datamodel to be initialised and installed before proceeding to further steps. Please follow the below link to configure datamodel - - #### [Playground](docs/getting_started/Playground.md) - -### Upgrading - -1. Make changes to the root.go file in your datamodel by remove one field, renaming another and adding one. - These datamodel changes are incompatible (although the newly added field wouldn't be incompatible if it had the `json:"omitempty"` tag ) - ```shell - cat <<< '--- root.go.orig 2023-01-05 04:22:07.475996737 -0800 - +++ root.go 2023-01-17 05:41:07.993795597 -0800 - @@ -25,7 +25,8 @@ - type Leader struct { - // Tags "Root" as a node in datamodel graph - nexus.Node - - - Name string - - Designation string - - DirectReports Manager `nexus:"children"` - + Name string - + Designation int - + DirectReports Manager `nexus:"children"` - + AdditionalData string - } - ' | patch root.go --ignore-whitespace - ``` - - - -2. Build your datamodel again. We have to use `--force=true` flag, or else the build would fail and show us the incompatible changes. - ``` - nexus datamodel build --name orgchart --force=true - DOCKER_REPO=orgchart VERSION=latest make docker_build - kind load docker-image orgchart:latest --name - ``` - -3. Delete leader object manually, as it is backwards incompatible - ```shell - kubectl -s localhost:5000 delete leaders.root.orgchart.org - ``` - -4. Install built datamodel into runtime. Like the build part, we also have to use force flag, or else the upgrade will fail due to incompatibility. - ``` - nexus datamodel install image orgchart:latest --namespace --force=true - ```