search

google / dart-shapeshift

https://google.github.io/dart-shapeshift/
Apache License 2.0
13 stars 9 forks source link

Support for automating API change detection (a feeler) #13

Closed pq closed 9 years ago

pq commented 9 years ago

I'd love to have a process in my build that verified my current public API against a baseline. I'm imagining a flow like this:

  1. create a baseline
  2. cut a release
  3. hack on code
  4. check changes against baseline and either
    • back out the changes, or
    • update my CHANGELOG and create a new baseline
  5. etc...

As a point of reference on baselines, the olde eclipse API tools come to mind.

Maybe this would be a separate tool?

srawlins commented 9 years ago

An interesting idea. So the "baseline" would be the JSON files that are output by dartdoc? And then are you wanting that step 4 is manual? Or a tool step?

Today, this whole process is possible with the dartdoc output and the shapeshift binary, and step 4 is manual.

I don't think I understand what is automated, then. Would you want a command that would diff the current code with the baseline JSON file, and then prepend to the CHANGELOG automatically?

pq commented 9 years ago

I don't mean automation in a big way, just streamline I guess. In the end, it would be nice if this could be part of a kind of pre-submit step. IOW: api_baseline_check fails if the current shape of the API does not match the baseline. It's up to the user to vet and update the baseline manually. That could be streamlined too of course and I love the idea that shapeshift could generate changelog entries for you though I expect you'll always want to inspect them. Ultimately I think it's up to the user to decide how breaking an API change is (this is just too hard a judgement for the tool to fully own). The point of the build/presubmit step would really be to communicate, "hey, your API looks different, you might want to (re)consider the change(s), update your docs, version number, etc. accordingly".

Regarding shapeshift's JSON, I haven't looked but I'm guessing it contains doc comments? I wasn't thinking that those would be part of a baseline but maybe they should be...

srawlins commented 9 years ago

That would be very cool. But I don't think it would be part of shapeshift itself...

pq commented 9 years ago

Cool. I think we could pretty easily come up with a compact baseline for APIs if we added the notion of an element signature to the analyzer. I've opened an issue to track the idea here.

Feel free to close. Thanks!