honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update deprecation practices, update release date, edits for readability and consistency (#29644) 

PR Close #29644
This commit is contained in:
jenniferfell 2019-04-01 15:46:37 -06:00 committed by Andrew Kushnir
parent 071ee64d91
commit 75a23ab623
2 changed files with 57 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
aio/content/guide/releases.md
View File

@ -1,4 +1,4 @@
# Angular versioning and releases # 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 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.
@ -6,7 +6,6 @@ We also share with you the desire for Angular to keep evolving. We strive to ens
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. 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="alert is-helpful"> <div class="alert is-helpful">
@ -15,7 +14,7 @@ The practices described in this document apply to Angular 2.0 and later. If you
</div> </div>
{@a angular-versioning} {@a versioning}
## 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 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.
@ -24,17 +23,44 @@ Angular version numbers have three parts: `major.minor.patch`. For example, vers
The version number is incremented based on the level of change included in the release. 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. * **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. * **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.
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 7.0.0 to 7.2.11, then you can update directly; you do not need to update from 7.0.0 to 7.1.0 before updating to 7.2.11.
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 5.x.x to version 7.x.x, we recommend that you update to the latest 6.x.x release first. After successfully updating to 6.x.x, you can then update to 7.x.x. * **Patch releases** are low risk, bug fix releases. No developer assistance is expected during update.
{@a updating}
### Supported update paths
In alignment with the versioning scheme described above, we commit to support the following update paths:
* 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, you can update directly from 7.0.0 to 7.2.11.
* 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 6.x.x to version 8.x.x, we recommend that you update to the latest 7.x.x release first. After successfully updating to 7.x.x, you can then update to 8.x.x.
See [Keeping Up-to-Date](guide/updating "Updating your projects") for more information about updating your Angular projects to the most recent version.
{@a previews}
### Preview releases
We let you preview what's coming by providing Beta releases and Release Candidates (`rc`) for each major and minor release:
<!--
* **Next:** The release that is under active development. The next release is indicated by a release tag appended with the `next` identifier, such as `8.1.0-next.0`. For the next version of the documentation, see [next.angular.io](https://next.angular.io).
-->
* **Beta:** A release that is under active development and testing. A Beta release is indicated by a release tag appended with the `beta` identifier, such as `8.0.0-beta.0`.
* **Release candidate:** A release that is feature complete and in final testing. A release candidate is indicated by a release tag appended with the `rc` identifier, such as version `8.1.0-rc`.
The next version of the documentation is available at [next.angular.io](https://next.angular.io). This includes any documentation for Beta or Release Candidate features and APIs.
Pre-release previews&mdash;such as Beta and Release Candidate versions&mdash;are indicated by appending a dash and a beta or rc identifier, such as version 8.0.0-beta.10.
{@a frequency} {@a frequency}
## Release frequency ## Release frequency
@ -49,9 +75,8 @@ In general, you can expect the following release cycle:
* A patch release almost every week * A patch release almost every week
We bake quality into our releases&mdash;and let you preview what's coming next&mdash;by providing Beta releases and release candidates (RCs) for each major and minor release. This cadence of releases gives you access to new features as soon as they are ready, while maintaining the stability and reliability of the platform for production users.
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} {@a schedule}
@ -73,6 +98,8 @@ The following table contains our current target release dates for the next two m
Compatibility note: The primary goal of the backward 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. Compatibility note: The primary goal of the backward 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} {@a lts}
{@a support} {@a support}
## Support policy and schedule ## Support policy and schedule
@ -81,26 +108,29 @@ All of our major releases are supported for 18 months.
* 6 months of *active support*, during which regularly-scheduled updates and patches are released. * 6 months of *active support*, during which regularly-scheduled updates and patches are released.
* 12 months of *long-term support (LTS)*, during which only critical fixes and security patches are released. * 12 months of *long-term support (LTS)*, during which only critical fixes and security patches are released.
The following table provides the support status and key dates for Angular version 5.0.0 and higher. The following table provides the status for Angular versions under support.
Version | Status | Released | Active Ends | LTS Ends Version | Status | Released | Active Ends | LTS Ends
------- | ------ | ------------ | ------------ | ------------ ------- | ------ | ------------ | ------------ | ------------
^7.0.0 | Active | Oct 18, 2018 | Apr 18, 2019 | Apr 18, 2020 ^8.0.0 | Active | May 22, 2019 | Nov 22, 2019 | Nov 22, 2020
^7.0.0 | LTS | Oct 18, 2018 | Apr 18, 2019 | Apr 18, 2020
^6.0.0 | LTS | May 3, 2018 | Nov 3, 2018 | Nov 3, 2019 ^6.0.0 | LTS | May 3, 2018 | Nov 3, 2018 | Nov 3, 2019
^5.0.0 | LTS | Nov 1, 2017 | May 1, 2018 | May 1, 2019
LTS for Angular version ^4.0.0 ended on September 23, 2018. Angular versions ^4.0.0 and ^5.0.0 are no longer under support.
{@a deprecation} {@a deprecation}
## Deprecation practices ## Deprecation practices
Sometimes &quot;breaking changes&quot;, 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. Sometimes &quot;breaking changes&quot;, 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: To make these transitions as easy as possible, we make these commitments to you:
* We work hard to minimize the number of breaking changes and to provide migration tools when possible. * We work hard to minimize the number of breaking changes and to provide migration tools when possible.
@ -108,15 +138,16 @@ To make these transitions as easy as possible, we make two commitments to you:
To help ensure that you have sufficient time and a clear path to update, this is our deprecation policy: To help ensure that you have sufficient time and a clear path to update, this is our deprecation policy:
* We announce deprecated features in the [change log](https://github.com/angular/angular/blob/master/CHANGELOG.md "Angular change log"). * **Announcement:** We announce deprecated features in the [change log](https://github.com/angular/angular/blob/master/CHANGELOG.md "Angular change log"). Deprecated APIs appear in the [documentation](api?status=deprecated) with ~~strikethrough.~~ When we announce a deprecation, we also announce a recommended update path. For convenience, a [Deprecation Summary](guide/deprecation) is also provided.
* 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. * **Deprecation period:** When an API or a feature is deprecated, it will still be present in the [next two major releases](#schedule). After that, deprecated APIs and features will be candidates for removal. A deprecation can be announced in any release, but the removal of a deprecated API or feature will happen only in major release. Until a deprecated API or feature is removed, it will be maintained according to the LTS support policy, meaning that only critical and security issues will be fixed.
* **npm dependencies:** We only make npm 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. This means that during minor Angular releases, npm dependency updates within Angular applications and libraries are optional.
* 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} {@a public-api}

5
aio/content/guide/updating.md
View File

@ -1,4 +1,4 @@
# Updating your Angular projects # Keeping your Angular Projects Up-to-Date
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. 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.
@ -51,6 +51,9 @@ The Angular Update Guide provides customized update instructions, based on the c
For simple updates, the CLI command [`ng update`](cli/update) 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. For simple updates, the CLI command [`ng update`](cli/update) 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.
[Angular Versioning and Releases](guide/releases#versioning "Angular Release Practices, Versioning") describes the level of change that you can expect based a release's version number. It also describes supported update paths.
{@a resources} {@a resources}
## Resource summary ## Resource summary