RFC 44: Make "Custom models" the default

[kaedroho]

Rendered

[chosak]

Something similar would need to be done for the Custom document model documentation page.

[lb-]

Hey, finally got the chance to read this and 100% agree that this would be helpful and enable a lot of future improvements over time.

I have also put up an issue on the main repo to add some fields to the image/document models that would be really useful wagtail/wagtail#5658.

Finally, I did some analysis of about 78 different document/image models I found on Github projects. This will give a bit of an indicator of the kinds of changes made by developers.

https://docs.google.com/spreadsheets/d/1JgrDb5s_ugAnL04r3GOBqh5DodZodqqp3rqrN1sTKpE/edit?usp=sharing

The top ten fields added in custom models are:

• 16 x caption probably because it is in the docs
• 12 x credit
• 11 x alt / alt_text yes, I know we are not adding this and I agree but just FYI
• 9 x description / details / summary
• 7 x author
• 7 x source / source_name
• 5 x source_url / external_url
• 4 x attribution
• 4 x file
• 4 x licence / license
• 3 x copyright_year / year

[kaedroho]

We discussed this as a croe team meeting so I think this is at least stage 2

[thibaudcolas]

Ref wagtail/wagtail#5789 – I’d love to see this happen. There are a few things here I’d like to see changed but they feel pretty minor. In particular more consideration on the app name, whether a rename of the existing models is worthwhile, and consideration to include a custom User model as well.

[thibaudcolas]

I would like to see alternative proposals for what this app should be called, ideally backed with data on what app name real-world projects put those models in.

[zerolab]

we used media (and added custom wagtailmedia classes there as well)

[thibaudcolas]

Here and below – I’m not sure I follow. I’d still call it a custom image model as it’s custom to each project. And the docs would still be useful for the thousands of project that have been existing before the changes suggested here. And the projects that get created without wagtail start?

[kaedroho]

My proposal here was to remove the option of not having a custom user model as much as possible, so everyone going forward would create one. This is one of the many things new users need to know about when building their first Wagtail project and I wanted to remove this as an option to reduce decision fatigue.

For existing users, we could provide a how-to-guide for "upgrading" to the new favoured approach (while making it clear the old way won't be removed) rather than an "advanced topics" document that implies it's an optional "advanced" feature.

I missed out projects that get created without wagtail start in this doc, perhaps we should add these models to the "adding to an existing django project" doc as well.

[thibaudcolas]

I’m not clear on whether the effort suggested here is justified? This feels like a lot of potential busywork.

[thibaudcolas]

Could we also add a custom User model, based on the same rationale?

[rgs258]

Any chance of a custom Page model :)

[thibaudcolas]

@rgs258 😄 can you say more?

[NotANormalNerd]

@thibaudcolas I can elavorate. It would be amazing to have a Swappable Page model, like the user model, so we can add custom fields and other stuff to the base page. Right now we have to fork wagtail and add changes to the base page there.
We can't add a "additonal" model via foreign key for performance and other reasons.

So to have the a custom page model by default, that can inherit from a "AbstractBasePage" would be amazing. Wagtail could work with the AbstractBasePage and people could add whatever they need to their Page Model.

[Stormheg]

We briefly discussed this RFC again during the core team meeting today. This RFC needs answers to the remaining comments by Thibaud and we can move this to final comment period after. Keen to see this become the default 👍

@kaedroho would you be okay with me taking over this RFC? Or would you rather implement it yourself.

[thibaudcolas]

Related: RFC 53: Swappable Page model, tentatively lined up for inclusion in the August 2026 release. And also related: Custom Image and Documents Models should use Django Swappable Models #10331.

Also worth noting our new-ish news template / starter kit comes with a custom image model. But not a custom document model.