Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

docs(faq): clarify the versioning strategy #15845

Merged
merged 3 commits into from
Mar 24, 2017
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 53 additions & 22 deletions docs/content/misc/faq.ngdoc
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updating --> upgrading (?)


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`.
Expand All @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The 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"
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add another example where versions are really locked as well?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mean locked down to the patch version without ~?

Copy link
Member

Choose a reason for hiding this comment

The 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:
Copy link
Member

Choose a reason for hiding this comment

The 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.
Also: have --> we have (?)


- Every commit must contain tests and documentation updates alongside the code changes and that all the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and that all --> and all (?)

Copy link
Member

Choose a reason for hiding this comment

The 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.
Copy link
Member

Choose a reason for hiding this comment

The 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.
Copy link
Member

Choose a reason for hiding this comment

The 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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't notice they were there before 😕 Fair enough.
👍 on rewording.



### Is AngularJS a templating system?

Expand Down