search

lookit / lookit-jspsych

0 stars 0 forks source link

Package/plugin/extension organization and naming #38

Closed becky-gilbert closed 1 month ago

becky-gilbert commented 3 months ago

TL;DR

We need to agree on some conventions for organizing the packages in our monorepo and for the researcher-facing plugin/extension names.

Summary

Currently, we have some different plugins/extensions nested inside of the record and survey packages:

These are available to researchers as:

We should decide if we want to stick with that pattern for all of the plugins/extensions we've created so far, and how to organize our future custom plugins/extensions (video config, video consent, etc.). We also need to adopt consistent naming conventions (e.g. should we include "Plugin" and/or "Extension" in the researcher-facing names?).

Here are some things to consider:

jsPsych conventions

jsPsych's convention is to create a separate package for every plugin/extension, and to include the word plugin/extension at the start of the package name. The package naming convention is extension/plugin-package-name, e.g.:

And the naming convention for exported classes is jsPsychPackageName for plugins and jsPsychExtensionPackageName for extensions. These are the names that researchers actually use in their code. E.g.

IDing plugins/extensions as part of CHS

In the same way that 'official' jsPsych plugins/extensions are prefixed with "jsPsych", we may want to add "chs" (or a similar identifier) to the start of our researcher-facing plugin/extension names, to make it clear to researchers when a plugin/extension is part of the custom CHS code/documentation vs part of the jsPsych library (or from some other source). This is what we have already done with chsRecord and chsSurvey. So future plugins/extensions might have the same prefix, e.g.

Adding 'chs' to these names might make it seem like we're trying to take credit for other developers' work, especially when our custom versions are simple wrappers for jsPsych code. So for each of our "chs" plugins/extensions, we should be clear in the docs/READMEs about what our customization is doing and make sure to credit other packages/authors.

Also, there's no need to use the "chs" prefix for the package names inside the repo, since they're already identified as being custom CHS packages because they're inside our lookit-jspsych repo. This is the same way that jsPsych does it ('jsPsych' is included in the researcher-facing name, but not the internal package name).

Releases and versioning

When plugins/extensions are nested within the same package, they will be released on npm together and therefore updated together. This means that, if just one plugin/extension needs to be updated, everything inside the same package will also get a version update. E.g. with our current nested structure, a patch update chsRecord.StartRecordPlugin plugin would result in a version bump for the whole record package. If we want to be able to keep the versioning separate for each plugin/extension, then we'd have to put everything into its own package.

Logical grouping

We currently have plugins/extensions grouped logically into the same package: recording-related plugins/extensions are together, and survey-related plugins/extensions are together. There are some advantages to this, such as being slightly easier to share/re-use code. But there are ways around this too if we want to separate out everything into its own package, such as loading some of the shared modules (e.g. recording) as external dependencies, so that this code is always loaded from a separate package post-build and not repeated inside packages.

If we stick with the logical grouping structure, we should make sure to clearly define what goes in/out of each package. For instance, should the record package include ALL plugins/extensions that use the webcam/mic (or even give researchers the option), or should this package include just the critical recording "helpers" that don't fall into the category of a typical plugin/trial (e.g. video consent, video config).

Package numbers and loading speed

Each package needs to be loaded into the study page separately via a CDN. More packages = more HTTP requests when starting an experiment. This may not be a big deal for users with fast internet connections, but can definitely impact the page loading time for certain users (e.g. on mobile devices and data connections, rural areas).

Nested naming structure

When our plugins/extensions are nested in the same package, their researcher-facing names will also have a nested structure (period in the name to separate package name and plugin/extension name), e.g.: chsRecord.StartRecording, chsRecord.StopRecording. Does this matter?

Possible solutions

For the package structure (ignore the actual names)

  1. Keep our nested structure for record and survey, but switch to separate packages for other custom plugins/extensions.
    • record
    • start
    • stop
    • trial
    • survey
    • consent
    • exit
    • video-config
    • video-consent
    • etc.
  2. Use a nested structure for custom plugins.
    • record
    • survey
    • plugin
    • video-consent
    • video-config
    • etc.
  3. Switch to a flat structure: every plugin/extension gets its own package.
    • consent-survey
    • exit-survey
    • start-record
    • stop-record
    • trial-record
    • video-consent
    • video-config
    • etc.

For naming conventions

  1. If we're using a flat package structure, we could use jsPsych-style names, but with "chs" instead of "jsPsych". Here are some suggestions, where the first name is the package name in the repo, and the second is the researcher-facing name:
    • plugin-consent-survey / chsConsentSurvey
    • plugin-exit-survey / chsExitSurvey
    • plugin-start-record / chsStartRecord
    • plugin-stop-record / chsStopRecord
    • extension-trial-record / chsTrialRecordExtension
    • plugin-video-consent / chsVideoConsent
    • plugin-video-config / chsVideoConfig
  2. If we're sticking with logical grouping of plugins/extensions inside packages, we could use the "chs" prefix just for the main package name. In this case, it probably wouldn't make sense to use the "plugin" and "extension" prefixes to the top-level package directories, since they can contain both. But we could add these prefixes to the file names inside the packages. Again, first name is the package name in the repo, and the second is the researcher-facing name:
    • survey / chsSurvey
    • plugin-consent / Consent
    • plugin-exit / Exit
    • record / chsRecord
    • plugin-start / StartRecord
    • plugin-stop / StopRecord
    • extension-trial / TrialRecordExtension
ianchandlercampbell commented 3 months ago

@becky-gilbert This looks great! I think for interoperatibility, I would prefer to use the jsPsych naming conventions moving forward (starting with plugin or extension). It seems like you're leaning that direction already, but want to affirm from the novice side that makes sense to me.

My thought is that for design/naming decisions we'll want existing jsPsych users to be able to navigate using the CHS plugins/extensions using their existing expectations. This works the other way too-- anyone who starts using jsPsych on CHS will also learn a bit about how to navigate other uses of jsPsych.

My initial thought is the nested structure would work better for explaining to others what packages they need to use for specific functions. In the EFP, I think we have a flat structure currently, correct? I think that has resulted in some issues like some researchers not understanding they needed to stop the recording with a separate frame.. A nested structure makes it more clear that they'll need to use multiple plugins to achieve certain purposes!

Feel free to ignore/correct me on anything I misunderstood! Trying to approach this from a UX perspective for researchers.

becky-gilbert commented 3 months ago

Thanks @ianchandlercampbell - this is all very useful feedback!

becky-gilbert commented 1 month ago

Closing this issue as we've decided to nest all CHS plugins that use recording inside the record package.

We've settled on the following organization and naming conventions: