Make the documentation clearer on whether version changes make sense or not in different scenarios

Author: zmievsa

docs/concepts/endpoint_migrations.md

@@ -1,10 +1,10 @@
 # Endpoint migrations
 
-Note that the endpoint constructor contains a second argument that describes the methods of the endpoints you would like to edit. If you have two routes for a single endpoint and you put both of their methods into the instruction -- both of them are going to be changed as you would expect.
+Note that the `endpoint(...)` constructor contains a second argument that describes the methods of the endpoints you would like to edit. If you have two routes for a single endpoint and you put both of their methods into the instruction -- both of them are going to be changed as you would expect.
 
 ## Defining endpoints that didn't exist in new versions
 
-If you had an endpoint in old version but do not have it in a new one, you must still define it but mark it as deleted.
+If you had an endpoint in an old version **but want to delete it in a new version**, you must still define it as usual with all your other endpoints but mark it as deleted.
 
 ```python
 @router.only_exists_in_older_versions
@@ -28,7 +28,7 @@ class MyChange(VersionChange):
 
 ## Defining endpoints that didn't exist in old versions
 
-If you have an endpoint in your new version that must not exist in older versions, you define it as usual and then mark it as "non-existing" in old versions:
+If you have an endpoint in your new version that must not exist in older versions for some reason, you define it as usual and then mark it as "non-existing" in old versions. Note that this is [not the recommended approach when adding new endpoints](../how_to/change_endpoints/index.md#add-a-new-endpoint).
 
 ```python
 from cadwyn import VersionChange, endpoint
@@ -58,6 +58,8 @@ class MyChange(VersionChange):
     )
 ```
 
+However, you only need to have a migration if it is a breaking change for your users.
+
 ### Dependency alteration warning
 
 Note that changing endpoint `dependencies` is only going to affect the initial validation. So Cadwyn will take your altered dependencies and run them on each request to the endpoint but ultimately your endpoint code is always going to use the HEAD version of your dependencies. So be careful.

docs/concepts/schema_migrations.md

@@ -2,6 +2,8 @@
 
 All of the following instructions affect only openapi schemas and their initial validation. All of your incoming requests will still be converted into your HEAD schemas.
 
+Please note that you only need to have a migration if it is a breaking change for your users. The scenarios below only describe "what you can do" but not "what you should do". For the "should", please refer to the [how-to docs](../how_to/change_openapi_schemas/add_field.md).
+
 ## Add a field to the older version
 
 ```python

docs/concepts/version_changes.md

@@ -93,6 +93,8 @@ HEAD is very similar to your latest version with a few key differences:
 
 `VersionChange` classes describe each atomic group of business capabilities that you have altered in a version.
 
+Note, however, that you only need to have a migration if it is a breaking change for your users. If you add a new endpoint or add a new field to your response schema, you do not need to have a migration for it because your users' code will not break. So by not having a migration you automatically add this change to all versions.
+
 ### VersionChange.\_\_name\_\_
 
 The name of the version change, `RemoveTaxIDEndpoints`, describes what breaking change has happened. It must be a verb and it is the best resource for your new developers to quickly understand what happened between the versions. Do not be shy to use really long names -- it is better to have a long name than to create a misunderstanding. Avoid generic names such as `RefactorUserFields`. Better have an ugly name such as `RenameCreationDatetimeAndUpdateDatetimeToCreatedAtAndUpdatedAt` then to have a generic name such as `RefactorFields`. Because after just a few of such version changes, your versioning structure can become completely unreadable:

docs/how_to/change_openapi_schemas/add_field.md

@@ -14,7 +14,7 @@ Now you have everything you need at your disposal: field `created_at` is availab
 
 Let's say we want our users to be able to specify a middle name but it is nullable. It is not a breaking change so no new version is necessary whether it is requests or responses.
 
-You just need to add a nullable `middle_name` field into `users.BaseUser`
+You just need to add a nullable `middle_name` field into `users.BaseUser` as if you were working with a barebones FastAPI app.
 
 ### Field is required
 
@@ -59,7 +59,6 @@ Let's say that our users had a field `country` that defaulted to `USA` but our p
     )
     ```
 
-
 That's it! Our old schemas will now contain a default but in HEAD country will be required. You might notice a weirdness: if we set a default in the old version, why would we also write a migration? That's because of a sad implementation detail of pydantic that [prevents us](../../concepts/schema_migrations.md#change-a-field-in-the-older-version) from using defaults from old versions.
 
 #### With incompatible default value in older versions
@@ -118,5 +117,4 @@ So we will make `phone` nullable in HEAD, then make it required in `latest`, and
     )
     ```
 
-
 See how we didn't remove the `phone` field from old versions? Instead, we allowed a nullable `phone` field to be passed into both old `UserResource` and old `UserCreateRequest`. This gives our users new functionality without needing to update their API version! It is one of the best parts of Cadwyn's approach: our users can get years worth of updates without switching their API version and without their integration getting broken.