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:

git+https://github.com/open-sdg/sdg-build@2.0.0

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:

remote_theme: open-sdg/open-sdg@2.0.0

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

The accessible_charts site configuration has been removed because the platform now automatically includes the accessibility improvements to charts.

accessible_tabs - always on

The accessible_tabs site configuration has been removed because the platform now automatically includes the accessibility improvements to tabs.

bootstrap_5 - always on

The 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

The 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

The 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

The 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:

  • indicator_number instead of indicator
  • target_number instead of target_id
  • goal_number instead of sdg_goal

data build - SDMX inputs, import_translation_keys change

The parameter for SDMX inputs called import_translation_keys has been removed, and replaced with import_codes.

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

The 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

The frontpage-alt layout has been removed. Now there is only a single layout for frontpage, called frontpage.

frontpage_goals_grid - required

The 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

The 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_introduction_banner.

frontpage_instructions - removed

The 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 frontpage_goals_grid.

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 classic.

header - removed

The 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: _includes/header.html

languages - required

The languages setting is now required, in both the site configuration and data configuration and must have at least one language. These two settings should be identical to each other.

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

The 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

The 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
_includes/assets/js/bootstrap5/accessibility.js _includes/assets/js/accessibility.js
_includes/assets/js/bootstrap5/accessibleTabs.js _includes/assets/js/accessibleTabs.js
_includes/bootstrap5/components/card.html _includes/components/card.html
_includes/bootstrap5/components/contrast-toggle.html _includes/components/contrast-toggle.html
_includes/bootstrap5/components/goal/breadcrumbs.html _includes/components/goal/breadcrumbs.html
_includes/bootstrap5/components/goal/header.html _includes/components/goal/header.html
_includes/bootstrap5/components/indicator/breadcrumbs.html _includes/components/indicator/breadcrumbs.html
_includes/bootstrap5/components/indicator/data-main.html _includes/components/indicator/data-main.html
_includes/bootstrap5/components/indicator/data-panes.html _includes/components/indicator/data-panes.html
_includes/bootstrap5/components/indicator/data-tabs.html _includes/components/indicator/data-tabs.html
_includes/bootstrap5/components/indicator/header.html _includes/components/indicator/header.html
_includes/bootstrap5/components/indicator/indicator-main.html _includes/components/indicator/indicator-main.html
_includes/bootstrap5/components/indicator/indicator-progress.html _includes/components/indicator/indicator-progress.html
_includes/bootstrap5/components/indicator/metadata-panes-default.html _includes/components/indicator/metadata-panes-default.html
_includes/bootstrap5/components/indicator/metadata-panes.html _includes/components/indicator/metadata-panes.html
_includes/bootstrap5/components/indicator/metadata-section.html _includes/components/indicator/metadata-section.html
_includes/bootstrap5/components/indicator/metadata-tabs-default.html _includes/components/indicator/metadata-tabs-default.html
_includes/bootstrap5/components/indicator/metadata-tabs.html _includes/components/indicator/metadata-tabs.html
_includes/bootstrap5/components/indicator/tags.html _includes/components/indicator/tags.html
_includes/bootstrap5/components/language-toggle-dropdown.html _includes/components/language-toggle-dropdown.html
_includes/bootstrap5/components/language-toggle-links.html _includes/components/language-toggle-links.html
_includes/bootstrap5/components/language-toggle.html _includes/components/language-toggle.html
_includes/bootstrap5/components/previous-next-links.html _includes/components/previous-next-links.html
_includes/bootstrap5/components/post/breadcrumbs.html _includes/components/post/breadcrumbs.html
_includes/bootstrap5/footer.html _includes/footer.html
_includes/bootstrap5/header.html _includes/header.html
_includes/bootstrap5/navigation-link.html _includes/navigation-link.html
_includes/bootstrap5/navigation.html _includes/navigation.html
_includes/bootstrap5/search.html _includes/search.html

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
_layouts/goal-bootstrap5.html _layouts/goal.html
_layouts/reportingstatus-bootstrap5.html _layouts/reportingstatus.html
_layouts/indicator-bootstrap5.html _layouts/indicator.html

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
_includes/assets/js/chartjs/accessibleCharts-chartjs3.js _includes/assets/js/chartjs/accessibleCharts.js
_includes/assets/js/indicatorView-chartjs3.js _includes/assets/js/indicatorView.js

Relevant blog posts

Here are blog posts for particular issues related to this upgrade: