search

zalando / zally

A minimalistic, simple-to-use API linter
https://zalando.github.io/zally
MIT License
885 stars 141 forks source link

Breaking change detection #981

Open viartemev opened 5 years ago

viartemev commented 5 years ago

This feature already discussed in an issue: https://github.com/zalando/zally/issues/874. Do you have a set of rules for it? Do you want to do it expandable and configurable? I found Google definitions of breaking changes and non-breaking changes, for me it looks reasonable: https://cloud.google.com/apis/design/compatibility

roxspring commented 5 years ago

Seems to me that the philosophy of Zally so far is to implement Zalando's chosen guidelines by default but that rules should be configurable and allow other deployments to make different choices. My assumption is that change detection would operate in the same way and the link above appears to be a great source of initial rules to extract.

I have a lot of respect for the ktlint and prettier approach of having strong opinions and few options, but I don't know how much we'd all agree how strict breaking change detection ought to be.

viartemev commented 5 years ago

@roxspring in this case, could breaking changes be added to violations? In this case rules can be configured as others.

roxspring commented 5 years ago

The big difference I see between existing rules and change rules is that the change rules need the additional context of some baseline version of the spec, and violations might need to reference locations in each to highlight an incompatibility. Additionally, we'd need a mechanism to identify what degree of change is acceptable for a given - i.e. some rules are likely a SHOULD for minor version bumps but MUST for bugfixes. Adding all these to existing Context, Rule, Violation potentially overcomplicates those objects for the existing codebase.

I guess I was assuming that would require a separate ChangeContext, separate ChangeRule annotation, and maybe even a ChangeViolation, but I've really not given it a great deal of thought so it might be practical to reuse much more infrastructure than I first imagined!

I think what I'm trying to get to is that I definitely see the same pattern being used but I'm not clear whether it's right and healthy to try and use the same APIs for the two different types of rule.

maxim-tschumak commented 5 years ago

First of all: I see a lot of value in this and I'm happy to provide my support.

This doesn't have to be a part of Zally server thought. I suggest creating a separate component for this purpose.

roxspring commented 5 years ago

Just to be clear @maxim-tschumak: Are you thinking this should still be part of the wider https://github.com/zalando/zally project or are you politely encouraging us to spin out an entirely separate project?

maxim-tschumak commented 5 years ago

@roxspring I hope it will be a part of the Zally project (with source code in this repository) :)