Skip to content

docs: add experimental API policy to contributing guide #3853

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nuglifeleoji wants to merge 1 commit into
base: main
Choose a base branch
from
+23 −0
Open

docs: add experimental API policy to contributing guide #3853

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,29 @@ The Zarr library is an implementation of a file format standard defined external

If an existing Zarr format version changes, or a new version of the Zarr format is released, then the Zarr library will generally require changes. It is very likely that a new Zarr format will require extensive breaking changes to the Zarr library, and so support for a new Zarr format in the Zarr library will almost certainly come in new `major` release. When the Zarr library adds support for a new Zarr format, there may be a period of accelerated changes as developers refine newly added APIs and deprecate old APIs. In such a transitional phase breaking changes may be more frequent than usual.


## Experimental API policy

The `zarr.experimental` namespace contains features that are under active development and may change without notice. When contributing to or depending on experimental features, please keep the following in mind:

### For contributors

When adding a new feature to `zarr.experimental`:

1. Place the feature under `src/zarr/experimental/` and export it from `src/zarr/experimental/__init__.py`.
2. Document the feature in `docs/user-guide/experimental.md` and note clearly that it is experimental.
3. Add a changelog entry categorized as `feature`.

We aim to either **promote** or **remove** experimental features within **6 months** of their addition. To promote a feature to stable:

1. Move it from `zarr.experimental` to the appropriate stable module.
2. Keep a deprecated re-export in `zarr.experimental` for one minor release.
3. Update the documentation to reflect the stable location.

### For users

Features in `zarr.experimental` carry no stability guarantees. They may be changed or removed in any release, including patch releases. If you depend on an experimental feature, pin your `zarr-python` version accordingly.

## Release procedure

Open an issue on GitHub announcing the release using the release checklist template:
Expand Down
Loading