Document upload_to method behavior when duplicate file is present

[Matthew Pava]

I have a FileField with a custom upload_to method that generates a completely new path and filename. In my unit tests, I discovered that the default behavior of adding random characters to the end of the file name was enabled when the file name already existed. It took me a week to figure this out. Documenting this fact would have been incredibly helpful.

​https://docs.djangoproject.com/en/3.0/ref/models/fields/#django.db.models.FileField.upload_to

[Matthew Pava]

So I just discovered that this detail is documented in Storage.save(), which is mentioned in the documentation for that method. So maybe this isn't completely necessary, but it still feels like this documentation could be improved here somewhat. But I also understand if we just mark this as invalid.

[Mariusz Felisiak]

Replying to Matthew Pava:

So I just discovered that this detail is documented in ​Storage.save(), which is mentioned in the documentation for that method. So maybe this isn't completely necessary, but it still feels like this documentation could be improved here somewhat. But I also understand if we just mark this as invalid.

Yes, exactly. It's ​documented "that the value is passed to the Storage.save() method" and in the Storage.save() ​documentation we have:

If there already exists a file with this name name, the storage system may modify the filename as necessary to get a unique name. The actual name of the stored file will be returned.

I think it's sufficient.