data icon indicating copy to clipboard operation
data copied to clipboard

Published 20 hours ago • verified publisher icon emberjs

🛤️ tracking: Rewrite Guides for EmberData

Open runspired opened this issue 2 years ago • 7 comments

EmberData has changed, and as we prepare for the Polaris edition a key milestone will be generating updated documentation to show modern usage.

The library as shown by the current guides at guides.emberjs.com, the code examples throughout the docs at api.emberjs.com, and the usage as shown in the tutorial app in the guide fall short of covering many key topics and no longer map to the recommended path.

This quest exists to assist us on the course of writing new guides, new tutorials, and in improving the api docs. For this quest, we want to focus on documentation that exists in four locations:

1. README's of the EmberData packages should contain an approachable learning story for the respective package, with appropriate linking to further reading on other packages and deeper subjects.

  • [ ] README for ember-data package
  • [ ] README for store package
  • [ ] README for request package
  • [ ] README for tracking package
  • [ ] README for adapter package
  • [ ] README for serializer package
  • [ ] README for debug package
  • [ ] README for json:api cache package
  • [ ] README for graph package
  • [ ] README for model package
  • [ ] README for legacy-compat package
  • [ ] README for canary-features package
  • [ ] README for private-build-infra package

2. Each package referenced in the API Documentation should have its own overview

This overview should mirror the content of the README by explaining what the package is for, when you might use it, how it fits into EmberData overall, and how to use its primary APIs.

  • [ ] api-docs overview for EmberData
  • [ ] api-docs overview for ember-data package
  • [ ] api-docs overview for store package
  • [ ] api-docs overview for request package
  • [ ] api-docs overview for tracking package
  • [ ] api-docs overview for adapter package
  • [ ] api-docs overview for serializer package
  • [ ] api-docs overview for debug package
  • [ ] api-docs overview for json:api cache package
  • [ ] api-docs overview for graph package
  • [ ] api-docs overview for model package
  • [ ] api-docs overview for legacy-compat package
  • [ ] api-docs overview for canary-features package
  • [ ] api-docs overview for (virtual) deprecations
  • [ ] api-docs overview for (virtual) experimental-preview-types package

3. API Documentation should be upgraded to ensure modern usage examples and to ensure that new users are steered towards recommended patterns at all times within the docs.

We should pay especial close attention to the documentation for the Store, and to ensuring that documentation for Adapter and Serializer make it clear that these are specific implementations of now legacy concepts, and steer folks to using new recommended patterns.

For Model we will want to similarly make it clear that @ember-data/model is an implementation of a presentation class for resources. It will remain the recommended approach for such until the library offers a new default solution (coming in 5.x).

4. Markdown files placed in <project>/guides/src/ should be written to replace and enhance the current guides content. (We are going to consider rewriting the Ember tutorial app out of the scope of this particular quest, but would be overjoyed for someone to take that effort on).

This learning story should teach EmberData "from the fetch up", the most basic usage being to use @ember-data/request for "just fetch". From fetch users learn about the difference between resources and documents and adding caching for them by installing @ember-data/store and configuring a Cache to match their API format (graphql, trpc json:api rest etc.). Finally, users learn about using instantiateRecord to hydrate data from the cache into rich presentational classes.

Guides Pages

Note this is currently an incomplete list

  • Fundamentals (these are designed as stand-alone articles, but ordered to build understanding from the ground up)

    • Fetching
    • Resources & Documents
    • Caching
    • Identity
    • Schemas
    • Presentation
    • Relationships
    • Polymorphism
    • Mutating Data

  • Tutorials

    • SSR
    • Mapping Concepts between a Resource/Field, a Schema, and a Model/Presentation Class
    • Auth Strategies
    • Streaming Responses
    • Cache Lifetimes
    • Paginated Queries
    • Paginated Relationships
    • Filtering and Sorting Relationships
    • Partitioning Data
    • Mutation Strategies & Rollback
    • Error Handling
    • Working with Meta
    • Non-JSON data
    • Typescript
    • querying local data (example question to solve https://github.com/emberjs/data/issues/8543)

  • Advanced

    • Configuring Identifier Generation
      • to solve the username / additional unique-key problem (example question to solve https://github.com/emberjs/data/issues/8543)
    • Cache Lifetimes
    • Implementing a Cache
    • Implementing Presentation Classes
    • Using the Graph
    • Approaches to Offline Support
    • Syncing Across Browsers

    Known Problem Areas

These are areas that others have requested documentation improvements in that may or may-not be covered by the above, we should be sure to ensure they also exist.

From @anlumo in #5756

  • [ ] snapshot, as passed into many DS.Adapter functions.
  • [ ] type, as passed into many DS.Adapter functions.
  • [ ] The meta object given to the function passed to the functions DS.Model.eachRelationship and DS.Model.eachAttribute.
  • [ ] How to notify the store about a record deletion from the server side.
  • [ ] DS.belongsTo and DS.hasMany being async by default.
  • [ ] When to use unloadRecord.
  • [ ] How to unset attributes in a way that they revert back to the defaultValue instead of null.
  • [ ] A full step-by-step guide on how to implement the whole ember-data layer with a custom adapter that does not inherit from DS.JSONAdapter (including serializers).
  • [ ] The undocumented fact that you have to push all changes that happened locally back to the store once they're on the server
  • [ ] Existing guides are outdated when describing RecordArray https://github.com/emberjs/data/issues/8599

runspired avatar Jan 11 '23 18:01 runspired

Is anyone working on it? If not I would like to contribute.

Aryan1982 avatar Mar 06 '23 09:03 Aryan1982

@Aryan1982 would love help! sorry, the notification here got buried in my inbox <3

runspired avatar Mar 18 '23 08:03 runspired

I would like to contribute to this ?

VedanthB avatar Mar 27 '23 20:03 VedanthB

@VedanthB awesome! I think starting with the items in section 1 would be best.

I began this work already (you can see the READMEs below) which could give you a good sense of the starting point, though even these READMEs should be reviewed and improved

runspired avatar Mar 27 '23 22:03 runspired

I would like to work on the guides, since I am new to open source could you suggest smaller packages that I can start with? @runspired

thevinitgupta avatar Sep 18 '23 11:09 thevinitgupta

@thevinitgupta I think either the request package or a broader guide to fetching. Being fairly new to OSS, especially if you haven't used EmberData or Ember much, you may want to join the ember discord to be able to ask questions.

I gave a bit of an architectural overview of the request management story here: https://discord.com/channels/480462759797063690/480501977931972608/1152722044002254929

runspired avatar Sep 18 '23 17:09 runspired