update readme to point to jspsych-dev

cherriechang · cherriechang · commit 2e37c753964e · 2025-03-06T14:52:56.000-05:00
diff --git a/README.md b/README.md
@@ -1,12 +1,15 @@
-# jspsych-timelines
+# jspsych-timelines: jsPsych community experiment timelines
 
-This is an open repository of timelines for jsPsych. The goal of this repository is to provide a place for researchers to share their jsPsych timelines with the community. Packages in this repository all implement a [uniform structure](#structure) that makes it easy to use them in your own experiments and combine them with other code. jsPsych also offers a [tool](https://github.com/jspsych/jspsych-dev/tree/main/packages/new-timeline) for building timelines in compliance with this structure and [guidelines](#guidelines-for-contributing-new-timelines) for contributing to this repository.
+This is an open repository of [jsPsych experiment timelines](https://www.jspsych.org/v8/overview/timeline/). The goal of this repository is to provide a place for researchers to share their timelines with the community. Packages in this repository all implement a [uniform structure](#structure) that makes it easy to use them in your own experiments and combine them with other code.
+
+If instead of an experiment timeline, you wish to share a [plugin](https://www.jspsych.org/v8/overview/plugins/) or [extension](https://www.jspsych.org/v8/overview/extensions/), you should check out the [jspsych-contrib](https://github.com/jspsych/jspsych-contrib) repository! 
 
 ## List of available timelines
 
-Here is an overview of the jsPsych timelines that have been contributed here by community members. You can find all of them in the `./packages` directory.
+The jsPsych timelines that have been contributed by community members can be found in the `/packages` directory. Here is a list overview of them:
 
 ### Timelines
+
 Timeline | Contributor | Description
 ----------- | ----------- | -----------
 [arrow-flanker](https://github.com/jspsych/jspsych-timelines/blob/main/packages/arrow-flanker/README.md) | [Josh de Leeuw](https://github.com/jodeleeuw) | Arrow flanker task for jsPsych 
@@ -25,7 +28,7 @@ This will load the timeline into the global namespace as `jsPsychTimelineArrowFl
 
 ```js
 const jsPsych = initJsPsych();
-const timeline = jsPsychTimelineArrowFlanker.createTimeline(jsPsych, {options});
+const timeline = jsPsychTimelineArrowFlanker.createTimeline(jsPsych, { options });
 jsPsych.run([timeline]);
 ```
 
@@ -36,28 +39,44 @@ In the above example, `timeline` is a jsPsych timeline object that can be added
 Each timeline module exports a `createTimeline()` method. This method returns an object with a `timeline` property that can be inserted into a jsPsych timeline.
 
 ```js
-const timeline = jsPsychTimelineModule.createTimeline(jsPsych, {options})
+const timeline = jsPsychTimelineModule.createTimeline(jsPsych, { options })
 jsPsych.run([timeline])
 ```
 
-Timeline modules may also export a `timelineUnits` objects and a `utils` object.
+Timeline modules may also export a `timelineUnits` objects and a `utils` object. 
 
 The `timelineUnits` object contains functions that create smaller units of a timeline than the main `createTimeline()` method. For example, if the main timeline contains two phases (e.g., memorization and test) then there could be `timelineUnits.createTestTimeline()` and `timelineUnits.createMemorizationTimeline()`. These functions could then be used for assembling the overall timeline in a different way than `createTimeline()` allows. There are no constraints on what kinds of timeline creation methods can be exported in `timelineUnits`, other than the requirement that all methods return an object that can be added to a jsPsych timeline. Some modules may export methods to create units as small as a single trial, while others export no methods at all.
 
 The `utils` object contains miscellaneous functions that may be useful when using the module. For example, if a timeline requires creating a complex stimulus that can be procedurally generated there could be a `utils.createStimulus()` method that returns HTML. Or if there is a timeline that involves a particular scoring system like a questionnaire with validated indicies then there could be a `utils.generateScore()` method. There are no constraints on what methods can be exported as part of the `utils` object.
 
 ## Guidelines for contributing new timelines
+Contributions to this repository must:
+
+* Work as described
+* Include the complete code for the timeline.
+* Include a `readme.md` file following our [template](readme-template.md).
+* Include a `package.json` file.
+
+Optionally, contributions can include:
+
+* A `/docs` directory with documentation matching the template for docs on jspsych.org 
+* An `/examples` directory with a working `.html` demo.
+* A test suite following the testing framework in our `-ts` templates.
+
+To submit a timeline, [open a pull request](https://github.com/jspsych/jspsych-contrib/pulls) that contains a directory for your timeline inside the `/packages` directory.
+In the pull request comments, please make it clear how we can verify that the timeline is functional. 
+This could be accomplished with a link to a demonstration experiment, the inclusion of an example file and/or testing files, or through some other means.
+We try to review pull requests quickly and add new timelines as soon as the minimal standards are met.
+
+## Creating a new timeline
 
-If you would like to contribute a new timeline to this repository, please follow these steps:
+We have a tool called [`new-timeline`](https://github.com/jspsych/jspsych-dev/tree/main/packages/new-timeline) for building new timelines at [jspsych-dev](https://github.com/jspsych/jspsych-dev/tree/main). Instructions for using the new-timeline tool can be found at the [`README.md`](https://github.com/jspsych/jspsych-dev/tree/main/packages/new-timeline/README.md) in this directory.
 
-1. Clone this repository on your machine and run `npm i` to install its packages.
-2. Run `npx @jspsych/new-timeline` and answer the prompts to create a new timeline template under `./packages`. This is a command-line tool we built to make setting up the development of a new timeline easier. Documentation for using this tool can be found [here](https://github.com/jspsych/jspsych-dev/tree/main/packages/new-timeline#readme).
-3. After you are done editing the timeline template, verify that it works by opening `examples/index.html` in your browser.
-4. Add a changeset by running `npm run changeset` in the main directory of the repository. This will prompt you for a description of the changes you made and creates a new changeset file in the `changesets` directory accordingly.
-5. Open a pull request to merge your branch into the `main` branch of this repository.
+You may also want to read the jsPsych documentation on [plugin development](https://www.jspsych.org/latest/developers/plugin-development/) to understand how to work with the `index.ts` file (for TypeScript development) and `index.js` file (for JavaScript development).
 
-We welcome timelines of all kinds!
+## jsPsych version compatibility
+To ensure your timeline can be run by others using the latest version of jsPsych, we encourage you to make your timeline compatible with jsPsych v7+. Documentation for how to migrate from v6.x to v7.x can be found [here](https://www.jspsych.org/v7/support/migration-v7/), and from v.7x to v8.x [here](https://www.jspsych.org/v8/support/migration-v8/).
 
-### What if my timeline requires a custom plugin?
+## What if my timeline requires a custom plugin?
 
-If your timeline requires a custom plugin, we'd recommend adding the plugin to [jspsych-contrib](https://github.com/jspsych/jspsych-contrib) before submitting the timeline here. This will make it easier for other researchers to use your plugin in their own experiments. Currently, this repository is aimed at timelines that use plugins that are published on `npm`.
+If your timeline requires a custom plugin, we'd recommend adding the plugin to [jspsych-contrib](https://github.com/jspsych/jspsych-contrib) before submitting the timeline here. This will make it easier for other researchers to use your plugin in their own experiments. Currently, this repository is aimed at timelines that use plugins that are published on `npm`. Make sure the plugin and your timeline are both compatible with jsPsych v7+ so that they can work with each other and with the latest jsPsych version.
