Unclear statement in custom model permission documentation

[Baptiste Mispelon]

The custom permission documentation at ​https://docs.djangoproject.com/en/dev/topics/auth/default/#default-permissions states that after you add a custom permission to a model's Meta:

it will create default permissions for new models each time you run manage.py migrate.

This is incorrect. What actually happens is that Django will detect the changes to the model's Meta and generate the appropriate migration for it when running makemigrations.

[Tim Graham]

The statement is still true as the permissions are created by create_permissions() which is connected to the post_migrate signal. The migration that's generated doesn't have any effect data-wise. Do you think this needs to be clarified?

[Baptiste Mispelon]

Ah, that explains it.

I was trying to create a data migration alongside the auto-generated one and was confused as to why it wasn't working (Django was complaining that my custom permission didn't exist yet).

The documentation is technically correct I guess though I still find it pretty confusing.
I don't really have an idea on how to improve it though so I'd be OK if you just want to close this.

[Tim Graham]

Here's a try.

[Baptiste Mispelon]

That's pretty good I think. Can we also add this sentence to the paragraph under the code at ​https://docs.djangoproject.com/en/dev/topics/auth/customizing/#custom-permissions?

Thanks.

[Tim Graham <timograham@…>]

In 217f173:

Fixed #25166 -- Clarified how auth permissions are created.

Thanks Baptiste Mispelon for report and review.

[Tim Graham <timograham@…>]

In 19ac8b2:

[1.8.x] Fixed #25166 -- Clarified how auth permissions are created.

Thanks Baptiste Mispelon for report and review.

Backport of 217f173be025d2cce6484c760ea6ec77436f26a1 from master