Browse Source

Update Versioning FAQ (#2368)

* Update Versioning FAQ

Includes a new section describing our approach to minor releases, and
why they don't always include new features.

* Brian's edits

* Delete the adverb
main
Andrew Clark 5 years ago
committed by GitHub
parent
commit
db0dc83473
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
  1. 20
      content/docs/faq-versioning.md

20
content/docs/faq-versioning.md

@ -10,12 +10,14 @@ React follows [semantic versioning (semver)](https://semver.org/) principles.
That means that with a version number **x.y.z**: That means that with a version number **x.y.z**:
* When releasing **critical bug fixes**, we make a **patch release** by changing the **z** number (ex: 15.6.2 to 15.6.3).
* When releasing **new features** or **non-critical fixes**, we make a **minor release** by changing the **y** number (ex: 15.6.2 to 15.7.0).
* When releasing **breaking changes**, we make a **major release** by changing the **x** number (ex: 15.6.2 to 16.0.0). * When releasing **breaking changes**, we make a **major release** by changing the **x** number (ex: 15.6.2 to 16.0.0).
* When releasing **new features**, we make a **minor release** by changing the **y** number (ex: 15.6.2 to 15.7.0).
* When releasing **bug fixes**, we make a **patch release** by changing the **z** number (ex: 15.6.2 to 15.6.3).
Major releases can also contain new features, and any release can include bug fixes. Major releases can also contain new features, and any release can include bug fixes.
Minor releases are the most common type of release.
### Breaking Changes {#breaking-changes} ### Breaking Changes {#breaking-changes}
Breaking changes are inconvenient for everyone, so we try to minimize the number of major releases – for example, React 15 was released in April 2016 and React 16 was released in September 2017; React 17 isn't expected until 2019. Breaking changes are inconvenient for everyone, so we try to minimize the number of major releases – for example, React 15 was released in April 2016 and React 16 was released in September 2017; React 17 isn't expected until 2019.
@ -46,3 +48,17 @@ In general, we *don't* bump the major version number for changes to:
This policy is designed to be pragmatic: certainly, we don't want to cause headaches for you. If we bumped the major version for all of these changes, we would end up releasing more major versions and ultimately causing more versioning pain for the community. It would also mean that we can't make progress in improving React as fast as we'd like. This policy is designed to be pragmatic: certainly, we don't want to cause headaches for you. If we bumped the major version for all of these changes, we would end up releasing more major versions and ultimately causing more versioning pain for the community. It would also mean that we can't make progress in improving React as fast as we'd like.
That said, if we expect that a change on this list will cause broad problems in the community, we will still do our best to provide a gradual migration path. That said, if we expect that a change on this list will cause broad problems in the community, we will still do our best to provide a gradual migration path.
### If a Minor Release Includes No New Features, Why Isn't It a Patch? {#minors-versus-patches}
It's possible that a minor release will not include new features. [This is allowed by semver](https://semver.org/#spec-item-7), which states **"[a minor version] MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes."**
However, it does raise the question of why these releases aren't versioned as patches instead.
The answer is that any change to React (or other software) carries some risk of breaking in unexpected ways. Imagine a scenario where a patch release that fixes one bug accidentally introduces a different bug. This would not only be disruptive to developers, but also harm their confidence in future patch releases. It's especially regrettable if the original fix is for a bug that is rarely encountered in practice.
We have a pretty good track record for keeping React releases free of bugs, but patch releases have an even higher bar for reliability because most developers assume they can be adopted without adverse consequences.
For these reasons, we reserve patch releases only for the most critical bugs and security vulnerabilities.
If a release includes non-essential changes — such as internal refactors, changes to implementation details, performance improvements, or minor bugfixes — we will bump the minor version even when there are no new features.

Loading…
Cancel
Save