|
| 1 | +# Versioning Strategy |
| 2 | + |
| 3 | +`twilio-python` uses a modified version of [Semantic Versioning][semver] for all |
| 4 | +changes to the helper library. It is strongly encouraged that you pin at least |
| 5 | +the major version and potentially the minor version to avoid pulling in breaking |
| 6 | +changes. |
| 7 | + |
| 8 | +Semantic Versions take the form of `MAJOR`.`MINOR`.`PATCH` |
| 9 | + |
| 10 | +When bugs are fixed in the library in a backwards compatible way, the `PATCH` |
| 11 | +level will be incremented by one. When new features are added to the library |
| 12 | +in a backwards compatible way, the `PATCH` level will be incremented by one. |
| 13 | +`PATCH` changes should _not_ break your code and are generally safe for upgrade. |
| 14 | + |
| 15 | +When a new large feature set comes online or a small breaking change is |
| 16 | +introduced, the `MINOR` version will be incremented by one and the `PATCH` |
| 17 | +version reset to zero. `MINOR` changes _may_ require some amount of manual code |
| 18 | +change for upgrade. These backwards-incompatible changes will generally be limited |
| 19 | +to a small number of function signature changes. |
| 20 | + |
| 21 | +The `MAJOR` version is used to indicate the family of technology represented by |
| 22 | +the helper library. It increased from `5.x.x` to `6.x.x` when Twilio moved to |
| 23 | +auto generation of helper libraries. Breaking changes that requires extensive |
| 24 | +reworking of code (like the `5.x.x` to `6.x.x` upgrade) will case the `MAJOR` |
| 25 | +version to be incremented by one, the `MINOR` and `PATCH` versions will be reset |
| 26 | +to zero. Twilio understands that this can be very disruptive, we will only |
| 27 | +introduce this type of breaking change when absolutely necessary. New `MAJOR` |
| 28 | +versions will be communicated in advance with `Release Candidates` and a |
| 29 | +schedule. |
| 30 | + |
| 31 | +## Supported Versions |
| 32 | + |
| 33 | +`twilio-python` follows an evergreen model of support. New features and |
| 34 | +functionality will only be added to the current version. The current version - |
| 35 | +1 will continue to be supported with bugfixes and security updates, but no new |
| 36 | +features. |
| 37 | + |
| 38 | +## Edge Features (alpha Branch) |
| 39 | + |
| 40 | +Twilio frequently rolls out new features in public and private beta periods. |
| 41 | +Twilio strives to ship early and often and bake customer feedback back into our |
| 42 | +products. To support that mission, the `twilio-python` helper library has an |
| 43 | +`Edge` version based off the `alpha` branch. This version is identified with an |
| 44 | +`alpha` metadata tag on the version number. |
| 45 | + |
| 46 | +The way the `Edge` artifact is created is by playing the `Edge` features on top |
| 47 | +of our stable artifact. The `Edge` artifact will always have the same version |
| 48 | +number as the stable artifact it was created from, but with an `alpha` suffix. |
| 49 | + |
| 50 | +For example, `6.0.0-alpha-1` is the `6.0.0` branch with `Edge` features included. |
| 51 | +If there is a change to one of the `Edge` features we may regenerate the `Edge` |
| 52 | +artifact and release a new `6.0.0-alpha-2`, new `Edge` artifacts simply increment |
| 53 | +the number after the `alpha` suffix. All `Edge` features are considered |
| 54 | +unstable and a backwards incompatible change in an `Edge` feature will not cause |
| 55 | +any version change so you should take care when upgrading from one `alpha` |
| 56 | +version to another. |
| 57 | + |
| 58 | +Once an `Edge` feature has matured it will be considered `Mainline` and included |
| 59 | +in the stable artifact, with a `MAJOR` or `MINOR` version bump. |
| 60 | + |
| 61 | +To use an `Edge` artifact in your PYTHON project you will have to make sure that |
| 62 | +you pin the artifact with `alpha` stability in your `setup.py` or `requirements.txt`. |
| 63 | + |
| 64 | +[semver]: http://semver.org/ |
0 commit comments