Blacklight 9 includes some backwards-incompatible changes. Follow this guide to upgrade a Blacklight 8 application to Blacklight 9.

1. Ensure your local application has a passing test suite. If needed, add automated tests for any important functionality, to make it obvious when something is broken.

2. Upgrade to the latest 8.x release so you can see any recent deprecation warnings.

3. Take note of any deprecation warnings originating from Blacklight in the logs and make the suggested changes.

4. Upgrade to Blacklight 9 and follow the Upgrade Notes below.

To test a plugin and validate it Run the plugin with the latest version of blacklight/main.

1. blacklight-hierarchy
2. blacklight_range_limit - Tested and working in blacklight 9.x pre-releases as of blacklight_range_limit 9.0
3. blacklight_dynamic_sitemap
4. blacklight-gallery
5. arclight https://github.com/projectblacklight/arclight/pull/1596 (needs a release cut)

1. spotlight Due to: https://github.com/projectblacklight/spotlight/pull/3429

1. blacklight_marc

1. blacklight_oai_provider
2. blacklight_iiif_search
3. blacklight_advanced_search - release needed
4. geoblacklight - a number of UI issues, in progress PR open

1. The shared/header_navbar partial no longer exists. If you used this in your application, then render blacklight_config.header_component.new(blacklight_config: blacklight_config) instead.

2. The catalog/constraints partial no longer exists. If you call this in your application, instead render blacklight_config.view_config(document_index_view_type).constraints_component.new(search_state: search_state)

3. If you use importmap-rails to access Blacklight Javascript files, change the line import 'blacklight' to import 'blacklight-frontend'. (probably in an application.js file)

4. If you used to use import 'blacklight-frontend/app/assets/javascripts/blacklight/blacklight', it should now be switched to import 'blacklight-frontend'

5. For SCSS, if you used to @import 'blacklight-frontend/app/assets/stylesheets/blacklight/blacklight';, it should now be switched to @import 'blacklight-frontend/stylesheets/blacklight';.

6. Blacklight::Document::Email and Blacklight::Document::Sms have been removed. You may need to modify your app/models/solr_document.rb to remove the use_extension for these.

7. Blacklight::ConstraintComponent now accepts a Blacklight::ClausePresenter, rather than a Blacklight::FacetItemPresenter

8. Blacklight::DocumentComponent's initializer no longer accepts a presenter parameter. Instead, pass a Blacklight::DocumentPresenter to the document parameter.

9. Blacklight::DocumentTitleComponent's initializer no longer accepts a document parameter. Instead, pass a Blacklight::DocumentPresenter to the presenter parameter.