blacklight 4.6.3 → 4.7.0.pre1

data/doc/Blacklight-3.2-Release-Notes-and-Upgrade-Guide.md

@@ -0,0 +1,191 @@
+## Overview
+
+Blacklight 3.2 introduces a number of new features to Blacklight, including the Rails asset pipeline, a configuration refactor, and support for Solr 3.x by default.
+
+### Upgrading to Rails 3.1
+
+If you are still using Rails 3.0, you should first update your project to work with Rails 3.1. Start by fixing any Rails 3.0 deprecation warnings (as those features may no longer exist or fail silently in Rails 3.1). There are some good resources to help you with the upgrade (e.g. [[http://railscasts.com/episodes/282-upgrading-to-rails-3-1?view=asciicast]]). 
+
+### Assets (CODEBASE-363)
+Blacklight 3.2 uses the Rails 3.1 asset pipeline for all assets, stylesheets and javascript. The CSS has been refactored and now uses SCSS to enable easy changing of some common parameters/colors. In addition, it no longer uses YUI-grids CSS framework. (Instead it uses Susy grid css framework).
+
+What does this mean for you?
+
+* Small (hopefully) upgrade costs.
+
+* Use of the asset pipeline to compress and streamline all css files into one.
+
+* Easier theming of blacklight.
+
+After having upgraded to BL 3.2 (and Rails 3.1), the first thing you should do is upgrade to use the asset pipeline. The Blacklight gem's standard behavior for including CSS and Javascript in your app **requires the asset pipeline**. (Of course, if you don't  use the CSS or Javascript distributed with Blacklight, or want to roll your own custom way to include it, you could choose to continue without using the asset pipeline) 
+
+Run the Blacklight generator to upgrade from Blacklight 3.1 to 3.2:
+```
+$ rails g blacklight
+```
+
+This should update the `application.css` and `application.js` files with references to the new Blacklight assets. You will still need to move or update your local assets and customizations. 
+
+**Note**
+
+* Now, if you have  you will need to change your layout to use the new ids, look at: [app/views/layouts/blacklight.html.erb](https://github.com/projectblacklight/blacklight/blob/master/) for reference on the new tags (#page, #bd, #hd, #footer, #main, #main_container, #sidebar). The old yui tags have no meaning in the new css.
+
+* This also means that any local CSS that overrides Blacklight's CSS, if your uses the old yui-grids id's in your CSS selectors, you probably want to change them to use the new id's. (#doc, #doc2, etc,, as well as any .yui-*)
+
+* You will need to remove the line `require "yui"` from your `./app/assets/stylesheets/application.css`. In previous versions, Blacklight provided the YUI css library as part of the gem. In Blacklight 3.2, because the Blacklight is no longer using YUI, this has been removed. If you wish to continue using YUI, you will need to provide your own copy in your application. You can download the [Blacklight 3.1 YUI file](https://github.com/projectblacklight/blacklight/blob/release-3.1/app/assets/stylesheets/yui.css) or from the (Yahoo YUI site)[http://developer.yahoo.com/yui/2/].
+
+### Per-controller configuration (CODEBASE-365)
+
+In previous versions of Blacklight, configuring Blacklight was done using a global configuration hash called `Blacklight.config` (created in `config/initializers/blacklight_config.rb`). Blacklight 3.2 deprecates this global configuration in favor of a per-controller, DSL-style configuration. Support for the old-style configuration is  still available (meaning, if you do absolutely nothing, Blacklight will convert Blacklight.config into the new-style configuration, and your application will probably continue to work), but we strongly recommend applications switch to the new-style configuration.
+
+The two major changes are moving from the global configuration (`Blacklight.config`) to a Controller-specific method (`blacklight_config`) and replacing the hash-based access with an OpenStruct-based domain-specific language. The new style maintains many of the old semantics, but should be better structured and more clear.
+
+On your CatalogController, you can configure the Blacklight Catalog:
+
+```ruby
+class CatalogController < ApplicationController  
+
+  include Blacklight::Catalog
+
+  configure_blacklight do |config|
+    config.default_solr_params = { 
+      :qt => 'search',
+      :rows => 10 
+    }
+
+    # solr field configuration for search results/index views
+    config.index.show_link = 'title_display'
+    config.index.record_display_type = 'format'
+
+    # solr field configuration for document/show views
+    config.show.html_title = 'title_display'
+    config.show.heading = 'title_display'
+    config.show.display_type = 'format'
+
+  # ....
+  end
+
+# ...
+end
+
+```
+
+
+#### Creating a new configuration
+
+An example of the new style configuration is available at 
+[[https://github.com/projectblacklight/blacklight/blob/master/lib/generators/blacklight/templates/catalog_controller.rb]] and shows most of the ways one can use the new configuration.
+
+There are helper methods for adding field configuration (facets, index, and show fields) as well as search and sort fields. All of these methods accept a variety of inputs and should be used in local applications in whatever form is most clear.
+
+Field + configuration hash
+
+```ruby
+config.add_facet_field 'format', :label => 'Format' 
+```
+
+Configuration hash
+
+```ruby
+config.add_sort_field :sort => 'score desc, pub_date_sort desc, title_sort asc', :label => 'relevance'
+```
+
+Field + block
+
+```ruby
+    config.add_search_field('title') do |field|
+      # solr_parameters hash are sent to Solr as ordinary url query params. 
+      field.solr_parameters = { :'spellcheck.dictionary' => 'title' }
+
+      # :solr_local_parameters will be sent using Solr LocalParams
+      # syntax, as eg {! qf=$title_qf }. This is neccesary to use
+      # Solr parameter de-referencing like $title_qf.
+      # See: http://wiki.apache.org/solr/LocalParams
+      field.solr_local_parameters = { 
+        :qf => '$title_qf',
+        :pf => '$title_pf'
+      }
+    end
+```
+
+#### Using the new configuration
+
+Within a controller, the configuration can be accessed using the method `blacklight_config`, which is also exposed to helpers or views as a helper method.
+
+Outside of a controller context (which should be rare, and likely undesirable), the configuration is exposed at the class level as well, e.g.:
+
+```ruby
+CatalogController.blacklight_config
+```
+
+Some configuration-driven helper methods have also been moved to the configuration object:
+
+```ruby
+blacklight_config.default_search_field
+blacklight_config.default_sort_field
+blacklight_config.max_per_page 
+```
+
+The Blacklight field configuration are stored as ordered hashes, with a key corresponding to the field name:
+
+```ruby
+CatalogController.blacklight_config.facet_fields
+
+# {
+#     "format" => #<Blacklight::Configuration::FacetField:0x1025a0c78
+#        :label => "Format",
+#        :field => "format"
+#     >,
+#     "pub_date" => #<Blacklight::Configuration::FacetField:0x1025a7aa0
+#        :label => "Publication Year",
+#        :field => "pub_date"
+#    >,
+# ...
+```
+
+Values can be accessed using OpenStruct methods or as a Hash:
+ 
+```ruby
+CatalogController.blacklight_config.facet_fields["format"].label # == "Format"
+CatalogController.blacklight_config.facet_fields["format"][:label] # == "Format"
+```
+
+### Using the new-style config in local overrides
+If you have overriden views or helpers in your local application and access `Blacklight.config` directly, you will need to update your overrides. In general, you should be able to search for references to `Blacklight.config` in your local application, replace it with the controller-level method `blacklight_config` and possibly fix up some naming differences.
+
+### Facet refactor
+Facet helpers and views have been refactored to take advantage of the new configuration style and new features in Rails. 
+
+The old `_facet_limit` view has been split in two,
+
+* `_facet_limit` : the partial to display the facet values
+* `_facet_layout` : a 'partial layout' that displays the facet structure and headers
+
+In the facet configuration, you can specify the partial to use to render a facet:
+```ruby
+config.add_facet_field 'format', :label => 'Format', :partial => 'my_custom_format_facet_display_partial'
+``` 
+
+### Solr 3.5 (CODEBASE-345)
+Blacklight-jetty has been updated to Solr 3.5 (previously it was still Solr 1.4). Blacklight is still compatible with both Solr 1.x and 3.x, but the demo application is based on a Solr 3.x configuration.
+
+#### SolrMarc 2.3.1
+Older versions of SolrMarc were incompatible with Solr 3.x. Blacklight is now distributed with SolrMarc 2.3.1. But previous versions of Blacklight erroneously copied a SolrMarc.jar into your local app's lib/SolrMarc.jar when installing Blacklight. 
+
+If you have a previously installed Blacklight, unless you have intentionally installed a local compile of SolrMarc.jar, you should remove the file at local ./lib/SolrMarc.jar, so your app will use the latest version of SolrMarc shipped with Blacklight.
+
+
+
+### Other changes
+
+* [CODEBASE-325](http://jira.projectblacklight.org/jira/browse/CODEBASE-325) - Allow Blacklight to function correctly when no user authentication system is provided
+* [CODEBASE-362](http://jira.projectblacklight.org/jira/browse/CODEBASE-362) - Blacklight facets do not work with integer-type fields
+* [CODEBASE-367](http://jira.projectblacklight.org/jira/browse/CODEBASE-367) - Pull in Hydra's jettywrapper to manage jetty
+* [CODEBASE-369](http://jira.projectblacklight.org/jira/browse/CODEBASE-369) - Advanced Search has an incompatible character encoding issue under ruby 1.9
+* [CODEBASE-371](http://jira.projectblacklight.org/jira/browse/CODEBASE-371) - SolrHelper#get_solr_response_for_field_values does not adequately escape value lists
+* [CODEBASE-375](http://jira.projectblacklight.org/jira/browse/CODEBASE-375) - fix rake solr:marc:index task and generator to use distro SolrMarc.jar
+* [CODEBASE-376](http://jira.projectblacklight.org/jira/browse/CODEBASE-376) - Look at the did_you_mean.feature scenarios, review for accuracy.
+* [CODEBASE-377](http://jira.projectblacklight.org/jira/browse/CODEBASE-377) - Convert opensearch.xml.erb to true XML builder style
+* [CODEBASE-379](http://jira.projectblacklight.org/jira/browse/CODEBASE-379) - Factor out use of RSolr's pagination feature and use Solr's start/rows parameters instead
+* [CODEBASE-380](http://jira.projectblacklight.org/jira/browse/CODEBASE-380) - ActionMailer deprecations
+

data/doc/Blacklight-3.3-release-notes-and-upgrade-guide.md

@@ -0,0 +1,37 @@
+Issues: https://github.com/projectblacklight/blacklight/issues?milestone=2&state=open
+
+## Upgrade notes:
+
+Note: Please make sure to upgrade to at least Blacklight **3.3.1** to avoid problems with compiled assets in 3.3.0. 
+
+If you previously ran the blacklight 3.3.0 generator, after upgrading to 3.3.1: Edit your local `./app/assets/stylesheets/blacklight_themes/standard.css.scss` file, change the line (wrong) `@import 'blacklight/grids/susy';` to instead be (right) `@import 'blacklight/grids/susy_grid';`
+
+If you previously ran the blacklight 3.2.x or 3.3.0 generator, look in your local `./config/application.rb`, *remove* the line `config.sass.line_comments = Rails.env.development?` if present. 
+
+### Compass/susy upgrade
+
+[Compass](https://github.com/chriseppstein/compass) (our CSS framework) and [Susy](http://susy.oddbird.net/) have been updated to a new major release. This will necessitate some changes in installations already running BL 3.2.
+
+New installations should just use the generator as normal.
+
+Existing installations should do the following:
+
+**1.** In your gemfile, in `group :assets`, remove any reference to the compass gem, and add:
+
+    gem 'sass-rails', '~> 3.2.0'
+    gem 'compass-rails', '~> 1.0.0'
+    gem 'compass-susy-plugin', '~> 0.9.0'
+
+**2.** You can remove 'config/initializers/sass.rb'
+
+**3.** You must add, if you have not already: 'config/compass.rb'
+ 
+    require 'susy'
+    project_type = :rails
+
+**4.** Replace any references in your css:
+
+`@import "blacklight/grids/susy_framework"` with `@import "susy"`
+ 
+`@import "blacklight/grids/susy"` with `@import "blacklight/grids/susy_grid"` 
+

data/doc/Blacklight-3.4-release-notes-and-upgrade-guide.md

@@ -0,0 +1,27 @@
+# Blacklight 3.4 Release notes
+Blacklight 3.4.0 is now available. It fixes a number of bugs and
+tests, but also adds a handful of new features.
+
+ - Fixed Rails 3.1 compatibility for rspec tests
+ - changes to make Blacklight work better with arbitrary solr indexes.
+ - Use ERb to parse the solr.yml configuration (allowing environment
+variables to be referenced in the config)
+ - fixed #351, saving Selected Items (Folder) to Bookmarks
+(SavedRecords), more than 10.
+ - fixed #398 document fetching/config refactor, which elevates
+document-request solr parameters into the controller's
+blacklight_config.
+ - fixed #333, Blacklight should throw more helpful errors if it
+unable to connect to Solr
+ - fixed #96, supporting configurable request handler paths
+
+The full list of Github issues are at:
+https://github.com/projectblacklight/blacklight/issues?milestone=4&state=closed
+
+Also, the GitHub compare view of this release vs. our last release is
+located at:
+https://github.com/projectblacklight/blacklight/compare/v3.3.0...v3.4.0
+
+# Upgrade notes
+
+No known issues updating from 3.3 to 3.4.

data/doc/Blacklight-3.5-release-notes-and-upgrade-guide.md

@@ -0,0 +1,44 @@
+# Blacklight 3.5 Release Notes And Upgrade Guide
+
+## Release Notes
+# Blacklight 3.5 Release notes
+Blacklight 3.5.0 is now available. It introduces i18n support for Blacklight, allowing applications to change and modify Blacklight-provided text strings without the need to override partials (in addition to providing multi-lingual support).
+
+- Fix #395, removing hard-coded no-reply@ email addresses from the ```RecordMailer``` (see below for upgrade notes)
+- Consistent use of polymorphic routing to the show views for documents. ```solr_document_url``` and ```solr_document_path``` are now part of the engine-provided routes, rather than helper-provided.
+- Refactor `blacklight.js` to take advantage of the Rails asset pipeline by moving separate blocks of code into individual files.
+- Fix problem with mounting Blacklight applications at a suburi rather than a document.
+
+The full list of Github issues are at:
+https://github.com/projectblacklight/blacklight/issues?milestone=7&state=closed
+
+Also, the GitHub compare view of this release vs. our last release is
+located at:
+https://github.com/projectblacklight/blacklight/compare/v3.4.2...release-3.5
+
+
+## Upgrade Guide
+
+No known issues updating from 3.4 to 3.5.
+
+## i18n
+
+Blacklight 3.5 introduces i18n (internationalization framework) support. See the Ruby on Rails [[i18n Rails guide|http://guides.rubyonrails.org/i18n.html]] for information on how to use i18n within your application. The list of blacklight-provided (English) translations are available in the engine's [[```config/locales/blacklight.en.yml```|https://github.com/projectblacklight/blacklight/blob/master/config/locales/blacklight.en.yml]]
+
+## RecordMailer default email
+
+In config/environments/development.rb:
+```ruby
+ActionMailer::Base.default :from => 'default@development-server.com'
+```
+
+In config/environments/production.rb:
+```ruby
+ActionMailer::Base.default :from => 'default@production-server.com'
+```
+
+You can also target the RecordMailer directly:
+
+```ruby
+RecordMailer.default :from => 'no-reply@projectblacklight.org'
+```

data/doc/Blacklight-3.6-release-notes-and-upgrade-guide.md

@@ -0,0 +1,25 @@
+# Blacklight 3.6 Release Notes And Upgrade Guide
+
+## Release Notes
+# Blacklight 3.6 Release notes
+Blacklight 3.6.0 is now available. This is mostly a collection of small patches.
+
+
+- Fix blacklight to be compatible with newly released version of Kaminari
+- Split document_header into its own partial
+- Utilizing rails own capability to determine partial paths for collections
+- #423 using response.total instead of the underlying hash
+- many more
+
+
+The full list of Github issues are at:
+https://github.com/projectblacklight/blacklight/issues?milestone=8&state=closed
+
+Also, the GitHub compare view of this release vs. our last release is
+located at:
+https://github.com/projectblacklight/blacklight/compare/release-3.5...release-3.6
+
+
+## Upgrade Guide
+
+No known issues updating from 3.5 to 3.6. If you are overriding `app/views/catalog/_document_list.html.erb` in your local application, you may want to look at how it is now written in the gem.  See https://github.com/projectblacklight/blacklight/commit/b712d79fa88e80155972ce3e9bc7629d7e63c1eb

data/doc/Blacklight-3.7-release-notes-and-upgrade-guide.md

@@ -0,0 +1,80 @@
+## Bookmarks and Folders merged
+
+When upgrading to Blacklight 3.7, if you want to keep the 'folders' feature (of session-based, anonymous item selection), you should add this gem to your Gemfile:
+
+```
+gem 'devise-guests'
+```
+
+The bookmarks (database persisted, user-based) and folders (session stored, session-based) features have been merged into a single bookmarks feature (database persisted, user-based). These bookmarks are database-persisted and assume an ActiveRecord-based user model. 
+
+The [devise-guests](http://rubygems.org/gems/devise-guests), generated into new applications by default, provides (session-based) guest user functionality to Devise (and, to Blacklight for applications that are using Devise). When a guest user logs in, the bookmarks associated with the guest user are transfered to the logged in user.
+
+If you are using `devise-guests`, you will want to regularly run a rake task it provides to purge old 'guest' data from your database: `RAILS_ENV=production rake devise_guests:delete_old_guest_users[7]`
+
+### Implementation details for those not using devise.
+
+We've added a new method ```#current_or_guest_user```. By default, this is just the value of ```#current_user``` (provided by Devise, or whatever authentication layer you are using). Applications that want to provide session-based bookmarks should implement ```#current_or_guest_user``` and ``#guest_user``` in the application and return the current user (when logged in) or a session-based guest user record.
+
+When a user logs in, your application should call ```#transfer_guest_user_actions_to_current_user``` to move the bookmarks and saved searches to the logged in user.
+
+## Query Facets
+
+Blacklight 3.7 adds support for Solr query facets. There's an example of this in the [Blacklight demo](http://demo.projectblacklight.org) with the Publish Date facet.
+
+The Publish Date facet is using this configuration:
+
+```ruby
+    config.add_facet_field 'example_query_facet_field', :label => 'Publish Date', :query => {
+       :years_5 => { :label => 'within 5 Years', :fq => "pub_date:[#{Time.now.year - 5 } TO *]" },
+       :years_10 => { :label => 'within 10 Years', :fq => "pub_date:[#{Time.now.year - 10 } TO *]" },
+       :years_25 => { :label => 'within 25 Years', :fq => "pub_date:[#{Time.now.year - 25 } TO *]" }
+    }
+```
+
+The first argument (which maps to the facet field for plain facets) is used in the Blacklight URL when the facet is selected.
+
+The ```:query``` hash maps the URL key into a facet label (to show to the user) and a fq to send to `facet.query` and, after selection, the Solr `fq` parameter.
+
+
+### A small change to the Blacklight configuration to get Blacklight to generate facet.query for you. 
+
+In older versions of Blacklight, the facet field keys mapped directly to the Solr ```facet.field``` parameter. By default, Blacklight generated the following into your CatalogController configuration:
+
+```
+    config.default_solr_params[:'facet.field'] = config.facet_fields.keys
+```
+
+In the new model, this logic is deferred as part of the Blacklight solr search params logic. The above line should be replaced with:
+
+```
+    # Have BL send all facet field names to Solr, which has been the default
+    # previously. Simply remove these lines if you'd rather use Solr request
+    # handler defaults, or have no facets.
+    config.add_facet_fields_to_solr_request!
+```
+
+This will add the plain facets to the ```facet.field``` and the query facets to the ```facet.query```.
+
+### Adding facet queries to the solr request handler yourself
+
+If you want to add the facet queries directly to your solr request handler, you should ensure the configuration for the Blacklight facet queries ```fq``` field matches a Solr ```facet.query``` field. 
+
+So, given this Solr response:
+
+```xml
+<lst name="facet_counts">
+  <lst name="facet_queries">
+    <int name="lc_alpha_facet:A">0</int>
+  </lst>
+  ...
+</lst>
+```
+
+The Blacklight-side config would look something like:
+
+```ruby
+    config.add_facet_field 'contrived_blacklight_configuration_example',  :query => {
+       :a => { :label => 'starting with A', :fq => "lc_alpha_facet:A" },
+    }
+```

data/doc/Blacklight-3.8-release-notes-and-upgrade-guide.md

@@ -0,0 +1,11 @@
+This is primarily a release to bring the Blacklight 3.x line up to feature-parity with the upcoming bootstrap release, and contains backports of features and bugfixes from the bootstrap work.
+
+Highlights include:
+
+- pulling bookmark data from solr (rather than a database-backed title cache)
+- clean-up of some pagination code 
+- pruning dead code around folders (removed in the 3.7 release)
+
+And more:
+
+[[https://github.com/projectblacklight/blacklight/compare/v3.7.2...v3.8.0]]

data/doc/Blacklight-4.0-release-notes-and-upgrade-guide.md

@@ -0,0 +1,135 @@
+# Blacklight 3.6 Release Notes And Upgrade Guide
+
+## Release Notes
+
+- Remove dependency on RSolr::Ext. In this first stage, some RSolr::Ext code is now maintained in Blacklight, e.g.:
+     - RSolr::Ext::Response::Facets => Blacklight::SolrResponse::Facets
+     - RSolr::Ext::Doc => Blacklight::Solr::Document
+     - etc
+
+- Bootstrap-based view templates and default stylesheet; removed compass/susy 
+- Drop support for Ruby 1.8; add support for Ruby 2.0 
+
+And the usual bug-fixes (some of which are backported into 3.8.x):
+
+- fix #64, show MoreLikeThis titles on record show page if available
+- fix #422; show prev/next options even when not linked
+- fix #450; support Solr 4.x and use it by default.
+- fix #484, use top-level constant BLACKLIGHT_VERBOSE_LOGGING (uninitialized by default) to log the full solr response with each solr query
+- fix #495 Remove blacklight_config.rb template
+- fix #496, removing hard-coded 'id' field reference in BookmarksController
+- remove unicode as an explicit Blacklight dependency, but use it if it is available
+- fix #499 When document_heading is an array, don't draw the array bracket…
+- fix #502, Endnote action tries to render partials and gives error
+- update per_page widget to use i18n strings; don't require echoParams
+- use 1.9-style string interpolation for template path lookups
+- consolidate solr pagination information lookup.
+
+## Plugins Compatibility
+
+As of 11/26:
+
+### Tested/Compatible
+
+* blacklight_advanced_search
+* blacklight_cql
+* blacklight_range_limit
+* blacklight_browse_nearby
+
+
+
+
+## Upgrade Guide
+
+When approaching the Blacklight 3.x => 4.0 upgrade, we'd strongly recommend adopting the bootstrap templates, update local overrides to use bootstrap, and do your own bootstrap stylesheet customization. 
+
+That said, it should be possible to do a fairly straightforward in-place upgrade if you so choose. Most of the Blacklight 4.x work was limited to views, javascript and stylesheets. If you want to keep the old Blacklight theme, you should be able to grab them from Blacklight and drop them into your application directly. We wouldn't recommend it though.
+
+To upgrade your application to Blacklight 4.x:
+
+- Update your application's gem dependency to use Blacklight 4.0:
+
+```ruby
+gem 'blacklight', "~>4.0"
+```
+
+- Add the unicode gem to your application's Gemfile (if you want to use it to normalize character encoding for refworks integration):
+
+```ruby
+gem 'unicode'
+```
+
+- Remove compass/susy references; replace with bootstrap-sass:
+
+```ruby
+# REMOVE:
+gem 'compass-rails', '~> 1.0.0', :group => :assets
+gem 'compass-susy-plugin', '~> 0.9.0', :group => :assets
+
+# ADD:
+gem 'bootstrap-sass'
+```
+
+- (Remember to ```bundle install```)
+
+- Add the following into your stylesheets directory (possibly as ```app/assets/stylesheets/blacklight.css.scss```):
+
+```scss
+@import 'bootstrap';
+@import 'bootstrap-responsive';
+
+@import 'blacklight/blacklight';
+```
+
+You no longer need the ```blacklight_themes directory``` and can remove ```require 'blacklight_themes/standard'``` (and the jquery UI css) from your application.css
+
+In ```app/assets/javascripts/application.js```, you can also remove
+
+```javascript
+//= require jquery-ui
+```
+
+- If you have local overrides of stylesheets, javascript or view templates, you should update them appropriately. Be warned that some of the bootstrapped Blacklight HTML element classes and IDs may have shifted slightly, and the previous susy-grid and YUI class names have been removed.
+
+In your `ApplicationController`, you need to tell your application which layout to use:
+
+```ruby
+# completely Blacklight 3.x-backwards compatible
+layout :choose_layout
+
+# if you don't need dynamic layout switching, just do the Rails-standard:
+layout 'blacklight'
+```
+
+- If you are using devise-guests, you probably want to update to devise-guests ~> 0.3. After doing so,
+
+```bash
+$ rails g devise_guests
+$ rake db:migrate
+```
+
+If you've already chosen a different layout for your application, you don't need to do anything at all.
+
+Here are some minor differences elsewhere:
+
+ - Some i18n strings have been updated to read better in the new UI
+ - the helper `#render_document_heading` returns an h4 instead of an h1.
+ - the helper `#document_show_fields` returns a hash instead of a list of keys
+
+## Document partial paths
+
+The default naming convention for format-specific partials was changed. In Blacklight 3.1, the default format-specific path was changed to `catalog/_index_[format_name].html.erb`, but support for the Blacklight 2.x style was left in place. In Blacklight 4, the Blacklight 2.x style was removed from the list of defaults.
+
+So, if you have partials in a directory like:
+
+```ruby
+catalog/_index_partials/[format_name].html.erb
+```
+
+they should be moved to
+
+```ruby
+catalog/_index_[format_name].html.erb
+```
+
+Or, alternatively, you may override the helpers [document_index_path_templates](https://github.com/projectblacklight/blacklight/blob/master/app/helpers/blacklight/blacklight_helper_behavior.rb#L382) and [document_partial_path_templates](https://github.com/projectblacklight/blacklight/blob/master/app/helpers/blacklight/blacklight_helper_behavior.rb#L423) with a custom naming convention.