Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs: deprecations usage improvements and one tech change #30400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 1 commit into from
Closed

docs: deprecations usage improvements and one tech change #30400

wants to merge 1 commit into from

Conversation

jenniferfell
Copy link
Contributor

@jenniferfell jenniferfell commented May 10, 2019 •
edited
Loading

PR Checklist

Please check if your PR fulfills the following requirements:

PR Type

What kind of change does this PR introduce?

  • Bugfix
  • Feature
  • Code style update (formatting, local variables)
  • Refactoring (no functional changes, no api changes)
  • Build related changes
  • CI related changes
  • Documentation content changes
  • angular.io application / infrastructure changes
  • Other... Please describe:

What is the current behavior?

  • API subsections are H4
  • Pipes section talks about removal candidate "in the next major version"
  • No quick way to see what might be removed in the next major version

Issue Number: N/A

What is the new behavior?

  • API subsections are H3
  • Pipes section talks about removal candidate "in version 9"
  • Added index to this doc, by removal candidate version. If something was a candidate for removal in v7 or v8, rounded up to say v9 because that's the next opportunity to remove them

Does this PR introduce a breaking change?

  • Yes
  • No

Other information

@jenniferfell jenniferfell requested a review from IgorMinar as a code owner May 10, 2019 18:37
@ngbot ngbot bot added this to the needsTriage milestone May 10, 2019
@jenniferfell jenniferfell added subtype: docs-clarification feature Issue that requests a new feature target: patch This PR is targeted for the next patch release labels May 10, 2019
@mary-poppins
Copy link

You can preview 7212366 at https://pr30400-7212366.ngbuilds.io/.

@jenniferfell
Copy link
Contributor Author

In nav, see Release Information > Deprecations

@jenniferfell jenniferfell requested a review from StephenFluin May 10, 2019 19:10
@jenniferfell
Copy link
Contributor Author

