Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

tools/data-api-differ: updating the output for non-breaking changes #3575

Open
tombuildsstuff opened this issue Jan 8, 2024 · 1 comment

Comments

@tombuildsstuff
Copy link
Member

Follow on to #3573


The Data API Differ tool allows for highlighting the changes between two sets of API Definitions (typically between those in main and those in a pull request), which are output as one of many types of Changes found within this package.

These changes then allow us to determine and render the:

  1. Breaking Changes.
  2. Non-Breaking Changes (e.g. new Constant, Model, Operation or Resource ID).
  3. New Static Identifiers (e.g. a new Resource ID Segment with a fixed value).

Between two sets of API Definitions (typically between the main branch and a pull request containing the updated API Definitions) - one such example of this can be found in the comments on this Pull Request.

Whilst the outputs for Breaking Changes and New Static Identifiers are succinct, when a new API Version/Resource contains a significant number of items (e.g. Constants/Models/Operations/Resource IDs) the Non-Breaking Changes can be extremely long - for example in the case of #3570 this is output as 6420 lines of
changes, of which over 5000 lines are from a new API Version for the Network Service - which both exceeds the maximum size of a comment (on Github) and is hard to read.

That said - having this granular level of diffing is extremely useful in identifying issues that can be introduced day-to-day as the upstream API Definitions get updated, as such
#3573 looked to simplify this by skipping outputting any nested items (e.g. Constants/Models/Operations/Resource IDs) when a new API Resource is added.

As such this issue tracks updating the output so that the differences are more easily readable - and need to ensure we consider:

  1. What should the output look like when there's a new API Version?
  2. What should the output look like when there's additive changes to an existing Service/API Version/Resource? (consider new values for a constant)
  3. What should the output look like when there's breaking changes to an existing Service/API Version/Resource? (consider a constant changing the casing of values)
  4. What should the output look like when an unused Service/API Version/Resource is removed? In this case, assume that we can detect this (for example by checking if this is used in the associated Terraform Providers).

It'd probably make sense to have a summary and then more specific sections, we've talked about using expandable/collapsable markdown blocks to render this - however it's also possible to render a larger set of changes onto the Github Action itself (in addition to/as an alternative to commenting on the associated PR) - so perhaps it'd be worth having a summary of changes, and then a link to the associated comment on the Github Action result? e.g.

## Summary of Changes

### Service `Compute`

* **New API Version:** `2020-03-01`
* **Update to API Version:** `2020-02-01` (3 new constants, 2 new models)

More details [can be found here](XXX).
## Full Changes

### Service `Compute` / API Version `2020-03-01`

API Resource `Magic`

* **New Constant:** `Blah` (Values: `key: value`, `key: value`).
* **New Model:** `Blah`.
* **New Operation:** `StartThing` (URI `/some/uri`)
* **New Resource ID:** `SomeId` (ID `/some/path/to/some/id`)

### Service `Compute` / API Version `2020-02-01`

API Resource `Magic`

* **New Constant:** `First` (Values: `key: value`, `key: value`).
* **New Constant:** `Second` (Values: `key: value`, `key: value`).
* **New Constant:** `Third` (Values: `key: value`, `key: value`).
* **New Model:** `Blah`.
* **New Model:** `Other`.
@tombuildsstuff
Copy link
Member Author

Example for where we could be detecting Renames too: #4036

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant