Merge pull request #115 from brown-ccv/feat-v3.3

feat: Documentation for Honeycomv v3.3

.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

.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 <<EOT >> ~/.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 "[email protected]"
-          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: [email protected]

.nvmrc

@@ -0,0 +1 @@
+v20.11.1

README.md

@@ -5,21 +5,21 @@ 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.
 
 ## 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 <version number>
+    npm run docusaurus docs:version <version number>
     ```
 
 2. Update `versions.json` to include the new version (make sure "current" is first in the array)

docs/deployments/firebase.mdx

@@ -23,7 +23,7 @@ Please have your PI contact [[email protected]](mailto:[email protected]
 
 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
 
       <img
@@ -104,39 +100,6 @@ firebase deploy --only firestore:rules
 
 Your task is now connected to an initialized Firebase project!
 
-## Registering Studies
-
-:::caution
-This step must be followed **exactly**. See [Security Rules](#security-rules) for more information.
-:::
-
-1. Navigate to your Firestore Database in the [console](https://console.firebase.google.com/).
-2. Click "Start collection"
-3. Enter `registered_studies` for the collection id and click "next"
-4. Enter the id of your study for the document id
-5. Add a field named `registered_participants` with the type "array"
-6. Add the id of each study participant as a string inside the array
-
-<div style={{ textAlign: "center" }}>
-  <img
-    src={firestoreCreateStudy}
-    alt="Create a study"
-    style={{ maxHeight: "600px" }}
-  />
-</div>
-<br />
-
-The study should like this when you're finished:
-
-<img
-  src={firestoreExampleStudy}
-  alt="Example study"
-/>
-<br />
-<br />
-
-**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,24 +112,24 @@ 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`.
 :::
 
 ## 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.
 
 ```shell title="Initialize Firebase hosting via Github actions"
 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. `<username>/<repository name>` 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. `<username>/<repository name>` 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,15 +152,15 @@ 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/)
    <img
      src={firebaseConsoleSettings}
      alt="Firebase project settings"
    />
 2. Click on the "Service accounts" tab
 3. Near the bottom, click "Generate new Private key" and "Generate Key"
 
-4. Rename the key `firebase-service-account.json` and move it to the root directory of your task. Be sure the file looks grayed out and is not picked up by git!
+4. Rename the key `firebase-service-account.json` and move it to the root directory of your task - be sure the file looks grayed out and is not picked up by git!
 
 :::danger
 A service account has total administrative access to ts Firebase project. The file and keys inside should never be shared and **never committed to GitHub.**
@@ -238,24 +201,73 @@ Firestore rules are defined in the `firestore.rules` file in the home directory.
 ```firestore-security-rules title="firestore.rules" showLineNumbers
 rules_version = '2';
 service cloud.firestore {
-  //highlight-start
   match /databases/{database}/documents {
-      match /participant_responses/{studyID}/participants/{participantID} {
-        allow create, read:
-        if participantID in get(/databases/$(database)/documents/registered_studies/$(studyID)).data.registered_participants;
-  //highlight-end
-        // ...
+    match /participant_responses/{studyID}/participants/{participantID} {
+      allow create, read:
+      // highlight-start
+      if
+        // Allows any combination of studyID and participantID to be created in Firebase
+        true
+        // participantID must be in the registered_participants array in the registered_studies/{studyID} document
+        // participantID in get(/databases/$(database)/documents/registered_studies/$(studyID)).data.registered_participants;
+      // highlight-end
+
+      // experimentID must be in the data subcollection
+      match /data/{experimentID} {
+        allow create, read: if true
+
+        // trialID must be in the trials subcollection
+        match /trials/{trialID} {
+          allow create, read: if true
+        }
       }
     }
+  }
 }
 ```
 
 Lines 3 and 4 indicate that Honeycomb attempts to connect to a document at `/databases/{database}/documents/participant_responses/{studyID}/participants/{participantID}` where `studyID` is a given study and `participantID` is a given participant within that study.
 
-Line 6 defines our rule - it must pass for Honeycomb to connect to the document. `participantID` must be found in an array called `registered_participants` inside of a document at `/databases/{database}/documents/registered_studies/{studyID}`.
+Line 5 indicates how Honeycomb can interact with that document. Note that Honeycomb cannot update or delete data! You must use the [CLI script](#using-the-cli-script) to delete data.
 
-Line 5 indicates how Honeycomb can interact with that document. Note that Honeycomb cannot update or delete data! You must manually make these changes from the Firestore console.
+Lines 6 through 10 defines our rule for creating a document for a given participant at `participant_responses/{studyID}/participants/{participantID}`. Honeycomb ships with two possible rules:
+
+1. Line 8 specifies `true` which allows any combination of `studyID` and `participantID` to be created in Firebase.
+
+   :::info
+   This is the default rule Honeycomb ships with. It is recommended to leave this rule as is and handle the registration of studies in another tool such as [Prolific](prolific).
+   :::
+
+2. Line 10 only allows a `participantID` to be created if the value is in an array called `registered_participants` inside of a document at `registered_studies/{studyID}`. This ensures pre-registration of every study and participant - the [next section](#registering-studies) explains how to register studies.
+
+:::caution
+Firestore rules define every valid path for data in your project. Attempting to connect anywhere besides the paths in your Firestore rules will be automatically denied, even if you have manually saved data elsewhere. This is why `firestore.rules` contains the nested rules in lines 12 - 20. These should be left alone.
 
-:::danger
-Firestore rules must define every match pattern in your project. Attempting to connect anywhere other than `/participant_responses/{studyID}/participants/{participantID}` will be automatically denied even if you add other collections to your database. This is why `firestore.rules` contains additional nested rules - these should be left alone.
 :::
+
+#### Registering Studies
+
+1. Navigate to your Firestore Database in the [Firebase console](https://console.firebase.google.com/)
+2. Click "Start collection"
+3. Enter `registered_studies` as the collection ID
+4. Enter the id of your study as the document id
+5. Click "Add Field".
+6. Enter `registered_participants` as the field name, and set the type "array"
+7. Add the id of each study participant to the array as type "string"
+
+   <div style={{ textAlign: "center" }}>
+     <img
+       src={firestoreCreateStudy}
+       alt="Create a study"
+       style={{ maxHeight: "600px" }}
+     />
+   </div>
+
+The study should look like this when you're finished:
+
+<img
+  src={firestoreExampleStudy}
+  alt="Example study"
+/>
+
+**Additional studies are created as documents inside the `registered_studies` collection**