docs: add new info about angular update policies and resources (#23551)
PR Close #23551
This commit is contained in:
jenniferfell
Igor Minar
parent
266d97de95
commit
d7ed9c9e9e
|
|
@ -1,4 +1,4 @@
|
|||
# AngularJS to Angular Quick Reference
|
||||
# AngularJS to Angular Concepts: Quick Reference
|
||||
|
||||
|
||||
{@a top}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,134 @@
|
|||
# Angular versioning and releases
|
||||
|
||||
We recognize that you need stability from the Angular framework. Stability ensures that reusable components and libraries, tutorials, tools, and learned practices don't become obsolete unexpectedly. Stability is essential for the ecosystem around Angular to thrive.
|
||||
|
||||
We also share with you the desire for Angular to keep evolving. We strive to ensure that the foundation on top of which you are building is continuously improving and enabling you to stay up-to-date with the rest of the web ecosystem and your user needs.
|
||||
|
||||
This document contains the practices that we follow to provide you with a leading-edge app development platform, balanced with stability. We strive to ensure that future changes are always introduced in a predictable way. We want everyone who depends on Angular to know when and how new features are added, and to be well-prepared when obsolete ones are removed.
|
||||
|
||||
See [Updating your projects](guide/updating "Updating your projects") for information about how to update your apps and libraries to the latest version of Angular.
|
||||
|
||||
<div class="l-sub-section">
|
||||
|
||||
The practices described in this document apply to Angular 2.0 and later. If you are currently using AngularJS, see [Upgrading from AngularJS](guide/upgrade "Upgrading from Angular JS"). _AngularJS_ is the name for all v1.x versions of Angular.
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
{@a angular-versioning}
|
||||
## Angular versioning
|
||||
|
||||
Angular version numbers indicate the level of changes that are introduced by the release. This use of [semantic versioning](https://semver.org/ "Semantic Versioning Specification") helps you understand the potential impact of updating to a new version.
|
||||
|
||||
Angular version numbers have three parts: `major.minor.patch`. For example, version 5.2.9 indicates major version 5, minor version 2, and patch version 9.
|
||||
|
||||
The version number is incremented based on the level of change included in the release.
|
||||
|
||||
* Major releases contain significant new features, some but minimal developer assistance is expected during the update. When updating to a new major release, you may need to run update scripts, refactor code, run additional tests, and learn new APIs.
|
||||
|
||||
* Minor releases contain new smaller features. Minor releases are fully backward-compatible; no developer assistance is expected during update, but you can optionally modify your apps and libraries to begin using new APIs, features, and capabilities that were added in the release. We update peer dependencies in minor versions by expanding the supported versions, but we do not require projects to update these dependencies.
|
||||
|
||||
* Patch releases are low risk, bug fix releases. No developer assistance is expected during update.
|
||||
|
||||
If you are updating within the same major version, then you can skip any intermediate versions and update directly to the targeted version. For example, if you want to update from 5.0.0 to 5.2.9, then you can update directly; you do not need to update from 5.0.0 to 5.1.0 before updating to 5.2.9.
|
||||
|
||||
If you are updating from one major version to another, then we recommend that you don't skip major versions. Follow the instructions to incrementally update to the next major version, testing and validating at each step. For example, if you want to update from version 4.x.x to version 6.x.x, we recommend that you update to the latest 5.x.x release first. After successfully updating to 5.x.x, you can then update to 6.x.x.
|
||||
|
||||
Pre-release previews—such as Beta and Release Candidate versions—are indicated by appending a dash and a beta or rc identifier, such as version 5.2.9-rc.3.
|
||||
|
||||
{@a frequency}
|
||||
## Release frequency
|
||||
|
||||
We work toward a regular schedule of releases, so that you can plan and coordinate your updates with the continuing evolution of Angular.
|
||||
|
||||
In general, you can expect the following release cycle:
|
||||
|
||||
* A major release every 6 months
|
||||
|
||||
* 1-3 minor releases for each major release
|
||||
|
||||
* A patch release almost every week
|
||||
|
||||
We bake quality into our releases—and let you preview what's coming next—by providing Beta releases and release candidates (RCs) for each major and minor release.
|
||||
|
||||
This cadence of releases gives you access to new beta features as soon as they are ready, while maintaining the stability and reliability of the platform for production users.
|
||||
|
||||
|
||||
{@a schedule}
|
||||
## Release schedule
|
||||
|
||||
<div class="l-sub-section">
|
||||
|
||||
Disclaimer: The dates are offered as general guidance and may be adjusted by us when necessary to ensure delivery of a high-quality platform.
|
||||
|
||||
</div>
|
||||
|
||||
The following table contains our current target release dates for the next two major versions of Angular:
|
||||
|
||||
Date | Stable Release | Compatibility
|
||||
---------------------- | -------------- | ----------------
|
||||
September/October 2018 | 7.0.0 | ^6.0.0
|
||||
March/April 2019 | 8.0.0 | ^7.0.0
|
||||
|
||||
Compatiblity note: The primary goal of the backwards compatibility promise is to ensure that changes in the core framework and tooling don't break the existing ecosystem of components and applications and don't put undue upgrade/migration burden on Angular application and component authors.
|
||||
|
||||
|
||||
{@a lts}
|
||||
## Long-term support
|
||||
|
||||
All of our releases are supported actively for about 6 months (until the next major release), and then they are supported through long-term support (LTS) for another 12 months.
|
||||
|
||||
During the LTS period, only critical fixes and security patches will be merged and released.
|
||||
|
||||
The LTS state of one major version starts on the day of the next major release. LTS status ends approximately one year later, when we release another major version.
|
||||
|
||||
|
||||
|
||||
Version | LTS Start Date | LTS End Date
|
||||
----------- | -------------- | ------------
|
||||
^4.0.0 | October 2017 | October 2018
|
||||
^5.0.0 | April 2018 | April 2019
|
||||
^6.0.0 | October 2018 | October 2019
|
||||
|
||||
|
||||
|
||||
|
||||
{@a deprecation}
|
||||
## Deprecation practices
|
||||
|
||||
Sometimes "breaking changes", such as the removal of support for select APIs and features, are necessary to innovate and stay current with new best practices, changing dependencies, or changes in the (web) platform itself.
|
||||
|
||||
To make these transitions as easy as possible, we make two commitments to you:
|
||||
|
||||
* We work hard to minimize the number of breaking changes and to provide migration tools when possible.
|
||||
|
||||
* We follow the deprecation policy described here, so you have time to update your apps to the latest APIs and best practices.
|
||||
|
||||
To help ensure that you have sufficient time and a clear path to update, this is our deprecation policy:
|
||||
|
||||
* When announce deprecated features in the [change log](https://github.com/angular/angular/blob/master/CHANGELOG.md "Angular change log").
|
||||
|
||||
* When we announce a deprecation, we also announce a recommended update path.
|
||||
|
||||
* We support existing use of a stable API during the deprecation period, so your code will keep working during that period.
|
||||
|
||||
* We support each deprecated API for at least two subsequent major releases, which means at least 12 months after deprecation.
|
||||
|
||||
* We only make peer dependency updates that require changes to your apps in a major release. In minor releases, we update peer dependencies by expanding the supported versions, but we do not require projects to update these dependencies until a future major version.
|
||||
|
||||
|
||||
{@a public-api}
|
||||
## Public API surface
|
||||
|
||||
Angular is a collection of many packages, sub-projects, and tools. To prevent accidental use of private APIs—and so that you can clearly understand what is covered by the practices described here—we document what is and is not considered our public API surface. For details, see [Supported Public API Surface of Angular](https://github.com/angular/angular/blob/master/docs/PUBLIC_API.md "Supported Public API Surface of Angular").
|
||||
|
||||
Any changes to the public API surface will be done using the versioning, support, and depreciation policies describe above.
|
||||
|
||||
{@a labs}
|
||||
## Angular Labs
|
||||
|
||||
Angular Labs is an initiative to cultivate new features and iterate on them quickly. Angular Labs provides a safe place for exploration and experimentation by the Angular team.
|
||||
|
||||
Angular Labs projects are are not ready for production use, and no commitment is made to bring them to production. The policies and practices that are described in this document do not apply to Angular Labs projects.
|
||||
|
||||
Angular Labs projects typically are in separate branches in the Angular repo, clearly separated from the main Angular codebase.
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
# Updating your Angular projects
|
||||
|
||||
Just like Web and the entire web ecosystem, Angular is continuously improving. Angular balances continuous improvement with a strong focus on stability and making updates easy. Keeping your Angular app up-to-date enables you to take advantage of leading-edge new features, as well as optimizations and bug fixes.
|
||||
|
||||
This document contains information and resources to help you keep your Angular apps and libraries up-to-date.
|
||||
|
||||
For information about our versioning policy and practices—including
|
||||
support and deprecation practices, as well as the release schedule—see [Angular versioning and releases](guide/releases "Angular versioning and releases").
|
||||
|
||||
|
||||
<div class="l-sub-section">
|
||||
|
||||
If you are currently using AngularJS, see [Upgrading from AngularJS](guide/upgrade "Upgrading from Angular JS"). _AngularJS_ is the name for all v1.x versions of Angular.
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
{@a announce}
|
||||
## Getting notified of new releases
|
||||
|
||||
To be notified when new releases are available, follow [@angular](https://twitter.com/angular "@angular on Twitter") on Twitter or subscribe to the [Angular blog](https://blog.angular.io "Angular blog").
|
||||
|
||||
{@a learn}
|
||||
## Learning about new features
|
||||
|
||||
What's new? What's changed? We share the most important things you need to know on the Angular blog in [release announcements]( https://blog.angular.io/tagged/release%20notes "Angular blog - release announcements").
|
||||
|
||||
To review a complete list of changes, organized by version, see the [Angular change log](https://github.com/angular/angular/blob/master/CHANGELOG.md "Angular change log").
|
||||
|
||||
|
||||
{@a checking-version-app}
|
||||
## Checking your version of Angular
|
||||
|
||||
To check your app's version of Angular: From within your project directory, use the `ng version` command.
|
||||
|
||||
|
||||
{@a checking-version-angular}
|
||||
## Finding the current version of Angular
|
||||
|
||||
The most recent stable released version of Angular appears in the [Angular documentation](https://angular.io/docs "Angular documentation") at the bottom of the left side navigation. For example, `stable (v5.2.9)`.
|
||||
|
||||
You can also find the most current version of Angular by using the [CLI command `ng update`](https://github.com/angular/angular-cli/wiki/update "Angular CLI update documentation"). By default, `ng update` (without additional arguments) lists the updates that are available to you.
|
||||
|
||||
|
||||
{@a updating}
|
||||
## Updating your environment and apps
|
||||
|
||||
To make updating easy, we provide complete instructions in the interactive [Angular Update Guide](https://update.angular.io/ "Angular Update Guide").
|
||||
|
||||
The Angular Update Guide provides customized update instructions, based on the current and target versions that you specify. It includes basic and advanced update paths, to match the complexity of your applications. It also includes troubleshooting information and any recommended manual changes to help you get the most out of the new release.
|
||||
|
||||
For simple updates, the [CLI command `ng update`](https://github.com/angular/angular-cli/wiki/update "Angular CLI update documentation") is all you need. Without additional arguments, `ng update` lists the updates that are available to you and provides recommended steps to update your application to the most current version.
|
||||
|
||||
{@a resources}
|
||||
## Resource summary
|
||||
|
||||
* Release announcements: [Angular blog - release announcements](https://blog.angular.io/tagged/release%20notes "Angular blog announcements about recent releases")
|
||||
|
||||
* Release announcements (older): [Angular blog - announcements about releases prior to August 2017](https://blog.angularjs.org/search?q=available&by-date=true "Angular blog announcements about releases prior to August 2017")
|
||||
|
||||
* Release details: [Angular change log](https://github.com/angular/angular/blob/master/CHANGELOG.md "Angular change log")
|
||||
|
||||
* Update instructions: [Angular Update Guide](https://update.angular.io/ "Angular Update Guide")
|
||||
|
||||
* Update command reference: [Angular CLI update documentation](https://github.com/angular/angular-cli/wiki/update "Angular CLI update documentation")
|
||||
|
||||
* Versioning, release, support, and deprecation practices: [Angular versioning and releases](guide/releases "Angular versioning and releases")
|
||||
|
||||
* Release schedule: [Angular versioning and releases](guide/releases#schedule "Angular versioning and releases")
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Upgrading from AngularJS
|
||||
# Upgrading from AngularJS to Angular
|
||||
|
||||
_Angular_ is the name for the Angular of today and tomorrow.
|
||||
_AngularJS_ is the name for all v1.x versions of Angular.
|
||||
|
|
|
|||
|
|
@ -495,17 +495,34 @@
|
|||
},
|
||||
|
||||
{
|
||||
"title": "Upgrading",
|
||||
"title": "Keeping Up-to-Date",
|
||||
"tooltip": "Angular release practices, planning for updates, and update resources.",
|
||||
"children": [
|
||||
{
|
||||
"url": "guide/updating",
|
||||
"title": "Updating Your Projects",
|
||||
"tooltip": "Information about updating Angular applications and libraries to the latest version."
|
||||
},
|
||||
{
|
||||
"url": "guide/releases",
|
||||
"title": "Angular Releases",
|
||||
"tooltip": "Angular versioning, release, support, and deprecation policies and practices."
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
{
|
||||
"title": "Upgrading from AngularJS",
|
||||
"tooltip": "Incrementally upgrade an AngularJS application to Angular.",
|
||||
"children": [
|
||||
{
|
||||
"url": "guide/upgrade",
|
||||
"title": "Upgrading from AngularJS",
|
||||
"title": "Upgrading Instructions",
|
||||
"tooltip": "Incrementally upgrade an AngularJS application to Angular."
|
||||
},
|
||||
{
|
||||
"url": "guide/ajs-quick-reference",
|
||||
"title": "Upgrade Cheatsheet",
|
||||
"title": "AngularJS-Angular Concepts",
|
||||
"tooltip": "Learn how AngularJS concepts and techniques map to Angular."
|
||||
}
|
||||
]
|
||||
|
|
|
|||
Loading…
Reference in New Issue