Add an upgrade guide for users on version 4 - #317
Conversation
rmseifried
left a comment
rmseifried
left a comment
There was a problem hiding this comment.
This is a review up until Step 5 > Partials that became components, mostly some minor requests for clarification and/or sharing some differences I'm seeing in the UMass documents (v4.5). I'll keep working on this later!
| Then, from the top level of your application directory: | ||
|
|
||
| ```bash | ||
| bundle install |
There was a problem hiding this comment.
As of 9/11/26, this installs geoblacklight v4.7 - perhaps change all the references to 4.6 to 4.7?
| normal deprecation system, so this makes them print to your terminal: | ||
|
|
||
| ```bash | ||
| RAILS_ENV=development bin/rails runner "Geoblacklight.deprecation.behavior = :stderr; Geoblacklight::DeprecatedConfiguration.warn!" |
There was a problem hiding this comment.
This code didn't work for me (it started a [dquote> block that I didn’t know what to do with). Instead, I edited a line in config/environments/development.rb that read config.active_support.deprecation = :log and changed log to stderr.
|
|
||
| ### What the warnings cover | ||
|
|
||
| A typical GeoBlacklight 4.5 application sees about eight lines. They fall into these groups. |
There was a problem hiding this comment.
I'm upgrading from 4.5 and got 34 warnings - 12 of them were for institutional icons, and another 6 were for things related to the Harvard Geospatial Library
| unless somebody reconciled it by hand, and GeoBlacklight 5 does not read the old names — the | ||
| affected relationships simply stop being displayed. GeoBlacklight 4.6 warns about this. Compare | ||
| your file against | ||
| [the current template](https://github.com/geoblacklight/geoblacklight/blob/main/lib/generators/geoblacklight/templates/settings.yml) |
There was a problem hiding this comment.
I note that the current template does not have the new "DOWNLOAD_FORMATS" or "TIMEOUT_DOWNLOAD" code that was added in the above steps. Is this expected?
| goes for the renamed icon translations, which depend on a `Settings.ICON_MAPPING` that 4.x does | ||
| not have, and for deleting overridden templates, which are still very much in use on 4.x. | ||
|
|
||
| So: keep the list, and work through it during step 5, 6 and 7 below. |
There was a problem hiding this comment.
I note that at this point, I am able to successfully launch my v4.7 application. Would it be worthwhile to mention that users can follow the guide up until this point if all they want to do is upgrade to 4.7?
| "postcss": "^8.5.15", | ||
| "postcss-cli": "^11.0.1", | ||
| "sass": "^1.101.0" | ||
| }, |
There was a problem hiding this comment.
We had these additional dependencies - not sure if they should be removed or kept:
- "@hotwired/turbo-rails": "^8.0.16",
- "blacklight-range-limit": "^9.0.0",
- "chart.js": "^4.5.0"
I also had this additional section that I deleted:
"devDependencies": {
sass-embedded": "^1.90.0",
"vite": "^8.2.2",
"vite-plugin-rails": "^0.5.0",
"vite-plugin-ruby": "^5.1.1"
}
|
|
||
| ```bash | ||
| yarn install | ||
| yarn build:css |
There was a problem hiding this comment.
I got a few deprecation warnings running this:
Deprecation Warning [import]: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.
Deprecation Warning [if-function]: The Sass if() syntax is deprecated in favor of the modern CSS syntax.
Deprecation Warning [global-builtin]: Global built-in functions are deprecated and will be removed in Dart Sass 3.0.0.
Deprecation Warning [color-functions]: red() is deprecated. Suggestion: color.channel($color, "red", $space: rgb)
Deprecation Warning [color-functions]: green() is deprecated. Suggestion: color.channel($color, "green", $space: rgb)
Deprecation Warning [color-functions]: blue() is deprecated. Suggestion: color.channel($color, "blue", $space: rgb)
| layout it finds it in: | ||
|
|
||
| ```diff | ||
| - <%= javascript_tag '$.fx.off = true;' if Rails.env.test? %> |
There was a problem hiding this comment.
We also had the following lines in this file, which I deleted:
<%= vite_client_tag %>
<%= vite_javascript_tag 'application' %>
|
|
||
| Add a template beside it at `app/components/my_header_component.html.erb`, starting from | ||
| [GeoBlacklight's own](https://github.com/geoblacklight/geoblacklight/blob/main/app/components/geoblacklight/header_component.html.erb) | ||
| and re-applying your changes. Then point the configuration at it: |
There was a problem hiding this comment.
Is this as simply as copying the contents of _header_navbar.html.erb into the new file my_header_component.html.erb? Maybe explain what "re-applying your changes" means.
| ### Partials that became components | ||
|
|
||
| If GeoBlacklight 4.6 warned you about any of these, replace your override with a subclass of the | ||
| listed component, in the same way as the header above. |
There was a problem hiding this comment.
It's not clear to me how to accomplish this. In our catalog_controller.rb, this seems to be the relevant code:
# solr field configuration for document/show views
# This sets the metadata to display below the map viewer.
# To move metadata above the map viewer,
# remove the lines deleting and re-adding the :show partial
config.show.display_type_field = 'format'
config.show.partials.delete(:show)
config.show.partials << 'show_default_display_note'
config.show.partials << 'show_default_viewer_container'
config.show.partials << 'show_default_attribute_table'
config.show.partials << 'show_default_viewer_information'
config.show.partials << :show
Do we delete those lines, or do we swap out the partial name with the GBLv5 replacement?
2 participants
Closes #303