How supported will upgrading an existing site be by installing the modules?

[andybroomfield]

Currently, Localgov works great by installing fresh as a distribution.
However installing the modules into an existing site produces errors with config.

• Can't install in BHCC site as requires Linkit ^6.0-beta1 localgov_core#34
• Fields need to be renamed to start with localgov_ prefix localgov_services#75
• Rename installed fields to localgov_ prefix localgov_core#35
• Geolocation google maps api should be optional? localgov_paragraphs#7

Whilst these can be easily fixed / bypassed, this has potential to be an ongoing problem.
Will simply installing the modules in an existing site be seen as supported, or is the intention that site will be new builds?

[ekes]

From slack:-

Andy Broomfield (BHCC) 11:38
@channel I'd like to get a discussion around renaming some of the old fields that use the field_ prefix instead of the localgov_ prefix.
I'm currently writing an update hook to rename some of these, and this will have implications for existing sites that updates would need to be co-oridinated.
Background and issue on Github is #112
To summarize, BHCC would like to try installing the Localgov modules on our existing Drupal 8 site instead of a full rebuild. However since Localgov is based on BHCCs site, the config names conflict. Its possible to resolve this by renaming the the conflicting fields to the distrobution prefix (which is what all new fields are using).
I have an initial PR which i've been wokring on to rename the field machine names here:
localgovdrupal/localgov_core#37
Renaming the fields has implications accross localgov, as any use of the old field names in templates or code logic has to be changed at the same time to avoid breaking.
Also any custom code or templates will also have to be updated at the same time.
Its therfore important that this change is co-ordinated to avoid breaking sites.
As this is legacy code / technical debt ideally it be better to move forward with this sooner.
The outcome of this will be to allow the modules to be easily installable in site that were not started with the localgov profile as all field machine names will be namespaced.
Please forward the discussion to anyone not on this channel.
#112 How supported will upgrading an existing site be by installing the modules?
https://github.com/localgovdrupal/localgov|localgovdrupal/localgovlocalgovdrupal/localgov | 2 Sep 2020 | Added by GitHub
#37 Rename the core provided fields to localgov_ prefix
https://github.com/localgovdrupal/localgov_core|localgovdrupal/localgov_corelocalgovdrupal/localgov_core | 14 Sep 2020 | Added by GitHub

ekes 11:51
Grep'ing code I don't think we did a bad job of following the if it's touched rename it rule [note: this was the original decision]. So most of the code written doesn't use field_ prefixes. Paragraphs stuff comes up. Tests - but I think that's just because it's creating fields for the test.
But masses of the templating, and default content etc. does.
Which possibly highlights the biggest stumbling block, any site that has their own templating will rely on the field names, and it'll require updating all of the custom theming?

Andy Broomfield (BHCC) 12:26
@ekes, i thing that may have been the original discussion when building out as a distro, however it has raised issues with trying to install and use the modules in an exsting site, which is why we are now pushing for a rename of all field names.
Yes templating, and any custom themes that rely on old field names are goiing to be the largest issue, so this needs to be co-ordinated.

ekes 12:28
It's more a major version change. Anyone upgrading to the next version needs to rewrite their theme?

Andy Broomfield (BHCC) 12:28
Being able to rename the field names so BHCC can install the modules is critical if BHCC is to use the code without waiting for the distribtion to be at full release (at which point BHCC will have diverged usage quite significantly), I'm currently working on changes to the BHCC service hub (landing page) content type on the old site. It would have been prefferable to be able to make those changes within the Localgov ecosystem or at least extend those content types ourselves instead of having to work with the legacy code (edited)

As alpha, should be ok to make this as breaking change, better to do now before beta? @ekes

ekes 12:34
Better done already 🙂 But I don't know how many existing (or almost existing) sites will need to rewrite.
So making it a major version change and still backporting security updates to the other version seems polite even if it's technically alpha.

Andy Broomfield (BHCC) 12:40
I think the precendent was replacing Campaigns for Sub sites which occured during the Croydon migration. Since it should only be 2 full sites (Croydon and Lambeth) and others in development (Bracknell, Hammermisth, London Councils, Cumbria?), and the change should be search and replace the issue may not be huge if done now. It should also be possible to provide the legacy field names to templates / code as a bridge in preprocess if the field does not alredy exist

[ekes]

@tanc How complicated do you think it it would be to change the field names on the theme level for Lambeth?

[tanc]

@ekes I don’t imagine it would be too hard, more of a find/replace kind of thing. Generally in Lambeth it would all be happening in the theme’s template directory where fields values are prepared and passed in as variables to the component twig templates.

To be confident nothing is missed or broken I’d want to have visual regression tests using backstop for all templates, so that would take a while to set up. But otherwise the process would be quite quick I imagine.

[andybroomfield]

What would the scope of the impact of renaming the fields from field_* to localgov_* be?

There are the fields in localgov_core that are part of localgov_services. However the update hook itself takes care of updating the config, it will still need a co-ordinated release. There is existing code to bring in this update in a branch of localgov_services.
Then there is the theme, which at least localgov_services_landing_page node template will require updating if its changing the module provided one. I assume there will be other issues there but its really just search and replace as @tanc mentioned.

So I think within project its doable to go ahead with a field rename and co-ordinate release updated accross the project.

The bigger imapace is on outside developers who have took the code. Is it feasable to ask anyone who has used it to also co-ordinate an update to their theme, and is that likley to be the only place that will be impacted. As mentioned above, it should / (would?) be possible to provide a compatability shim to so that calls to old names referenece the new field name data.

[andybroomfield]

Is the main concern from an external sites perspective twig templates?
If so, I did a quick experiment and it is possible to provide the old field names in a preprocess hook with the values from the renamed field. This will work with twig only, so any PHP logic that relies on the field name would have to be updated.

[andybroomfield]

Here is the list of effected fields.
Taken from a default Localgov Drupal install with localgov_demo module installed.

Field name	Entity type	Field type	Used in
field_address	node	Text (formatted, long) (module: text)	Service landing page
field_address_first_line	node	Text (plain) (module: core)	Service landing page
field_common_tasks	node	Link (module: link)	Service pageService landing page
field_contact_us_online	node	Text (plain) (module: core)	Service landing page
field_destinations	node	Entity reference (module: core)	Service landing page
field_download_links	node	Link (module: link)	Service page
field_enable_service_updates	node	Boolean (module: core)
field_hearing_difficulties_phone	node	Text (plain) (module: core)	Service landing page
field_hide_related_topics	node	Boolean (module: core)	Service page
field_link_to_map	node	Link (module: link)	Service landing page
field_localgov_services_landing	node	Entity reference (module: core)
field_media_image	node	Entity reference (module: core)
field_opening_hours	node	Text (formatted, long) (module: text)	Service landing page
field_other_team_contacts	node	Text (plain) (module: core)	Service landing page
field_override_related_links	node	Boolean (module: core)	Service page
field_page_components	node	Entity reference (module: core)	Service page
field_popular_topics	node	Entity reference (module: core)	Service landing page
field_related_links	node	Link (module: link)	Service page
field_service_status	node	List (text) (module: options)	Service status
field_service_status_on_landing	node	Boolean (module: core)	Service status
field_service_status_on_list	node	Boolean (module: core)	Service status
field_topics	node	Entity reference revisions (module: entity_reference_revisions)	Service sub-landing page
field_reusable_paragraph	paragraph	Entity reference (module: core)	From library

[andybroomfield]

This piece of work is done.