astrowidgets
astrowidgets copied to clipboard
astropy
Policy on how backend can propose API changes to established Protocol
The situation: astrowidgets finally has a stable release with established API. A backend developer realized that the API does not satisfy certain requirements (either specific for the backend or in general). For instance, maybe the API needs extra keyword to support Jupyter Notebook version 999 that just came out. Or maybe astronomers found yet another way to represent the World Coordinates System that requires API change.
Assumption:
- We went with the sphinx-astropy.conf way of versioning, which means we have multiple versions of Protocol definitions available in a given release.
Proposed workflow:
- Decide if this API change can be backward compatible.
2a. If yes, how far back is it compatible? This is only applicable if astrowidgets has more than one stable release by the time this happens. 2b. If no, why not?
3a. For each backward compatible Protocol module, apply the desired changes in a backward compatible way. 3b. Apply the desired changes only in the unreleased Protocol module.
-
Propose your desired changes as a draft pull request. Bonus: Have a companion pull request downstream showing how your backend would use this.
-
Ping interested parties to review the draft pull request. Maybe includes sending out a memo to astropy-dev mailing list and relevant channel(s) in Astropy Slack.
-
After a period of reviews and maybe back-and-forth changes, this request would either be approved or denied.
Sorry for the long delay in looking at this. This approach looks good to me.
Maybe we put this somewhere in docs when finalized, so it will be part of RTD doc.