diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 8921b089..2c260098 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,23 +1,25 @@ -name: Test Build +name: 🧪 Test Build +on: pull_request -on: - pull_request: +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 + - name: ⬇️ Checkout repo + uses: actions/checkout@v4 + + - name: ⎔ Setup node + uses: actions/setup-node@v4 with: - node-version: '16' - - name: Test Build - run: | - if [ -e yarn.lock ]; then - yarn install --frozen-lockfile - elif [ -e package-lock.json ]; then - npm ci - else - npm i - fi - npm run build + node-version-file: .nvmrc + cache: npm + + - name: 📥 Install Dependencies + run: npm ci + + - name: 🔨 Test Build + run: npm run build diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b726130f..aca3fb22 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,39 +1,34 @@ name: Release to GitHub Pages on: push: - branches: [main] + branches: main + +permissions: + contents: write jobs: gh-release: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - - name: Add key to allow access to repository - env: - SSH_AUTH_SOCK: /tmp/ssh_agent.sock - run: | - mkdir -p ~/.ssh - ssh-keyscan github.com >> ~/.ssh/known_hosts - echo "${{ secrets.GH_PAGES_DEPLOY }}" > ~/.ssh/id_rsa - chmod 600 ~/.ssh/id_rsa - cat <> ~/.ssh/config - Host github.com - HostName github.com - IdentityFile ~/.ssh/id_rsa - EOT - - name: Release to GitHub Pages - env: - USE_SSH: true - GIT_USER: git - run: | - git config --global user.email "actions@gihub.com" - git config --global user.name "gh-actions" - if [ -e yarn.lock ]; then - yarn install --frozen-lockfile - elif [ -e package-lock.json ]; then - npm ci - else - npm i - fi - npx docusaurus deploy + - name: ⬇️ Checkout repo + uses: actions/checkout@v4 + + - name: ⎔ Setup node + uses: actions/setup-node@v4 + with: + node-version-file: .nvmrc + cache: npm + + - name: 📥 Install Dependencies + run: npm ci + + - name: 🔨 Build the website + run: npm run build + + - name: 🚀 Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./build + user_name: ccv-cj + user_email: ccv-bot@brown.edu diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 00000000..2efc7e11 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +v20.11.1 \ No newline at end of file diff --git a/README.md b/README.md index 441f792e..54088411 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,13 @@ This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern ## Installation ```console -yarn install +npm run install ``` ## Local Development ```console -yarn start +npm run start ``` This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server. @@ -19,7 +19,7 @@ This command starts a local development server and open up a browser window. Mos ## Build ```console -yarn build +npm run build ``` This command generates static content into the `build` directory and can be served using any static contents hosting service. @@ -35,7 +35,7 @@ To edit files for the current version, update the files under the `docs` directo 1. To add a new version, make sure that the new version content is finalized in the `docs` directory, then run: ```console - yarn run docusaurus docs:version + npm run docusaurus docs:version ``` 2. Update `versions.json` to include the new version (make sure "current" is first in the array) diff --git a/docs/deployments/firebase.mdx b/docs/deployments/firebase.mdx index d52145b9..81ff33a6 100644 --- a/docs/deployments/firebase.mdx +++ b/docs/deployments/firebase.mdx @@ -23,7 +23,7 @@ Please have your PI contact [support@ccv.brown.edu](mailto:support@ccv.brown.edu First we'll configure [Firebase Hosting](https://firebase.google.com/docs/hosting) and [Cloud Firestore](https://firebase.google.com/docs/firestore) on your project. -1. Log in to Firebase with your Google account on the [Firebase console](https://console.firebase.google.com/). +1. Log in to Firebase with your Google account on the [Firebase console](https://console.firebase.google.com/) 2. Navigate to your project from the console 3. Register a new web app to your project ([Register your app](https://firebase.google.com/docs/web/setup#register-app)) @@ -34,7 +34,7 @@ First we'll configure [Firebase Hosting](https://firebase.google.com/docs/hostin 4. Add Firestore Database to your project ([Create a Cloud Firestore database](https://firebase.google.com/docs/firestore/quickstart#create)) :::note - Chose `production mode` for the starting mode and the default "Cloud Firestore Location" + Choose `production mode` for the starting mode and the default "Cloud Firestore Location" ::: The Firebase project is now fully set up! Now we'll connect your task to that project from your computer. @@ -43,15 +43,11 @@ The Firebase project is now fully set up! Now we'll connect your task to that pr The Firebase CLI is installed with the node package manager just like the rest of Honeycomb's dependencies. Be sure to log in with same account you used when logging into the console! -```shell title="Install the Firebase CLI" -npm install -g firebase-tools -``` - ```shell title="Login to Firebase" firebase login ``` -_A "command not found" error usually indicates `firebase-tools` has not been installed correctly_ +_A `command not found` error usually indicates firebase-tools has not been installed correctly. Re-running `npm install -g firebase-tools` should fix this issue._ ### Connecting Your Firebase Project @@ -67,7 +63,7 @@ _A "command not found" error usually indicates `firebase-tools` has not been ins 2. Copy the web app credentials from the Firebase console to the corresponding variables in `.env.firebase` - 1. Return to your project on the [Firebase console](https://console.firebase.google.com/). + 1. Return to your project on the [Firebase console](https://console.firebase.google.com/) 2. Navigate to your project setting - Create a study - -
- -The study should like this when you're finished: - -Example study -
-
- -**Additional studies must be created inside the `registered_studies` collection** - ## Developing With Firebase _Two terminal windows must be used while developing for Firebase. See [here](https://code.visualstudio.com/docs/terminal/basics#_groups-split-panes) for instructions on splitting terminals in VSCode._ @@ -149,7 +112,7 @@ npm run dev:firebase npm run firebase:emulators:start ``` -Honeycomb is now running in the browser and connected to data on an emulated instance of Firestore. It may be viewed at [http://localhost:4000/firestore](http://localhost:4000/firestore). +Honeycomb is now running in the browser and connected to data on an emulated instance of Firestore. It may be viewed on [localhost:4000](http://localhost:4000/firestore). :::info Honeycomb populates the Firestore emulators with the study `s1` and participant `p1`. @@ -157,7 +120,7 @@ Honeycomb populates the Firestore emulators with the study `s1` and participant ## Deploying on Firebase -Firebase deployments are handled automatically following [Continuous Integration Continuous Development (CI/CD)](ci_cd) practices using GitHub Actions. Here we will connect create custom actions that are connected to the task's Firebase project. +Firebase deployments are handled automatically following [Continuous Integration Continuous Development (CI/CD)](ci_cd) practices using GitHub Actions. Here we will create custom actions that are connected to the task's Firebase project. Execute the following command to begin initializing Firebase hosting via GitHub actions. Be sure to follow the instructions below as the prompts appear. @@ -165,8 +128,8 @@ Execute the following command to begin initializing Firebase hosting via GitHub firebase init hosting:github ``` -1. The window should log you in automatically. If not, follow the prompts to log in with the same account you used in the console. -2. `/` refers to the name of your repository in Github. Be sure it's typed correctly! +1. The window should log you in automatically; if not, follow the prompts to log in with the same account you used in the console +2. `/` refers to the name of your repository in Github - be sure it's typed correctly! 3. Enter `y` for the prompt "Set up the workflow to run a build script before every deploy?" 4. Enter `npm install && npm run build:firebase` for the prompt "What script should be run before every deploy?" 5. Enter `y` to overwrite the current workflow file @@ -189,7 +152,7 @@ Honeycomb ships with a CLI script for managing data in Firebase. A local service Service accounts are accounts that are not attached to a human user. They authorize access to a Firebase project without someone physically logging in online. We use a service account to give the download script access to the Firestore database automatically. -1. Return to the project settings your project on the [Firebase console](https://console.firebase.google.com/). +1. Return to the project settings your project on the [Firebase console](https://console.firebase.google.com/) Firebase project settings + Create a study + + +The study should look like this when you're finished: + +Example study + +**Additional studies are created as documents inside the `registered_studies` collection** diff --git a/docs/deployments/local_application.mdx b/docs/deployments/local_application.mdx index 0e6eebbe..01e9e417 100644 --- a/docs/deployments/local_application.mdx +++ b/docs/deployments/local_application.mdx @@ -5,9 +5,13 @@ title: Local Application description: Guide for deploying a task as a local application --- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import CodeBlock from "@theme/CodeBlock"; + A major feature of Honeycomb is the ability to bundle JsPsych tasks into applications that can be run on any computer in a lab or clinic. Installers for these applications can be created for Windows, Mac, and Linux. The applications can be run without an internet connection, and do not require any additional software to be installed on the computer. -Installers for these application can be created on demand and/or automatically when a new release is created. This is called "Continuous Deployment" - more information about Honeycomb's CI/CD workflow can be found here [here](ci_cd). +Installers for these applications can be created on demand and/or automatically when a new release is created. This is called "Continuous Deployment" - more information about Honeycomb's CI/CD workflow can be found here [here](ci_cd). ## Creating a Release @@ -19,15 +23,76 @@ The tag should be in the format `vX.X.X` where `X.X.X` is the version number of Your release **must** included a new tag for the CI/CD workflow to work. ::: -## Running the task +## Installing the task -1. Navigate to the repository's "Releases" tab and select the tag you just created. -2. Download the installer for your operating system. +1. Navigate to the repository's "Releases" tab and select the tag you created from [above](#creating-a-release) +2. Download the correct installer for your operating system 3. Double click the installer to run it. Follow the instructions to install the application. -4. The application will automatically start after the first instillation. -The executable does not require installation of any additional software! +## Running the Task + +The task can be run by double-clicking the application icon on the desktop. + +The local application will run the task in a full-screen window. This aims to prevent study participants from doing anything else on the computer while the task is running. However, the task can be exited if needed with the following shortcut: + + + + Control + W + + + ⌘ + Q + + + Control + W + + ## Working with Data -Data is automatically saved to a nested folder structure on the Desktop. Each session will be saved as its own `.json` file nested under the id of the study and participant. +Data is automatically saved throughout the task and moved to a nested folder structure on the Desktop when the task is completed. Note how the folders are organized by `studyID` and `participantID`. Each session is saved as its own `.json` file; it's name is the timestamp of `start_date` of the task. + +### Early Exits + +The run-through of an experiment in which the tasks exits prematurely will NOT be sent to the desktop. However, what data was collected is available in the user's "userData" folder which can be found in the following location: + + + + %APPDATA%\honeycomb\TempData + + + ~/Library/Application Support/honeycomb/TempData + + + ~/.config/honeycomb/TempData + + + +:::caution +The `.json` file will likely not be formatted correctly because of the early exit. Take extra care to fix the file before using it for data analysis. +::: diff --git a/docs/deployments/psiturk.mdx b/docs/deployments/psiturk.mdx index f078771c..fad6de24 100644 --- a/docs/deployments/psiturk.mdx +++ b/docs/deployments/psiturk.mdx @@ -5,11 +5,11 @@ title: PsiTurk description: Guide for the different deploying a task to PsiTurk --- -While honeycomb is optimized for use on a [local application](local_application), we added functionality for usage with [PsiTurk](https://psiturk.org/). The application will detect if it's being used in a Turk environment and will save the data to the default PsiTurk SQLite database. +While Honeycomb is optimized for use on a [local application](local_application), we added functionality for usage with [PsiTurk](https://psiturk.org/). The application will detect if it's being used in a Turk environment and will save the data to the default PsiTurk SQLite database. ### Prebuilt version -When GitHub Actions is run, a PsiTurk build will be created automatically, and can be downloaded from its artifacts. The workflows responsible for building the PsiTurk application are `.github/workflows/package.yml` and `.github/workflows/release.yml`. The first one has to be triggered manually, the latter is triggered when you tag a release. +When a GitHub Action is run, a PsiTurk build will be created automatically, and can be downloaded from its artifacts. The workflows responsible for building the PsiTurk application are `.github/workflows/package.yml` and `.github/workflows/release.yml`. The first one has to be triggered manually, the latter is triggered when you tag a release. If this is all you need, the build instructions below can be skipped! diff --git a/docs/external_tools/event_triggers.mdx b/docs/external_tools/event_triggers.mdx new file mode 100644 index 00000000..86dd4cfc --- /dev/null +++ b/docs/external_tools/event_triggers.mdx @@ -0,0 +1,34 @@ +--- +id: event_triggers +slug: /event_triggers +title: Event Triggers +description: Guide for setting up ports for equipment used in the clinic +--- + +## BrainVision Trigger Box setup + +Follow the TriggerBox setup instructions in the BrainVision Trigger Box manual. Plug the TriggerBox into the computer running the task. Check your operating system’s device list to identify the COM port that the TriggerBox is connected to. Create a new system environment variable: + +```shell +COMNAME +``` + +and set the COM port to the correct value (e.g., COM3). + +## Open Source Event Trigger setup + +Details on how to make the open source event trigger and photodiode can be found [here](https://github.com/neuromotion/USB-event-marker). + +Connect the open source event trigger to the computer running the task using a USB to micro-USB cable. Check your operating system’s USB device list to identify the product ID of the teensyduino event marker. + +Create a new system environment variable: `EVENT_MARKER_PRODUCT_ID` and set to the product ID of the event marker. + +## Send event code triggers + +Change the `eventCodes` values listed in the src/config/trigger.js file to the desired values. Import eventCodes from `./trigger` and export as `eventCodes`. + +Whenever you would like to send an event code in a trial, load `eventCodes` from `../config/main/`, and call `pdSpotEncode` with the proper code (e.g. `eventCode.Fixation`) as input. + +## Run the task with event triggers + +Honeycomb automatically checks whether your event marker is connected and running at the start of the task. If it is not connected, the task will present an error and will not be able to run. diff --git a/docs/external_tools/prolific.mdx b/docs/external_tools/prolific.mdx new file mode 100644 index 00000000..97a2ce7e --- /dev/null +++ b/docs/external_tools/prolific.mdx @@ -0,0 +1,22 @@ +--- +id: prolific +slug: /prolific +title: Prolific +description: Guide for integrating Honeycomb with Prolific +--- + +## Prolific Setup + +:::caution +Prolific integration is only available in Honeycomb for tasks deployed to Firebase. +::: + +Please follow the discussion post [Configure participant and study ID in prolific](https://github.com/brown-ccv/honeycomb/discussions/125) to configure a Prolific study that integrates with Honeycomb. + +- The "Prolific ID" should be set to `participantID` +- The "Study ID" should be set to `studyID` +- The "Session ID" should be set to `SESSION_ID` + +## Further Reading + +The [jsPsych Documentation](https://www.jspsych.org/7.3/overview/prolific/) also provides a guide for Prolific integration. Please note that this documentation will differ slightly from the Honeycomb integration. diff --git a/docs/further_reading/github_discussions.mdx b/docs/further_reading/github_discussions.mdx new file mode 100644 index 00000000..481c269c --- /dev/null +++ b/docs/further_reading/github_discussions.mdx @@ -0,0 +1,14 @@ +--- +id: github_discussions +slug: /github_discussions +title: Github Discussions +description: "Links to the Honeycomb repository discussions board and instructions for reporting bugs." +--- + +The [Honeycomb repository](https://github.com/brown-ccv/honeycomb) includes a [discussions](https://github.com/brown-ccv/honeycomb/discussions) board. It is a place to ask questions, share ideas, and engage with the community! Official announcements from the project are posted to the [Announcements](https://github.com/brown-ccv/honeycomb/discussions/categories/announcements) section. + +Please direct all [feature requests](https://github.com/brown-ccv/honeycomb/discussions/categories/feature-requests) and [questions](https://github.com/brown-ccv/honeycomb/discussions/categories/q-a) to the discussions board. + +## Reporting Bugs + +Bugs with Honeycomb should be reported directly to the [issues](https://github.com/brown-ccv/honeycomb/issues) tab of the repository. Please select "Bug report" and include as much information as possible. If you are able to provide a minimal example that reproduces the bug, that is even better! diff --git a/docs/further_reading/javascript_basics.mdx b/docs/further_reading/javascript_basics.mdx index b0177d89..3124ee7f 100644 --- a/docs/further_reading/javascript_basics.mdx +++ b/docs/further_reading/javascript_basics.mdx @@ -1,8 +1,8 @@ --- id: javascript -slug: /javascript # Hides folder structure from slug +slug: /javascript title: JavaScript -description: 'Links to begin learning JavaScript' +description: "Links to begin learning JavaScript" --- ## Learning JavaScript diff --git a/docs/further_reading/version_control.mdx b/docs/further_reading/version_control.mdx index 824380a5..42ded779 100644 --- a/docs/further_reading/version_control.mdx +++ b/docs/further_reading/version_control.mdx @@ -1,6 +1,6 @@ --- id: version_control -slug: /version_control # Hides folder structure from slug +slug: /version_control title: Version Control description: "Version control basics with Git and GitHub" --- @@ -9,7 +9,7 @@ description: "Version control basics with Git and GitHub" Git is a version control system that enables you to track changes to files. With Git, you are able to revert files back to previous versions, restore deleted files, remove added files and even track down where a particular line of code was introduced. -Nearly all operations that are performed by Git are in your local computing environment, for the exception of few used purely to synchronize with a remote. Some of the most common git operations are depicted below. +Nearly all operations that are performed by Git are in your local computing environment, with the exception of a few used to synchronize with the GitHub remote host. Some of the most common git operations are depicted below. ![Git basics](/assets/further_reading/git_basics.png) @@ -25,39 +25,13 @@ Pull requests are useful before you merge your branch with the main branch. You ![git pr info](/assets/further_reading/add_reviewers.png) -## Stay up-to-date with Honeycomb template repo - -Honeycomb is an active project, and will be updated with new features over time. To bring changes from the Honeycomb template repository to your task: - -1. Add Honeycomb as an additional remote as follows: - - ```shell - git remote add honeycomb https://github.com/brown-ccv/honeycomb.git - ``` - -2. Fetch the changes made to Honeycomb - - ```shell - git fetch --all - ``` - -3. Merge the current Honeycomb repo - - ```shell - git merge honeycomb/main --allow-unrelated histories - ``` - -:::caution -There will almost certainly be many "merge conflicts" when merging in changes form the template repository. It is tedious but extremely import to not accidentally overwrite your task when resolving these conflicts -::: - ## Best Practices ### Git Branches - `main` is the default branch and where releases are made from. This branch should be in clean/working conditions at all times. This branch is protected and can only be merged from Pull Requests for topic branches. -- `topic` branches are created for new features, fixes, or really any changes. E.g, `fix-task-trial2-stuck-button` +- `topic` branches are created for new features, fixes, or really any changes. E.g, `fix-task-trial2-stuck-button`. Note how the branch name describes the changes. This flow is sometimes referred to as [Feature Branch Workflow](https://docs.gitlab.com/ee/gitlab-basics/feature_branch_workflow.html) @@ -65,27 +39,26 @@ This flow is sometimes referred to as [Feature Branch Workflow](https://docs.git We recommend using a simple flow based on following rules: -- Use topic/feature branches, no direct commits on main. -- Perform tests and code reviews before merges into main, not afterwards. -- Every branch starts from main, and targets main. -- Commit messages reflect intent. +- Use topic/feature branches, no direct commits on main +- Perform tests and code reviews before merges into main, not afterwards +- Every branch starts from main, and targets main +- Commit messages reflect intent ### Comment styles We encourage using [Commitizen](http://commitizen.github.io/cz-cli/), a great tool for recording descriptions of commits in a standardized format which makes it easier for people to understand what changed in the code. -## Cheatsheet - -### Git Commands +## Git Commands -| Command | Brief | -| :---------------------------- | :----------------------------------------------------------------- | -| git add <files> | add a file to next commit \(stage\) | -| git commit -m <message> | commit staged files | -| git push | upload staged commit to repo | -| git pull | get remote repo commits and download \(try and resolve conflicts\) | -| git clone <url> | download entire repository | -| git checkout <branch> | checkout and create the branch you want to use | +| Command | Brief | +| :----------------------------- | :----------------------------------------------------------------- | +| git add <files> | add a file to next commit \(stage\) | +| git commit -m <message> | commit staged files | +| git push | upload staged commit to repo | +| git pull | get remote repo commits and download \(try and resolve conflicts\) | +| git clone <url> | download entire repository | +| git checkout -b <branch> | create and checkout a new branch | +| git checkout <branch> | checkout the branch you want to use | ```shell # create branch with your feature @@ -100,12 +73,33 @@ git commit -m "My feature is ready" git push origin feature_name ``` -### Alternative options +## GUI Based Source Control + +- [VS Code](https://code.visualstudio.com/) is the default IDE installed by Honeycomb. Check out [this overview](https://code.visualstudio.com/docs/sourcecontrol/overview) of source control in VS Code! +- [GitHub Desktop](https://desktop.github.com/) is a GUI application built specifically for working with Git. It is one of the programs installed as a prerequisite of Honeycomb. Check out [this overview](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop) of source control in GitHub Desktop! + +## Stay up-to-date with Honeycomb template repo + +Honeycomb is an active project, and will be updated with new features over time. To bring changes from the Honeycomb template repository to your task: + +1. Add Honeycomb as an additional remote as follows: + + ```shell + git remote add honeycomb https://github.com/brown-ccv/honeycomb.git + ``` + +2. Fetch the changes made to Honeycomb -#### VS Code + ```shell + git fetch --all + ``` -Most IDEs have some built in tools for working with Git and VS Code is no exception. Check out [this overview](https://code.visualstudio.com/docs/sourcecontrol/overview) of source control in VS Code! +3. Merge the current Honeycomb repo -#### GitHub Desktop + ```shell + git merge honeycomb/main --allow-unrelated histories + ``` -[GitHub Desktop](https://desktop.github.com/) is a GUI application for working with git. It is one of the programs installed as a prerequisite of Honeycomb. Check out [this overview](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop) of source control in GitHub Desktop! +:::caution +There will almost certainly be many "merge conflicts" when merging in changes from the template repository. It is tedious, but extremely import, to not accidentally overwrite your task when resolving these conflicts. +::: diff --git a/docs/introduction.mdx b/docs/introduction.mdx index 0d2da68e..3d300dac 100644 --- a/docs/introduction.mdx +++ b/docs/introduction.mdx @@ -5,7 +5,7 @@ title: Introduction description: Basic introduction to Honeycomb --- -Honeycomb is an open source task-template repository that combines well-accepted practices and technologies from the cognitive science and web development communities to build psychophysiological tasks that are ready for deployment to different settings (desktop, or online) and support electrophysiological recordings, without significant changes to the code base. +Honeycomb is an open source task-template repository that combines well-accepted practices and technologies from the cognitive science and web development communities to build psychophysiological tasks that support lab equipment recordings and are ready for deployment to different settings (desktop or online) without significant changes to the code base. ### Flexible deployment online and in the lab @@ -17,7 +17,7 @@ Deployment specifications are abstracted as parameters that are easy to configur ### Foundation in jsPsych -jsPsych 7 tasks can be converted to the Honeycomb structure to take advantage of the flexible deployment and automated GitHub Actions workflow that Honeycomb provides. +Honeycomb is built on top of [jsPsych](https://www.jspsych.org/), a JavaScript library for running behavioral experiments in a web browser. jsPsych7 tasks can be moved directly into Honeycomb to take advantage of the flexible deployment and automated GitHub Actions workflow that Honeycomb provides. ### Community Driven diff --git a/docs/prerequisites.mdx b/docs/prerequisites.mdx index b27e21f7..c38768f9 100644 --- a/docs/prerequisites.mdx +++ b/docs/prerequisites.mdx @@ -5,7 +5,7 @@ title: Prerequisites description: Overview of prerequisite software and how to install them --- -It is important that your computer is set up with the necessary packages before you begin development. You will come across a variety of errors if these prerequisites are not installed. **The [quick start](quick_start#installing-prerequisites) guide explains how to run an automated install**, this page details what programs and packages are needed to run and build Honeycomb. There are some OS specific prerequisites needed to build a task as a desktop application. +It is important that your computer is set up with the necessary packages before you begin development. You will come across a variety of errors if these prerequisites are not installed. **The [quick start](quick_start#installing-prerequisites) guide explains how to run an automated install**. This page details what programs and packages are needed to run and build Honeycomb. There are some OS-specific prerequisites needed to build a task as a desktop application. ## OS Independent @@ -23,16 +23,16 @@ It is important that your computer is set up with the necessary packages before [Python](https://www.python.org) is a high-level programming language. Some "under the hood" tools needed by Honeycomb are written in python so it must be installed on your system. -:::note -Honeycomb needs version 3.7 or later to run - the installers use version 3.11. +:::danger +Honeycomb **cannot** use Python version 3.12 or newer. The installers will install version 3.11. ::: ### Oracle JDk -[Java](https://www.oracle.com/java/) is another high-level programming languages that some tools are written in (namely, the Firebase Emulators). We must install a JDK (Java Development Kit) for it to run. +[Java](https://www.oracle.com/java/) is another high-level programming language that some tools are written in (namely, the Firebase Emulators). We must install a JDK (Java Development Kit) for it to run. :::note -Honeycomb needs version 11 or later to run - the installers use version 18. +Honeycomb needs Java version 11 or later to run - the installers use version 18. ::: ### Visual Studio Code @@ -51,19 +51,21 @@ Honeycomb needs version 11 or later to run - the installers use version 18. ### Rosetta -Rosetta is a translation layer built for Mac computers with Apple Silicon. It should ask to be installed if any of the prerequisite tools need it. Otherwise, [this guide](https://support.apple.com/en-us/HT211861) can be used to make sure it is on your Apple silicon system. +Rosetta is a translation layer built for Mac computers with Apple Silicon. It should ask to be installed if any of the prerequisite tools need it. Otherwise, [this guide](https://support.apple.com/en-us/HT211861) can be used to make sure it is on your Apple Silicon system. ## Windows-specific Install ### Visual Studio -[Visual Studio](https://visualstudio.microsoft.com) is a special IDE for the Windows platform. It comes with everything needed to compile desktop applications from a PC. Visual Studio Community is a free to use platform. +[Visual Studio](https://visualstudio.microsoft.com) is a special IDE for the Windows platform. It comes with everything needed to compile desktop applications from a PC. Visual Studio Community is free to use. :::caution The "Desktop development with C++" workload must also be installed with Visual Studio. The automated installers should preselect this but you should double check to be certain! ::: -## Manual Installation (macOS) +## Manual Installation + +### macOS The links below will take you to each project installation page should you prefer to manually install the prerequisite software. @@ -75,7 +77,7 @@ The links below will take you to each project installation page should you prefe - [VS Code](https://code.visualstudio.com/download) - [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) -## Manual Installation (Windows) +### Windows The links below will take you to each project installation page should you prefer to manually install the prerequisite software. @@ -89,7 +91,7 @@ The links below will take you to each project installation page should you prefe - [Visual Studio 2022 Community](https://visualstudio.microsoft.com/vs/community/) - Install the [Native C++ Workflow](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#step-4---choose-workloads-1) -## Manual Installation (Linux) +### Linux The links below will take you to each project installation page should you prefer to manually install the prerequisite software. Your preferred installation method for the programs listed [above](#os-independent) should get you up and running on any Linux distro new enough to support GLIBC_2.28. diff --git a/docs/project_organization/ci_cd.mdx b/docs/project_organization/ci_cd.mdx index b60fbde7..10cc455e 100644 --- a/docs/project_organization/ci_cd.mdx +++ b/docs/project_organization/ci_cd.mdx @@ -24,7 +24,7 @@ Honeycomb includes workflows to build and create installers for Windows, Mac and Event code triggers and photodiode spots can only be used on local applications! They will not appear when Honeycomb is deployed on the web. ::: -- `pull_request.yaml`: Every time an Pull Request (PR) is opened the software is built and tests are run for all platforms with `home` and `clinic` settings. This workflow does not upload desktop installers. +- `pull_request.yaml`: Every time a Pull Request (PR) is created the software is built and tests are run for all platforms with `home` and `clinic` settings. This workflow does not upload desktop installers. - `release.yml`: Every time a release is created, edited, or published installers for the Honeycomb app are created and uploaded to the release. This also builds a PsiTurk version and deploys the app to GitHub pages. - `workflow-package.yaml`: Create installers for any/all platforms for the `home` and/or `clinic` setting on demand. The installers/executables are uploaded as artifacts and are available for download from the GitHub Actions tab. This also builds a PsiTurk version when linux or all operating systems are selected. @@ -32,7 +32,7 @@ Event code triggers and photodiode spots can only be used on local applications! On-demand workflows are triggered manually from the GitHub Actions tab. Each GitHub organization/individual has a quota on storage in private repositories. Uploading artifacts counts against your quota. You may consider configuring your workflows to only upload what you need. You can learn more about GitHub's storage limits in their [official documentation](https://docs.github.com/en/billing/managing-billing-for-github-actions/about-billing-for-github-actions#about-billing-for-github-actions). ::: -- `workflow-delete-artifacts.yaml`: On demand workflow for deleting artifacts form your GitHub repository. This can be useful when the `package.yaml` workflow is run multiple times and you want to delete the artifacts from previous runs. +- `workflow-delete-artifacts.yaml`: On-demand workflow for deleting artifacts form your GitHub repository. This can be useful when the `package.yaml` workflow is run multiple times and you want to delete the artifacts from previous runs. ### Firebase @@ -43,5 +43,5 @@ Event code triggers and photodiode spots can only be used on local applications! ::: :::note -If you are not planning on ever using Firebase these workflows may be safely deleted. +These workflows may be safely deleted if you are not planning to ever use Firebase. ::: diff --git a/docs/project_organization/directory_structure.mdx b/docs/project_organization/directory_structure.mdx index 981a9424..bf5ce6e7 100644 --- a/docs/project_organization/directory_structure.mdx +++ b/docs/project_organization/directory_structure.mdx @@ -5,11 +5,11 @@ title: Directory Structure description: Overview of Honeycomb's directory structure --- -This project directory is organized to be very modular and composable. In general, files and functions should be relatively small and self-contained, global scope should not be used and only the pieces of code needed for any given file should be imported. This keeps the code maintainable with clear lineage and purpose for each piece of code. +This project directory is organized to be modular and composable. In general, files and functions should be relatively small and self-contained, global scope should not be used, and only the pieces of code needed for any given file should be imported. ## assets/ -This folder contains any static files that are used by the app. Honeycomb starts with a few images used as icons for the installed applications. +This folder contains static files that are used by the application. Honeycomb uses a few images as icons for the installed applications. :::caution Assets that pertain to your specific task should be added to the [public/assets/](#assets-1) folder, not here! @@ -17,18 +17,18 @@ Assets that pertain to your specific task should be added to the [public/assets/ ## build/ -The [build scripts](npm_scripts#npm-build) automatically create a `build` folder at the root of the repository and update it on subsequent builds. `build/` should be left alone! +The [build scripts](npm_scripts#npm-build) automatically create a `build` folder at the root of the repository and update it on subsequent builds. -:::danger -The build folder is in Honeycomb's `.gitignore` and should never be added to git +:::caution +`build/` should be left alone! It is in Honeycomb's `.gitignore` and should never be added to git. ::: ## emulator_data/ -This folder contains starter data for the Firebase Emulators to use while developing locally. See the [Firebase Scripts](npm_scripts#firebase) to use the data. +This folder contains starter data for the Firebase Emulators to use while developing locally. The [Firebase Scripts](npm_scripts#firebase) detail how to use this data. -:::danger -`emulator_data/` is written to when running `npm run firebase:emulators:save` and should never be manually edited. +:::caution +`emulator_data/` is written to when running `npm run firebase:emulators:save` and should never be edited. ::: ## env/ @@ -37,8 +37,8 @@ This folder contains different files used to pass environment variables (setting ## node_modules/ -:::danger -`node_modules/` is written to when running `npm install` and should never be manually edited. +:::caution +`node_modules/` is written to when running `npm install` and should never be edited. It is in Honeycomb's `.gitignore` and should never be added to git. ::: ## psiturkit/ @@ -46,7 +46,7 @@ This folder contains different files used to pass environment variables (setting The file `psiturk-it` inside `psiturkit/` is a bash script used to instal PsiTurk locally - see [PsiTurk](psiturk#build-instructions) for more information. :::caution -Nothing in this folder should ever need to be manually edited. +This folder involves a Honeycomb deployment. The files do not need to be edited. ::: ## public/ @@ -54,120 +54,164 @@ Nothing in this folder should ever need to be manually edited. The `public` directory contains files that are used as assets in the built app. - `index.html` is the entry point of the website - - Changing `Honeycomb` will update the name you can see in the browser tab. -- `favicon.ico` is the small icon you can see in the browser tab. -- `electron.js` contains all of the code related to the electron app. + - Changing `Honeycomb` will update the text in the browser tab! +- `favicon.ico` is the small (16x16px) icon you can see in the browser tab +- `manifest.json` contains metadata about the web app + +:::caution +`manifest.json` involves project metadata and does not need to be edited. +::: ### assets/ -The `public/assets/` directory contains all of the images and videos needed to run your task. +The `public/assets/` directory contains all of the audio, images, and videos needed to run your task. -### lib/ +### electron/ -The `public/lib/` directory contains the files PsiTurk needs to run. Note that `index.html` references these files inside the `