Skip to content
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.

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

Update version guarantees page #139

Merged
merged 4 commits into from
Jun 24, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions changes/139.docs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add a warning in version guarantees page, explaining pre-release guarantees (breaking changes in minor versions allowed)
21 changes: 12 additions & 9 deletions docs/pages/version_guarantees.rst
Original file line number Diff line number Diff line change
@@ -1,15 +1,18 @@
Version Guarantees
==================

This library follows `semantic versioning model <https:semver.org>`_, which means the major version
is updated every time there is an incompatible (breaking) change made to the public API. However
due to the fairly dynamic nature of Python, it can be hard to discern what can be considered a
breaking change, and what isn't.

First thing to keep in mind is that breaking changes only apply to **publicly documented
functions and classes**. If it's not listed in the documentation here, it's an internal feature,
that's it's not considered a part of the public API, and thus is bound to change. This includes
documented attributes that start with an underscore.
.. attention::
Mcproto is currently in the pre-release phase (pre v1.0.0). During this phase, these guarantees will NOT be
followed! This means that **breaking changes can occur in minor version bumps**, though micro version bumps are
still strictly for bugfixes, and will not include any features or breaking changes.

This library follows `semantic versioning model <https:semver.org>`_, which means the major version is updated every
time there is an incompatible (breaking) change made to the public API. However due to the fairly dynamic nature of
Python, it can be hard to discern what can be considered a breaking change, and what isn't.

First thing to keep in mind is that breaking changes only apply to **publicly documented functions and classes**. If
it's not listed in the documentation here, it's an internal feature, that isn't considered a part of the public API,
and thus is bound to change. This includes documented attributes that start with an underscore.

.. note::
The examples below are non-exhaustive.
Expand Down