Upgrading - NatLibFi/Skosmos GitHub Wiki

Upgrading Skosmos to a newer version

Generic upgrade notes

The normal upgrade procedure is:

make a backup of your current installation, especially config.ttl (or config.inc and vocabularies.ttl for <2.0)
upgrade your code to the new version, either:
- download a new version and replace the files, or
- switch to the new version branch using e.g. git checkout v2.18-maintenance
migrate (copy) config.ttl to your new installation if necessary, or create a new one (see Configuration)
update Composer just in case: php composer.phar self-update
update dependencies: php composer.phar update --no-dev
- If you want to do your own development, run unit tests, generate documentation etc., you should omit the --no-dev option and Composer will install required packages for development as well.
- if Composer asks for your Github username and password, you may have hit the Github API rate limit - see the Composer documentation for details (either give your username/password or use an OAuth token)
clear Twig template cache (default location: /tmp/skosmos-template-cache)
restart Apache (this will clear gettext and APC caches - reloading is not enough!)
clear your browser cache, as it may contain JavaScript or CSS files from the old version
see version-specific notes below for more

Version specific notes

From Skosmos 2.17 to 2.18

The support for PHP 7.x was dropped in this release. Skosmos 2.18 runs on PHP 8.0 and 8.1.
The fallback mechanism for vocabulary titles has changed. If you don't have vocabulary titles in all of your UI languages, you should add a fallback titles without a language code. Previously, a title in any other language could be used as a fallback.
This release brings better support for SEO and social media sharing metadata in generated HTML pages. Some of this is automatic, but extended description texts for specific page types and for individual vocabularies can be provided in global and vocabulary-specific Configuration.

From Skosmos 2.16 to 2.17

Nothing out of ordinary, following the normal upgrading procedure is enough.

From Skosmos 2.15 to 2.16

There are some CSS changes as well as a major upgrade of the jQuery library. Any CSS customizations and JavaScript plugins/widgets may need to be updated.

From Skosmos 2.14 to 2.15

This release upgrades Bootstrap from version 3 to version 5. There are a lot of changes to HTML templates and CSS rules. Customized Skosmos instances will have to be adjusted accordingly.
This release drops support for PHP 7.2. The code in this release should still work on PHP 7.2 but we cannot offer any guarantees going forward.

From Skosmos 2.13 to 2.14

There have been changes to the configuration of Plugins. In particular, the order in which plugins are configured determines the order of plugin initialization and order of callbacks.
Skosmos has been tested to work with Fuseki 4.4.0 and unit tests are now using that version. We recommend upgrading Fuseki to a recent release, in which the log4j security issues have been addressed.
It is now possible to run Skosmos with PHP 8.0 as well as older versions 7.2, 7.3 and 7.4.

From Skosmos 2.12 to 2.13

You can now do theming in Skosmos by overriding CSS custom properties ("CSS variables") that define the colors used in the user interface. Take a look at the colors defined at the top of the styles.css file and PR #1226 where this feature was implemented.
If your vocabulary uses dct:modified timestamps and uses deprecated concepts, it is now possible to configure these separately with properties skosmos:showChangeList "true" and skosmos:showDeprecatedChanges "true". The former generates a tab in the vocabulary sidebar with a list of latest concepts. The latter shows also deprecated concepts in this list, with a redirect to the replacing concept if such is present in the same vocabulary. The option of showing the deprecated concepts will double the loading time of the change list tab.
It is now possible to configure property labels and tooltips for the concept page, with skosmos:propertyLabelOverride configuration option. Refer to Configuration page for further information.

From Skosmos 2.11 to 2.12

By default, SKOS notations are now shown on the concept page as regular properties. If you wish not to show them, the skosmos:showNotationAsProperty option needs to be set to false in config.ttl.

From Skosmos 2.10 to 2.11

Nothing out of ordinary, following normal upgrading procedure is enough.

From Skosmos 2.9 to 2.10

PHP 7.1 is no longer supported. If you are still running that version, you need to upgrade PHP first before (or at the same time as) upgrading Skosmos. Support for PHP 7.4 has been introduced.
If you have been running Skosmos as a Docker container, check out the new Dockerfiles. See the wiki page for running Skosmos with Docker for details.

From Skosmos 2.8 to 2.9

Nothing out of ordinary, following normal upgrading procedure is enough.

From Skosmos 2.7 to 2.8

In the Skosmos version 2.8, several major changes have been made in the HTML structure and CSS rules. Before upgrading to the Skosmos 2.8, you must do the following:

If you use your own CSS styles, check that there are no conflicts between Skosmos CSS styles and them.
Check that your own CSS styles still work properly.

From Skosmos 2.6 to 2.7

It is now possible to configure the order of properties shown on concept and search result pages. See Setting the property order for details.
Tooltips can now be shown for custom properties (non-SKOS, non-DC properties that have been defined within the vocabulary data). The tooltip text is read from rdfs:comment and skos:definition properties. If you use custom properties in your data, please make sure that the tooltips are what you expect.
The PHP internationalisation extension (intl) is now required. Installing this extension has been mentioned in the InstallTutorial for a long time, but until now it has been possible to use Skosmos without it. It can usually be installed from the system package php-intl or a version-specific package such as php7.3-intl.

From Skosmos 2.5 to 2.6

The 2.6 release brings enhanced functionality for generating Last-Modified headers and responding to If-Modified-Since requests with 304 responses, which speeds up page reload times and REST API access when the client already has a cached copy of the resource. This requires a reliable dc:modified timestamp on the main concept scheme (for example Skosify can add this) and must be enabled on a per-vocabulary basis with the skosmos:useModified configuration setting. (Note that this may slow down the worst case, cold-cache performance slightly)

From Skosmos 2.4 to 2.5

There is now support for parameterized (configurable) plugins. For example, the message plugin can now be customized with a message.

From Skosmos 2.3 to 2.4

New per-vocabulary configuration setting skosmos:searchByNotation (boolean) can be used to enable searching concepts by their notation codes. If you use jena-text, you will also need to add skos:notation to the EntityMap in the Fuseki configuration file for your dataset (see this commit for an example) and rebuild your text index.
New per-vocabulary configuration setting skosmos:alphabeticalListQualifier can be set to the value skos:notation to show notation codes in the alphabetical index.

From Skosmos 2.2 to 2.3

The minimum required PHP version is now 7.1. PHP 7.2 and 7.3 are also supported.
If you have previously set the skosmos:loadExternalResourcesto false, you may now want to enable it as external resources (mappings) are now loaded in a separate AJAX-style query.

From Skosmos 2.1 to 2.2

Skosmos can now create Last-Modified HTTP headers for concepts or vocabularies which include dct:modified timestamps. This needs to be enabled with the per-vocabulary setting skosmos:useModifiedDate "true" in config.ttl.
MARCXML has been added to the supported downloading formats. Set the vocabulary data dump location (an IRI) as you would normally do with void:dataDump and state the following triples dct:format "application/marcxml+xml" ; dct:language "$rdflangtag" . about that IRI.
skosmos:marcSourceCode may be set language independently per vocabulary and retrieved via REST API using the /vocabid/ general information retrieving method.

From Skosmos 2.0 to 2.1

PHP 7.2 now works since the compatibility issue in the JsonLD library has been fixed. So you may use either PHP 7.0, 7.1 or 7.2.

From Skosmos 1.* to 2.0

As of 2.0, Skosmos requires php version 7.0 or newer. Note that there are problems with PHP 7.2 related to the JsonLD library, so it might be easiest to use either PHP 7.0 or 7.1.
The configuration files config.inc and vocabularies.ttl are no longer used. Instead, all configuration is done in the file config.ttl. There is a migration script that can be used to convert from old-style configuration to the new format like this: php migrate-config.php config.inc vocabularies.ttl >config.ttl

From Skosmos 1.9 to 1.10

The EasyRdf library has been upgraded. All EasyRdf classes have been renamed in the new version. Be extra sure to restart Apache, since the APC cache needs to be cleared.
The alphabetical index can now be properly sorted into natural sort order. However, this requires Jena Fuseki 3.4.0 or newer. This can be enabled by setting the option "SPARQL_COLLATION_ENABLED" to true in config.inc.

From Skosmos 1.8 to 1.9

As of 1.9, installing Skosmos dependencies requires PHP version 5.6 or newer. However, this can be circumvented by removing two development related dependencies from the composer.json file locally before running composer. These are "symfony/dom-crawler" and "mockery/mockery".
There are two new configurable settings (UI_HONEYPOT_ENABLE and UI_HONEYPOT_TIME) for fine tuning the new feedback form honeypot. The new honeypot should prevent spam more effectively than the old one. More details at the configuration page of this wiki.

From Skosmos 1.7 to 1.8

nothing special

From Skosmos 1.6 to 1.7

