docs: add documentation for v1.8 (#3669)

docs/content/development/entities/create.md

@@ -3,11 +3,11 @@ description: 'Learn how to create an entity in Medusa. This guide also explains
 addHowToData: true
 ---
 
-# Create an Entity
+# How to Create an Entity
 
-In this document, you’ll learn how you can create an [Entity](./overview.mdx).
+In this document, you’ll learn how you can create a custom [Entity](./overview.mdx).
 
-## Create the Entity
+## Step 1: Create the Entity
 
 To create an entity, create a TypeScript file in `src/models`. For example, here’s a `Post` entity defined in the file `src/models/post.ts`:
 
@@ -52,46 +52,85 @@ export class Post extends SoftDeletableEntity {
 
 You can learn more about what decorators and column types you can use in [Typeorm’s documentation](https://typeorm.io/entities).
 
-### Create a Migration
+---
+
+## Step 2: Create a Migration
 
 Additionally, you must create a migration for your entity. Migrations are used to update the database schema with new tables or changes to existing tables.
 
-You can learn more about Migrations, how to create them, and how to run them in the [Migration documentation](./migrations/overview.mdx).
+You can learn more about Migrations, how to create or generate them, and how to run them in the [Migration documentation](./migrations/overview.mdx).
 
-### Create a Repository
+---
+
+## Step 3: Create a Repository
 
 Entities data can be easily accessed and modified using Typeorm [Repositories](https://typeorm.io/working-with-repository). To create a repository, create a file in `src/repositories`. For example, here’s a repository `PostRepository` created in `src/repositories/post.ts`:
 
 ```ts title=src/repositories/post.ts
-import { EntityRepository, Repository } from "typeorm"
-
 import { Post } from "../models/post"
+import { 
+  dataSource,
+} from "@medusajs/medusa/dist/loaders/database"
 
-@EntityRepository(Post)
-export class PostRepository extends Repository<Post> { }
+export const PostRepository = dataSource
+  .getRepository(Post)
+
+export default PostRepository
 ```
 
-This repository is created for the `Post` and that is indicated using the decorator `@EntityRepository`.
+The repository is created using the `getRepository` method of the data source exported from the core package in Medusa. This method accepts the entity as a parameter.
 
 :::tip
 
-Be careful with your file names as it can cause unclear errors in Typeorm. Make sure all your file names are small letters for both entities and repositories to avoid any issues with file names.
+A data source is Typeorm’s connection settings that allows you to connect to your database. You can learn more about it in [Typeorm’s documentation](https://typeorm.io/data-source).
 
 :::
 
+If you want to add methods to that repository or override Typeorm's Repository methods, you can do that using the `extend` method:
+
+```ts title=src/repositories/post.ts
+import { Post } from "../models/post"
+import { 
+  dataSource,
+} from "@medusajs/medusa/dist/loaders/database"
+
+export const PostRepository = dataSource
+  .getRepository(Post)
+  .extend({
+    customFunction(): void {
+      // TODO add custom implementation
+      return
+    },
+  })
+
+export default PostRepository
+```
+
+You can learn about available Repository methods in [Typeorm's documentation](https://typeorm.io/repository-api).
+
 ---
 
-## Access a Custom Entity
+## Step 4: Run Migrations
 
-:::note
+Before you start using your entity, make sure to run the migrations that reflect the entity on your database schema.
 
-Before trying this step make sure that you’ve created and run your migrations. You also need to re-build your code using:
+To do that, run the `build` command that transpiles your code:
 
 ```bash npm2yarn
 npm run build
 ```
 
-:::
+Then, run the `migration` command:
+
+```bash npm2yarn
+medusa migrations run
+```
+
+You should see that your migration have executed.
+
+---
+
+## Step 5: Use Your Entity
 
 You can access your custom entity data in the database in services or subscribers using the repository. For example, here’s a service that lists all posts:
 
@@ -107,9 +146,9 @@ class PostService extends TransactionBaseService {
   }
 
   async list() {
-    const postRepository = this.manager_
-      .getCustomRepository(this.postRepository)
-    return await postRepository.find()
+    const postRepo = this.manager_
+      .withRepository(this.postRepository)
+    return await postRepo.find()
   }
 }
 
@@ -118,15 +157,13 @@ export default PostService
 
 In the constructor, you can use dependency injection to get access to instances of services and repositories. Here, you initialize class fields `postRepository` and `manager`. The `manager` is a [Typeorm Entity Manager](https://typeorm.io/working-with-entity-manager).
 
-Then, in the method `list`, you can obtain an instance of the `PostRepository` using `this.manager_.getCustomRepository` passing it `this.postRepository` as a parameter. This lets you use [Custom Repositories with Typeorm](https://typeorm.io/custom-repository) to create custom methods in your repository that work with the data in your database.
+Then, in the method `list`, you can create an instance of the `PostRepository` using the `this.manager_.withRepository` method passing it `this.postRepository` as a parameter.
 
-After getting an instance of the repository, you can then use [Typeorm’s Repository methods](https://typeorm.io/repository-api) to perform Create, Read, Update, and Delete (CRUD) operations on your entity.
-
-If you need access to your entity in endpoints, you can then use the methods you define in the service.
+After getting an instance of the repository, you can then use [Typeorm’s Repository methods](https://typeorm.io/repository-api) to perform Create, Read, Update, and Delete (CRUD) operations on your entity. You can also use any custom methods that you defined in the Repository.
 
 :::note
 
-This same usage of repositories can be done in subscribers as well.
+This same usage of repositories can be done in other resources such as subscribers or endpoints.
 
 :::
 
@@ -142,5 +179,5 @@ await postRepository.softDelete(post.id)
 
 ## See Also
 
-- [Migrations Overview](./migrations/overview.mdx)
+- [Extend Entity](./extend-entity.md)
 - [Create a Plugin](../plugins/create.md)