From 7d5c6957ca7b2072b4bff4e47101a126a6e9e9ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Behrendt?= Date: Thu, 4 Jun 2026 17:30:55 +0200 Subject: [PATCH 1/2] chore: document branch compare output --- doc/compiled.json | 150 +++++++++++++++++++++++++++++++++ paths/branches/compare.yaml | 4 + schemas.yaml | 6 ++ schemas/branch_comparison.yaml | 119 ++++++++++++++++++++++++++ 4 files changed, 279 insertions(+) create mode 100644 schemas/branch_comparison.yaml diff --git a/doc/compiled.json b/doc/compiled.json index 792b08532..263a3b62a 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -473,6 +473,149 @@ "updated_at": "2015-01-28T09:52:53Z" } }, + "branch_comparison": { + "type": "object", + "title": "branch_comparison", + "description": "Comparison result of a branch against its base branch. Top-level properties correspond to\nresource types. Each resource type lists changes made in the base branch (`base_changes`),\nchanges made in the feature branch (`head_changes`), and conflicting entries (`conflicts`).\n", + "properties": { + "translation_keys": { + "$ref": "#/components/schemas/branch_comparison_resource_diff" + }, + "translations": { + "$ref": "#/components/schemas/branch_comparison_resource_diff" + }, + "locales": { + "$ref": "#/components/schemas/branch_comparison_resource_diff" + }, + "tags": { + "$ref": "#/components/schemas/branch_comparison_resource_diff" + } + }, + "example": { + "translation_keys": { + "base_changes": [ + { + "from": { + "name": "welcome.title", + "description": null, + "name_plural": null, + "is_plural": false, + "data_type": "string", + "max_characters_allowed": null, + "deleted_at": null, + "locations": [], + "options": {} + }, + "to": { + "name": "welcome.heading", + "description": null, + "name_plural": null, + "is_plural": false, + "data_type": "string", + "max_characters_allowed": null, + "deleted_at": null, + "locations": [], + "options": {} + } + } + ], + "head_changes": [], + "conflicts": {} + }, + "translations": { + "base_changes": [], + "head_changes": [ + { + "from": { + "state": "unverified", + "content": "Hello", + "changed_in_main_locale": false, + "excluded_from_export": false, + "plural_suffix": null + }, + "to": { + "state": "translated", + "content": "Hello World", + "changed_in_main_locale": false, + "excluded_from_export": false, + "plural_suffix": null + } + } + ], + "conflicts": {} + }, + "locales": { + "base_changes": [], + "head_changes": [], + "conflicts": {} + }, + "tags": { + "base_changes": [], + "head_changes": [], + "conflicts": {} + } + } + }, + "branch_comparison_resource_diff": { + "type": "object", + "title": "branch_comparison_resource_diff", + "properties": { + "base_changes": { + "type": "array", + "description": "Changes made to this resource type in the base branch since the branch was created.", + "items": { + "$ref": "#/components/schemas/branch_comparison_change" + } + }, + "head_changes": { + "type": "array", + "description": "Changes made to this resource type in the feature branch.", + "items": { + "$ref": "#/components/schemas/branch_comparison_change" + } + }, + "conflicts": { + "type": "object", + "description": "Conflicting changes present in both branches, keyed by conflict type.\nPossible conflict type keys: `changed_in_head_changed_in_base`,\n`added_in_head_added_in_base`, `changed_in_head_deleted_in_base`,\n`deleted_in_head_changed_in_base`. Each value contains `base` and `head`\narrays of changed attribute objects.\n", + "additionalProperties": { + "type": "object", + "properties": { + "base": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + } + }, + "head": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + } + }, + "branch_comparison_change": { + "type": "object", + "title": "branch_comparison_change", + "description": "A single resource change. `from` holds the state before the change (null when the resource\nwas added). `to` holds the state after (null when the resource was deleted).\nFields depend on the resource type.\n", + "properties": { + "from": { + "type": "object", + "nullable": true, + "additionalProperties": true + }, + "to": { + "type": "object", + "nullable": true, + "additionalProperties": true + } + } + }, "comment": { "type": "object", "title": "comment", @@ -20263,6 +20406,13 @@ "X-Rate-Limit-Reset": { "$ref": "#/components/headers/X-Rate-Limit-Reset" } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/branch_comparison" + } + } } }, "400": { diff --git a/paths/branches/compare.yaml b/paths/branches/compare.yaml index fa37e7ea8..13a77491c 100644 --- a/paths/branches/compare.yaml +++ b/paths/branches/compare.yaml @@ -27,6 +27,10 @@ responses: "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" X-Rate-Limit-Reset: "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" + content: + application/json: + schema: + "$ref": "../../schemas/branch_comparison.yaml#/branch_comparison" '400': "$ref": "../../responses.yaml#/400" '404': diff --git a/schemas.yaml b/schemas.yaml index 95bc21dbb..b4e6a1ac5 100644 --- a/schemas.yaml +++ b/schemas.yaml @@ -6,6 +6,12 @@ schemas: "$ref": schemas/authorization_with_token.yaml#/authorization_with_token blacklisted_key: "$ref": schemas/blacklisted_key.yaml#/blacklisted_key + branch_comparison: + "$ref": schemas/branch_comparison.yaml#/branch_comparison + branch_comparison_resource_diff: + "$ref": schemas/branch_comparison.yaml#/branch_comparison_resource_diff + branch_comparison_change: + "$ref": schemas/branch_comparison.yaml#/branch_comparison_change comment: "$ref": schemas/comment.yaml#/comment comment_reaction: diff --git a/schemas/branch_comparison.yaml b/schemas/branch_comparison.yaml new file mode 100644 index 000000000..127a193ad --- /dev/null +++ b/schemas/branch_comparison.yaml @@ -0,0 +1,119 @@ +--- +branch_comparison: + type: object + title: branch_comparison + description: | + Comparison result of a branch against its base branch. Top-level properties correspond to + resource types. Each resource type lists changes made in the base branch (`base_changes`), + changes made in the feature branch (`head_changes`), and conflicting entries (`conflicts`). + properties: + translation_keys: + "$ref": "#/branch_comparison_resource_diff" + translations: + "$ref": "#/branch_comparison_resource_diff" + locales: + "$ref": "#/branch_comparison_resource_diff" + tags: + "$ref": "#/branch_comparison_resource_diff" + example: + translation_keys: + base_changes: + - from: + name: welcome.title + description: null + name_plural: null + is_plural: false + data_type: string + max_characters_allowed: null + deleted_at: null + locations: [] + options: {} + to: + name: welcome.heading + description: null + name_plural: null + is_plural: false + data_type: string + max_characters_allowed: null + deleted_at: null + locations: [] + options: {} + head_changes: [] + conflicts: {} + translations: + base_changes: [] + head_changes: + - from: + state: unverified + content: Hello + changed_in_main_locale: false + excluded_from_export: false + plural_suffix: null + to: + state: translated + content: Hello World + changed_in_main_locale: false + excluded_from_export: false + plural_suffix: null + conflicts: {} + locales: + base_changes: [] + head_changes: [] + conflicts: {} + tags: + base_changes: [] + head_changes: [] + conflicts: {} + +branch_comparison_resource_diff: + type: object + title: branch_comparison_resource_diff + properties: + base_changes: + type: array + description: Changes made to this resource type in the base branch since the branch was created. + items: + "$ref": "#/branch_comparison_change" + head_changes: + type: array + description: Changes made to this resource type in the feature branch. + items: + "$ref": "#/branch_comparison_change" + conflicts: + type: object + description: | + Conflicting changes present in both branches, keyed by conflict type. + Possible conflict type keys: `changed_in_head_changed_in_base`, + `added_in_head_added_in_base`, `changed_in_head_deleted_in_base`, + `deleted_in_head_changed_in_base`. Each value contains `base` and `head` + arrays of changed attribute objects. + additionalProperties: + type: object + properties: + base: + type: array + items: + type: object + additionalProperties: true + head: + type: array + items: + type: object + additionalProperties: true + +branch_comparison_change: + type: object + title: branch_comparison_change + description: | + A single resource change. `from` holds the state before the change (null when the resource + was added). `to` holds the state after (null when the resource was deleted). + Fields depend on the resource type. + properties: + from: + type: object + nullable: true + additionalProperties: true + to: + type: object + nullable: true + additionalProperties: true From 747b6c16c017753df87cad1d7fddc3495af6fa42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Behrendt?= Date: Wed, 10 Jun 2026 17:05:54 +0200 Subject: [PATCH 2/2] Simplify resource names --- doc/compiled.json | 12 ++++++------ schemas.yaml | 4 ++-- schemas/branch_comparison.yaml | 12 ++++++------ 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 263a3b62a..5c5035c47 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -479,16 +479,16 @@ "description": "Comparison result of a branch against its base branch. Top-level properties correspond to\nresource types. Each resource type lists changes made in the base branch (`base_changes`),\nchanges made in the feature branch (`head_changes`), and conflicting entries (`conflicts`).\n", "properties": { "translation_keys": { - "$ref": "#/components/schemas/branch_comparison_resource_diff" + "$ref": "#/components/schemas/branch_comparison_diff" }, "translations": { - "$ref": "#/components/schemas/branch_comparison_resource_diff" + "$ref": "#/components/schemas/branch_comparison_diff" }, "locales": { - "$ref": "#/components/schemas/branch_comparison_resource_diff" + "$ref": "#/components/schemas/branch_comparison_diff" }, "tags": { - "$ref": "#/components/schemas/branch_comparison_resource_diff" + "$ref": "#/components/schemas/branch_comparison_diff" } }, "example": { @@ -556,9 +556,9 @@ } } }, - "branch_comparison_resource_diff": { + "branch_comparison_diff": { "type": "object", - "title": "branch_comparison_resource_diff", + "title": "branch_comparison_diff", "properties": { "base_changes": { "type": "array", diff --git a/schemas.yaml b/schemas.yaml index b4e6a1ac5..02c46b8f4 100644 --- a/schemas.yaml +++ b/schemas.yaml @@ -8,8 +8,8 @@ schemas: "$ref": schemas/blacklisted_key.yaml#/blacklisted_key branch_comparison: "$ref": schemas/branch_comparison.yaml#/branch_comparison - branch_comparison_resource_diff: - "$ref": schemas/branch_comparison.yaml#/branch_comparison_resource_diff + branch_comparison_diff: + "$ref": schemas/branch_comparison.yaml#/branch_comparison_diff branch_comparison_change: "$ref": schemas/branch_comparison.yaml#/branch_comparison_change comment: diff --git a/schemas/branch_comparison.yaml b/schemas/branch_comparison.yaml index 127a193ad..53f0fd47d 100644 --- a/schemas/branch_comparison.yaml +++ b/schemas/branch_comparison.yaml @@ -8,13 +8,13 @@ branch_comparison: changes made in the feature branch (`head_changes`), and conflicting entries (`conflicts`). properties: translation_keys: - "$ref": "#/branch_comparison_resource_diff" + "$ref": "#/branch_comparison_diff" translations: - "$ref": "#/branch_comparison_resource_diff" + "$ref": "#/branch_comparison_diff" locales: - "$ref": "#/branch_comparison_resource_diff" + "$ref": "#/branch_comparison_diff" tags: - "$ref": "#/branch_comparison_resource_diff" + "$ref": "#/branch_comparison_diff" example: translation_keys: base_changes: @@ -65,9 +65,9 @@ branch_comparison: head_changes: [] conflicts: {} -branch_comparison_resource_diff: +branch_comparison_diff: type: object - title: branch_comparison_resource_diff + title: branch_comparison_diff properties: base_changes: type: array