emberjs · runspired · Aug 16, 2022 · Aug 13, 2022 · Aug 13, 2022 · Aug 16, 2022
diff --git a/README.md b/README.md
@@ -1,20 +1,18 @@
-ember-data
+EmberData
 ==============================================================================
 
 [![Build Status](https://github.com/emberjs/data/workflows/CI/badge.svg)](https://github.com/emberjs/data/actions?workflow=CI)
 [![Code Climate](https://codeclimate.com/github/emberjs/data/badges/gpa.svg)](https://codeclimate.com/github/emberjs/data)
 [![Discord Community Server](https://img.shields.io/discord/480462759797063690.svg?logo=discord)](https://discord.gg/zT3asNS)
 
-`ember-data` is a library for robustly managing data in applications built with
-[Ember.js](https://github.com/emberjs/ember.js/).
 
-`ember-data` is designed to be agnostic to the underlying persistence
-mechanism, so it works just as well with `JSON API` over `HTTP` as it does
-with streaming `WebSockets` or local `IndexedDB` storage.
+# Overview
 
-It provides many of the facilities you'd find in server-side `ORM`s like
-`ActiveRecord`, but is designed specifically for the unique environment of
-`JavaScript` in the browser.
+`EmberData` is a lightweight reactive data library for JavaScript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation. You can plug-and-play as desired for any api  structure and format.
+
+It was designed for robustly managing data in applications built with [Ember](https://github.com/emberjs/ember.js/) and is agnostic to the underlying persistence mechanism, so it works just as well with [JSON:API](https://jsonapi.org/) or [GraphQL](https://graphql.org/) over `HTTPS` as it does with streaming `WebSockets` or local `IndexedDB` storage.
+
+It provides many of the features you'd find in server-side `ORM`s like `ActiveRecord`, but is designed specifically for the unique environment of `JavaScript` in the browser.
 
 - [Usage Guide](https://guides.emberjs.com/release/models/)
 - [API Documentation](https://api.emberjs.com/ember-data/release)
@@ -25,29 +23,111 @@ It provides many of the facilities you'd find in server-side `ORM`s like
 - [Blog](https://emberjs.com/blog)
 
 
-Installation
-------------------------------------------------------------------------------
+## Basic Installation
 
-`ember-data` is installed by default for new applications generated with `ember-cli`.
-
-If you wish to add `ember-data` to an `addon` or `application`, you can do so by running
-the following command, which will use `yarn` or `npm` to install `ember-data` as a `devDependency`.
+Install using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)
 
 ```no-highlight
-ember install ember-data
+pnpm add -D ember-data
+```
+
+`ember-data` is installed by default for new applications generated with `ember-cli`. You can check what version is installed by looking in the `devDependencies` hash of your project's [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file.
+
+If you have generated a new `Ember` application using `ember-cli` but do 
+not wish to use `ember-data`, remove `ember-data` from your project's `package.json` file and run your package manager's install command to update your lockfile.
+
+## Advanced Installation
+
+EmberData is organized into primitives that compose together via public APIs.
+
+- [@ember-data/store](./packages/store) is the core and handles coordination
+- [@ember-data/record-data](./packages/record-data) is a resource cache for JSON:API structured data. It integrates with the store via the hook `createRecordDataFor`
+- [@ember-data/model](./packages/model) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.
+- [@ember-data/adapter](./packages/adapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.
+- [@ember-data/serializer](./packages/serializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/record-data`.
+- [@ember-data/debug](./packages/debug) provides debugging support for the `ember-inspector`.
+- [ember-data](./packages/-ember-data) is a "meta" package which bundles all of these together for convenience
+
+The packages interop with each other through well defined public API boundaries. The core
+of the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully
+public APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.
+
+## Configuration
+
+### Deprecation Stripping
+
+EmberData allows users to opt-in and remove code that exists to support deprecated behaviors.
+
+If your app has resolved all deprecations present in a given version, you may specify that version as your "compatibility" version to remove the code that supported the deprecated behavior from your app.
+
+```ts
+let app = new EmberApp(defaults, {
+  emberData: {
+    compatWith: '4.8',
+  },
+});
+```
+
+- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)
+
+### randomUUID polyfill
+
+EmberData uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill
+the necessary feature if your browser support or deployment environment demands it. To
+activate this polyfill:
+
+```ts
+let app = new EmberApp(defaults, {
+  '@embroider/macros': {
+    setConfig: {
+      '@ember-data/store': {
+        polyfillUUID: true
+      },
+    },
+  },
+});
 ```
 
-Similarly, if you have generated a new `Ember` application using `ember-cli` but do 
-not wish to use `ember-data`, remove `ember-data` from your `package.json`.
+### removing inspector support in production
+
+If you do not with to ship inspector support in your production application, you can specify
+that all support for it should be stripped from the build.
+
+```ts
+let app = new EmberApp(defaults, {
+  emberData: {
+    includeDataAdapterInProduction: false
+  }
+});
+```
+
+- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)
+
+### Debugging
+
+Many portions of the internals are helpfully instrumented with logging that can be activated
+at build time. This instrumentation is always removed from production builds or any builds
+that has not explicitly activated it. To activate it set the appropriate flag to `true`.
 
+```ts
+  let app = new EmberApp(defaults, {
+    emberData: {
+      debug: {
+          LOG_NOTIFICATIONS: false,
+          LOG_REQUEST_STATUS: false,
+          LOG_IDENTIFIERS: false,
+          LOG_GRAPH: false,
+          LOG_INSTANCE_CACHE: false,
+      }
+    }
+  });
+  ```
 
-Contributing
-------------------------------------------------------------------------------
+## Contributing
 
 See the [Contributing](CONTRIBUTING.md) guide for details.
 
 
-License
-------------------------------------------------------------------------------
+### License
 
 This project is licensed under the [MIT License](LICENSE.md).
diff --git a/packages/-ember-data/addon/index.js b/packages/-ember-data/addon/index.js
@@ -1,3 +1,100 @@
+/**
+ # Overview
+
+`EmberData` is a lightweight reactive data library for javascript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation that you can plug-and-play as desired for any api  structure and format.
+
+It was designed for robustly managing data in applications built with [Ember](https://github.com/emberjs/ember.js/) and is agnostic to the underlying persistence mechanism, so it works just as well with [JSON:API](https://jsonapi.org/) or [GraphQL](https://graphql.org/) over `HTTPS` as it does with streaming `WebSockets` or local `IndexedDB` storage.
+
+It provides many of the facilities you'd find in server-side `ORM`s like `ActiveRecord`, but is designed specifically for the unique environment of `JavaScript` in the browser.
+
+EmberData is organized into primitives that compose together via public APIs.
+
+- [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore is the core and handles coordination
+- [@ember-data/record-data](/ember-data/release/modules/@ember-data%2Frecord-data) is a resource cache for JSON:API structured data. It integrates with the store via the hook `createRecordDataFor`
+- [@ember-data/model](/ember-data/release/modules/@ember-data%2Fmodel) is a presentation layer, it integrates with the store via the hooks `instantiateRecord` and `teardownRecord`.
+- [@ember-data/adapter](/ember-data/release/modules/@ember-data%2Fadapter) provides various network API integrations for APIS built over specific REST or JSON:API conventions.
+- [@ember-data/serializer](/ember-data/release/modules/@ember-data%2Fserializer) pairs with `@ember-data/adapter` to normalize and serialize data to and from an API format into the `JSON:API` format understood by `@ember-data/record-data`.
+- [@ember-data/debug](/ember-data/release/modules/@ember-data%2Fdebug) provides debugging support for the `ember-inspector`.
+- **ember-data** is a "meta" package which bundles all of these together for convenience
+
+The packages interop with each other through well defined public API boundaries. The core
+of the library is the store provided by `@ember-data/store`, while each of the other libraries plugs into the store when installed. Because these packages interop via fully
+public APIs, other libraries or applications may provide their own implementations. For instance, [ember-m3](https://github.com/hjdivad/ember-m3) is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.
+
+## Configuration
+
+### Deprecation Stripping
+
+EmberData allows users to opt-in and remove code that exists to support deprecated behaviors.
+
+If your app has resolved all deprecations present in a given version, you may specify that version as your "compatibility" version to remove the code that supported the deprecated behavior from your app.
+
+```ts
+let app = new EmberApp(defaults, {
+  emberData: {
+    compatWith: '4.8',
+  },
+});
+```
+
+- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdeprecations)
+
+### randomUUID polyfill
+
+EmberData uses `UUID V4` by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill
+the necessary feature if your browser support or deployment environment demands it. To
+activate this polyfill:
+
+```ts
+let app = new EmberApp(defaults, {
+  '@embroider/macros': {
+    setConfig: {
+      '@ember-data/store': {
+        polyfillUUID: true
+      },
+    },
+  },
+});
+```
+
+### removing inspector support in production
+
+If you do not with to ship inspector support in your production application, you can specify
+that all support for it should be stripped from the build.
+
+```ts
+let app = new EmberApp(defaults, {
+  emberData: {
+    includeDataAdapterInProduction: false
+  }
+});
+```
+
+- [Full Documentation](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fdebug)
+
+### Debugging
+
+Many portions of the internals are helpfully instrumented with logging that can be activated
+at build time. This instrumentation is always removed from production builds or any builds
+that has not explicitly activated it. To activate it set the appropriate flag to `true`.
+
+```ts
+  let app = new EmberApp(defaults, {
+    emberData: {
+      debug: {
+          LOG_NOTIFICATIONS: false,
+          LOG_REQUEST_STATUS: false,
+          LOG_IDENTIFIERS: false,
+          LOG_GRAPH: false,
+          LOG_INSTANCE_CACHE: false,
+      }
+    }
+  });
+  ```
+
+ @module ember-data-overview
+ @main ember-data-overview
+*/
 import 'ember-inflector';
 
 import { dependencySatisfies, importSync, macroCondition } from '@embroider/macros';

diff --git a/packages/-ember-data/node-tests/fixtures/expected.js b/packages/-ember-data/node-tests/fixtures/expected.js
@@ -14,6 +14,7 @@ module.exports = {
     '@ember-data/serializer/json-api',
     '@ember-data/serializer/rest',
     '@ember-data/store',
+    'ember-data-overview',
   ],
   classitems: [
     '(private) @ember-data/adapter BuildURLMixin#_buildURL',
@@ -155,6 +156,11 @@ module.exports = {
     '(public) @ember-data/adapter/rest RESTAdapter#sortQueryParams',
     '(public) @ember-data/adapter/rest RESTAdapter#updateRecord',
     '(public) @ember-data/adapter/rest RESTAdapter#useFetch',
+    "(public) @ember-data/debug DebugLogging#LOG_GRAPH",
+    "(public) @ember-data/debug DebugLogging#LOG_IDENTIFIERS",
+    "(public) @ember-data/debug DebugLogging#LOG_INSTANCE_CACHE",
+    "(public) @ember-data/debug DebugLogging#LOG_NOTIFICATIONS",
+    "(public) @ember-data/debug DebugLogging#LOG_REQUEST_STATUS",
     '(public) @ember-data/model @ember-data/model#attr',
     '(public) @ember-data/model @ember-data/model#belongsTo',
     '(public) @ember-data/model @ember-data/model#hasMany',

diff --git a/packages/-ember-data/package.json b/packages/-ember-data/package.json
@@ -2,7 +2,11 @@
   "name": "ember-data",
   "version": "4.8.0-alpha.3",
   "description": "A data layer for your Ember applications.",
-  "repository": "git://github.com/emberjs/data.git",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:emberjs/data.git",
+    "directory": "packages/-ember-data"
+  },
   "directories": {
     "doc": "docs",
     "test": "tests"

diff --git a/packages/adapter/package.json b/packages/adapter/package.json
@@ -1,11 +1,15 @@
 {
   "name": "@ember-data/adapter",
   "version": "4.8.0-alpha.3",
-  "description": "The default blueprint for ember-cli addons.",
+  "description": "Reference Adapter Implementations for use with @ember-data/store",
   "keywords": [
     "ember-addon"
   ],
-  "repository": "https://github.com/emberjs/data/tree/master/packages/adapter",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:emberjs/data.git",
+    "directory": "packages/adapter"
+  },
   "license": "MIT",
   "author": "",
   "directories": {

diff --git a/packages/canary-features/package.json b/packages/canary-features/package.json
@@ -7,7 +7,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/emberjs/data.git",
+    "url": "git+ssh://git@github.com:emberjs/data.git",
     "directory": "packages/canary-features"
   },
   "license": "MIT",

diff --git a/packages/debug/package.json b/packages/debug/package.json
@@ -5,7 +5,11 @@
   "keywords": [
     "ember-addon"
   ],
-  "repository": "https://github.com/emberjs/data/tree/master/packages/adapter",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:emberjs/data.git",
+    "directory": "packages/debug"
+  },
   "license": "MIT",
   "author": "",
   "directories": {

diff --git a/packages/model/package.json b/packages/model/package.json
@@ -1,11 +1,15 @@
 {
   "name": "@ember-data/model",
   "version": "4.8.0-alpha.3",
-  "description": "The default blueprint for ember-cli addons.",
+  "description": "A presentation layer for apps built with @ember-data/store",
   "keywords": [
     "ember-addon"
   ],
-  "repository": "https://github.com/emberjs/data/tree/master/packages/model",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:emberjs/data.git",
+    "directory": "packages/model"
+  },
   "license": "MIT",
   "author": "",
   "directories": {