Hello! I’m thinking of introducing versioning to t...
# generalr
red-balloon-89377
02/19/2020, 2:29 PMHello! I’m thinking of introducing versioning to the pants metrics json output. This will make it easier for consumers to keep up to date with changes when upgrading pants versions. I’m not sure this is the solution to the problem, bit I feel like it’s the best, to add a lint check that checks if one has changed the json format but not the version number. Is that fair? Or an integration test, maybe
a
average-vr-56795
02/19/2020, 2:55 PMWhat versioning are you thinking? What problem are you trying to solve? 🙂
r
red-balloon-89377
02/19/2020, 2:56 PMThe problem is “I, as a consumer of pants stats, don’t know how to keep track of changes to the json when upgrading pants versions”
red-balloon-89377
02/19/2020, 2:57 PMThe kind of versioning can be whatever, it’s just a way to signal upstream consumers “hey, you should check because there are changes to the json now”
a
average-vr-56795
02/19/2020, 3:19 PMGenerally there are two things I want to know in terms of schema changes:
1. Have you removed anything I care about?
2. Is the absence of something a sign that there was no data, or that I was using something which produced the data which didn’t produce it
3. Is there new information I may want to consume?
What specific problems are you hoping to address? :)
r
red-balloon-89377
02/19/2020, 3:20 PMThis specific case is the rename of a field, from
compile.zinccompile.rsca
average-vr-56795
02/19/2020, 3:25 PMAha, we’re making backwards incompatible changes! Ugh…
average-vr-56795
02/19/2020, 3:26 PMHonestly it feels like the problem here is that task names leaked into the public API without people giving much thought to that being an API, and if we’d been thinking about it we may have avoided that in some way?
r
red-balloon-89377
02/19/2020, 5:19 PMI think in practice it’s okay for this to be the case, because I value the flexibility of changing task names with the usual deprecation cycle a lot more than spending 1-2 hours chasing down changes once in a while, but I’d still like to make that chasing easy, if that makes sense.
red-balloon-89377
02/19/2020, 5:20 PMThat said, it’s a good design exercise to come up with a way to make this better in a principled way
g
gentle-wolf-58752
02/19/2020, 7:18 PMIIRC we current return the pants and stats versions as a
User-Agent🔥 1
👌 1
gentle-wolf-58752
02/19/2020, 7:18 PMa
aloof-angle-91616
02/19/2020, 9:22 PMa graphql schema can be used to describe arbitrary json, and for metrics/reporting i think its use is extremely interesting because supporting it means we can do graphql queries against the data. i don't know what features graphql offers regarding versioning, if any.
aloof-angle-91616
02/19/2020, 9:22 PMand @gentle-wolf-58752 thanks!! i didn't know that!
👍 1
aloof-angle-91616
02/19/2020, 9:24 PMaloof-angle-91616
02/19/2020, 9:26 PMVersioning
While there's nothing that prevents a GraphQL service from being versioned just like any other REST API, GraphQL takes a strong opinion on avoiding versioning by providing the tools for the continuous evolution of a GraphQL schema.
Why do most APIs version? When there's limited control over the data that's returned from an API endpoint, any change can be considered a breaking change, and breaking changes require a new version. If adding new features to an API requires a new version, then a tradeoff emerges between releasing often and having many incremental versions versus the understandability and maintainability of the API.
In contrast, GraphQL only returns the data that's explicitly requested, so new capabilities can be added via new types and new fields on those types without creating a breaking change. This has led to a common practice of always avoiding breaking changes and serving a versionless API.
aloof-angle-91616
02/19/2020, 9:29 PMthe way that makes sense here is, if we can have a graphql schema against the metrics API, we can have an integration test which uses some tool to perform some graphql query (as above)
4 Views