There is a new setting SPARQL_TIMEOUT in config.inc that you may wish to set in config.inc (see config.inc.dist for an example). If not set, it defaults to 20 seconds. In previous versions, SPARQL requests always timed out at 10 seconds (see #509)
The DEFAULT_SEARCH_LIMIT setting in config.inc has been removed and replaced by a new setting SEARCH_RESULTS_SIZE, which sets the number of items to load at a time on the search results page. It defaults to 20 if not set. The old setting was badly named and had a default value of 100, which caused poor performance for long search results.

From Skosmos 1.5 to 1.6

nothing special

From Skosmos 1.4 to 1.5

The CSS style sheets have been refactored in this version. If you have defined your own custom CSS rules, be sure to check that they still work.

From Skosmos 1.3 to 1.4

Skosmos 1.4 requires Jena Fuseki 1.3.0 or 2.3.0 if you use the JenaText index (NOTE: Fuseki 1.3.1 and 2.3.1 have a bug which affects Skosmos so they are not recommended). With this version of Fuseki we make use of the new features in Jena 3 to provide even faster text search and alphabetical index. You will also need to change the Fuseki configuration and rebuild the text index. See the InstallFusekiJenaText page for details about the new text index configuration (you will need to add text:storeValues, text:uidField and text:langField settings). Note that these versions of Jena Fuseki require a Java 8 environment, so you may need to upgrade that first.
Skosmos now includes a default favicon . If you don't like it, you can create your own favicon and name it custom-favicon.ico in the root folder of Skosmos, then it will be used instead of the default favicon. If you already have a favicon.ico file, then you should rename it before upgrading.

From Skosmos 1.2 to 1.3

nothing special

From Skosmos 1.1 to 1.2

There is a new setting HTTP_TIMEOUT that you need to set in your config.inc file. See config.inc.dist for an example.

From Skosmos 1.0 to 1.1

nothing special

From Skosmos 0.7.x to 1.0

nothing special

From Skosmos 0.6.x to 0.7

the headline on the Skosmos front page, above the vocabulary list, is now taken from the label of the skos:ConceptScheme instance in vocabularies.ttl (see issue #151). You may want to check that the label makes sense (the default is "Skosmos Vocabulary Categories") and add labels in all the languages that you use.
if you have problems such as excessively long page load times for concept pages or such pages don't load at all, and your vocabulary contains links to external vocabularies (skos:exactMatch, owl:sameAs or other mapping relationships), you may want to set the new option skosmos:loadExternalResources to false, which will disable the fetching of linked data for external resources. See issue #118 and the Vocabularies page for details.
The Skosmos CSS layout has changed slightly (for the better we hope!), if you have local CSS customizations in your installation you may want to check that they still give the expected result. For example, the color and layout of the bars at the top has been adjusted.

From Skosmos 0.5.x to 0.6

Skosmos 0.6 requires Jena Fuseki 1.1.1 if you use the JenaText index. With this version of Fuseki we make use of the new LowerCaseKeywordAnalyzer to provide even faster text search. You will also need to change the Fuseki configuration and rebuild the text index. See the InstallFusekiJenaText page for details about the new text index configuration.
Composer is no longer included as part of Skosmos code (see pull request #57). You will need to install it separately, e.g. using the command wget https://getcomposer.org/composer.phar

From Skosmos 0.4.x to 0.5

Skosmos 0.5 requires Jena Fuseki 1.1.0 if you use the JenaText index. In this version of Fuseki, text searches support leading wildcards (e.g. '*ism') and Skosmos make use of this to optimize suffix queries. You should upgrade to Fuseki 1.1.0 before attempting to use Skosmos 0.5. There is no need to rebuild TDB or the jena-text index.
- you may want to use Fuseki 1.1.1-SNAPSHOT from 2014-09-17 or later if you have supplementary Unicode characters in your data (e.g. in Lexvo.org data); see issue #76 and JENA-785 for details.
it's recommended that you assign short names to your vocabularies using the skosmos:shortName property in vocabularies.ttl; otherwise, your vocabulary id's will be used as short names in the user interface. See wiki page on vocabularies.ttl for details.
Skosmos now loads external Linked Data resources if you have mapping relationships in your vocabularies. Some external resources can be large (e.g. DBpedia concepts) and you may need to increase the PHP memory_limit setting to 256M (see issue #98).
be sure to configure your PHP date.timezone setting, otherwise you may get errors when displaying date values

From ONKI Light 0.3 to Skosmos 0.4

The LANGUAGES constant in config.inc was changed to the $LANGUAGES variable, which is an array that maps language codes to system locales. If you reuse an old config.inc, be sure to change this (see config.inc.dist for an example). Use locale -a to list your available system locales on a *nix system.
The FEEDBACK_ENVELOPE_SENDER and CUSTOM_CSS constants in config.inc have been added. Be sure to copy these from config.inc.dist if you reuse an old config.inc file.
The vocabularies.ttl file now uses a skosmos: namespace instead of the old onki: namespace. If you reuse an old vocabularies.ttl file, you should perform these changes:
- Replace the line @prefix onki: <http://schema.onki.fi/onki#> . with @prefix skosmos: <http://purl.org/net/skosmos#> .
- Replace all occurrences of onki: with skosmos: