Migrating Node.js

Migrating Node.js

Preparation

Choosing Node.js version

Before upgrading the Node.js version, it is important to decide which version to upgrade to. Broadly speaking, migrate only to even-numbered Node.js releases as only even-numbered versions will be provided with Long-Term Support.

Read more about Node.js release lines here.

The npm version will be upgraded automatically accordingly to the Node.js version since it is downloaded alongside Node.js. Hence, do check that this upgrade does not cause any issues.

Setup

Install to help switch between different node versions. Switch to use the Node.js version that you are migrating to.

Migration steps

1. Refactor any deprecated syntax
   • Go to the Node.js changelog of the new version
   • Go through the list of deprecated syntax and check if it is being used in MarkBind
   • Replace any deprecated syntax
2. Check that all user-facing functionalities are working
   • A quick way to do this is to go to the Reader Facing Features in the User Guide.
3. Check that there are no issues with development setup
   • Set up the development environment by running through the steps in Setting Up to ensure there are no problems
4. Update GitHubActions
   • Go to MarkBind/markbind-action and update the Node.js version numbers
     • See Update node version from 14 to 16 PR for an example
   • Test there are no issues with workflows

     • Testing instructions located here: markbind-action and markbind-reusable-workflows

       If a different npm version is needed

       Install correct version of npm in action.yml and fork-build.yml. Refer to Update node version from 14 to 16 PR to see where npm install should be run.

5. Check deployment to Netlify/other platforms
   • Deployment to Netlify

     • Follow steps in Deploying to Netlify but change the NODE_VERSION value accordingly. Check there are no issues with deployment and deployed site is as expected.

     • MarkBind has two repos init-minimal-netlify and init-typical-netlify which allows deployment to Netlify by using a config file. Update the config file netlify.toml with the correct Node.js version and check that deployment using button in README works as expected.

       If a different npm version is needed

       To specify the npm version add an environment variable NPM_VERSION with the correct version number.

   • Deployment to Github pages
     • Using the markbind deploy command
       • Build site using correct Node.js version
       • Follow steps in Using the markbind deploy command and check there are no issues with deployment or with the site.
     • Using CI platforms
       • Follow steps in Using CI Platforms but update the config files for the various CI Platforms to use the correct Node.js version. Try deploying and ensure there are no problems with deployment.
         If a different npm version is needed

         Install the correct npm version before running npm commands.
6. Update documentation
   • Update Node.js and npm version in documentation. See Update to use Node 16 as an example.
     Don't forget to update the version numbers in the example config files in Deploying the Site!
7. Update neftlify.toml
   • The neftlify.toml file in the markbind repo's root directory is used to deploy our documentation site to Netlify. Update the NODE_VERSION value to the new Node.js version.