docs: mention the upgrade guide in getting started (#1588)

* docs: mention the upgrade guide in getting started

* chore: make sure the upgrade guide is at the top

Author: alanpoulain

core/getting-started.md

@@ -20,6 +20,8 @@ project:
 
 There are no mandatory configuration options although [many settings are available](configuration.md).
 
+**Warning**: If you are migrating from an older version of API Platform than 2.7, make sure you read the [Upgrade Guide](upgrade-guide.md).
+
 ## Before Reading this Documentation
 
 If you haven't read it already, take a look at [the Getting Started guide](../distribution/index.md).

core/upgrade-guide.md

@@ -2,42 +2,42 @@
 
 ## API Platform 2.7/3.0
 
-### I want to try the new metadata system
+### I Want to Try the New Metadata System
 
 Note that if you want to use the **new metadata system**, you need to set:
 
 ```yaml
+# api/config/packages/api_platform.yaml
 api_platform:
     metadata_backward_compatibility_layer: false
 ```
 
 This will be the default value in 3.0, in 2.7 it's left to `true` so that nothing breaks by updating.
 By doing so you won't get access to legacy services and this will probably break things on code using `api-platform/core:2.6`.
 
-### I'm migrating from 2.6 and want to prepare for 3.0
+### I'm Migrating From 2.6 and Want to Prepare For 3.0
 
 1. Update the code to 2.7: `composer require api-platform/core:^2.7`
-2. Take care of the deprecations and update your code to the new interfaces, documented on this page.
+2. Take care of the deprecations and update your code to the new interfaces, documented on this page
 3. Switch the `metadata_backward_compatibility_layer` flag to `false`
 4. Use the [`api:upgrade-resource` command](#the-upgrade-command)
 
 Read more about the `metadata_backward_compatibility_layer` flag [here](#the-metadata_backward_compatibility_layer-flag).
 
 ## Changes
 
-### Summary of the changes between 2.6 And 2.7/3.0
+### Summary of the Changes Between 2.6 And 2.7/3.0
 
 - New Resource metadata allowing to declare multiple Resources on a class: `ApiPlatform\Metadata\ApiResource`
 - Clarification of some properties within the ApiResource declaration
-- Removal of the item and collection difference on operation declaration
+- Removal of item and collection differences on operation declaration
 - `ApiPlatform\Core\DataProvider\...DataProviderInterface` has a new
 interface `ApiPlatform\State\ProviderInterface`
 - `ApiPlatform\Core\DataPersister\...DataPersisterInterface` has a new
 interface `ApiPlatform\State\ProcessorInterface`
 - New ApiProperty metadata `ApiPlatform\Metadata\ApiProperty`
-- Configuration flag `metadata_backward_compatibility_layer` that allows
-- `ApiPlatform\Core\DataTransformer\DataTransformerInterface` is deprecated and will be removed in 3.0.
-the use of legacy metadata layers
+- Configuration flag `metadata_backward_compatibility_layer` that allows the use of legacy metadata layers
+- `ApiPlatform\Core\DataTransformer\DataTransformerInterface` is deprecated and will be removed in 3.0
 - Subresources are now additional resources marked with an `#[ApiResource]` attribute (see [the new subresource documentation](./subresources.md))
 
 The detailed changes are present in the [CHANGELOG](https://github.com/api-platform/core/blob/main/CHANGELOG.md).
@@ -97,32 +97,32 @@ class Book
 You can use the `api:upgrade-resource` command to upgrade
 your resources automatically, [see instructions here](#the-upgrade-command).
 
-### Removal of Item/Collection operations
+### Removal of Item/Collection Operations
 
-We removed the notion of item and collection. Instead, use
-http verbs matching the operation you want to declare.
-There is also a `collection` flag instructing wether the
+We removed the notion of item and collection.
+Instead, use HTTP verbs matching the operation you want to declare.
+There is also a `collection` flag instructing whether the
 operation returns an array or an object.
-The default ApiResource attribute still declares a CRUD:
+The default `ApiResource` attribute still declares a CRUD:
 
 ```php
 #[ApiResource]
 ```
 
-is the same as
+is the same as:
 
 ```php
-#[ApiResource(operations=[
+#[ApiResource(operations: [
     new Get(),
     new Put(),
     new Patch(),
     new Delete(),
     new GetCollection(),
-    new Post()
+    new Post(),
 ])]
 ```
 
-### Metadata changes
+### Metadata Changes
 
 #### #[ApiResource]
 
@@ -145,7 +145,7 @@ is the same as
 |`iri: 'https://schema.org/Book'`|`types: ['https://schema.org/Book']`|
 |`type: 'string'`|`builtinTypes: ['string']`|
 
-Note that builtinTypes are computed automatically from php types.
+Note that `builtinTypes` are computed automatically from PHP types.
 
 For example:
 
@@ -158,34 +158,35 @@ class Book
 
 Will compute: `builtinTypes: ['string', Isbn::class]`
 
-### The `metadata_backward_compatibility_layer` flag
+### The `metadata_backward_compatibility_layer` Flag
 
 In 2.7 the `metadata_backward_compatibility_layer` flag is set to `true`.
 This means that all the legacy services will still work just as they used
 to work in 2.6 (for example `PropertyMetadataFactoryInterface` or
-`ResourceMetadataFactoryInterface`). When updating we advise to first
-resolve the deprecations then to set this flag to `false` to use the new metadata system.
+`ResourceMetadataFactoryInterface`).
+When updating we advise to first resolve the deprecations then to set this
+flag to `false` to use the new metadata system.
 
 When `metadata_backward_compatibility_layer` is set to `false`:
 - there's still a bridge with the legacy `ApiPlatform\Core\Annotation\ApiResource` and old metadata will still work
-- the deprecated symfony services will have their interface changed (for example `ApiPlatform\Core\Api\IriConverterInterface` will be `ApiPlatform\Api\IriConverterInterface`) and it may break your dependency injection.
+- the deprecated Symfony services will have their interface changed (for example `ApiPlatform\Core\Api\IriConverterInterface`
+will be `ApiPlatform\Api\IriConverterInterface`) and it may break your dependency injection.
 - the new metadata system is available `ApiPlatform\Metadata\ApiResource`
 
-
 ### SearchFilter
 
 If you want to use the new namespaces for the search filter
 (`ApiPlatform\Doctrine\Orm\Filter\SearchFilter` instead of`ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\SearchFilter` or
 `ApiPlatform\Doctrine\Odm\Filter\SearchFilter` instead of`ApiPlatform\Core\Bridge\Doctrine\Odm\Filter\SearchFilter`) you
-need to use the `metadata_backward_compatibility_layer` to false as this filter relies on the implementation
+need to set the `metadata_backward_compatibility_layer` to `false` as this filter relies on the implementation
 of the new `ApiPlatform\Api\IriConverterInterface`.
 
 In 3.0 this flag will default to `false` and the legacy code will be removed.
 
-## The upgrade command
+## The Upgrade Command
 
 The upgrade command will automatically upgrade the old `ApiPlatform\Core\Annotation\ApiResource` to `ApiPlatform\Metadata\ApiResource`.
-By default this does a dry run and shows a diff:
+By default, this does a dry run and shows a diff:
 
 ```bash
 php bin/console api:upgrade-resource
@@ -199,7 +200,9 @@ php bin/console api:upgrade-resource -f
 
 ## Providers/Processors
 
-Providers and Processors are replacing DataProviders and DataPersisters. We reduced their interface to only one method and the class used by your operation can be specified directly within the metadata. Using doctrine, a default resource would use these:
+Providers and Processors are replacing DataProviders and DataPersisters.
+We reduced their interface to only one method and the class used by your operation can be specified directly within the metadata.
+Using Doctrine, a default resource would use these:
 
 ```php
 
@@ -224,8 +227,9 @@ See also the respective documentation:
 - [State Processor](./state-processors.md)
 - [State Provider](./state-providers.md)
 
-## DataTransformers and DTO support
+## DataTransformers and DTO Support
 
-Data transformers have been deprecated, instead you can still document the `output` or the `input` DTO. Then, just handle the `input` in a custom [State Processor](./state-processors.md) or return another `output` in a custom [State Provider](./state-providers.md).
+Data transformers have been deprecated, instead you can still document the `output` or the `input` DTO.
+Then, just handle the `input` in a custom [State Processor](./state-processors.md) or return another `output` in a custom [State Provider](./state-providers.md).
 
 The [dto documentation](./dto.md) has been adapted accordingly.

outline.yaml

@@ -11,6 +11,7 @@ chapters:
     items:
       - index
       - getting-started
+      - upgrade-guide
       - design
       - extending
       - testing
@@ -54,7 +55,6 @@ chapters:
       - bootstrap
       - configuration
       - migrate-from-fosrestbundle
-      - upgrade-guide
   - title: The Schema Generator Component
     path: schema-generator
     items: