Upgrading from v1.x to 2.0.0

Upgrading from v1.x to 2.0.0

The 2.0.0 release represents a major upgrade to the Roadmap codebase. Please follow the instructions below to ensure that your site functions properly after upgrade.

We highly recommend that you backup your existing database and that you perform these tasks in a development environment first so that you can confirm the functionality of your system before running the upgrade in your production environment!

Overview of data model changes

• Added new table stats to facilitate the Usage Statistics page available to Admins
• Added new versionable_id field to the following tables to help ensure accurate transfer of template customizations when a funder template changes: annotations, questions, sections, phases
• Added default: false to boolean fields: guidance_groups.published, guidance_groups.optional_subset, notes.archived, orgs.is_other
• Added limit: 80 to users.email
• Dropped unused tables: file_types, file_uploads, splash_logs
• Removed unused fields: guidances.question_id, orgs.wayfless_entity, orgs.parent_id, orgs.banner_text, orgs.logo_file_name, phases.slug, plans.slug, users.orcid_id, users.shibboleth_id
• Various index changes in support of the above changes

Part One

The first script repairs any existing records in your guidance_groups, notes or orgs tables that would become invalid by the new validation rules added during the db:migrate step. It then runs the database migrations and finally runs a script that scans your tables for invalid data. We have added validation logic to the models in the codebase that may cause issues with your existing data. Please review the output of the script and fix any issues that it reports.

TODO: Add explanation of issues reported and how to address them via data_cleanup rules

Data cleanup

Extensive changes were made to improve data validation for this release. The following tasks should be run to correct any existing data that would become invalidated by these changes:

Run the task to identify data that needs to be fixed:

> rake data_cleanup:find_known_invalidations

Review the report and then run the following script to clean up the records identified above:

> rake data_cleanup:clean_invalid_records

Once the cleanup task is complete (can take a while depending on the size of your database) you should run the find_known_invalidations task again to ensure that it cleaned up all of the bad records.

Data migration

Once you have cleaned up the data you should run through the normal database migrations

> rake db:migrate

Rake tasks

Run the following rake task after the migrations have finished to correct any issues with your ISO language codes and to initialize the new versionable_id fields for templates, phases, sections, questions and annotations.

Please note that if you are not currently on version v1.1.4 you should run the specific Rake upgrade tasks for each incremental version, [v0_3_3, v1_0_0, v1_1_2] before running the following task. For example if you are on version 1.0.0 then you will need to run rake upgrade:v1_1_2 prior to the task below.

> rake upgrade:v2_0_0

Updating your deployment scripts

This release also involved some changes to the basic infrastructure of the system. Please check and update your deployment scripts as needed for your individual installations.

• Tests are now run via RSpec instead of MiniTest. Use rpec spec/ to run the tests
• Modifications were made to the Webpack configuration. To compile you assets for production (or any situation where you do not want Webpack to watch your assets for changes) you should now use npm run bundle -- -p --no-watch
• We have updated the Gemfile to segregate deployment specific gems so that you can exclude them as needed when running bundle install --without [groupA] [groupB]. For example: bundle install --without mysql puma thin:
  • puma
  • thin
  • mysql
  • postgres
• You will need to setup a job (e.g. via CRON) that runs the rake stat:build_monthly task at the beginning of each month

Changes to the developer guide

We have also updated our Wiki to improve our developer guides. Please review the updated documentation.