[BUG] Migration documentation leads to misfunctioning migrations

[thorin-schiffer]

Describe the bug Example for iterative migration will lead to migration being not applied to any document.

To Reproduce

class Tag(BaseModel):
    color: str
    name: str


class OldNote(Document):
    name: str
    tag: Tag

    class Settings:
        name = "notes"


class Note(Document):
    title: str
    tag: Tag

    class Settings:
        name = "notes"

makes an impression that if there is a model called Car, the name should be 'cars' (it is like this in Django for example). Instead, if no other name was specified, the actual collection for Car is 'Car', the same name as the model name. This leads to a situation, where migration creates a new collection named cars and so iterative migration iterates over a new empty collection, resulting in nothing happening. This is very confusing for new users, as they see no output and don't know if migration ran at all.

Besides, as it's probable that the user will rename the model to some versions of it, like NewCar and OldCar, it's beneficial to mention that the name argument is then crucial to point to the existing collection.

Expected behavior I would prefer migrations not to create new collections implicitly at all. If that is not possible, update the documentation to remove ambiguity.

[roman-right]

Hi! Thank you for the catch! It should be mentioned in the doc. I'll think about if the collection should be or should not be created at this case.