Docs: How to version UI extensions

[mckn]

What this PR does / why we need it:
This aims to provide some good guide lines for how to version your extension points to allow plugin authors to change the extensions without breaking any plugins consuming the extension point.

Todo:

• Add a first draft for how to work with versions
• Add step-by-step examples for both plugin extensions and components.

Which issue(s) this PR fixes:
Fixes grafana/grafana#92202

Fixes #

Special notes for your reviewer:

[github-actions]

Hello! 👋 This repository uses Auto for releasing packages using PR labels.

✨ This PR can be merged. It will not be considered when calculating future versions of the npm packages and will not appear in the changelogs.

[josmperez]

Very nice doc! A question and a few minor style nits, otherwise LGTM. For future reference, emphasis isn't so necessary -- and we use italics instead of bold for emphasis.

[jackw]

LGTM! 🚀

[leventebalogh]

Nice one @mckn 🚀

[jarben]

LGTM!

[sympatheticmoose]

Overall this is looking good! I've made a few comments and suggestions which I would appreciate your thoughts on prior to merging

[sympatheticmoose]

non-blocking - it would be nice to have both an extension point and component example to be more explicit

[mckn]

So I started on this and it gets a bit complex to include it in the docs. I will create an issue adding it to examples (not sure I will have time before parental leave) and then reference that example in this doc. Sounds ok?

[jewbetcha]

Thanks for doing this!

[manderson-dev]

Looks like a good approach. This will take some coordination to start using.

I'm thinking we can start by adding /v1 to all our machine-learning exposed extension points, and leave the current ones there also, then ask other teams consuming our extensions to swap over to the /v1 version.

It'll be a good way to get everyone used to it.

Thanks for doing this, it'll help us a lot when introducing changes that could have impact in lots of places.

[mckn]

Looks like a good approach. This will take some coordination to start using.

I'm thinking we can start by adding /v1 to all our machine-learning exposed extension points, and leave the current ones there also, then ask other teams consuming our extensions to swap over to the /v1 version.

It'll be a good way to get everyone used to it.

Thanks for doing this, it'll help us a lot when introducing changes that could have impact in lots of places.

Super! We decided to consider the grafana-core extension points as v1 even tho they don't have the version suffix. When we need to introduce a breaking change we will create an en extension point Id with the v2 suffix.