feat(openapi-tooling): add checks for API breaking changes #23370

aramissennyeydd · 2024-03-02T19:08:22Z

Hey, I just made a Pull Request!

This is the initial work to integrate with Optic's breaking changes checks. You can check the output from the artifacts of the API Breaking Changes (Trigger) job as comment.md. This builds on #18689 with better security.

✔️ Checklist

A changeset describing the change and affected packages. (more info)
Added or updated documentation
Tests for new functionality and regression tests for bug fixes
Screenshots attached (for UI changes)
All your commits have a Signed-off-by line in the message. (more info)

backstage-goalie · 2024-03-02T19:08:54Z

Missing Changesets

The following package(s) are changed by this PR but do not have a changeset:

@backstage/plugin-catalog-backend

See CONTRIBUTING.md for more information about how to add changesets.

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@backstage/repo-tools	packages/repo-tools	minor	`v0.8.0`
@backstage/plugin-catalog-backend	plugins/catalog-backend	none	`v1.21.1`

packages/repo-tools/src/lib/exec.ts

github-actions · 2024-03-02T19:17:40Z

Uffizzi Cluster pr-23370 was deleted.

aramissennyeydd · 2024-03-02T23:17:55Z

Summary for commit (`5f549db`)

1 API had breaking changes.

1 API had warnings.

APIs with Changes

API	Changes	Rules
/plugins/catalog-backend/	1 operation changed `POST /entities/by-refs` (changed)	⚠️ 1/2 failed

APIs with Warnings

API	Warning
/plugins/todo-backend/	No check:api script found in package.json

Routes with Breakages

/plugins/catalog-backend/
- POST /entities/by-refs request body: application/json property: fields
```
cannot make a request property required. This is a breaking change.
```

github-actions · 2024-03-09T23:53:43Z

This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution!

github-actions · 2024-03-30T20:16:43Z

This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution!

github-actions · 2024-04-08T23:53:53Z

This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution!

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>

Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

Signed-off-by: web-next-automation <web-platform@doordash.com>

camilaibs

This is super helpful, thanks for opening this pull request!
Just left non-blocking comments 🙌🏻

camilaibs · 2024-04-11T14:55:23Z

.github/workflows/api-breaking-changes-comment.yml

+        # Fetch output (zip archive) from the workflow run that triggered this workflow.
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          script: |


This script looks similar to what we are doing on the uffizzi-preview action here, would it be a good idea to put it in /scripts and reuse it somehow? BTW, I'm not sure if what I suggested is recommended, let me check with @backstage/maintainers 🙂

I think we could? The concern is users being able to edit the script and grab credentials, but I think a script in the secondary action would be fine as it would run from master.

camilaibs · 2024-04-12T13:44:27Z

packages/repo-tools/src/lib/openapi/optic/helpers.ts

