mirror of
https://github.com/p2p-ld/numpydantic.git
synced 2024-11-15 03:04:29 +00:00
85 lines
3.1 KiB
Markdown
85 lines
3.1 KiB
Markdown
|
# Development
|
||
|
|
|
||
|
|
## Versioning
|
||
|
|
|
||
|
|
This package uses a colloquial form of [semantic versioning 2](https://semver.org/).
|
||
|
|
|
||
|
|
Specifically:
|
||
|
|
|
||
|
|
- Major version `2.*.*` is reserved for the transition from nptyping to using
|
||
|
|
`TypeVarTuple`, `Generic`, and `Protocol`. Until `2.*.*`...
|
||
|
|
- breaking changes will be indicated with an advance in `MINOR`
|
||
|
|
version, taking the place of `MAJOR` in semver
|
||
|
|
- backwards-compatible bugfixes **and** additions in functionality
|
||
|
|
will be indicated by a `PATCH` release, taking the place of `MINOR` and
|
||
|
|
`PATCH` in semver.
|
||
|
|
- After `2.*.*`, semver as usual will resume
|
||
|
|
|
||
|
|
You are encouraged to set an upper bound on your version dependencies until
|
||
|
|
we pass `2.*.*`, as the major function of numpydantic is stable,
|
||
|
|
but there is still a decent amount of jostling things around to be expected.
|
||
|
|
|
||
|
|
|
||
|
|
### API Stability
|
||
|
|
|
||
|
|
- All breaking changes to the **public API** will be signaled by a major
|
||
|
|
version's worth of deprecation warnings
|
||
|
|
- All breaking changes to the **development API** will be signaled by a
|
||
|
|
minor version's worth of deprecation warnings.
|
||
|
|
- Changes to the remainder of the package, whether marked as private with a
|
||
|
|
leading underscore or not, including the import structure of the package,
|
||
|
|
are not considered part of the API and should not be relied on as stable
|
||
|
|
until explicitly marked otherwise.
|
||
|
|
|
||
|
|
#### Public API
|
||
|
|
|
||
|
|
**Only the {class}`.NDArray` and {class}`.Shape` classes should be considered
|
||
|
|
part of the stable public API.**
|
||
|
|
|
||
|
|
All associated functionality for validation should also be considered
|
||
|
|
a stable part of the `NDArray` and `Shape` classes - functionality
|
||
|
|
will only be added here, and the departure for the string-form of the
|
||
|
|
shape specifications (and its removal) will take place in `v3.*.*`
|
||
|
|
|
||
|
|
End-users of numpydantic should pin an upper bound for the `MAJOR` version
|
||
|
|
until after `v2.*.*`, after which time it is up to your discretion -
|
||
|
|
no breaking changes are planned, but they would be signaled by a major version change.
|
||
|
|
|
||
|
|
#### Development API
|
||
|
|
|
||
|
|
**Only the {class}`.Interface` class and its subclasses,
|
||
|
|
along with the Public API,
|
||
|
|
should be considered part of the stable development API.**
|
||
|
|
|
||
|
|
The `Interface` class is the primary point of external development expected
|
||
|
|
for numpydantic. It is still somewhat in flux, but it is prioritized for stability
|
||
|
|
and deprecation warnings above the rest of the package.
|
||
|
|
|
||
|
|
Dependent packages that define their own `Interface`s should pin an upper
|
||
|
|
bound for the `PATCH` version until `2.*.*`, and afterwards likely pin a `MINOR` version.
|
||
|
|
Tests are designed such that it should be easy to test major features against
|
||
|
|
each interface, and that work is also ongoing. Once the test suite reaches
|
||
|
|
maturity, it should be possible for any downstream interfaces to simply use those to
|
||
|
|
ensure they are compatible with the latest version.
|
||
|
|
|
||
|
|
## Release Schedule
|
||
|
|
|
||
|
|
There is no release schedule. Versions are released according to need and available labor.
|
||
|
|
|
||
|
|
## Contributing
|
||
|
|
|
||
|
|
### Dev environment
|
||
|
|
|
||
|
|
```{todo}
|
||
|
|
Document dev environment
|
||
|
|
|
||
|
|
Really it's very simple, you just clone a fork and install
|
||
|
|
the `dev` environment like `pip install '.[dev]'`
|
||
|
|
```
|
||
|
|
|
||
|
|
### Pull Requests
|
||
|
|
|
||
|
|
```{todo}
|
||
|
|
Document pull requests if we ever receive one
|
||
|
|
```
|