From e4ee1194e54492cdcd5d6850d08b21747b5d2f73 Mon Sep 17 00:00:00 2001 From: Martin Staffa Date: Thu, 16 Mar 2017 12:59:37 +0100 Subject: [PATCH 1/3] docs(faq): clarify the versioning strategy - When do breaking changes appear - Relationship with Semver - Compatibility of modules --- docs/content/misc/faq.ngdoc | 75 ++++++++++++++++++++++++++----------- 1 file changed, 53 insertions(+), 22 deletions(-) diff --git a/docs/content/misc/faq.ngdoc b/docs/content/misc/faq.ngdoc index a05a2edc0b97..7386b11511a0 100644 --- a/docs/content/misc/faq.ngdoc +++ b/docs/content/misc/faq.ngdoc @@ -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. + +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" +} +``` + +#### How does AngularJS ensure code quality and guard against regressions? + +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 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. + ### Is AngularJS a templating system? From 3384876a65d578ada3ae70318ed279c9d2de6721 Mon Sep 17 00:00:00 2001 From: Martin Staffa Date: Fri, 24 Mar 2017 10:52:39 +0100 Subject: [PATCH 2/3] fixup! updates --- docs/content/misc/faq.ngdoc | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/content/misc/faq.ngdoc b/docs/content/misc/faq.ngdoc index 7386b11511a0..fdf1a1073745 100644 --- a/docs/content/misc/faq.ngdoc +++ b/docs/content/misc/faq.ngdoc @@ -33,7 +33,7 @@ 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, a measurable performance improvement, or a better -developer experience (especially with regard to updating to Angular). +developer experience (especially with regard to upgrading to Angular). 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 @@ -64,10 +64,10 @@ AngularJS code is separated into a main module ("angular"), and a few different ("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. +down to the patch number, otherwise your application might break. 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. +the following means that "angular" and "angular-animate" are always updated to the same version: ``` { @@ -76,14 +76,24 @@ the following ensures that "angular" and "angular-animate" are always updated to } ``` +If you define exact versions, make sure core and optional modules are the same: + +``` +{ + "angular": "1.6.3", + "angular-animate": "1.6.3" +} +``` + + #### How does AngularJS ensure code quality and guard against regressions? -When adding new code to branches of AngularJS, have a very stringent commit policy: +When adding new code to AngularJS, we 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. +for release notes ([see the contributing guidelines](https://github.com/angular/angular.js/blob/master/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 @@ -130,8 +140,8 @@ Yes. See instructions in {@link downloading}. ### What browsers does AngularJS work with? We run our extensive test suite against the following browsers: the latest versions of Chrome, -Firefox, Safari, and Safari for iOs, as well as Internet Explorer versions 9-11. See {@link guide/ie -Internet Explorer Compatibility} for more details on supporting legacy IE browsers. +Firefox, Safari, and Safari for iOs, Edge, as well as Internet Explorer versions 9-11. See +{@link guide/ie Internet Explorer Compatibility} for more details on supporting legacy IE browsers. If a browser is untested, it doesn't mean it won't work; for example, older Android (2.3.x) is supported in the sense that we avoid the dot notation for reserved words as property names, From df4ac0bd72e07222a03a194164de0af1d8c0b899 Mon Sep 17 00:00:00 2001 From: Martin Staffa Date: Fri, 24 Mar 2017 12:09:18 +0100 Subject: [PATCH 3/3] fixup! moar updates --- docs/content/misc/faq.ngdoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/content/misc/faq.ngdoc b/docs/content/misc/faq.ngdoc index fdf1a1073745..cb3838f6e219 100644 --- a/docs/content/misc/faq.ngdoc +++ b/docs/content/misc/faq.ngdoc @@ -90,10 +90,9 @@ If you define exact versions, make sure core and optional modules are the same: When adding new code to AngularJS, we 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; +- Every commit must pass all existing tests, contain tests for code changes, and update the documentation - Commit messages must be written in a specific manner that allows us to parse them and extract the changes -for release notes ([see the contributing guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md)). +for release notes ([see the contributing guidelines](https://github.com/angular/angular.js/blob/master/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 @@ -140,7 +139,7 @@ Yes. See instructions in {@link downloading}. ### What browsers does AngularJS work with? We run our extensive test suite against the following browsers: the latest versions of Chrome, -Firefox, Safari, and Safari for iOs, Edge, as well as Internet Explorer versions 9-11. See +Firefox, Safari, and Safari for iOS, as well as Internet Explorer versions 9-11. See {@link guide/ie Internet Explorer Compatibility} for more details on supporting legacy IE browsers. If a browser is untested, it doesn't mean it won't work; for example, older Android (2.3.x)