+  results.completed.length > 0
+    ? `### APIs with Changes
+
+<table>


I noticed that the text is a bit hard to read because there's no indentation or syntax highlighting.... Is it possible to use a template? It would be nice to have this if it's possible and doesn't require too much effort. It might not be changed frequently, so I understand if it's not worth it

I agree it's not super readable, but I pulled this pretty much intact from the Optic codebase and I'd prefer to keep it as is for now to handle any updates to keep it in line with the output from Optic CLI.

camilaibs · 2024-04-12T13:58:14Z

plugins/catalog-backend/package.json

@@ -42,6 +42,7 @@
  ],
  "scripts": {
    "build": "backstage-cli package build",
+    "check:api": "backstage-repo-tools package schema openapi check",


Nit: This is something that may be not noticed by plugin developers who don't see the changelog. Is there a way to show what's new in this cli? For example, if you use the verify command log that there is a new check command as well, or perhaps other ideas to make this more visible to other plugin developers since it's optional?

I haven't put much thought into it, new commands in CLI seems like a hard problem to tackle, any examples of what you're suggesting that you could point me to?

camilaibs · 2024-04-12T13:59:54Z

packages/repo-tools/package.json

@@ -49,6 +49,7 @@
    "@stoplight/spectral-rulesets": "^1.18.0",
    "@stoplight/spectral-runtime": "^1.1.2",
    "@stoplight/types": "^14.0.0",
+    "@useoptic/openapi-utilities": "^0.54.8",


Curiosity: The community version of optic appears to be sufficient for us. Do you have any concerns?

Not sure I'm following, wdym?

packages/repo-tools/src/commands/index.ts

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

freben

Alright, I'd say let's try this out and then tweak if needed. Maybe consolidate the scripts or so if we feel it gets unwieldy. But for now ... happy to merge and iterate

github-actions · 2024-05-02T15:10:10Z

Thank you for contributing to Backstage! The changes in this pull request will be part of the 1.27.0 release, scheduled for Tue, 14 May 2024.

github-actions bot added the area:catalog Related to the Catalog Project Area label Mar 2, 2024

github-advanced-security bot found potential problems Mar 2, 2024

View reviewed changes

packages/repo-tools/src/lib/exec.ts Fixed Show fixed Hide fixed

aramissennyeydd marked this pull request as ready for review March 2, 2024 23:35

aramissennyeydd requested review from a team and backstage-service as code owners March 2, 2024 23:35

aramissennyeydd requested review from freben, camilaibs and Edje-C March 2, 2024 23:35

github-actions bot added the stale label Mar 9, 2024

aramissennyeydd removed the stale label Mar 11, 2024

aramissennyeydd force-pushed the openapi-tooling/breaking-changes branch from 62490e5 to d5c2f8d Compare March 16, 2024 04:06

github-actions bot added the stale label Mar 23, 2024

backstage deleted a comment from github-actions bot Mar 23, 2024

aramissennyeydd removed the stale label Mar 23, 2024

github-actions bot added the stale label Mar 30, 2024

freben removed the stale label Mar 30, 2024

github-actions bot added the stale label Apr 8, 2024

aramissennyeydd added 5 commits April 8, 2024 20:58

feat(openapi-tooling): add breaking changes checks to the verify command

665d118

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

example breakage

0b3fac6

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

testing using the uffizzi workflow

7cd1586

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

add attribution comment as well

7b06c6c

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

update paths requirement

53c1ec2

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

aramissennyeydd and others added 13 commits April 8, 2024 20:58

update git command for GA env

fe4c265

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

use base ref instead

b0b1371

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

get the actual sha and run with that

d1b44c9

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

actually check out the needed branches

dce3d78

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

add origin to base ref

e2c9b91

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

update comment to show correctly

8f68158

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

update workflow with improved comment structure

351ae33

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

add changeset

683870a

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

revert catalog changes

d3d227d

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

revert prettier change

9341347

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

small refactoring

f4aebb8

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

add changeset

61a9e88

Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>

revert verify changes

5d091a6

Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> Signed-off-by: web-next-automation <web-platform@doordash.com>

aramissennyeydd force-pushed the openapi-tooling/breaking-changes branch from 0f78254 to 5d091a6 Compare April 9, 2024 00:59

web-next-automation added 3 commits April 8, 2024 21:01

fix merge issue

490d968

Signed-off-by: web-next-automation <web-platform@doordash.com>

add cli report

5826d70

Signed-off-by: web-next-automation <web-platform@doordash.com>

revert

fd84ca4

Signed-off-by: web-next-automation <web-platform@doordash.com>

github-actions bot removed the stale label Apr 9, 2024

camilaibs approved these changes Apr 12, 2024

View reviewed changes

aramissennyeydd added 2 commits April 20, 2024 22:15

update to diff instead of check

821f902

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

add api report

f4856e9

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

freben approved these changes May 2, 2024

View reviewed changes

freben merged commit b379061 into backstage:master May 2, 2024
36 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(openapi-tooling): add checks for API breaking changes #23370

feat(openapi-tooling): add checks for API breaking changes #23370

aramissennyeydd commented Mar 2, 2024 •

edited

Loading

backstage-goalie bot commented Mar 2, 2024 •

edited

Loading

github-actions bot commented Mar 2, 2024 •

edited

Loading

aramissennyeydd commented Mar 2, 2024 •

edited

Loading

github-actions bot commented Mar 9, 2024

github-actions bot commented Mar 30, 2024

github-actions bot commented Apr 8, 2024

camilaibs left a comment

camilaibs Apr 11, 2024 •

edited

Loading

aramissennyeydd Apr 21, 2024

camilaibs Apr 12, 2024

aramissennyeydd Apr 21, 2024

camilaibs Apr 12, 2024 •

edited

Loading

aramissennyeydd Apr 21, 2024

camilaibs Apr 12, 2024

aramissennyeydd Apr 21, 2024

freben left a comment

github-actions bot commented May 2, 2024

feat(openapi-tooling): add checks for API breaking changes #23370

feat(openapi-tooling): add checks for API breaking changes #23370

Conversation

aramissennyeydd commented Mar 2, 2024 • edited Loading

Hey, I just made a Pull Request!

✔️ Checklist

backstage-goalie bot commented Mar 2, 2024 • edited Loading

Missing Changesets

Changed Packages

github-actions bot commented Mar 2, 2024 • edited Loading

aramissennyeydd commented Mar 2, 2024 • edited Loading

Summary for commit (5f549db)

APIs with Changes

APIs with Warnings

Routes with Breakages

github-actions bot commented Mar 9, 2024

github-actions bot commented Mar 30, 2024

github-actions bot commented Apr 8, 2024

camilaibs left a comment

Choose a reason for hiding this comment

camilaibs Apr 11, 2024 • edited Loading

Choose a reason for hiding this comment

aramissennyeydd Apr 21, 2024

Choose a reason for hiding this comment

camilaibs Apr 12, 2024

Choose a reason for hiding this comment

aramissennyeydd Apr 21, 2024

Choose a reason for hiding this comment

camilaibs Apr 12, 2024 • edited Loading

Choose a reason for hiding this comment

aramissennyeydd Apr 21, 2024

Choose a reason for hiding this comment

camilaibs Apr 12, 2024

Choose a reason for hiding this comment

aramissennyeydd Apr 21, 2024

Choose a reason for hiding this comment

freben left a comment

Choose a reason for hiding this comment

github-actions bot commented May 2, 2024

aramissennyeydd commented Mar 2, 2024 •

edited

Loading

backstage-goalie bot commented Mar 2, 2024 •

edited

Loading

github-actions bot commented Mar 2, 2024 •

edited

Loading

aramissennyeydd commented Mar 2, 2024 •

edited

Loading

Summary for commit (`5f549db`)

camilaibs Apr 11, 2024 •

edited

Loading

camilaibs Apr 12, 2024 •

edited

Loading