From 441be383ce23353cb33b5a041c773d7cc7f0c053 Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Wed, 23 Oct 2019 21:57:05 +0100 Subject: [PATCH 1/9] Make "Custom image model" the default --- text/xxx-image-models.md | 54 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 text/xxx-image-models.md diff --git a/text/xxx-image-models.md b/text/xxx-image-models.md new file mode 100644 index 00000000..5cc678d6 --- /dev/null +++ b/text/xxx-image-models.md @@ -0,0 +1,54 @@ +# RFC X: Make "custom image model" the default + +* Authors: Karl Hobley +* Created: 2019-10-23 +* Last Modified: 2018-10-23 + +## Abstract + +Custom image models is a feature that Wagtail has had since the very beginning. It allows developers to replace Wagtail's built-in image model with their own one and customise it by adding new fields or overriding methods to change behaviour. + +The problem is it’s very hard to migrate to them once you already have built a website that uses Wagtail’s built-in image model. This also makes it difficult for us to build optional add-on features for images that require a custom image model (such as AMP support or translation). + +This RFC proposes that we start recommending that all new Wagtail projects uses custom image model from the start. This will add a small amount of extra code to the project template, which I know we would want to avoid. But I think avoiding a potentially very difficult migration later outweighs the overhead of having on extra app in the project. + +This also applies to document models as well. + +## Specification + +To implement this RFC, we will make the following changes. + + +### Update the project template to use a custom image model + +We will add a new app called `assets` into the base project template. This will contain three models: `Image`, `Rendition` and `Document`. + +All three of these models will exactly match their built-in counterparts (we will not add an `alt` field to the image model out of the box). + + +### Add a custom image model to bakerydemo + +We will add the `assets` app as described in the previous section and update the fixtures and foreign keys to use this new app. + + +### Rename the built-in models to fix naming conflict and discourage their use + +Currently, custom image models are often called `CustomImage` or `WebsiteNameImage`. This is because you can’t call the model `Image` because this would cause the name of a reverse relation to clash. + +We will not remove the built-in image model as that would force developers to perform a migration that this RFC hopes to put an end to. But we could rename it to something obsolete sounding to discourage it’s use (`LegacyImage`?). This should only require developers to update foreign keys and create a simple schema migration to update for. + + +### Tweak the beginners tutorial so it uses the custom image model + +We will only make necessary tweaks so that it works with the new project template. I don’t think there’s any need to describe the image model in the beginners tutorial. + + +### Remove the “Custom image model” advanced topics doc + +We could replace this with a reference document that describes the methods that developers can override to tweak its behaviour. + + +### Stop calling it “Custom image model” + +The documentation will be updated to no longer refer to “Custom Image models” as an extra feature any more. + From 52994495e05728b952f563b5a79d35ddee81504a Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Wed, 23 Oct 2019 21:58:09 +0100 Subject: [PATCH 2/9] Number 44 --- text/{xxx-image-models.md => 044-image-models.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename text/{xxx-image-models.md => 044-image-models.md} (98%) diff --git a/text/xxx-image-models.md b/text/044-image-models.md similarity index 98% rename from text/xxx-image-models.md rename to text/044-image-models.md index 5cc678d6..866e12c7 100644 --- a/text/xxx-image-models.md +++ b/text/044-image-models.md @@ -1,4 +1,4 @@ -# RFC X: Make "custom image model" the default +# RFC 44: Make "custom image model" the default * Authors: Karl Hobley * Created: 2019-10-23 From 9df856f151c9ef8dbba896ada67fd60597633bd1 Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Wed, 30 Oct 2019 15:31:32 +0000 Subject: [PATCH 3/9] Update text/044-image-models.md Co-Authored-By: Andy Chosak --- text/044-image-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/044-image-models.md b/text/044-image-models.md index 866e12c7..6c64d6b3 100644 --- a/text/044-image-models.md +++ b/text/044-image-models.md @@ -10,7 +10,7 @@ Custom image models is a feature that Wagtail has had since the very beginning. The problem is it’s very hard to migrate to them once you already have built a website that uses Wagtail’s built-in image model. This also makes it difficult for us to build optional add-on features for images that require a custom image model (such as AMP support or translation). -This RFC proposes that we start recommending that all new Wagtail projects uses custom image model from the start. This will add a small amount of extra code to the project template, which I know we would want to avoid. But I think avoiding a potentially very difficult migration later outweighs the overhead of having on extra app in the project. +This RFC proposes that we start creating all new Wagtail projects with a custom image model from the start. This will add a small amount of extra code to the project template, which I know we would want to avoid. But I think avoiding a potentially very difficult migration later outweighs the overhead of having one extra app in the project. This also applies to document models as well. From ec46dfa68276f91fba1312931f0bd17772828b70 Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Wed, 30 Oct 2019 15:31:40 +0000 Subject: [PATCH 4/9] Update text/044-image-models.md Co-Authored-By: Andy Chosak --- text/044-image-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/044-image-models.md b/text/044-image-models.md index 6c64d6b3..ded4a2ef 100644 --- a/text/044-image-models.md +++ b/text/044-image-models.md @@ -16,7 +16,7 @@ This also applies to document models as well. ## Specification -To implement this RFC, we will make the following changes. +To implement this RFC, we will make the following changes: ### Update the project template to use a custom image model From a52cc07f285f3b6173b76138418272ab9d15af17 Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Wed, 30 Oct 2019 15:31:54 +0000 Subject: [PATCH 5/9] Update text/044-image-models.md Co-Authored-By: Andy Chosak --- text/044-image-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/044-image-models.md b/text/044-image-models.md index ded4a2ef..f08c01b9 100644 --- a/text/044-image-models.md +++ b/text/044-image-models.md @@ -19,7 +19,7 @@ This also applies to document models as well. To implement this RFC, we will make the following changes: -### Update the project template to use a custom image model +### Update the project template to use custom image, rendition, and document models We will add a new app called `assets` into the base project template. This will contain three models: `Image`, `Rendition` and `Document`. From 9e5ce46066b23a27d9ee1e2e78a8d2683053b512 Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Wed, 30 Oct 2019 15:32:10 +0000 Subject: [PATCH 6/9] Update text/044-image-models.md Co-Authored-By: Andy Chosak --- text/044-image-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/044-image-models.md b/text/044-image-models.md index f08c01b9..6b672434 100644 --- a/text/044-image-models.md +++ b/text/044-image-models.md @@ -35,7 +35,7 @@ We will add the `assets` app as described in the previous section and update the Currently, custom image models are often called `CustomImage` or `WebsiteNameImage`. This is because you can’t call the model `Image` because this would cause the name of a reverse relation to clash. -We will not remove the built-in image model as that would force developers to perform a migration that this RFC hopes to put an end to. But we could rename it to something obsolete sounding to discourage it’s use (`LegacyImage`?). This should only require developers to update foreign keys and create a simple schema migration to update for. +We will not remove the built-in image model as that would force developers to perform a migration that this RFC hopes to put an end to. But we could rename it to something obsolete sounding to discourage its use (`LegacyImage`?). This should only require developers to update foreign keys and create a simple schema migration to update for. ### Tweak the beginners tutorial so it uses the custom image model From 9e0b82d10c2d08d748a9e3b3ed0742cbcbfb649e Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Wed, 30 Oct 2019 15:32:26 +0000 Subject: [PATCH 7/9] Update text/044-image-models.md Co-Authored-By: Andy Chosak --- text/044-image-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/044-image-models.md b/text/044-image-models.md index 6b672434..8b020a53 100644 --- a/text/044-image-models.md +++ b/text/044-image-models.md @@ -12,7 +12,7 @@ The problem is it’s very hard to migrate to them once you already have built a This RFC proposes that we start creating all new Wagtail projects with a custom image model from the start. This will add a small amount of extra code to the project template, which I know we would want to avoid. But I think avoiding a potentially very difficult migration later outweighs the overhead of having one extra app in the project. -This also applies to document models as well. +This also applies to image rendition and document models as well. ## Specification From 5843785f13a8b764f17076d702b94d16f76ed0da Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Wed, 30 Oct 2019 16:00:17 +0000 Subject: [PATCH 8/9] Wording tweaks --- text/044-image-models.md | 66 +++++++++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 25 deletions(-) diff --git a/text/044-image-models.md b/text/044-image-models.md index 8b020a53..6b247d8c 100644 --- a/text/044-image-models.md +++ b/text/044-image-models.md @@ -6,49 +6,65 @@ ## Abstract -Custom image models is a feature that Wagtail has had since the very beginning. It allows developers to replace Wagtail's built-in image model with their own one and customise it by adding new fields or overriding methods to change behaviour. - -The problem is it’s very hard to migrate to them once you already have built a website that uses Wagtail’s built-in image model. This also makes it difficult for us to build optional add-on features for images that require a custom image model (such as AMP support or translation). - -This RFC proposes that we start creating all new Wagtail projects with a custom image model from the start. This will add a small amount of extra code to the project template, which I know we would want to avoid. But I think avoiding a potentially very difficult migration later outweighs the overhead of having one extra app in the project. - -This also applies to image rendition and document models as well. +"Custom image models" is a feature that allows developers to supply a +model for Wagtail to use to store image metadata instead of using the +built-in one. This feature enables developers to add custom fields to +images and customise Wagtail's behaviour by overriding its methods. + +The problem is that it\'s challenging to switch to a custom image model +once the site has already made use of Wagtail's built-in image model. +Because of this, it\'s difficult for us to build optional add-on +features for images that require a custom image model (such as AMP +support or translation) as many users will need to go through a +complicated migration to use them. + +This RFC proposes that we start creating new Wagtail projects with a +custom image model from the start. This change will add a small amount +of extra code to the project template, which I know we would want to +avoid, but I think preventing a potentially arduous migration later +outweighs the overhead of having one extra app in the project. + +This change also applies to image rendition and document models as well. ## Specification To implement this RFC, we will make the following changes: - ### Update the project template to use custom image, rendition, and document models -We will add a new app called `assets` into the base project template. This will contain three models: `Image`, `Rendition` and `Document`. - -All three of these models will exactly match their built-in counterparts (we will not add an `alt` field to the image model out of the box). +We will add a new app called `assets` into the base project template. +This app will contain three models: `Image`, `Rendition` and `Document`. +All three of these models will exactly match their built-in counterparts +(we will not add an `alt` field to the image model out of the box). ### Add a custom image model to bakerydemo -We will add the `assets` app as described in the previous section and update the fixtures and foreign keys to use this new app. - +We will add the `assets` app as described in the previous section and +update the fixtures and foreign keys to use this new app. ### Rename the built-in models to fix naming conflict and discourage their use -Currently, custom image models are often called `CustomImage` or `WebsiteNameImage`. This is because you can’t call the model `Image` because this would cause the name of a reverse relation to clash. - -We will not remove the built-in image model as that would force developers to perform a migration that this RFC hopes to put an end to. But we could rename it to something obsolete sounding to discourage its use (`LegacyImage`?). This should only require developers to update foreign keys and create a simple schema migration to update for. - - -### Tweak the beginners tutorial so it uses the custom image model - -We will only make necessary tweaks so that it works with the new project template. I don’t think there’s any need to describe the image model in the beginners tutorial. +Currently, custom image models are often called `CustomImage` or +`WebsiteNameImage` because calling the model `Image` would cause the +name of a reverse relation to clash. +We will not remove the built-in image model, as that would only force +developers to perform the complex migration that this RFC aims to +eliminate for future projects. -### Remove the “Custom image model” advanced topics doc +### Tweak the beginners tutorial, so it uses the custom image model -We could replace this with a reference document that describes the methods that developers can override to tweak its behaviour. +We will only make necessary tweaks so that it works with the new project +template. I don't think there's any need to describe the image model in +the beginners tutorial. +### Remove the "Custom image model" advanced topics doc -### Stop calling it “Custom image model” +We could replace this with a reference document that describes the +methods that developers can override to tweak its behaviour. -The documentation will be updated to no longer refer to “Custom Image models” as an extra feature any more. +### Stop calling it "Custom image model" +The documentation will be updated to no longer refer to "Custom Image +models" as an extra feature any more. From 5655986d6564661737ddbe2a18e50b7fd367983e Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Tue, 12 Nov 2019 09:07:28 +0000 Subject: [PATCH 9/9] Tweaks --- text/044-image-models.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/text/044-image-models.md b/text/044-image-models.md index 6b247d8c..70903c45 100644 --- a/text/044-image-models.md +++ b/text/044-image-models.md @@ -8,15 +8,13 @@ "Custom image models" is a feature that allows developers to supply a model for Wagtail to use to store image metadata instead of using the -built-in one. This feature enables developers to add custom fields to -images and customise Wagtail's behaviour by overriding its methods. - -The problem is that it\'s challenging to switch to a custom image model -once the site has already made use of Wagtail's built-in image model. -Because of this, it\'s difficult for us to build optional add-on -features for images that require a custom image model (such as AMP -support or translation) as many users will need to go through a -complicated migration to use them. +built-in one. It enables developers to add custom fields to images and +override Wagtail's default image handling behaviour. + +It's challenging to switch to a custom image model once a site +has already made use of Wagtail's built-in image model. Because of +this, we can't add new features that require a custom image model as it +may not be feasible for some users to migrate to one. This RFC proposes that we start creating new Wagtail projects with a custom image model from the start. This change will add a small amount