apaskulin updated https://gitlab.wikimedia.org/repos/generated-data-platform/aqs/analytics-api/-/merge_requests/10

Add stability policy

apaskulin merged https://gitlab.wikimedia.org/repos/generated-data-platform/aqs/analytics-api/-/merge_requests/10

Add stability policy

In T366974#9882212, @apaskulin wrote:

@VirginiaPoundstone, I'd like to request your sign off on the versioning page for the AQS docs site: https://doc.wikimedia.org/generated-data-platform/aqs/analytics-api/documentation/stability-policy.html

I copied the RESTBase versioning policy (see details on the merge request), but I'm happy to make any changes to better align with your plans for the future. We can keep things broad if concrete plans aren't ready yet, as long as we're setting the right expectations with users.

I also added a link to the MediaWiki API announce mailing list, which is the standard way of communicating API changes, but let me know if there's another channel you'd prefer. Edit: Such as the analytics mailing list

Edit: Updated links

@SGupta-WMF and @WDoranWMF any issues with reusing the versioning policy from RESTbase?

@apaskulin Surbhi worked on a doc outlining the versions and in it is the conclusion:

• Semantic versioning for code base using git tags and proper change management
• Versioning using request URI when we establish new URI in Phase 2 (not now)

As far as I can tell what you have drafted in the page is aligned with this.

@SGupta-WMF and @WDoranWMF any issues with reusing the versioning policy from RESTbase?

@apaskulin Surbhi worked on a doc outlining the versions and in it is the conclusion:

• Semantic versioning for code base using git tags and proper change management
• Versioning using request URI when we establish new URI in Phase 2 (not now)

As far as I can tell what you have drafted in the page is aligned with this.

I believe including the version number in the path is the right approach, as we all agreed on URI versioning.

Just wanted to call out another part of my question so it doesn't get missed: Which mailing list will you be notifying of major updates to the API? The options I'm aware of are the analytics mailing list and the api announce

@apaskulin I think we would use both of those, yes. And the policy lgtm.

apaskulin opened https://gitlab.wikimedia.org/repos/generated-data-platform/aqs/analytics-api/-/merge_requests/38

Restore updates section

apaskulin merged https://gitlab.wikimedia.org/repos/generated-data-platform/aqs/analytics-api/-/merge_requests/38

Restore updates section

Thanks! I've updated the page