Discuss usage and public API for tool

[asgrim]

So far we have not defined or even discussed what kind of usage this tool has. Creating this issue to discuss and formalise usage, before 1.0.0.

[asgrim]

brain dump:

• @Ocramius mentioned we should aim for the tool to simply be added to CI
• need to determine what is the "last" version automatically to do this (maybe ocramius/package-versions could help? if not, would have to pull from git porcelain directly?)
• obviously use yaml for any configuration 😈
• what configuration? maybe disable specific checks, tho seems like a bad idea............

[Ocramius]

• need to determine what is the "last" version automatically to do this (maybe ocramius/package-versions could help? if not, would have to pull from git porcelain directly?)

More like the last stable minor. For instance, if we are On 2.5.7, the BC compatibility should be computed from 2.5.0

obviously use yaml for any configuration 😈

You are dead to me.

[Ocramius]

what configuration? maybe disable specific checks, tho seems like a bad idea............

Don't think we need any configuration for now

[asgrim]

I think the usage should be something like:

• composer require --dev roave/api-compare
• Add vendor/bin/api-compare to CI
• As above, should detect the last stable minor version
  • Clone & check out old version in a temp workspace & switch to last major
  • Run the comparator of the current checkout vs the temp workspace

However, failing the build may not be desirable; just because there is a BC break, doesn't mean the build should fail (i.e. a new major version may be being prepared), so not sure how we can "flag" this to the user... I wonder if we could somehow automatically make a comment on the github PR (if it's github)?

Additional CLI option idea: --version=<specific version to check out> if you want to compare to a specific version

[asgrim]

Output formats: --output=json --output=text --output=xml perhaps (is there anything like this, a standard, or even de-facto standard in other libs?)

[asgrim]

--output=markdown is going to be useful to generate changelogs too

[asgrim]

So; I see two use cases:

• CI as above
• Running manually to identify differences: e.g. to generate changelogs as I mentioned

[asgrim]

Closing this as the relevant parts have been extracted to their own issues.