Important upload_to parameter is missing from upload doc

[Vlada Macek]

The file uploads topic and even ref page don't mention the upload_to parameter that is required:

• ​https://docs.djangoproject.com/en/dev/topics/http/file-uploads/
• ​https://docs.djangoproject.com/en/dev/ref/forms/fields/

If the newbie follows the top example on the topic page:

class UploadFileForm(forms.Form):
    title = forms.CharField(max_length=50)
    file  = forms.FileField()

he or she is immediatelly confused by the model validation error.

[Karen Tracey]

It would be out-of-place and confusing to say anything about upload_to near where the quoted snippet appears in the documentation, because that snippet concerns a plain form, not a model form, and putting upload_to on the forms.FileField would be an error. upload_to is a required parameter of models.FileField, and its documentation clearly notes that (​https://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.FileField). Where upload_to could be mentioned in the referenced doc is: ​https://docs.djangoproject.com/en/dev/topics/http/file-uploads/#handling-uploaded-files-with-a-model. Something could be added in those first two sentences noting that the models.FileField upload_to parameter controls where the file will be saved.

I don't think it would be appropriate to add any mention of upload_to to the forms field reference, as it is not a parameter of the forms-level FileField.

[Vlada Macek]

Of course, I confused the forms vs. models FileField myself. :) Sorry for the noise.

[Tim Graham <timograham@…>]

In [c6088bc91d29b6b49eba0ec82b0239a557c658ef]:

Fixed #18840 - Added a mentioned of the upload_to parameter to the ModelForm example in file uploads.

[Tim Graham <timograham@…>]

In [c9f1a13f87174b21fe2b6230fc1b2f44e03c8d61]:

[1.4.X] Fixed #18840 - Added a mentioned of the upload_to parameter to the ModelForm example in file uploads.

Backport of c6088bc91d from master