aid needed actions on schema update #214

New issue

Closed

opened 2025-02-28 10:51:30 +01:00 by kiara · 1 comment

kiara commented

2025-02-28 10:51:30 +01:00

Owner

As an operator,
Given one of my applications has updated to a version introducing breaking changes to configuration options (#159),
I want for Fediversity to aid me in taking the required actions,
so that I may resolve these issues and make use of my updated applications.

implementation notes

API (#368): send a diff (missing rename?).
front-end:
- form mode: present the operator with side-by-side forms for both the old schema (potentially read-only form) and the new schema (to be completed by the user)
  - side-by-side form may render one side out of its regular order to show renames together
- power mode:
  - show a diff of the JSON-Schema (see #213)
  - in the form(s?) maybe additionally display the fields' keys as used on the JSON level
  - present the JSON value of the incumbent old deployment configuration (read-only) based on the old schema, then another (for the user to correct and submit) for the new schema. (avoid yaml over spacing, toml over key repetition in sub-headers.)
aside from notifying the user of changes (#213), we should handle forward operations (see #629) for JSON schema (strict) according to their type, if default values have not been supplied. in practice, this comes down to notifying the user action is needed (or possible, i.e. option added or type changed).
aiding migration on backward-incompatible changes should mean:
- on migration attempt, notify the user in case of failing validation
- eagerly validating values in the migrated form, to show which configuration values are not yet deemed valid
Nix default fallbacks will not be represented in an Operator's config (see #1021), so we need to take that into account in case of updates/migrations. This would probably need to be handled by prompting the Operator to verify whether changes in defaults are acceptable or allowing them to enter configuration equivalent to the old default. - split out to #1104

breakdown on action required/optional/neither

no action needed:

rename
Remove optional field
Remove required field

action optional:

Add optional field
Add union/oneof variant
Widen a scalar type

action conditionally required:

Remove union/oneof variant
Narrow a scalar type

action required:

Add required field

other:

type change: maybe cast, otherwise regard as (new) field for which we may show old value for reference

**As** an operator, **Given** one of my applications has updated to a version introducing breaking changes to configuration options (#159), **I want** for Fediversity to aid me in taking the required actions, **so that** I may resolve these issues and make use of my updated applications. ### implementation notes - API (#368): send a [diff](https://github.com/getsentry/json-schema-diff) (missing rename?). - front-end: - form mode: present the operator with [side-by-side forms](https://stackoverflow.com/posts/3488454/revisions) for both the old schema (potentially read-only form) and the new schema (to be completed by the user) - side-by-side form may render one side out of its regular order to show renames together - power mode: - show a diff of the JSON-Schema (see #213) - in the form(s?) maybe additionally display the fields' keys as used on the JSON level - present the JSON value of the incumbent old deployment configuration (read-only) based on the old schema, then another (for the user to correct and submit) for the new schema. (avoid yaml over spacing, toml over key repetition in sub-headers.) - aside from notifying the user of changes (#213), we should handle [forward operations](https://docs.confluent.io/platform/7.9/schema-registry/fundamentals/schema-evolution.html#summary) (see #629) for JSON schema (strict) according to their type, if default values have not been supplied. in practice, this comes down to notifying the user action is needed (or possible, i.e. option added or type changed). - aiding migration on backward-incompatible changes should mean: - on migration attempt, notify the user in case of failing validation - eagerly validating values in the migrated form, to show which configuration values are not yet deemed valid - Nix `default` fallbacks will not be represented in an Operator's config (see #1021), so we need to take that into account in case of updates/migrations. This would probably need to be handled by prompting the Operator to verify whether changes in defaults are acceptable or allowing them to enter configuration equivalent to the old default. - split out to #1104 <details> <summary> breakdown on action required/optional/neither </summary> no action needed: - rename - Remove optional field - Remove required field action optional: - Add optional field - Add union/oneof variant - Widen a scalar type action conditionally required: - Remove union/oneof variant - Narrow a scalar type action required: - Add required field other: - type change: maybe cast, otherwise regard as (new) field for which we may show old value for reference </details>

Rows
Columns