Github has introduced quite some new api endpoints lately, most of them requiring a preview accept-header. This to indicate the api is not stable and can change any time.

We want to support those endpoints too but by adding them to our code they fall into the semver bc policy. So we can't actually keep up with the changes github could apply to those endpoints.

So I would like to propose to mark these preview endpoints as @experimental (or another name) so the users know these endpoints are not considered stable yet. Symfony introduced this kind of system to test new features in real applications. This would allow us to actually do BC breaking changes to these endpoints.

But the annotation should not necessarily mean we will break BC, ofcourse we will/should keep the BC breaks to a minimum. It would allow us to follow and implement the update github applies to the preview api's, so when the endpoint is marked stable our code is equal to the actual endpoint. All BC breaks to those "experimental" endpoints will be documented in a separate section of the changelog in each release. This way users will have an easy way to followup on these changes.

Wdyt?

/cc Tagging some active users/contributors @Nyholm @m1guelpf @GrahamCampbell