Skip to content

Latest commit

 

History

History
80 lines (55 loc) · 2.68 KB

versioning.rst

File metadata and controls

80 lines (55 loc) · 2.68 KB
Raw

Versioning and API stability

What the version number means

.. index:: versioning

There are 3 numbers in a EXP version: A.B.C

  • A is the major version. This will rarely change and will signify very large changes.
  • B is the release number. This will include many changes including features and things that possibly break backward compatibility, although we strive to keep these cases at a minimum.
  • C is the bugfix release number. A bugfix release will not break backward compatibility, although it may add some (usually minor) new features.

Backward-incompatibilities are explicitly mentioned in the :ref:`release notes <news>`, and may require special attention before upgrading.

The latest version of EXP will always be the HEAD of the main branch. EXP developers may use temporary branches for developing and testing new features. However, these should not be expected to work until they are merged to main by a git pull request. All users outside of the EXP-code organization can contribute to development by forking the code in GitHub and submitting git pull requests to the main EXP branch based on their development branches.

For easy identification, the code maintainers will indicate a stable version on the EXP-code/EXP web page under Releases in the right-hand column of the main branch page. A release refers to a particular commit that the developers feels have no significant unresolved issues.

API stability

.. index:: API stability

We intend for the API to be stable in major versions and will try to maintain stability and backward compatibility through major versions, if possible.

Methods or functions that start with a single dash (_) are private and should never be relied upon as stable.

Also, keep in mind that stable doesn't mean complete: stable APIs could grow new methods or functionality but the existing methods should keep working the same way.

Deprecation policy

.. index:: deprecation

We aim to maintain support for deprecated EXP features for at least 1 year.

For example, if a feature is deprecated in a EXP version released on June 15th 2020, that feature should continue to work in versions released on June 14th 2021 or before that.

Any new EXP release after a year may remove support for that deprecated feature.

All deprecated features removed in a EXP release are explicitly mentioned in the :ref:`release notes <news>`.