astropy / astropy/astro-image-display-api

Policy on how backend can propose API changes to established Protocol

Open
#25 2 comments 0 reactions 0 assignees View on GitHub
from astrowidgets governance
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.