Upgrading to 1.0.0
This document is intended for developers, to help with the process of upgrading to version 1.0.0 of Open SDG, from any previous release.
If your site is pointing at the standard set of translations (most likely something like
https://open-sdg.github.io/sdg-translations/translations.json) then you can skip to "Data repository updates" below. But if your site is pointing to a forked set of translations, then you should be aware of some new required translation keys.
The new translation keys required by Open SDG, along with links to their English translations, are as follows:
- calendar.January (along with the other 11 months of the year)
- metadata_fields.comments_limitations (this is a change, rather than an addition)
Language code changes¶
If you are using the following languages, be aware that the language codes in sdg-translations have changed. Your translation folders should use the updated language code. Your site itself can continue using the old language code, as described below in site repository section, with the
- Armenian: changed from "am" to "hy"
- Kazakh: changed from "kz" to "kk"
Data repository updates¶
Next it is recommended to make the following updates to your data repository.
Upgrade to sdg-build 1.0.0¶
requirements.txt file to:
Take advantage of YAML-based configuration¶
If you are using the default data management approach -- .CSV files for data and .MD files for metadata -- then it is recommended that you adopt a new, simpler data repository configuration. You can do this by emulating the data starter, but here are the details:
- Add a configuration file called
config_data.yml. Start with this file and edit as needed. You should read through the whole file, but in particular:
- Adjust the
languageslist (as described in the data starter config).
- If your site repository was pointing at custom translations repositories, adjust the defaults for
translations(as described in the data starter config).
- Note that these should point directly to Git repositories (usually ending in .git) and NOT to .json files.
- Note that if you are using the standard
open-sdg/sdg-translationstranslations, that you should use version 1.0.0, as demonstrated here (link TBD).
- If your site uses the Open SDG mapping functionality, uncomment and adjust the
map_layers(as described in the data starter config).
- Adjust the
- Replace the contents of the scripts you use to check and build data. They are likely called
build_data.py, in your
scriptsfolder. Unless you need special customisations, you can use the exact versions from the data starter (check_data.py and build_data.py.
If you are not able to use this new YAML-based configuration approach, or you would prefer not to, you can use the sdg-build classes directly, as demonstrated in the sdg-build example. This requires some knowledge of Python.
Update some special metadata fields, if you use them¶
The expected structure of the
data_start_values metadata field has changed to be a list of objects, rather than a list of strings. See an example of using data_start_values. If you use
data_start_values for any indicators, update their structure before going further.
Confirm that your data and metadata passes validation¶
The validation rules for data and metadata have changed, in some ways becoming more strict. To save time in resolving any issues, you can run the validation locally (if you have Python 3 installed) like so:
pip install -r scripts/requirements.txt
If you see no output from the above command, that means your data and metadata is already fine. However if you see any output, you will need to fix your data and/or metadata as described in the output.
Copy over any local translations from your site repository¶
With Open SDG 1.0.0, it is recommended that your "local" custom translations be in your data repository instead of your site repository. If you have any such translations, they are likely in a "data/translations" folder in your site repository. You can simply move them over as-is.
The new locations for the translations should be in a folder in your data repository called
translations, as demonstrated by the data starter translations folder.
For example, if you had translations in your site repository at
/my-site-repository/data/translations and your data repository is at
/my-data-repository, then you would move them over with something like this:
mv /my-site-repository/data/translations /my-data-repository/
Afterwards you should have a folder of translations at
Deploy the updated data repository¶
At this point your data repository is ready to be deployed in the usual way, by merging the changes to the
Site repository updates¶
Next you should make the following updates to your site repository.
Update version of Open SDG to 1.0.0¶
_config.yml file, update the version of Open SDG in
remote_theme, like so:
Update version of jekyll-open-sdg-plugins to 1.0.0¶
In your Gemfile, update the version of jekyll-open-sdg-plugins like so:
gem "jekyll-open-sdg-plugins", "1.0.0"
Delete all indicator files, goal files, and some pages¶
Open SDG is now capable of automatically creating your indicators, goals, and some of your pages. This allows you to remove them from your site repository.
You still have the option of leaving them in, but it is recommended to remove them unless you have special circumstances that requires them.
If you chose to remove them, you can delete the following folders/files, if needed:
- the entire
- the entire
- the following pages (along with any translated versions):
index.md(the home page)
search.md(the search page)
reporting-status.md(the reporting status page)
indicators.json(the data for the search page)
Perform some updates to the
The following changes should be made in the
_config.yml file, if needed:
- Check the format of the
menusettings and make sure they match the site starter config
- Update the
map_layersconfiguration, if your site is using the Open SDG mapping functionality. In particular:
- Remove each map layer's
- Add a
subfolder(which should match the
output_subfolderyou added to your data repository)
- Add a
label(a human-readable description of the layer, which will be displayed on a download button)
- Remove each map layer's
The following config settings can be removed, if needed:
defaults(unless you had a custom use for it)
pluginsif it's there
custom_css(and see below about updating custom CSS)
The follow config settings should be added, if needed:
data_edit_urlas done in the site starter config
metadata_edit_urlas done in the site starter config
create_indicatorsas done in the site starter config
create_goalsas done in the site starter config
create_pagesas done in the site starter config
- Add and cusotmise
footer_menuas done in the site starter config
non_global_metadataas done in the site starter config
- If you are using the Armenian language, and would like to continue using a language code of "am", you should add the following:
languages_public: hy: am
- If you are using the Kazakh language, and would like to continue using a language code of "kz", you should add the following:
languages_public: kk: kz
- If you are upgradiing to 1.0.0 from a much lower version, there may be additional settings needed. You should scan through the site starter config and decide if there is anything else you need to add to yours.
Update any custom CSS¶
As you may have gathered from above, the
custom_css configuration option is deprecated in favor of a more standard Jekyll approach. To add custom styles it is recommended to put a
custom.scss in your site repository's
_sass folder. This has the effect of overriding the
_sass/custom.css file in Open SDG.
In short, create a
_sass folder and a file inside it called
custom.scss. Copy all of your custom CSS into this folder.
Important: This file should NOT include the
---lines at the top, like you may have had previously. You must remove those lines.
Custom includes and layouts¶
If you have any files in your
_layouts folders, you will most likely need to adjust them, as nearly every include/layout in Open SDG has changed. For each of these, the easiest route depends on how much you modified your version from the original:
For overrides with only small changes¶
If your version of a file contains only small changes from the original, you may find it easier to start with the updated originals from this theme (see the Open SDG
_includes folder and the Open SDG
_layouts folder) and re-do your changes.
For overrides with large amounts of changes¶
If your version of a file is dramatically changed from the original, you may find it easier to understand what changed in version 1.0.0, and make those changes to your own version. See this diff between 0.10.0 and 1.0.0 and look for the file in question. In general, the main changes will be:
thas changed to
page.t. Eg: t.general.goal is now page.t.general.goal.
- Global variables like
current_language, etc. are no longer available, and have been replaced with variables on the
pageobject, as described in the Jekyll template customisation docs.
Test your site locally¶
Because this is a major version change, it is recommended that you test your site locally. As described in the local development docs, this requires Ruby, and the following commands:
bundle exec jekyll serve
Deploy the updated site repository¶
At this point your site repository is ready to be deployed in the usual way, by merging the changes to the