add a v7 migration guide

docs/support/migration-v7.md

@@ -0,0 +1,115 @@
+# Migrating an experiment to v7.x
+
+The release of version 7.0 changes a number of core components of jsPsych. 
+We made these changes to improve jsPsych's compatibility with modern JavaScript tools like package managers and bundlers and to improve the developer experience for people contributing to jsPsych's codebase. 
+We hope these changes will improve the long-term viability of the project and encourage more developers to contribute to jsPsych.
+
+Our aim was to accomplish these goals with minimal changes to the user experience of jsPsych. 
+However, we did have to change a few critical things. 
+This guide is aimed at users who are familiar with v6.x of jsPsych and would like to understand what's changed in v7.x.
+
+## Loading jsPsych
+
+There are now three different ways you can load jsPsych into your HTML file. 
+We've updated the [hello world tutorial](/tutorials/hello-world.md) to walk through each of the three options. 
+If you are looking for the option that is most similar to the version 6.x experience, check out [option 2](/tutorials/hello-world/#option-2-download-and-host-jspsych). 
+The biggest difference from what you are used to is that the directory structure of the downloaded library is slightly different and plugin files are named a little bit differently.
+
+## Initializing and running jsPsych
+
+We've removed `jsPsych.init()` and split the features into two different functions. 
+
+At the start of your experiment script, you'll now call `initJsPsych()` to get a new instance of jsPsych. 
+This is where you will pass in the variety of parameters that used to go into `jsPsych.init()`, with the exception of the `timeline` parameter.
+
+```js
+var jsPsych = initJsPsych({
+  use_webaudio: false,
+  on_finish: function(){
+    jsPsych.data.displayData();
+  }
+});
+```
+
+Once you've created your timeline, then you'll launch the experiment by calling `jsPsych.run()`, passing in the timeline as the only argument.
+
+```js
+var timeline = [...]
+
+jsPsych.run(timeline);
+```
+
+## The `type` parameter for trials
+
+The `type` parameter now expects the value to be a plugin class rather than a string. 
+
+For example, if you load the `html-keyboard-response` plugin from the CDN...
+
+```html
+<script src="http://unpkg.com/@jspsych/plugin-html-keyboard-response@1.0.0"></script>
+```
+
+... or from the `plugin-html-keyboard-response.js` file in the release archive...
+
+```html
+<script src="plugin-html-keyboard-response.js"></script>
+```
+
+... then a global variable defining the plugin's class called `jsPsychHtmlKeyboardResponse` is available.
+
+To create a trial using the plugin, pass this class as the `type` parameter. 
+Note that the value is *not a string*.
+
+```js
+var trial = {
+  type: jsPsychHtmlKeyboardResponse,
+  stimulus: 'Hello, version 7.0!'
+}
+```
+
+## Using extensions
+
+Like plugins, extensions are now also referenced by their class. Extensions are initiliazed in `initJsPsych()` instead of `jsPsych.init()`.
+
+```js
+var jsPsych = initJsPsych({
+  extensions: [
+    {type: jsPsychExtensionWebgazer}
+  ]
+})
+```
+
+The class is also used in trials that use the extension.
+
+```js
+var trial = {
+  type: jsPsychHtmlKeyboardResponse,
+  stimulus: 'Hello, version 7.0!',
+  extensions: [
+    {type: jsPsychExtensionWebgazer}
+  ]
+}
+```
+
+## Custom plugins
+
+If you have custom plugins that you would like to upgrade to be compatible with v7.x we recommend using our [plugin template](https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-template/index.js).
+
+The new template implements plugins as a class, but the core components are essentially unchanged. 
+
+* Anything in `plugin.info` from a v6.x plugin should be moved into the `info` object. Note that the `type` argument for the parameters follows a slightly different syntax in the v7.x plugins. This object is then [assigned as a static property of the class](https://github.com/jspsych/jspsych-contrib/blob/6a27c3fc72fdb1feb1a4041cd670775a7c4bf51d/packages/plugin-template/index.js#L39).
+* Anything in `plugin.trial` from a v6.x plugin should be moved into the `trial` method inside the class. 
+* The new template has a `constructor()` function that accepts an instance of jsPsych. You do not need to adjust this portion of the plugin.
+
+There are a few changes to be aware of that may affect your code.
+
+* We removed the `registerPreload` function and we now auto-detect media to preload via the `type` argument specified in the `info` object. If a parameter is listed as `IMAGE`, `AUDIO`, or `VIDEO`, it will be automatically preloaded. If you wish to disable preloading you can set the `preload` flag to `false` for the parameter.
+* If you invoke any functions from jsPsych, like `jsPsych.finishTrial()`, note that `jsPsych` is no longer a global variable and you must use the reference to jsPsych that is passed to the constructor. To do this, simple prefix all `jsPsych` references with `this.`, e.g., `jsPsych.finishTrial()` becomes `this.jsPsych.finishTrial()`.
+
+## Need help?
+
+If you encounter issues migrating code to v7.x, feel free to post in our [support thread for migration](https://github.com/jspsych/jsPsych/discussions/2179).
+
+
+
+

mkdocs.yml

@@ -127,6 +127,7 @@ nav:
   - 'Extension Development': 'developers/extension-development.md'
 - Support:
   - 'Getting Help': 'support/support.md'
+  - 'Migrating from 6.x to 7.x': 'support/migration-v7.md'
 - About:
   - 'About jsPsych': 'about/about.md'
   - 'License': 'about/license.md'