-
Notifications
You must be signed in to change notification settings - Fork 27.4k
docs(faq): clarify the versioning strategy #15845
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -25,37 +25,30 @@ So it's definitely not a plugin or some other native browser extension. | |
In AngularJS we do not allow intentional breaking changes to appear in versions where only the "patch" | ||
number changes. For example between 1.3.12 and 1.3.13 there can be no breaking changes. We do allow | ||
breaking changes happen between "minor" number changes. For example between 1.3.15 and 1.4.0 there | ||
will be a number of breaking changes. We also allow breaking changes between beta releases of AngularJS. | ||
are a number of breaking changes. That means AngularJS does not follow | ||
[semantic versioning (semver)](http://semver.org/) where breaking changes are only | ||
allowed when the "major" version changes. | ||
|
||
We also allow breaking changes between beta releases of AngularJS. | ||
For example between 1.4.0-beta.4 and 1.4.0-beta.5 there may be breaking changes. We try hard to minimize | ||
these kinds of change only to those where there is a strong use case such as a strongly requested feature | ||
improvement, a considerable simplification of the code or a measurable performance improvement. | ||
|
||
When adding new code to branches of AngularJS, have a very stringent commit policy: | ||
|
||
- Every commit must contain tests and documentation updates alongside the code changes and that all the | ||
tests must pass; | ||
- Commit messages must be written in a specific manner that allows us to parse them and extract the changes | ||
for release notes. | ||
|
||
The AngularJS code base has a very large set of unit tests (over 4000) and end to end tests, which are pretty | ||
comprehensive. This means that a breaking change will require one or more tests to be changed to allow the | ||
tests to pass. So when a commit includes tests that are being removed or modified, this is a flag that the | ||
code might include a breaking change. When reviewing the commit we can then decide whether there really is | ||
a breaking change and if it is appropriate for the branch to which it is being merged. If so, then we | ||
require that the commit message contains an appropriate breaking change message. | ||
|
||
Additionally, when a commit lands in our master repository it is synced to Google where we test it against | ||
over 2000 applications using the test suites of these applications. This allows us to catch regressions | ||
quickly before a release. We've had a pretty good experience with this setup. Only bugs that affect features | ||
not used at Google or without sufficient test coverage, have a chance of making it through. | ||
improvement, a considerable simplification of the code, a measurable performance improvement, or a better | ||
developer experience (especially with regard to updating to Angular). | ||
|
||
Lastly, when we are making a release we generate updates to the changelog directly from the commits. This | ||
When we are making a release we generate updates to the changelog directly from the commits. This | ||
generated update contains a highlighted section that contains all the breaking changes that have been | ||
extracted from the commits. We can quickly see in the new changelog exactly what commits contain breaking | ||
changes and so can application developers when they are deciding whether to update to a new version of | ||
AngularJS. | ||
|
||
Features with non-breaking changes can also appear in the "patch" version, e.g. in version 1.6.3 there might | ||
be a feature that is not available in 1.6.2. | ||
|
||
Finally, deprecation of features might also appear in "minor" version updates. That means the features | ||
will still work in this version, but sometimes must be activated specifically. | ||
|
||
#### When are deprecated features removed from the library? | ||
|
||
Most of the time we remove a deprecated feature in a next minor version bump. For example, the | ||
`preAssignBindingsEnabled` `$compileProvider` method was defined in AngularJS `1.5.10`, deprecated in `1.6` and | ||
will be removed in `1.7`. | ||
|
@@ -65,6 +58,44 @@ is also deprecated but we only remove the feature once it's removed from jQuery | |
jqLite and jQuery. One such example is the `bind` method, deprecated in favor of `on` but unlikely to be removed | ||
from jqLite any time soon. | ||
|
||
#### What is the version compatibility between AngularJS main and optional modules? | ||
|
||
AngularJS code is separated into a main module ("angular"), and a few different optional modules | ||
("angular-animate", "angular-route" etc) that are dependant on the main module. | ||
When a new AngularJS version is released, all modules are updated to the new version. | ||
This means that the main module and the optional modules must always have the exact same version, | ||
down the patch number, otherwise your application might break. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. down the --> down to the (?) |
||
|
||
Therefore you must always explicitly lock down your dependencies, for example in the package.json, | ||
the following ensures that "angular" and "angular-animate" are always updated to the same version. | ||
|
||
``` | ||
{ | ||
"angular": "~1.6.0", | ||
"angular-animate": "~1.6.0" | ||
} | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe add another example where versions are really locked as well? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You mean locked down to the patch version without ~? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes, to indicate that if you lock to a specific version, all versions need to be the same. |
||
``` | ||
|
||
#### How does AngularJS ensure code quality and guard against regressions? | ||
|
||
When adding new code to branches of AngularJS, have a very stringent commit policy: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Not sure what "branches" refers to 😁 Update: I get it now (after reading further below), but people won't know. |
||
|
||
- Every commit must contain tests and documentation updates alongside the code changes and that all the | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. and that all --> and all (?) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. and that all --> and all (or is it intentional?) |
||
tests must pass; | ||
- Commit messages must be written in a specific manner that allows us to parse them and extract the changes | ||
for release notes. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Let's add a link to the commit message guidelines (or CONTRIBUTING.md). |
||
|
||
The AngularJS code base has a very large set of unit tests and end-to-end tests. This means that a breaking change will require one or more tests to be changed to allow the | ||
tests to pass. So when a commit includes tests that are being removed or modified, this is a flag that the | ||
code might include a breaking change. When reviewing the commit we can then decide whether there really is | ||
a breaking change and if it is appropriate for the branch to which it is being merged. If so, then we | ||
require that the commit message contains an appropriate breaking change message. | ||
|
||
Additionally, commits are periodically synced to Google where we test it against applications using | ||
the test suites of these applications. This allows us to catch regressions | ||
quickly before a release. We've had a pretty good experience with this setup. Only bugs that affect features | ||
not used at Google or without sufficient test coverage, have a chance of making it through. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I am not sure the last two paragraphs are super-relevant to external contributors. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I assume they are meant to inspire confidence in the stability of AngularJS (I've just reworded them from their previous state) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I didn't notice they were there before 😕 Fair enough. |
||
|
||
|
||
### Is AngularJS a templating system? | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
updating --> upgrading (?)