add saved_objects server folder convention

Author: pgayvallet

src/core/CONVENTIONS.md

@@ -7,6 +7,7 @@
     - [Applications](#applications)
     - [Services](#services)
     - [Usage Collection](#usage-collection)
+    - [Saved Objects Types](#saved-objects-types)
 
 ## Plugin Structure
 
@@ -31,6 +32,9 @@ my_plugin/
     │   └── index.ts
     ├── collectors
     │   └── register.ts
+    ├── saved_objects
+    │   ├── index.ts
+    │   └── my_type.ts
     ├── services
     │   ├── my_service
     │   │   └── index.ts
@@ -259,6 +263,45 @@ export function registerMyPluginUsageCollector(usageCollection?: UsageCollection
 }
 ```
 
+### Saved Objects Types
+
+Saved object type definitions should be defined in their own `server/saved_objects` directory.
+
+The folder should contain a file per type, named after the snake_case name of the type, and an `index.ts` file exporting all the types.
+
+```typescript
+// src/plugins/my-plugin/server/saved_objects/my_type.ts
+import { SavedObjectsType } from 'src/core/server';
+
+export const myType: SavedObjectsType = {
+  name: 'my-type',
+  hidden: false,
+  namespaceAgnostic: true,
+  mappings: {
+    properties: {
+      someField: {
+        type: 'text',
+      },
+      anotherField: {
+        type: 'text',
+      },
+    },
+  },
+  migrations: {
+    '1.0.0': migrateFirstTypeToV1,
+    '2.0.0': migrateFirstTypeToV2,
+  },
+};
+```
+
+```typescript
+// src/plugins/my-plugin/server/saved_objects/index.ts
+
+export { myType } from './my_type';
+```
+
+Migration example from the legacy format is available in `src/core/MIGRATION_EXAMPLES.md#saved-objects-types`
+
 ### Naming conventions
 
 Export start and setup contracts as `MyPluginStart` and `MyPluginSetup`. 

src/core/MIGRATION_EXAMPLES.md

@@ -889,7 +889,7 @@ export class MyPlugin implements Plugin {
 
 ### Changes in structure compared to legacy
 
-The NP `registerType` expected input is very close to the legacy format, However there are some minor changes:
+The NP `registerType` expected input is very close to the legacy format. However, there are some minor changes:
 
 - The `schema.isNamespaceAgnostic` property has been renamed: `SavedObjectsType.namespaceAgnostic`
 

src/core/server/saved_objects/utils.test.ts

@@ -195,7 +195,7 @@ describe('convertLegacyTypes', () => {
     expect(Object.keys(converted[1]!.migrations!)).toEqual(Object.keys(migrationsB));
   });
 
-  it('migrates the migration to the new format', () => {
+  it('converts the migration to the new format', () => {
     const legacyMigration = jest.fn();
     const migrationsA = {
       '1.0.0': legacyMigration,