@IgorMinar : Fixed heading levels and "in the next major version"(from your previous comments)
@gkalpak @StephenFluin @brandonroberts : Added index by the release in which a feature can be removed (per a couple votes from y'all on focusing on future-proofing apps as soon as practical, instead of focusing on the past or anything that encourages foot-dragging on migration)

Note: Many of the items listed as candidates for removal in v9 were actually candidates for removal in v7 and v8, but v9 is the next opportunity for removal. See comments in markup for details.

@jenniferfell jenniferfell mentioned this pull request May 10, 2019
Closed
trotyl
trotyl reviewed May 11, 2019
View reviewed changes
aio/content/guide/deprecations.md Outdated
| `@angular/upgrade` | [`@angular/upgrade`](#upgrade) | <!--v8--> v9 |
| `@angular/upgrade` | [`getAngularLib`](#upgrade-static) | <!--v8--> v9 |
| `@angular/upgrade` | [`setAngularLib`](#upgrade-static) | <!--v8--> v9 |
| template syntax | [`/deep/`, `>>>`, and `::ng-deep`](#component-styles) | <!--v7--> v9 |
Copy link
Contributor

Choose a reason for hiding this comment

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

::ng-deep was only deprecated but never planed to be removed in future.

Copy link
Contributor Author

@jenniferfell jenniferfell May 14, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

@IgorMinar : Need engineering confirmation. The docs say that it is going to be removed: https://angular.io/guide/component-styles#deprecated-deep--and-ng-deep

"The shadow-piercing descendant combinator is deprecated and support is being removed from major browsers and tools. As such we plan to drop support in Angular (for all 3 of /deep/, >>> and ::ng-deep). Until then ::ng-deep should be preferred for a broader compatibility with the tools."

Copy link
Contributor

Choose a reason for hiding this comment

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

Ref #17867 (comment)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Related #25160

Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah, I don't think that we should mark this as scheduled for removal in Angular version 9. We need to get the alternative feature shipped first and work has not started on it.

Copy link
Contributor

Choose a reason for hiding this comment

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

@StephenFluin thoughts?

@jenniferfell jenniferfell force-pushed the jfell-deprecation-updates branch 2 times, most recently from 226235d to 9b64f47 Compare May 14, 2019 05:59
@jenniferfell jenniferfell changed the title docs: deprecations usage improvements docs: deprecations usage improvements and one tech change May 14, 2019
@mary-poppins
Copy link

You can preview 9fd3ee7 at https://pr30400-9fd3ee7.ngbuilds.io/.

@mary-poppins
Copy link

You can preview 226235d at https://pr30400-226235d.ngbuilds.io/.

@mary-poppins
Copy link

You can preview 9b64f47 at https://pr30400-9b64f47.ngbuilds.io/.

Splaktar
Splaktar approved these changes May 14, 2019
View reviewed changes
Copy link
Contributor

@Splaktar Splaktar left a comment

Choose a reason for hiding this comment

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

LGTM in general. I think that the h4 to h3 change helped, but I still feel like the general structure of the page needs some improvements. Perhaps just some better white space would help, but it also feels a little odd having a huge list of deprecated APIs come first and then the latest removed APIs (which are likely the most frequently updated and interesting) left to the end.

@jenniferfell
Copy link
Contributor Author

@Splaktar Thanks for looking at this, and so quickly! I'll try to look at the white space tonight. Re the overall structure, we also have release notes for each release, which are intended to highlight exactly what is announced as deprecated or being removed in that particular release happening right now. So, I went with an org that focuses on the idea that "you need to migrate off all of these things in the next 18 months." As deprecated features are removed, they fall to the bottom of the page...or perhaps even off the page. We're not sure how far back we want this list of removals to go, but we had to have a place in AIO (not in the release note on the blog) that helped with redirects for @angular/http api pages.

Pondering your comments more. Maybe we can slack when I'm online next week. Thanks again!

@brandonroberts brandonroberts force-pushed the jfell-deprecation-updates branch from 9b64f47 to 92d290a Compare May 17, 2019 13:09
@brandonroberts brandonroberts added the action: merge The PR is ready for merge by the caretaker label May 17, 2019
@mary-poppins
Copy link

You can preview 92d290a at https://pr30400-92d290a.ngbuilds.io/.

@trotyl
Copy link
Contributor

trotyl commented May 21, 2019

"Candidate for removal at version x" does not mean that it will be removed

Then any reason for calling it "candidate for removal at version X" if it's never designed to be removed at version X?

there are features that were announced as deprecated in versions 4 and 5 but are not yet removed.

"Removal delayed" and "removal not planed" are different scenarios, the former is ready to be removed and the latter is not.

@googlebot
Copy link

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored or co-authored by someone other than the pull request submitter. We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of all the commit author(s), set the cla label to yes (if enabled on your project), and then merge this pull request when appropriate.

ℹ️ Googlers: Go here for more info.

@googlebot
Copy link

A Googler has manually verified that the CLAs look good.

(Googler, please make sure the reason for overriding the CLA status is clearly documented in these comments.)

ℹ️ Googlers: Go here for more info.

@IgorMinar IgorMinar mentioned this pull request May 21, 2019
Closed
IgorMinar
IgorMinar approved these changes May 21, 2019
View reviewed changes
Copy link
Contributor

@IgorMinar IgorMinar left a comment

Choose a reason for hiding this comment

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

I pushed a few more commits with changes I made. quick summary:

@googlebot
Copy link

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored or co-authored by someone other than the pull request submitter. We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of all the commit author(s), set the cla label to yes (if enabled on your project), and then merge this pull request when appropriate.

ℹ️ Googlers: Go here for more info.

@jenniferfell jenniferfell force-pushed the jfell-deprecation-updates branch from 37572b4 to c86c63e Compare May 21, 2019 17:11
@googlebot
Copy link

CLAs look good, thanks!

ℹ️ Googlers: Go here for more info.

@jenniferfell
Copy link
Contributor Author

  • Rebased
  • Removed other mention of deprecatedOverrideProvider from the doc.
  • Squashed commits

@jenniferfell jenniferfell force-pushed the jfell-deprecation-updates branch from c86c63e to 372dc7a Compare May 21, 2019 18:11
@mary-poppins
Copy link

You can preview 372dc7a at https://pr30400-372dc7a.ngbuilds.io/.

@IgorMinar
Copy link
Contributor

this now conflicts. I'm going to rebase it.

@IgorMinar IgorMinar force-pushed the jfell-deprecation-updates branch from 372dc7a to 1b38235 Compare May 21, 2019 20:42
@IgorMinar
Copy link
Contributor

rebased + forcepushed

@mary-poppins
Copy link

You can preview 1b38235 at https://pr30400-1b38235.ngbuilds.io/.

jasonaden pushed a commit that referenced this pull request May 21, 2019
@jenniferfell @jasonaden
docs: deprecations summary fix api heading level, remove inject, add …
68b08cf 
…index by version (#30400)

PR Close #30400
@jasonaden jasonaden closed this in 0f5da82 May 21, 2019
@jenniferfell jenniferfell deleted the jfell-deprecation-updates branch May 21, 2019 21:05
@angular-automatic-lock-bot
Copy link

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

This action has been performed automatically by a bot.

@angular-automatic-lock-bot angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 15, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@Splaktar Splaktar Splaktar approved these changes

@trotyl trotyl trotyl left review comments

@IgorMinar IgorMinar IgorMinar approved these changes

@StephenFluin StephenFluin Awaiting requested review from StephenFluin

Assignees

@IgorMinar IgorMinar

Labels
action: merge The PR is ready for merge by the caretaker cla: yes feature Issue that requests a new feature target: patch This PR is targeted for the next patch release
Projects
None yet
Milestone
version 8
Development

Successfully merging this pull request may close these issues.
8 participants
@jenniferfell @mary-poppins @trotyl @googlebot @IgorMinar @Splaktar @brandonroberts @kara