Skip to content
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.

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

Advance RFC #0724 "Official TypeScript Support" to Stage Recommended #952

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

emberjs-rfcs-bot
Copy link
Collaborator

@emberjs-rfcs-bot emberjs-rfcs-bot commented Aug 24, 2023

Advance #724 to the Recommended Stage

Summary

This pull request is advancing the RFC to the Recommended Stage.

An FCP is required before merging this PR to advance.

Recommended Stage Summary

The "Recommended" stage is the final milestone for an RFC. It provides a signal to the wider community to indicate that a feature has been put through its ecosystem paces and is ready to use.

To reach the "Recommended" stage, the following should be true:

If appropriate, the feature is integrated into the tutorial and the guides prose. API documentation is polished and updates are carried through to other areas of API docs that may not directly pertain to the feature.

If the proposal replaces an existing feature, the addon ecosystem has largely updated to work with both old and new features.

If the proposal updates or replaces an existing feature, high-quality codemods are available.

If needed, Ember debugging tools as well as popular IDE support have been updated to support the feature.

If the feature is part of a suite of features that were designed to work together for best ergonomics, the other features are also ready to be "Recommended".

Any criteria for "Recommended" for this proposal that were established in the Ready For Release stage have been met.

An FCP is required to enter this stage. Multiple RFCs may be moved as a batch into "Recommended" with the same PR.

Checklist to move to Recommended

  • Criteria specific to this feature: Any additional criteria for "Recommended" for this proposal that were established in the Ready For Release stage have been met.
  • Tutorial: If appropriate, the feature is integrated into the tutorial.
  • Guides: If appropriate, the feature is integrated into the guides prose.
  • API Docs: API documentation is polished and updates are carried through to other areas of API docs that may not directly pertain to the feature.
  • Addon Ecosystem: If the proposal replaces an existing feature, the addon ecosystem has largely updated to work with both old and new features.
  • Codemods: If the proposal updates or replaces an existing feature, high-quality codemods are available.
  • Debugging Tools: If needed, Ember debugging tools (e.g. Ember Inspector, Deprecation Workflow) have been updated to support the feature.
  • IDE Support: If needed, popular IDE support has been updated to support the feature.
  • Engines, SSR: If needed, ecosystem feature such as Ember Engines, SSR support have been updated to support the feature.
  • Blueprints: Blueprints have been updated to support the feature and to reflect the new best practices implied by this feature.
  • Linting: Lint rules have been updated or added or removed to support the feature and to reflect the new best practices implied by this feature.
  • Deprecations: If this feature implies that other features are no longer best practice, RFCs have been created to deprecate those features.
  • Blog Post: Consider if a blog post should be written to introduce this feature to the community.
  • Feature Suite: If the feature is part of a suite of features that were designed to work together for best ergonomics, the other features are also ready to be "Recommended".
  • FCP to Recommended: This PR has been converted from a draft to a regular PR and the Final Comment Period label has been added to start the FCP.

Criteria for moving to Recommended (required)

<-- Copy and paste the criteria for "Recommended" from the Ready For Release stage here -->

A set of criteria for moving this RFC to the Recommended Stage, following release:

  1. Add TypeScript chapter to Ember Guides.

@emberjs-rfcs-bot emberjs-rfcs-bot added RFC Advancement S-Recommended PR to move to the Recommended Stage labels Aug 24, 2023
@ef4
Copy link
Contributor

ef4 commented Sep 7, 2023

Even though official stable types in ember-source have been released for a while, the latest app blueprint in ember-cli still uses DefinitelyTyped instead.

@gitKrystan
Copy link
Contributor

I've started a PR to the Guides for basic TS documentation. WIP PR here: ember-learn/guides-source#1960

@gitKrystan
Copy link
Contributor

Even though official stable types in ember-source have been released for a while, the latest app blueprint in ember-cli still uses DefinitelyTyped instead.

This is intentional because the ember-source stable types do not currently work with the ember-data types yet. The guides section will explain this and we are working toward getting ember-data types working with ember-source stable types ASAP.

@ef4
Copy link
Contributor

ef4 commented Sep 29, 2023

Latest update here: people are working through the issues for the ember-data types. That is the remaining blocker to enable this feature in the default blueprint.

@gitKrystan
Copy link
Contributor

TypeScript chapter for the Ember Guides:
PR: ember-learn/guides-source#1960
Preview: https://deploy-preview-1960--ember-guides.netlify.app/release/using-typescript/

@ef4
Copy link
Contributor

ef4 commented Oct 27, 2023

Status update during rfc review: people are actively working on the ember-data types, probably going to re-use the strategy ember-source has been using.

@ef4
Copy link
Contributor

ef4 commented Mar 29, 2024

  • ember-data canary has now has types
  • the ember data packages are about to start shipping separate type packages to aid migration.

@ef4
Copy link
Contributor

ef4 commented Apr 26, 2024

The ember-data separate type packages have shipped and there is now a guide.

There is work to do to integrate these new types with the main emberjs guides.

@ef4
Copy link
Contributor

ef4 commented May 3, 2024

Status notes:

  • the implementation side needs more people to test the alpha types so we can build confidence
  • the guides could begin getting updated as long as it's labeled to explain that these are the alpha types

@kategengler
Copy link
Member

kategengler commented May 17, 2024

Open question for Ember Data types: (from @runspired) What is acceptable to reach stable? Do we need to reduce the surface area of files to match the JS Files that are shipping for it to be official? Possible option is "dts buddy".

Krystan and Peter: Not necessary for official?

Runspired: What about types that they shouldn't have access to?

Ed: Internal structure leaking is a problem. There are hacks in the addon authoring blueprint to avoid these references.

Peter: Good point on imports, probably needs to be resolved.

Ed: Ember doesn't roll up

Verdict: need a solution

@ef4
Copy link
Contributor

ef4 commented Jun 14, 2024

The guides already have a "Zoe says" box pointing to the blog post that has instructions to use the native types, explaining the caveat that they're not default because ember-data users can't use them yet.

Maybe we can update that info to also point to the ember-data unstable types?

@gitKrystan
Copy link
Contributor

gitKrystan commented Jun 19, 2024

PR to point Guides users to the EmberData alpha types in conjunction with the Ember native types: ember-learn/guides-source#2036 (now merged).

@ef4
Copy link
Contributor

ef4 commented Jun 28, 2024

We think it's time to PR the blueprints in ember-cli to replace the definitely-typed packages, since even including unstable ember-data types is going to be a better experience.

@ef4
Copy link
Contributor

ef4 commented Jul 12, 2024

There were concerns about the lack of type-rollup meaning that internal paths would be usable in apps. We think it would be sufficient to document that types including (for example) /-private are not supported public API.