[Docs] Sync docs between versions

docs/installation-laravel.md

@@ -42,28 +42,32 @@ Package Version | Laravel Version
     php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
     ```
 
-6. NOTE: **If you are using UUIDs**, see the Advanced section of the docs on UUID steps, before you continue. It explains some changes you may want to make to the migrations and config file before continuing. It also mentions important considerations after extending this package's models for UUID capability.
+6. BEFORE RUNNING MIGRATIONS
 
-    **If you are going to use the TEAMS features**, you must update your [`config/permission.php` config file](https://github.com/spatie/laravel-permission/blob/main/config/permission.php) and set `'teams' => true,`; and in your database if you want to use a custom foreign key for teams you must change `team_foreign_key`.
+   - **If you are using UUIDs**, see the Advanced section of the docs on UUID steps, before you continue. It explains some changes you may want to make to the migrations and config file before continuing. It also mentions important considerations after extending this package's models for UUID capability.
 
-7. NOTE: If you are using MySQL 8, look at the migration files for notes about MySQL 8 to set/limit the index key length, and edit accordingly.
+   - **If you are going to use the TEAMS features** you must update your [`config/permission.php` config file](https://github.com/spatie/laravel-permission/blob/main/config/permission.php):
+       - must set `'teams' => true,`
+       - and (optional) you may set `team_foreign_key` name in the config file if you want to use a custom foreign key in your database for teams
 
-8. **Clear your config cache**. This package requires access to the `permission` config. Generally it's bad practice to do config-caching in a development environment. If you've been caching configurations locally, clear your config cache with either of these commands:
+   - **If you are using MySQL 8**, look at the migration files for notes about MySQL 8 to set/limit the index key length, and edit accordingly.
+
+7. **Clear your config cache**. This package requires access to the `permission` config settings in order to run migrations. If you've been caching configurations locally, clear your config cache with either of these commands:
 
         php artisan optimize:clear
         # or
         php artisan config:clear
 
-9. **Run the migrations**: After the config and migration have been published and configured, you can create the tables for this package by running:
+8. **Run the migrations**: After the config and migration have been published and configured, you can create the tables for this package by running:
 
         php artisan migrate
 
-10. **Add the necessary trait to your User model**: 
+9. **Add the necessary trait to your User model**: 
 
         // The User model requires this trait
         use HasRoles;
 
-   Consult the **Basic Usage** section of the docs to get started using the features of this package.
+10. Consult the **Basic Usage** section of the docs to get started using the features of this package.
 
 .
 

docs/upgrading.md

@@ -15,13 +15,15 @@ ALL upgrades of this package should follow these steps:
 
 3. Config file. Incorporate any changes to the permission.php config file, updating your existing file. (It may be easiest to make a backup copy of your existing file, re-publish it from this package, and then re-make your customizations to it.)
 
-4. Models. If you have made any custom Models from this package into your own app, compare the old and new models and apply any relevant updates to your custom models.
+4. Models. If you have made any custom Models by extending them into your own app, compare the package's old and new models and apply any relevant updates to your custom models.
 
 5. Custom Methods/Traits. If you have overridden any methods from this package's Traits, compare the old and new traits, and apply any relevant updates to your overridden methods.
 
-6. Apply any version-specific special updates as outlined below...
+6. Contract/Interface updates. If you have implemented this package's contracts in any models, check to see if there were any changes to method signatures. Mismatches will trigger PHP errors.
 
-7. Review the changelog, which details all the changes: [CHANGELOG](https://github.com/spatie/laravel-permission/blob/main/CHANGELOG.md)
+7. Apply any version-specific special updates as outlined below...
+
+8. Review the changelog, which details all the changes: [CHANGELOG](https://github.com/spatie/laravel-permission/blob/main/CHANGELOG.md)
 and/or consult the [Release Notes](https://github.com/spatie/laravel-permission/releases)