mirror of
https://github.com/dream-num/univer.git
synced 2026-09-19 10:29:12 +08:00
95 lines
4.8 KiB
Markdown
95 lines
4.8 KiB
Markdown
# API Stability Policy
|
|
|
|
This document defines how Univer treats public APIs, experimental APIs, internal APIs, deprecations, and breaking changes.
|
|
|
|
Univer is currently pre-1.0, so the project can still make breaking changes when they are needed for architecture, correctness, or long-term maintainability. Even in pre-1.0 releases, the project should make API risk visible before users depend on it.
|
|
|
|
## Stability Levels
|
|
|
|
### Stable
|
|
|
|
Stable APIs are intended for application and plugin developers.
|
|
|
|
An API is stable when it is exported from a public package entry point and is documented in the generated API reference, package README, guide, or examples without an experimental warning.
|
|
|
|
Examples include:
|
|
|
|
- Public package entry points such as `@univerjs/core`, `@univerjs/sheets`, and `@univerjs/presets`.
|
|
- Documented Facade APIs such as workbook, worksheet, range, formula, and document APIs.
|
|
- Public plugin classes, configuration types, commands, and service interfaces documented for extension authors.
|
|
|
|
Stable APIs should not be removed or changed incompatibly without a deprecation path.
|
|
|
|
### Experimental
|
|
|
|
Experimental APIs are usable, but their behavior, names, parameters, or package location may change.
|
|
|
|
An API is experimental when any of the following is true:
|
|
|
|
- It is documented as experimental, alpha, beta, preview, or under active development.
|
|
- It belongs to a product surface that is explicitly marked as under active development.
|
|
- It is exposed for early integration feedback before the project has committed to its final shape.
|
|
|
|
Experimental APIs should include a short note in docs or JSDoc that explains the instability. Breaking changes to experimental APIs should still be called out in release notes when they affect users.
|
|
|
|
### Internal
|
|
|
|
Internal APIs are implementation details and are not covered by compatibility guarantees.
|
|
|
|
An API should be treated as internal when it is:
|
|
|
|
- Not documented for application or plugin authors.
|
|
- Located under implementation folders such as controllers, render controllers, models, views, utilities, or test helpers without a public export contract.
|
|
- Exported only to support package composition inside the monorepo.
|
|
- Marked `@internal`, `@private`, or described as implementation-only.
|
|
|
|
Avoid depending on internal APIs in user applications. If an internal API is needed for real integrations, open an issue or discussion so it can be promoted to a public API intentionally.
|
|
|
|
### Deprecated
|
|
|
|
Deprecated APIs are still available for compatibility, but users should migrate away from them.
|
|
|
|
When deprecating an API:
|
|
|
|
1. Mark it with `@deprecated` in JSDoc and link to the replacement when one exists.
|
|
2. Log a deprecation warning through `ILogService` when runtime usage can be detected without excessive noise.
|
|
3. Add migration guidance in the relevant guide, README, or release notes when the API is broadly used.
|
|
|
|
Deprecated stable APIs should remain available until the next major release unless the API is unsafe, broken, or impossible to preserve. In pre-1.0 releases, removals may happen in a minor release, but they should be documented as breaking changes.
|
|
|
|
## Breaking Changes
|
|
|
|
A change is breaking when it requires users to modify application code, plugin code, build configuration, package versions, persisted data assumptions, or runtime integration behavior.
|
|
|
|
Breaking changes should be documented in the changelog or release notes with:
|
|
|
|
- The affected package or feature area.
|
|
- What changed.
|
|
- Why the change was necessary.
|
|
- The migration path or replacement API.
|
|
|
|
Pull requests that introduce breaking changes should include a `BREAKING CHANGE:` section in the PR description.
|
|
|
|
## Package Version Alignment
|
|
|
|
Keep all `@univerjs/*` packages on the same version. If an application uses Univer Pro packages, keep all `@univerjs-pro/*` packages aligned with the matching Univer release line as well.
|
|
|
|
Mixing package versions can bypass compatibility checks and produce runtime failures, especially around plugin registration, Facade API composition, locales, commands, and shared data models.
|
|
|
|
## Public API Checklist
|
|
|
|
Before exposing a new public API, confirm that:
|
|
|
|
- The API has a clear owner package and entry point.
|
|
- The name follows the repository naming convention.
|
|
- The API works in the intended runtime: browser, Node.js, worker, or shared.
|
|
- Facade APIs are registered by the correct package or preset.
|
|
- The API has tests for expected behavior and at least one usage example or reference entry.
|
|
- Experimental status is explicitly documented if the design is not final.
|
|
|
|
## User Expectations
|
|
|
|
Users can rely on documented stable APIs as the preferred integration surface. Users should expect experimental APIs to evolve and internal APIs to change without notice.
|
|
|
|
If the documentation and package exports disagree, treat the documentation as the intended public contract and report the mismatch.
|