Upgrading to 2.0.0
This document is intended for developers, to help with the process of upgrading to version 2.0.0 of Open SDG, from 1.8.0 or higher.
Because this is a major upgrade, please ensure you are upgraded to 1.8.0 or higher, and have read this entire document, before proceeding..
Upgrade data repository to sdg-build 2.0.0¶
In your data repository, update your
requirements.txt file to:
Upgrade translations to sdg-translations 2.0.0¶
In your data repository's config file, update the version of sdg-translations in the "translations" section:
translations: - class: TranslationInputSdgTranslations source: https://github.com/open-sdg/sdg-translations.git tag: 2.0.0
Update version of Open SDG to 2.0.0¶
In your site repository's
_config.yml file, update the version of Open SDG in
remote_theme, like so:
Update version of jekyll-open-sdg-plugins to 2.0.0¶
In your site repository's
Gemfile, update the version of jekyll-open-sdg-plugins like so:
gem "jekyll-open-sdg-plugins", "2.0.0"
Changes in 2.0.0¶
Because 2.0.0 is a major upgrade, there are many changes to be aware of:
accessible_charts - always on¶
accessible_charts site configuration has been removed because the platform now automatically includes the accessibility improvements to charts.
accessible_tabs - always on¶
accessible_tabs site configuration has been removed because the platform now automatically includes the accessibility improvements to tabs.
bootstrap_5 - always on¶
bootstrap_5 site configuration that was added in 1.8.0 has been removed because the platform now automatically uses Bootstrap 5.
Notably, any "include" files that were placed into the "bootstrap5" subfolder have been moved out of that folder, and any "layout" files that ended with "-bootstrap5" have been renamed to remove that suffix. See the "Overrides" section below for more details on this.
chartjs_3 - always on¶
chartjs_3 site configuration that was added in 1.8.0 has been removed because the platform now automatically uses Chart.js 3.
Notably, any "include" files that ended with "-chartjs3" have been renamed to remove that suffix. See the "Overrides" section below for more details on this.
contrast_type - removed¶
contrast_type site configuration has been removed and the platform will behave as though the "single" option were chosen, there the contrast toggle button is a single button in the top right corner.
create_goals - layout removed¶
layout option in the
create_goals site configuration has been removed, and the platform will always use the "goal" layout.
create_pages - automate two pages¶
Throughout 1.x the
create_pages site configuration has been expected to contain items for the frontpage and for an "indicators.json" file. These can now be removed from
create_pages because they will be automatically created. For example, see the difference between the
create_pages settings from the 1.8.0 site starter and the 2.0.0 site starter (links TBD).
create_pages - deprecated structure removed¶
Throughout 1.x the
create_pages site configuration has supported an older structure, but in 2.0.0 this will no longer work. Your
create_pages setting will need to fit the structure detailed in our documentation.
data build - indicator property changes¶
The data build automatically assigns various properties as metadata to each indicator. A few of these properties were being duplicated for backwards compatibility, but those duplicates will now be removed. These will likely not affect you unless you had some custom code (such as data or metadata alterations) which was relying on the older properties. The changes are:
data build - SDMX inputs, import_translation_keys change¶
The parameter for SDMX inputs called
import_translation_keys has been removed, and replaced with
data columns/fields - default sorting change¶
Throughout 1.x the default sorting logic for disaggregation dropdowns and options has been "alphabetical", but now the default will be "default" -- where the sorting is based on position in the data. See the
datapackage "sorting" option for more information. To keep alphabetical sorting, you will need to configure your data build as described in the link above, to 'alphabetical'.
date_formats - deprecated structure removed¶
Throughout 1.x the
date_formats site configuration has supported an older structure, but in 2.0.0 this will no longer work. Your
data_formats setting will need to fit the structure detailed in our documentation.
favicons - removed¶
favicons site configuration has been removed and the platform will always use the
favicon.io approach. This may be a breaking change for any implementation still using older favicon images, and in this case you would need to create new favicon images according to this favicon tutorial.
frontpage-alt layout removed¶
frontpage-alt layout has been removed. Now there is only a single layout for frontpage, called
frontpage_goals_grid - required¶
frontpage_goals_grid is now required if you would like the goal icons to display on your frontpage. Existing implementations of Open SDG may be using a particular frontpage layout in which the goals grid displays automatically. However, as of 2.0.0, if you would like the goals grid to display, you must use the
frontpage_goals_grid site configuration. For example:
frontpage_goals_grid: title: frontpage.heading_short description: frontpage.instructions_short
You may also want to add the frontpage introduction banner as well, with the following:
frontpage_introduction_banner: title: frontpage.intro_title description: frontpage.intro_body
frontpage_heading - removed¶
frontpage_heading site configuration has been removed. The new setting used to control this text on the frontpage is
frontpage_introduction_banner. Any custom text that you have in
frontpage_heading should be copied to
frontpage_instructions - removed¶
frontpage_instructions site configuration has been removed. The new setting used to control this text on the frontpage is
frontpage_goals_grid. Any custom text that you have in
frontpage_instructions should be copied to
graph_color_set - default changed to "accessible"¶
The default color set for graphs is now the
accessible option. Previously it was a different set called
default. If you would like to continue using this
default color set, you can change this setting to
header - removed¶
header site configuration has been removed, and the platform will always use a consistent header. The "include file" that is used for the header is:
languages - required¶
A more technical consequence is that, while previously there was a distinction between a "translated build" and "non-translated build", now all builds will be translated. This will make no difference in practice, but you may notice that your data builds are placed in a subfolder for each language, if you were not already using languages.
non_global_metadata - removed¶
non_global_metadata setting has been removed. The only affects platforms that were using something other than "National" for the non-global metadata tab. In order to maintain this feature you will need to use the
metadata_tabs site configuration to specify the labels used for each tab.
series_toggle - always on¶
series_toggle setting has been removed and the platform will behave as if it were always on. This means that the series column in your data will be rendered more like a unit and less like a disaggregation. Note that you can control the name of the series column, and you also have control over your data columns, so there are multiple ways to continue to have your series behave like a disaggregation if you would prefer that.
Upgrading from 1.8.0 with Bootstrap 5¶
If you are already using Bootstrap 5 (you have
bootstrap_5 set to
true), and you have overriden any files in
bootstrap/ subfolders, then you will need to change the location of those overrides. Whereas in 1.8.0, using Bootstrap 5 was optional, in 2.0.0 it is required. So, in 2.0.0 we no longer need to use the
bootstrap5 subfolders. Here is a list of these files, and the new location of them in 2.0.0.
In short, if you are overriding any of the files on the left, you should move your overrides to the location on the right.
|1.8.0 location||2.0.0 location|
In addition, some layouts have had
-bootstrap5 removed from their name. If you are overriding any of the following files on the left, you should rename them to the version on the right.
|1.8.0 file||2.0.0 file|
Upgrading from 1.8.0 with Chart.js 3¶
If you are already using Chart.js 3 (you have
chartjs_3 set to
true), and you have overriden any files with
chartjs3 in the filename, then you will need to rename those overrides. Whereas in 1.8.0, using Chart.js 3 was optional, in 2.0.0 it is required. So, in 2.0.0 we no longer need
chartjs3 versions of files. Here is a list of these files, and the new name for them in 2.0.0.
In short, if you are overriding any of the files on the left, you should rename them to the version on the right.
|1.8.0 file||2.0.0 file|
Relevant blog posts¶
Here are blog posts for particular issues related to this upgrade: