astropy / astropy/astro-image-display-api
Policy on how backend can propose API changes to established Protocol
- Dominant language
- Python
- Stars
- 4
- Forks
- 5
- PR merge metrics
- No merged PRs in 30d
Description
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](https://github.com/astropy/sphinx-astropy/tree/main/sphinx_astropy/conf) way of versioning, which means we have multiple versions of Protocol definitions available in a given release.
Proposed workflow:
1. 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.
4. Propose your desired changes as a draft pull request. Bonus: Have a companion pull request downstream showing how your backend would use this.
5. 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.
6. After a period of reviews and maybe back-and-forth changes, this request would either be approved or denied.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing the versioning approach in sphinx-astropy.conf and the repository's current Protocol definitions. Trace how a backend would propose a compatible or incompatible API change, including review and downstream usage. Done means the workflow is agreed and documented for future API changes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- jupyter-notebook, python
- Domain
- api, backend-api-design, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100