Merge pull request #200 from revisit-studies/2.4.0

v2.4.0

Author: JackWilb

blog/2026-02-23-release-2.4.md

@@ -0,0 +1,99 @@
+--- 
+layout: post
+title: "reVISit 2.4: All About Speed and Stability!"
+authors:
+  - team
+--- 
+
+Version 2.4 of reVISit is out – and for once it doesn’t pack a lot of new features. Rather, it’s all about **quality of life**: we fixed bugs, improved stability, and, most importantly, made the documentation much much better! 
+
+We also added a few new things here and there, but they’re just quality of life improvements for supporting studies currently under development by the community.
+
+### Should I Update Now?
+
+We recommend that all reVISit users update to version 2.4, since it should provide a better experience to both developers and participants. However, if you have a study implemented in 2.3 that you’ve tested and piloted already and want to run tomorrow, you should probably stick with 2.3. After updating, make sure to run pilots with 2.4 to see whether everything works as expected. 
+
+So, let's dive into the details of what’s new in 2.4!
+
+### Assigning Conditions via URL Parameters
+
+Even with Latin squares, it can be [tricky to get the balance of participants between conditions](https://revisit.dev/docs/faq/#q-how-can-i-ensure-balanced-numbers-of-participants-between-conditions-in-my-study-design) in a between-subjects design right. To address this, we introduced conditions that can be passed into a study as a URL parameter. Check out the [demo](https://revisit.dev/study/demo-condition/) and the [documentation](https://revisit.dev/docs/designing-studies/sequences/url-conditions/). 
+
+For example, in a study with three conditions, this URL: [https://revisit.dev/study/demo-condition?condition=shape](https://revisit.dev/study/demo-condition?condition=shape) will drop a participant in the `shape` condition. You can see this in the study browser.
+
+![The Study Browser and the Study Card showing the new conditional feature. In the browser, it’s evident that only one condition is active. In the card, you can choose the condition of the study](/img/blog_posts/2026-02-23-release-2.4/url-conditional.png)
+
+As always, the recorded data will contain the condition information allowing you to easily differentiate between cases in analysis. You can also see all of the defined conditions and jump right into them from the study card, as shown above. 
+
+You can define conditionals like this: 
+
+```json
+{
+ "sequence": {
+   "order": "fixed",
+   "components": [
+     "introduction",
+     {
+       "id": "color",
+       "conditional": true,
+       "components": ["color-trial-1", "color-trial-2"],
+       "order": "random"
+     },
+     {
+       "id": "shape",
+       "conditional": true,
+       "components": ["shape-trial-1", "shape-trial-2"],
+       "order": "fixed"
+     }
+   ]
+ }
+}
+```
+
+The key additions to get this functionality are the `conditional` flag and the `id` key. Make sure to make your ids unique! 
+
+With this feature, you’ll be able to use dedicated links to recruit participants for each condition (for example, using two different Prolific studies), and keep recruiting until you have reached the desired number of participants for each. 
+
+You can also assign multiple conditions at the same time, like this: [https://revisit.dev/demo-condition?condition=color,size](https://revisit.dev/demo-condition?condition=color,size)
+
+
+### Include the Same Component Multiple Times
+
+Sometimes you want to include the same component multiple times in your study. For example, you might want to measure task load after each task. This wasn’t possible in reVISit yet (you could hack it by using inheritance). Now, however, that’s easy to do: just include the same component multiple times. For example, if you include a component `nasa-tlx` after each task, you’ll have access to `nasa-tlx-1`, `nasa-tlx-2`, etc, in the data. 
+
+
+### Changes to How Library Components are Included
+
+We previously supported referring to components of libraries as `$libraryName.co.componentName` as well as `$libraryName.component.componentName`, and similarly used `.se` or `.sequence` for sequence. The shorthand is now deprecated; new studies should only use `.component` and `.sequence`.
+
+
+### Performance
+
+We have **virtualized our study browser** so that it does not render information for every possible study component at once. For studies which had large amounts of components (think 1000+) this was causing slowdowns during development.
+
+We have also fixed a number of small bugs that impacted performance, especially for studies which contained large amounts of provenance data. Such studies should see a significant participant facing performance improvement in 2.4. 
+
+### Testing
+
+A key focus of this update has been to improve the robustness of our infrastructure. Previously we had focused on using integration level tests using the playwright test framework. With this update we added more than 300 unit tests, which improves the quality of our tests, makes the run faster, and more specifically. 
+
+
+### Better Errors and Warnings
+
+Good error messages are essential for the development experience, so we’ve improved how errors and warnings for specification problems look: 
+
+![A comparison of before and after for error messages. The before shows a bullet list with no formatting, the after has nice formatting, highlighting and separation.][/img/blog_posts/2026-02-23-release-2.4/errors.png]
+
+### Bug fixes and Updating
+With this release, we closed over 80 issues on github. For details on the bugs that were fixed, take a look at the [release logs](https://github.com/revisit-studies/study/releases/tag/v2.4.0)
+
+
+
+
+
+
+
+
+
+
+

docs/analysis/config.md

@@ -0,0 +1,67 @@
+# Config
+
+The Config tab shows all the different versions of your study configuration that participants have used.
+
+## Overview
+
+Each time you change your `config.json` file and deploy it, reVISit creates a unique hash for that version. 
+
+![Config tab](./img/config/config.png)
+
+The Config table has several columns. The version column shows the identifier from your `studyMetadata.version` field (like `1.0.0` or `pilot`). The hash column shows a unique code based on your actual config content. If anything changes in your config, you get a new hash, even if you forget to update the version number. Hover over the info icon to see the full hash, or click the copy icon to copy it.
+
+The date column shows when you created that version (from `studyMetadata.date`). The time frame column shows when participants actually used it, from the first to the last participant. The participants column tells you how many people used each version.
+
+Update your `studyMetadata` in `config.json` every time you make changes:
+
+```json
+{
+  "studyMetadata": {
+    ...
+    "version": "pilot",
+    "date": "2026-02-17",
+  }
+}
+```
+
+## View Config
+
+Click the view icon in the Actions column to see the full JSON for any config version. This opens a modal showing the complete configuration file, which is helpful when you need to check exactly what settings were used for a particular version.
+
+![View Config](./img/config/view-config.png)
+
+## Download Config
+
+Download individual configs by clicking the Download button in the Actions column. The file will be named `{studyId}_{hash}_config.json`, like `study_abc123_config.json`.
+
+![Download Config](./img/config/download-config.png)
+
+For multiple configs, check the boxes next to the ones you want and click Download Configs at the top. This creates a zip file named `{studyId}_config.zip` with all the selected configs inside.
+Download configs to back up your study versions, share with collaborators, archive for publication, or compare changes outside reVISit.
+
+## Compare Config
+
+Select exactly two configs using the checkboxes, then click Compare Configs. You'll see a side-by-side view with red highlighting for removed content, green for added content, and no highlighting for unchanged content.
+
+![Compare Config](./img/config/compare-config.png)
+
+:::note
+Compare Config cannot track white space changes.
+:::
+
+## Filter Config
+
+The Config tab syncs with filters in other tabs. Config names are displayed as `{version}-{first 6 digits of hash}`, like `pilot-abc123`.
+
+![Filter Config](./img/config/filter-config.png)
+
+Select "ALL" to see everyone, or choose specific versions to analyze just those participants. This is useful when you want to analyze only your final version, compare responses across versions, exclude pilot data, or analyze different study runs separately.
+
+<!-- Importing links -->
+import StructuredLinks from '@site/src/components/StructuredLinks/StructuredLinks.tsx';
+
+<StructuredLinks
+    demoLinks={[
+        {name: "Survey Demo", url: "https://revisit.dev/study/analysis/stats/demo-survey/config"}
+    ]}
+/>

docs/analysis/data-export.md

@@ -29,6 +29,12 @@ Tidy data format is a structured approach to organizing tabular data where each
 You may check more details [here](https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html).
 :::
 
+:::note
+If your study includes [audio recording](../../designing-studies/think-aloud), you can optionally include a transcript column in your tidy CSV export. This column contains the transcribed text from each trial, making it easy to analyze what participants said alongside their responses. You must be using Firebase as your storage engine.
+
+Downloading transcripts for large datasets can take significant time. If you're downloading data for **50 or more participants** with transcripts, you'll see a warning about potential delays. The system fetches transcripts with concurrency limits to avoid overwhelming the browser.
+:::
+
 ## Example Workflow in R
 
 ### 1. Install Necessary Packages