From c384e7b1338c66f370d57f74b814729736d24241 Mon Sep 17 00:00:00 2001 From: gh-actions Date: Wed, 20 Sep 2023 19:33:53 +0000 Subject: [PATCH] Deploy website - based on b680db35c2ba733b6a0ca535555e26a7c43c6708 --- 404.html | 4 ++-- assets/js/{021ef33c.97ad3225.js => 021ef33c.72d9e87c.js} | 2 +- assets/js/{038eb3f9.f91e41b4.js => 038eb3f9.6f924714.js} | 2 +- assets/js/{126c24b0.54e0b4b7.js => 126c24b0.016ae088.js} | 2 +- assets/js/{16d466d3.7ea6aac7.js => 16d466d3.570f96d0.js} | 2 +- assets/js/{18d66fd2.703f0abf.js => 18d66fd2.835a389b.js} | 2 +- assets/js/{1d5c4879.081fb8a6.js => 1d5c4879.8aa00a3e.js} | 2 +- assets/js/{26eac671.815c7f66.js => 26eac671.ae5d5f88.js} | 2 +- assets/js/{2e3bbbfb.fec2812f.js => 2e3bbbfb.6c534b09.js} | 2 +- assets/js/{2e7e1f7d.5a229109.js => 2e7e1f7d.d09346a0.js} | 2 +- assets/js/{2f756f52.002f0cca.js => 2f756f52.84d05b98.js} | 2 +- assets/js/{31f23339.6ba8aaa0.js => 31f23339.ec923ffe.js} | 2 +- assets/js/{320598df.fafafca2.js => 320598df.bec75318.js} | 2 +- assets/js/{345c7eb3.6d58b5ed.js => 345c7eb3.05955795.js} | 2 +- assets/js/{3875cc13.1b4acc4d.js => 3875cc13.dd9d897e.js} | 2 +- assets/js/{399eddc3.e2f86dd6.js => 399eddc3.06e04276.js} | 2 +- assets/js/{41ba2ed4.f6ff7350.js => 41ba2ed4.09a19979.js} | 2 +- assets/js/{4cfc1f6d.9ae9c555.js => 4cfc1f6d.a3884173.js} | 2 +- assets/js/{50a1c39b.24e840dd.js => 50a1c39b.a67b3e30.js} | 2 +- assets/js/{5523f789.6924922f.js => 5523f789.55573eb7.js} | 2 +- assets/js/{55717fdc.5dfd7a47.js => 55717fdc.069d2ada.js} | 2 +- assets/js/{56e3640d.6113f738.js => 56e3640d.4c6bafad.js} | 2 +- assets/js/{57376ffa.ec53853e.js => 57376ffa.a3677df2.js} | 2 +- assets/js/{57a33906.9cb00462.js => 57a33906.aacbc7ae.js} | 2 +- assets/js/{5ab8d7cd.d4bb3185.js => 5ab8d7cd.03bce93c.js} | 2 +- assets/js/{5c12e3d5.9fbcb8f3.js => 5c12e3d5.dad546a5.js} | 2 +- assets/js/{5fa663bb.112acf33.js => 5fa663bb.3a236831.js} | 2 +- assets/js/{683171a4.51a6ee3c.js => 683171a4.7816111f.js} | 2 +- assets/js/{68b345d2.f4b48129.js => 68b345d2.04aaf9e3.js} | 2 +- assets/js/{7057cd16.90f1b0c1.js => 7057cd16.29e7a81b.js} | 2 +- assets/js/{770946dd.89fbeb76.js => 770946dd.59e2332b.js} | 2 +- assets/js/{7a18207a.38faf5b4.js => 7a18207a.358922bf.js} | 2 +- assets/js/{7a9953f0.2950f3a8.js => 7a9953f0.9e99af8a.js} | 2 +- assets/js/{7cf27cd9.eb01dde3.js => 7cf27cd9.855e7d8d.js} | 2 +- assets/js/{82f5f04f.40c0b7ad.js => 82f5f04f.3ae8b78c.js} | 2 +- assets/js/{86cc4549.0a4b6811.js => 86cc4549.6eb4d56c.js} | 2 +- assets/js/{8c92f8b1.d164c38d.js => 8c92f8b1.28a13eee.js} | 2 +- assets/js/{8cb632e5.32e048f7.js => 8cb632e5.4a709434.js} | 2 +- assets/js/{8d7a93e2.b15ce2e6.js => 8d7a93e2.66149a91.js} | 2 +- assets/js/{8e825d18.7a345c9a.js => 8e825d18.c29a92dc.js} | 2 +- assets/js/{972d9d57.b7963d3d.js => 972d9d57.5b23fcc7.js} | 2 +- assets/js/{9ca3efa6.e1d515f3.js => 9ca3efa6.92aa3f88.js} | 2 +- assets/js/{a1d415eb.80b97768.js => a1d415eb.50468a98.js} | 2 +- assets/js/{a3adbb79.bf24130c.js => a3adbb79.c1cab26d.js} | 2 +- assets/js/{a3d433e0.67999623.js => a3d433e0.84581677.js} | 2 +- assets/js/{a76de88e.9f36f353.js => a76de88e.0c155f8f.js} | 2 +- assets/js/{a98a78f3.c5176b7a.js => a98a78f3.70b94eb2.js} | 2 +- assets/js/{abd38d44.fbeb0e30.js => abd38d44.78ea6382.js} | 2 +- assets/js/{b7b6eed1.c3c63929.js => b7b6eed1.d95ea072.js} | 2 +- assets/js/{b9f44a27.0244f067.js => b9f44a27.79055b4d.js} | 2 +- assets/js/{bc497764.16a9f6ab.js => bc497764.9f41ebf8.js} | 2 +- assets/js/{be8bb97f.2418c58c.js => be8bb97f.a7d815a6.js} | 2 +- assets/js/{c2cb1cd1.b3d14b1d.js => c2cb1cd1.39cc485c.js} | 2 +- assets/js/{c577e57c.77220a78.js => c577e57c.7ca0d874.js} | 2 +- assets/js/{c8da9515.959f2c96.js => c8da9515.0290b148.js} | 2 +- assets/js/{cd949796.e32e17ef.js => cd949796.9a7d6f39.js} | 2 +- assets/js/{e1651c90.02f0a941.js => e1651c90.9c5c82a6.js} | 2 +- assets/js/{e3312cea.99e869dc.js => e3312cea.f1e456f5.js} | 2 +- assets/js/{e36f51a1.acbfcac5.js => e36f51a1.b38951a6.js} | 2 +- assets/js/{e425a490.c800191f.js => e425a490.d549aa14.js} | 2 +- assets/js/{e89c0fdd.b9997864.js => e89c0fdd.36e03c12.js} | 2 +- assets/js/{efd1bcf6.0424ef8b.js => efd1bcf6.ee698154.js} | 2 +- assets/js/{f1192dde.b679f101.js => f1192dde.0178c90b.js} | 2 +- assets/js/{f144c3d6.a35b9cee.js => f144c3d6.842ab184.js} | 2 +- assets/js/{f5534f4b.c2ccbaeb.js => f5534f4b.0cc9d59e.js} | 2 +- assets/js/{f8662fe8.56655291.js => f8662fe8.fc24e83c.js} | 2 +- assets/js/{fa4eb42f.b49af774.js => fa4eb42f.6ebc377c.js} | 2 +- assets/js/runtime~main.1de94f45.js | 1 - assets/js/runtime~main.60759070.js | 1 + docs/1.1.0/ci/index.html | 6 +++--- docs/1.1.0/configuration/index.html | 6 +++--- docs/1.1.0/event_triggers/index.html | 6 +++--- docs/1.1.0/folders/index.html | 6 +++--- docs/1.1.0/index.html | 6 +++--- docs/1.1.0/npm_scripts/index.html | 6 +++--- docs/1.1.0/online_integration/index.html | 6 +++--- docs/1.1.0/quick_start/index.html | 6 +++--- docs/1.1.0/software_prerecs/index.html | 6 +++--- docs/1.1.0/troubleshooting/index.html | 6 +++--- docs/1.1.0/version_control/index.html | 6 +++--- docs/2.x/ci/index.html | 6 +++--- docs/2.x/configuration/index.html | 6 +++--- docs/2.x/event_triggers/index.html | 6 +++--- docs/2.x/firebase/index.html | 6 +++--- docs/2.x/folders/index.html | 6 +++--- docs/2.x/index.html | 6 +++--- docs/2.x/npm_scripts/index.html | 6 +++--- docs/2.x/online_integration/index.html | 6 +++--- docs/2.x/quick_start/index.html | 6 +++--- docs/2.x/software_prerecs/index.html | 6 +++--- docs/2.x/troubleshooting/index.html | 6 +++--- docs/2.x/version_control/index.html | 6 +++--- docs/3.0.0/ci/index.html | 6 +++--- docs/3.0.0/configuration/index.html | 6 +++--- docs/3.0.0/event_triggers/index.html | 6 +++--- docs/3.0.0/firebase/index.html | 6 +++--- docs/3.0.0/folders/index.html | 6 +++--- docs/3.0.0/index.html | 6 +++--- docs/3.0.0/npm_scripts/index.html | 6 +++--- docs/3.0.0/online_integration/index.html | 6 +++--- docs/3.0.0/quick_start/index.html | 6 +++--- docs/3.0.0/setup_details/index.html | 6 +++--- docs/3.0.0/troubleshooting/index.html | 6 +++--- docs/3.0.0/variants/index.html | 6 +++--- docs/3.0.0/version_control/index.html | 6 +++--- docs/3.1.x/ci/index.html | 6 +++--- docs/3.1.x/deploy_online/index.html | 6 +++--- docs/3.1.x/environment_variables/index.html | 6 +++--- docs/3.1.x/event_triggers/index.html | 6 +++--- docs/3.1.x/firebase/index.html | 6 +++--- docs/3.1.x/index.html | 6 +++--- docs/3.1.x/javascript/index.html | 6 +++--- docs/3.1.x/npm_scripts/index.html | 6 +++--- docs/3.1.x/prerequisites/index.html | 6 +++--- docs/3.1.x/project_organization/index.html | 6 +++--- docs/3.1.x/quick_start/index.html | 6 +++--- docs/3.1.x/troubleshooting/index.html | 6 +++--- docs/3.1.x/variants/index.html | 6 +++--- docs/3.1.x/version_control/index.html | 6 +++--- docs/ci_cd/index.html | 6 +++--- docs/directory_structure/index.html | 6 +++--- docs/environment_variables/index.html | 6 +++--- docs/event_triggers/index.html | 6 +++--- docs/firebase/index.html | 6 +++--- docs/gh_pages/index.html | 6 +++--- docs/index.html | 6 +++--- docs/javascript/index.html | 6 +++--- docs/local_application/index.html | 6 +++--- docs/npm_scripts/index.html | 6 +++--- docs/prerequisites/index.html | 6 +++--- docs/psiturk/index.html | 6 +++--- docs/quick_start/index.html | 6 +++--- docs/troubleshooting/index.html | 6 +++--- docs/variants/index.html | 6 +++--- docs/version_control/index.html | 6 +++--- index.html | 4 ++-- 136 files changed, 269 insertions(+), 269 deletions(-) rename assets/js/{021ef33c.97ad3225.js => 021ef33c.72d9e87c.js} (99%) rename assets/js/{038eb3f9.f91e41b4.js => 038eb3f9.6f924714.js} (98%) rename assets/js/{126c24b0.54e0b4b7.js => 126c24b0.016ae088.js} (99%) rename assets/js/{16d466d3.7ea6aac7.js => 16d466d3.570f96d0.js} (99%) rename assets/js/{18d66fd2.703f0abf.js => 18d66fd2.835a389b.js} (99%) rename assets/js/{1d5c4879.081fb8a6.js => 1d5c4879.8aa00a3e.js} (99%) rename assets/js/{26eac671.815c7f66.js => 26eac671.ae5d5f88.js} (98%) rename assets/js/{2e3bbbfb.fec2812f.js => 2e3bbbfb.6c534b09.js} (98%) rename assets/js/{2e7e1f7d.5a229109.js => 2e7e1f7d.d09346a0.js} (99%) rename assets/js/{2f756f52.002f0cca.js => 2f756f52.84d05b98.js} (99%) rename assets/js/{31f23339.6ba8aaa0.js => 31f23339.ec923ffe.js} (99%) rename assets/js/{320598df.fafafca2.js => 320598df.bec75318.js} (99%) rename assets/js/{345c7eb3.6d58b5ed.js => 345c7eb3.05955795.js} (99%) rename assets/js/{3875cc13.1b4acc4d.js => 3875cc13.dd9d897e.js} (99%) rename assets/js/{399eddc3.e2f86dd6.js => 399eddc3.06e04276.js} (98%) rename assets/js/{41ba2ed4.f6ff7350.js => 41ba2ed4.09a19979.js} (99%) rename assets/js/{4cfc1f6d.9ae9c555.js => 4cfc1f6d.a3884173.js} (99%) rename assets/js/{50a1c39b.24e840dd.js => 50a1c39b.a67b3e30.js} (98%) rename assets/js/{5523f789.6924922f.js => 5523f789.55573eb7.js} (99%) rename assets/js/{55717fdc.5dfd7a47.js => 55717fdc.069d2ada.js} (98%) rename assets/js/{56e3640d.6113f738.js => 56e3640d.4c6bafad.js} (99%) rename assets/js/{57376ffa.ec53853e.js => 57376ffa.a3677df2.js} (99%) rename assets/js/{57a33906.9cb00462.js => 57a33906.aacbc7ae.js} (99%) rename assets/js/{5ab8d7cd.d4bb3185.js => 5ab8d7cd.03bce93c.js} (99%) rename assets/js/{5c12e3d5.9fbcb8f3.js => 5c12e3d5.dad546a5.js} (99%) rename assets/js/{5fa663bb.112acf33.js => 5fa663bb.3a236831.js} (99%) rename assets/js/{683171a4.51a6ee3c.js => 683171a4.7816111f.js} (99%) rename assets/js/{68b345d2.f4b48129.js => 68b345d2.04aaf9e3.js} (98%) rename assets/js/{7057cd16.90f1b0c1.js => 7057cd16.29e7a81b.js} (97%) rename assets/js/{770946dd.89fbeb76.js => 770946dd.59e2332b.js} (97%) rename assets/js/{7a18207a.38faf5b4.js => 7a18207a.358922bf.js} (99%) rename assets/js/{7a9953f0.2950f3a8.js => 7a9953f0.9e99af8a.js} (99%) rename assets/js/{7cf27cd9.eb01dde3.js => 7cf27cd9.855e7d8d.js} (99%) rename assets/js/{82f5f04f.40c0b7ad.js => 82f5f04f.3ae8b78c.js} (99%) rename assets/js/{86cc4549.0a4b6811.js => 86cc4549.6eb4d56c.js} (98%) rename assets/js/{8c92f8b1.d164c38d.js => 8c92f8b1.28a13eee.js} (99%) rename assets/js/{8cb632e5.32e048f7.js => 8cb632e5.4a709434.js} (98%) rename assets/js/{8d7a93e2.b15ce2e6.js => 8d7a93e2.66149a91.js} (98%) rename assets/js/{8e825d18.7a345c9a.js => 8e825d18.c29a92dc.js} (99%) rename assets/js/{972d9d57.b7963d3d.js => 972d9d57.5b23fcc7.js} (98%) rename assets/js/{9ca3efa6.e1d515f3.js => 9ca3efa6.92aa3f88.js} (99%) rename assets/js/{a1d415eb.80b97768.js => a1d415eb.50468a98.js} (99%) rename assets/js/{a3adbb79.bf24130c.js => a3adbb79.c1cab26d.js} (99%) rename assets/js/{a3d433e0.67999623.js => a3d433e0.84581677.js} (98%) rename assets/js/{a76de88e.9f36f353.js => a76de88e.0c155f8f.js} (99%) rename assets/js/{a98a78f3.c5176b7a.js => a98a78f3.70b94eb2.js} (98%) rename assets/js/{abd38d44.fbeb0e30.js => abd38d44.78ea6382.js} (98%) rename assets/js/{b7b6eed1.c3c63929.js => b7b6eed1.d95ea072.js} (99%) rename assets/js/{b9f44a27.0244f067.js => b9f44a27.79055b4d.js} (82%) rename assets/js/{bc497764.16a9f6ab.js => bc497764.9f41ebf8.js} (98%) rename assets/js/{be8bb97f.2418c58c.js => be8bb97f.a7d815a6.js} (99%) rename assets/js/{c2cb1cd1.b3d14b1d.js => c2cb1cd1.39cc485c.js} (99%) rename assets/js/{c577e57c.77220a78.js => c577e57c.7ca0d874.js} (99%) rename assets/js/{c8da9515.959f2c96.js => c8da9515.0290b148.js} (99%) rename assets/js/{cd949796.e32e17ef.js => cd949796.9a7d6f39.js} (99%) rename assets/js/{e1651c90.02f0a941.js => e1651c90.9c5c82a6.js} (98%) rename assets/js/{e3312cea.99e869dc.js => e3312cea.f1e456f5.js} (99%) rename assets/js/{e36f51a1.acbfcac5.js => e36f51a1.b38951a6.js} (98%) rename assets/js/{e425a490.c800191f.js => e425a490.d549aa14.js} (99%) rename assets/js/{e89c0fdd.b9997864.js => e89c0fdd.36e03c12.js} (99%) rename assets/js/{efd1bcf6.0424ef8b.js => efd1bcf6.ee698154.js} (99%) rename assets/js/{f1192dde.b679f101.js => f1192dde.0178c90b.js} (99%) rename assets/js/{f144c3d6.a35b9cee.js => f144c3d6.842ab184.js} (99%) rename assets/js/{f5534f4b.c2ccbaeb.js => f5534f4b.0cc9d59e.js} (97%) rename assets/js/{f8662fe8.56655291.js => f8662fe8.fc24e83c.js} (99%) rename assets/js/{fa4eb42f.b49af774.js => fa4eb42f.6ebc377c.js} (99%) delete mode 100644 assets/js/runtime~main.1de94f45.js create mode 100644 assets/js/runtime~main.60759070.js diff --git a/404.html b/404.html index c611afd1..737cde38 100644 --- a/404.html +++ b/404.html @@ -4,13 +4,13 @@ Page Not Found | Honeycomb - +
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

- + \ No newline at end of file diff --git a/assets/js/021ef33c.97ad3225.js b/assets/js/021ef33c.72d9e87c.js similarity index 99% rename from assets/js/021ef33c.97ad3225.js rename to assets/js/021ef33c.72d9e87c.js index 90023487..9abd1728 100644 --- a/assets/js/021ef33c.97ad3225.js +++ b/assets/js/021ef33c.72d9e87c.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[6447],{3905:(e,t,o)=>{o.d(t,{Zo:()=>p,kt:()=>f});var n=o(7294);function a(e,t,o){return t in e?Object.defineProperty(e,t,{value:o,enumerable:!0,configurable:!0,writable:!0}):e[t]=o,e}function i(e,t){var o=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),o.push.apply(o,n)}return o}function r(e){for(var t=1;t=0||(a[o]=e[o]);return a}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,o)&&(a[o]=e[o])}return a}var l=n.createContext({}),c=function(e){var t=n.useContext(l),o=t;return e&&(o="function"==typeof e?e(t):r(r({},t),e)),o},p=function(e){var t=c(e.components);return n.createElement(l.Provider,{value:t},e.children)},d="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef((function(e,t){var o=e.components,a=e.mdxType,i=e.originalType,l=e.parentName,p=s(e,["components","mdxType","originalType","parentName"]),d=c(o),m=a,f=d["".concat(l,".").concat(m)]||d[m]||u[m]||i;return o?n.createElement(f,r(r({ref:t},p),{},{components:o})):n.createElement(f,r({ref:t},p))}));function f(e,t){var o=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var i=o.length,r=new Array(i);r[0]=m;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[d]="string"==typeof e?e:a,r[1]=s;for(var c=2;c{o.r(t),o.d(t,{assets:()=>l,contentTitle:()=>r,default:()=>u,frontMatter:()=>i,metadata:()=>s,toc:()=>c});var n=o(7462),a=(o(7294),o(3905));const i={id:"ci_cd",slug:"/ci_cd",title:"Continuous Integration / Deployment",description:"Descriptions of the GitHub Actions for Honeycomb's CI/CD workflows"},r=void 0,s={unversionedId:"project_organization/ci_cd",id:"project_organization/ci_cd",title:"Continuous Integration / Deployment",description:"Descriptions of the GitHub Actions for Honeycomb's CI/CD workflows",source:"@site/docs/project_organization/ci_cd.mdx",sourceDirName:"project_organization",slug:"/ci_cd",permalink:"/honeycomb-docs/docs/ci_cd",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/docs/project_organization/ci_cd.mdx",tags:[],version:"current",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"ci_cd",slug:"/ci_cd",title:"Continuous Integration / Deployment",description:"Descriptions of the GitHub Actions for Honeycomb's CI/CD workflows"},sidebar:"mySidebar",previous:{title:"Environment Variables",permalink:"/honeycomb-docs/docs/environment_variables"},next:{title:"Local Application",permalink:"/honeycomb-docs/docs/local_application"}},l={},c=[{value:"What are Github Actions",id:"what-are-github-actions",level:2},{value:"Honeycomb's CI/CD Workflows",id:"honeycombs-cicd-workflows",level:2},{value:"Firebase",id:"firebase",level:3}],p={toc:c},d="wrapper";function u(e){let{components:t,...o}=e;return(0,a.kt)(d,(0,n.Z)({},p,o,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings, both on demand and automatically as code is pushed to the repository. Honeycomb's CI/CD is managed by GitHub Actions. These workflows provide Honeycomb's foundation and can easily be modified or extended to meet more needs."),(0,a.kt)("h2",{id:"what-are-github-actions"},"What are Github Actions"),(0,a.kt)("p",null,(0,a.kt)("a",{parentName:"p",href:"https://docs.github.com/en/actions"},"GitHub Actions")," automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in ",(0,a.kt)("a",{parentName:"p",href:"https://docs.github.com/en/actions/reference/events-that-trigger-workflows"},"GitHub's documentation")),(0,a.kt)("p",null,"GitHub Actions are written as YML files inside the ",(0,a.kt)("inlineCode",{parentName:"p"},".github/workflows/")," folder of your repository."),(0,a.kt)("h2",{id:"honeycombs-cicd-workflows"},"Honeycomb's CI/CD Workflows"),(0,a.kt)("p",null,"Honeycomb includes workflows to build and create installers for Windows, Mac and Linux, as well as for deploying to Firebase. These workflows exist for two configurations of the tasks:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"Home"),": The app does not expect event code triggers and photodiode spots."),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"Clinic"),": The app expects event code triggers and photodiode spots.")),(0,a.kt)("admonition",{type:"tip"},(0,a.kt)("p",{parentName:"admonition"},"Event code triggers and photodiode spots can only be used on local applications! They will not appear when Honeycomb is deployed on the web.")),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},"pull_request.yaml"),": Every time an Pull Request (PR) is opened the software is built and tests are run for all platforms with ",(0,a.kt)("inlineCode",{parentName:"p"},"home")," and ",(0,a.kt)("inlineCode",{parentName:"p"},"clinic")," settings. This workflow does not upload desktop installers.")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},"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.")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},"workflow-package.yaml"),": Create installers for any/all platforms for the ",(0,a.kt)("inlineCode",{parentName:"p"},"home")," and/or ",(0,a.kt)("inlineCode",{parentName:"p"},"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."),(0,a.kt)("admonition",{parentName:"li",type:"note"},(0,a.kt)("p",{parentName:"admonition"},"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 ",(0,a.kt)("a",{parentName:"p",href:"https://docs.github.com/en/billing/managing-billing-for-github-actions/about-billing-for-github-actions#about-billing-for-github-actions"},"official documentation"),"."))),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},"workflow-delete-artifacts.yaml"),": On demand workflow for deleting artifacts form your GitHub repository. This can be useful when the ",(0,a.kt)("inlineCode",{parentName:"p"},"package.yaml")," workflow is run multiple times and you want to delete the artifacts from previous runs."))),(0,a.kt)("h3",{id:"firebase"},"Firebase"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"firebase-hosting-merge.yaml"),": Deploys the web version of the application to Firebase when a PR is merged into the ",(0,a.kt)("inlineCode",{parentName:"li"},"main")," branch."),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"firebase-hosting-pull-request.yaml"),": Creates a preview version of the application with Firebase when a PR is opened.",(0,a.kt)("admonition",{parentName:"li",type:"warning"},(0,a.kt)("p",{parentName:"admonition"},"While this workflow uses a preview link it does use the production database. Ensure you use a test study to not conflict with your participant data.")))),(0,a.kt)("admonition",{type:"note"},(0,a.kt)("p",{parentName:"admonition"},"If you are not planning on ever using Firebase these workflows may be safely deleted.")))}u.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[6447],{3905:(e,t,o)=>{o.d(t,{Zo:()=>p,kt:()=>f});var n=o(7294);function a(e,t,o){return t in e?Object.defineProperty(e,t,{value:o,enumerable:!0,configurable:!0,writable:!0}):e[t]=o,e}function i(e,t){var o=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),o.push.apply(o,n)}return o}function r(e){for(var t=1;t=0||(a[o]=e[o]);return a}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,o)&&(a[o]=e[o])}return a}var l=n.createContext({}),c=function(e){var t=n.useContext(l),o=t;return e&&(o="function"==typeof e?e(t):r(r({},t),e)),o},p=function(e){var t=c(e.components);return n.createElement(l.Provider,{value:t},e.children)},d="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef((function(e,t){var o=e.components,a=e.mdxType,i=e.originalType,l=e.parentName,p=s(e,["components","mdxType","originalType","parentName"]),d=c(o),m=a,f=d["".concat(l,".").concat(m)]||d[m]||u[m]||i;return o?n.createElement(f,r(r({ref:t},p),{},{components:o})):n.createElement(f,r({ref:t},p))}));function f(e,t){var o=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var i=o.length,r=new Array(i);r[0]=m;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[d]="string"==typeof e?e:a,r[1]=s;for(var c=2;c{o.r(t),o.d(t,{assets:()=>l,contentTitle:()=>r,default:()=>u,frontMatter:()=>i,metadata:()=>s,toc:()=>c});var n=o(7462),a=(o(7294),o(3905));const i={id:"ci_cd",slug:"/ci_cd",title:"Continuous Integration / Deployment",description:"Descriptions of the GitHub Actions for Honeycomb's CI/CD workflows"},r=void 0,s={unversionedId:"project_organization/ci_cd",id:"project_organization/ci_cd",title:"Continuous Integration / Deployment",description:"Descriptions of the GitHub Actions for Honeycomb's CI/CD workflows",source:"@site/docs/project_organization/ci_cd.mdx",sourceDirName:"project_organization",slug:"/ci_cd",permalink:"/honeycomb-docs/docs/ci_cd",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/docs/project_organization/ci_cd.mdx",tags:[],version:"current",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"ci_cd",slug:"/ci_cd",title:"Continuous Integration / Deployment",description:"Descriptions of the GitHub Actions for Honeycomb's CI/CD workflows"},sidebar:"mySidebar",previous:{title:"Environment Variables",permalink:"/honeycomb-docs/docs/environment_variables"},next:{title:"Local Application",permalink:"/honeycomb-docs/docs/local_application"}},l={},c=[{value:"What are Github Actions",id:"what-are-github-actions",level:2},{value:"Honeycomb's CI/CD Workflows",id:"honeycombs-cicd-workflows",level:2},{value:"Firebase",id:"firebase",level:3}],p={toc:c},d="wrapper";function u(e){let{components:t,...o}=e;return(0,a.kt)(d,(0,n.Z)({},p,o,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings, both on demand and automatically as code is pushed to the repository. Honeycomb's CI/CD is managed by GitHub Actions. These workflows provide Honeycomb's foundation and can easily be modified or extended to meet more needs."),(0,a.kt)("h2",{id:"what-are-github-actions"},"What are Github Actions"),(0,a.kt)("p",null,(0,a.kt)("a",{parentName:"p",href:"https://docs.github.com/en/actions"},"GitHub Actions")," automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in ",(0,a.kt)("a",{parentName:"p",href:"https://docs.github.com/en/actions/reference/events-that-trigger-workflows"},"GitHub's documentation")),(0,a.kt)("p",null,"GitHub Actions are written as YML files inside the ",(0,a.kt)("inlineCode",{parentName:"p"},".github/workflows/")," folder of your repository."),(0,a.kt)("h2",{id:"honeycombs-cicd-workflows"},"Honeycomb's CI/CD Workflows"),(0,a.kt)("p",null,"Honeycomb includes workflows to build and create installers for Windows, Mac and Linux, as well as for deploying to Firebase. These workflows exist for two configurations of the tasks:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"Home"),": The app does not expect event code triggers and photodiode spots."),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"Clinic"),": The app expects event code triggers and photodiode spots.")),(0,a.kt)("admonition",{type:"tip"},(0,a.kt)("p",{parentName:"admonition"},"Event code triggers and photodiode spots can only be used on local applications! They will not appear when Honeycomb is deployed on the web.")),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},"pull_request.yaml"),": Every time an Pull Request (PR) is opened the software is built and tests are run for all platforms with ",(0,a.kt)("inlineCode",{parentName:"p"},"home")," and ",(0,a.kt)("inlineCode",{parentName:"p"},"clinic")," settings. This workflow does not upload desktop installers.")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},"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.")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},"workflow-package.yaml"),": Create installers for any/all platforms for the ",(0,a.kt)("inlineCode",{parentName:"p"},"home")," and/or ",(0,a.kt)("inlineCode",{parentName:"p"},"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."),(0,a.kt)("admonition",{parentName:"li",type:"note"},(0,a.kt)("p",{parentName:"admonition"},"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 ",(0,a.kt)("a",{parentName:"p",href:"https://docs.github.com/en/billing/managing-billing-for-github-actions/about-billing-for-github-actions#about-billing-for-github-actions"},"official documentation"),"."))),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("p",{parentName:"li"},(0,a.kt)("inlineCode",{parentName:"p"},"workflow-delete-artifacts.yaml"),": On demand workflow for deleting artifacts form your GitHub repository. This can be useful when the ",(0,a.kt)("inlineCode",{parentName:"p"},"package.yaml")," workflow is run multiple times and you want to delete the artifacts from previous runs."))),(0,a.kt)("h3",{id:"firebase"},"Firebase"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"firebase-hosting-merge.yaml"),": Deploys the web version of the application to Firebase when a PR is merged into the ",(0,a.kt)("inlineCode",{parentName:"li"},"main")," branch."),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"firebase-hosting-pull-request.yaml"),": Creates a preview version of the application with Firebase when a PR is opened.",(0,a.kt)("admonition",{parentName:"li",type:"warning"},(0,a.kt)("p",{parentName:"admonition"},"While this workflow uses a preview link it does use the production database. Ensure you use a test study to not conflict with your participant data.")))),(0,a.kt)("admonition",{type:"note"},(0,a.kt)("p",{parentName:"admonition"},"If you are not planning on ever using Firebase these workflows may be safely deleted.")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/038eb3f9.f91e41b4.js b/assets/js/038eb3f9.6f924714.js similarity index 98% rename from assets/js/038eb3f9.f91e41b4.js rename to assets/js/038eb3f9.6f924714.js index 05a74662..8008daa7 100644 --- a/assets/js/038eb3f9.f91e41b4.js +++ b/assets/js/038eb3f9.6f924714.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[526],{3905:(e,t,o)=>{o.d(t,{Zo:()=>p,kt:()=>m});var r=o(7294);function n(e,t,o){return t in e?Object.defineProperty(e,t,{value:o,enumerable:!0,configurable:!0,writable:!0}):e[t]=o,e}function a(e,t){var o=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),o.push.apply(o,r)}return o}function s(e){for(var t=1;t=0||(n[o]=e[o]);return n}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,o)&&(n[o]=e[o])}return n}var l=r.createContext({}),c=function(e){var t=r.useContext(l),o=t;return e&&(o="function"==typeof e?e(t):s(s({},t),e)),o},p=function(e){var t=c(e.components);return r.createElement(l.Provider,{value:t},e.children)},d="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var o=e.components,n=e.mdxType,a=e.originalType,l=e.parentName,p=i(e,["components","mdxType","originalType","parentName"]),d=c(o),f=n,m=d["".concat(l,".").concat(f)]||d[f]||u[f]||a;return o?r.createElement(m,s(s({ref:t},p),{},{components:o})):r.createElement(m,s({ref:t},p))}));function m(e,t){var o=arguments,n=t&&t.mdxType;if("string"==typeof e||n){var a=o.length,s=new Array(a);s[0]=f;var i={};for(var l in t)hasOwnProperty.call(t,l)&&(i[l]=t[l]);i.originalType=e,i[d]="string"==typeof e?e:n,s[1]=i;for(var c=2;c{o.r(t),o.d(t,{assets:()=>l,contentTitle:()=>s,default:()=>u,frontMatter:()=>a,metadata:()=>i,toc:()=>c});var r=o(7462),n=(o(7294),o(3905));const a={id:"software_prerecs",title:"Software Prerequisites"},s=void 0,i={unversionedId:"software_prerecs",id:"version-1.1.0/software_prerecs",title:"Software Prerequisites",description:"Windows",source:"@site/versioned_docs/version-1.1.0/software_prerecs.md",sourceDirName:".",slug:"/software_prerecs",permalink:"/honeycomb-docs/docs/1.1.0/software_prerecs",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-1.1.0/software_prerecs.md",tags:[],version:"1.1.0",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"software_prerecs",title:"Software Prerequisites"}},l={},c=[{value:"Windows",id:"windows",level:2},{value:"Visual Studio",id:"visual-studio",level:4},{value:"Python",id:"python",level:4},{value:"Node.js",id:"nodejs",level:4},{value:"Git bash",id:"git-bash",level:4},{value:"Note: restart computer after all installs are complete",id:"note-restart-computer-after-all-installs-are-complete",level:4}],p={toc:c},d="wrapper";function u(e){let{components:t,...o}=e;return(0,n.kt)(d,(0,r.Z)({},p,o,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("h2",{id:"windows"},"Windows"),(0,n.kt)("h4",{id:"visual-studio"},"Visual Studio"),(0,n.kt)("p",null,"Install the latest version of Visual Studio (",(0,n.kt)("a",{parentName:"p",href:"https://visualstudio.microsoft.com/downloads/"},"https://visualstudio.microsoft.com/downloads/"),") with the Desktop Development for C++ Workflow.\nTo add the workflow, follow the instructions linked below:\n",(0,n.kt)("a",{parentName:"p",href:"https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#:~:text=If%20you%20have%20Visual%20Studio,Then%2C%20choose%20Modify"},"https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#:~:text=If%20you%20have%20Visual%20Studio,Then%2C%20choose%20Modify"),"."),(0,n.kt)("h4",{id:"python"},"Python"),(0,n.kt)("p",null,"Install Python. For new Python users, we recommend installing via Anaconda: ",(0,n.kt)("a",{parentName:"p",href:"https://docs.anaconda.com/anaconda/install/windows/"},"https://docs.anaconda.com/anaconda/install/windows/")),(0,n.kt)("h4",{id:"nodejs"},"Node.js"),(0,n.kt)("p",null,"Install Node.js: ",(0,n.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"https://nodejs.org/en/download/")),(0,n.kt)("h4",{id:"git-bash"},"Git bash"),(0,n.kt)("p",null,"Install git bash: ",(0,n.kt)("a",{parentName:"p",href:"https://git-scm.com/downloads"},"https://git-scm.com/downloads")),(0,n.kt)("h4",{id:"note-restart-computer-after-all-installs-are-complete"},"Note: restart computer after all installs are complete"))}u.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[526],{3905:(e,t,o)=>{o.d(t,{Zo:()=>p,kt:()=>m});var r=o(7294);function n(e,t,o){return t in e?Object.defineProperty(e,t,{value:o,enumerable:!0,configurable:!0,writable:!0}):e[t]=o,e}function a(e,t){var o=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),o.push.apply(o,r)}return o}function s(e){for(var t=1;t=0||(n[o]=e[o]);return n}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,o)&&(n[o]=e[o])}return n}var l=r.createContext({}),c=function(e){var t=r.useContext(l),o=t;return e&&(o="function"==typeof e?e(t):s(s({},t),e)),o},p=function(e){var t=c(e.components);return r.createElement(l.Provider,{value:t},e.children)},d="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},f=r.forwardRef((function(e,t){var o=e.components,n=e.mdxType,a=e.originalType,l=e.parentName,p=i(e,["components","mdxType","originalType","parentName"]),d=c(o),f=n,m=d["".concat(l,".").concat(f)]||d[f]||u[f]||a;return o?r.createElement(m,s(s({ref:t},p),{},{components:o})):r.createElement(m,s({ref:t},p))}));function m(e,t){var o=arguments,n=t&&t.mdxType;if("string"==typeof e||n){var a=o.length,s=new Array(a);s[0]=f;var i={};for(var l in t)hasOwnProperty.call(t,l)&&(i[l]=t[l]);i.originalType=e,i[d]="string"==typeof e?e:n,s[1]=i;for(var c=2;c{o.r(t),o.d(t,{assets:()=>l,contentTitle:()=>s,default:()=>u,frontMatter:()=>a,metadata:()=>i,toc:()=>c});var r=o(7462),n=(o(7294),o(3905));const a={id:"software_prerecs",title:"Software Prerequisites"},s=void 0,i={unversionedId:"software_prerecs",id:"version-1.1.0/software_prerecs",title:"Software Prerequisites",description:"Windows",source:"@site/versioned_docs/version-1.1.0/software_prerecs.md",sourceDirName:".",slug:"/software_prerecs",permalink:"/honeycomb-docs/docs/1.1.0/software_prerecs",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-1.1.0/software_prerecs.md",tags:[],version:"1.1.0",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"software_prerecs",title:"Software Prerequisites"}},l={},c=[{value:"Windows",id:"windows",level:2},{value:"Visual Studio",id:"visual-studio",level:4},{value:"Python",id:"python",level:4},{value:"Node.js",id:"nodejs",level:4},{value:"Git bash",id:"git-bash",level:4},{value:"Note: restart computer after all installs are complete",id:"note-restart-computer-after-all-installs-are-complete",level:4}],p={toc:c},d="wrapper";function u(e){let{components:t,...o}=e;return(0,n.kt)(d,(0,r.Z)({},p,o,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("h2",{id:"windows"},"Windows"),(0,n.kt)("h4",{id:"visual-studio"},"Visual Studio"),(0,n.kt)("p",null,"Install the latest version of Visual Studio (",(0,n.kt)("a",{parentName:"p",href:"https://visualstudio.microsoft.com/downloads/"},"https://visualstudio.microsoft.com/downloads/"),") with the Desktop Development for C++ Workflow.\nTo add the workflow, follow the instructions linked below:\n",(0,n.kt)("a",{parentName:"p",href:"https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#:~:text=If%20you%20have%20Visual%20Studio,Then%2C%20choose%20Modify"},"https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#:~:text=If%20you%20have%20Visual%20Studio,Then%2C%20choose%20Modify"),"."),(0,n.kt)("h4",{id:"python"},"Python"),(0,n.kt)("p",null,"Install Python. For new Python users, we recommend installing via Anaconda: ",(0,n.kt)("a",{parentName:"p",href:"https://docs.anaconda.com/anaconda/install/windows/"},"https://docs.anaconda.com/anaconda/install/windows/")),(0,n.kt)("h4",{id:"nodejs"},"Node.js"),(0,n.kt)("p",null,"Install Node.js: ",(0,n.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"https://nodejs.org/en/download/")),(0,n.kt)("h4",{id:"git-bash"},"Git bash"),(0,n.kt)("p",null,"Install git bash: ",(0,n.kt)("a",{parentName:"p",href:"https://git-scm.com/downloads"},"https://git-scm.com/downloads")),(0,n.kt)("h4",{id:"note-restart-computer-after-all-installs-are-complete"},"Note: restart computer after all installs are complete"))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/126c24b0.54e0b4b7.js b/assets/js/126c24b0.016ae088.js similarity index 99% rename from assets/js/126c24b0.54e0b4b7.js rename to assets/js/126c24b0.016ae088.js index 0a05a3d6..27369e59 100644 --- a/assets/js/126c24b0.54e0b4b7.js +++ b/assets/js/126c24b0.016ae088.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[1485],{3905:(e,t,r)=>{r.d(t,{Zo:()=>p,kt:()=>h});var a=r(7294);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function n(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,a)}return r}function i(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var s=a.createContext({}),c=function(e){var t=a.useContext(s),r=t;return e&&(r="function"==typeof e?e(t):i(i({},t),e)),r},p=function(e){var t=c(e.components);return a.createElement(s.Provider,{value:t},e.children)},m="mdxType",d={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var r=e.components,o=e.mdxType,n=e.originalType,s=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),m=c(r),u=o,h=m["".concat(s,".").concat(u)]||m[u]||d[u]||n;return r?a.createElement(h,i(i({ref:t},p),{},{components:r})):a.createElement(h,i({ref:t},p))}));function h(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var n=r.length,i=new Array(n);i[0]=u;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l[m]="string"==typeof e?e:o,i[1]=l;for(var c=2;c{r.r(t),r.d(t,{assets:()=>s,contentTitle:()=>i,default:()=>d,frontMatter:()=>n,metadata:()=>l,toc:()=>c});var a=r(7462),o=(r(7294),r(3905));const n={id:"version_control",slug:"/version_control",title:"Version Control",description:"Version control basics with Git and GitHub"},i=void 0,l={unversionedId:"further_reading/version_control",id:"version-3.1.x/further_reading/version_control",title:"Version Control",description:"Version control basics with Git and GitHub",source:"@site/versioned_docs/version-3.1.x/further_reading/version_control.mdx",sourceDirName:"further_reading",slug:"/version_control",permalink:"/honeycomb-docs/docs/3.1.x/version_control",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/further_reading/version_control.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"version_control",slug:"/version_control",title:"Version Control",description:"Version control basics with Git and GitHub"},sidebar:"mySidebar",previous:{title:"Continuous Integration",permalink:"/honeycomb-docs/docs/3.1.x/ci"},next:{title:"JavaScript",permalink:"/honeycomb-docs/docs/3.1.x/javascript"}},s={},c=[{value:"Git Overview",id:"git-overview",level:2},{value:"Create a Pull Request",id:"create-a-pull-request",level:2},{value:"Stay up-to-date with Honeycomb template repo",id:"stay-up-to-date-with-honeycomb-template-repo",level:2},{value:"Best Practices",id:"best-practices",level:2},{value:"Git Branches",id:"git-branches",level:3},{value:"Basic Workflow",id:"basic-workflow",level:3},{value:"Comment styles",id:"comment-styles",level:3},{value:"Cheatsheet",id:"cheatsheet",level:2},{value:"Git Commands",id:"git-commands",level:3},{value:"Alternative options",id:"alternative-options",level:3},{value:"VS Code",id:"vs-code",level:4},{value:"GitHub Desktop",id:"github-desktop",level:4}],p={toc:c},m="wrapper";function d(e){let{components:t,...n}=e;return(0,o.kt)(m,(0,a.Z)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h2",{id:"git-overview"},"Git Overview"),(0,o.kt)("p",null,"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."),(0,o.kt)("p",null,"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."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Git basics",src:r(1428).Z,width:"874",height:"509"})),(0,o.kt)("p",null,"If you would like to make any changes to current repository, it is always good to start with creating a feature branch, where you can save all the changes."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Example branch",src:r(3858).Z,width:"773",height:"337"})),(0,o.kt)("h2",{id:"create-a-pull-request"},"Create a Pull Request"),(0,o.kt)("p",null,"Pull requests are useful before you merge your branch with the main branch. You can request a review from your colleagues and check for any conflicts with the main branch. After you pushed all the changes to your branch, you can go to the original GitHub repository and click on the pull request."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"git pr",src:r(8264).Z,width:"2408",height:"1330"})),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"git pr info",src:r(8382).Z,width:"2408",height:"1902"})),(0,o.kt)("h2",{id:"stay-up-to-date-with-honeycomb-template-repo"},"Stay up-to-date with Honeycomb template repo"),(0,o.kt)("p",null,"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:"),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Add Honeycomb as an additional remote as follows:"),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"git remote add honeycomb https://github.com/brown-ccv/honeycomb.git\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Fetch the changes made to Honeycomb"),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"git fetch --all\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Merge the current Honeycomb repo"),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"git merge honeycomb/main --allow-unrelated histories\n")))),(0,o.kt)("admonition",{type:"caution"},(0,o.kt)("p",{parentName:"admonition"},'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')),(0,o.kt)("h2",{id:"best-practices"},"Best Practices"),(0,o.kt)("h3",{id:"git-branches"},"Git Branches"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("inlineCode",{parentName:"p"},"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.")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("inlineCode",{parentName:"p"},"topic")," branches are created for new features, fixes, or really any changes. E.g, ",(0,o.kt)("inlineCode",{parentName:"p"},"fix-task-trial2-stuck-button")))),(0,o.kt)("p",null,"This flow is sometimes referred to as ",(0,o.kt)("a",{parentName:"p",href:"https://docs.gitlab.com/ee/gitlab-basics/feature_branch_workflow.html"},"Feature Branch Workflow")),(0,o.kt)("h3",{id:"basic-workflow"},"Basic Workflow"),(0,o.kt)("p",null,"We recommend using a simple flow based on following rules:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"Use topic/feature branches, no direct commits on main."),(0,o.kt)("li",{parentName:"ul"},"Perform tests and code reviews before merges into main, not afterwards."),(0,o.kt)("li",{parentName:"ul"},"Every branch starts from main, and targets main."),(0,o.kt)("li",{parentName:"ul"},"Commit messages reflect intent.")),(0,o.kt)("h3",{id:"comment-styles"},"Comment styles"),(0,o.kt)("p",null,"We encourage using ",(0,o.kt)("a",{parentName:"p",href:"http://commitizen.github.io/cz-cli/"},"Commitizen"),", 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."),(0,o.kt)("h2",{id:"cheatsheet"},"Cheatsheet"),(0,o.kt)("h3",{id:"git-commands"},"Git Commands"),(0,o.kt)("table",null,(0,o.kt)("thead",{parentName:"table"},(0,o.kt)("tr",{parentName:"thead"},(0,o.kt)("th",{parentName:"tr",align:"left"},"Command"),(0,o.kt)("th",{parentName:"tr",align:"left"},"Brief"))),(0,o.kt)("tbody",{parentName:"table"},(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git add ","<","files",">"),(0,o.kt)("td",{parentName:"tr",align:"left"},"add a file to next commit ","(","stage",")")),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git commit -m ","<","message",">"),(0,o.kt)("td",{parentName:"tr",align:"left"},"commit staged files")),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git push"),(0,o.kt)("td",{parentName:"tr",align:"left"},"upload staged commit to repo")),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git pull"),(0,o.kt)("td",{parentName:"tr",align:"left"},"get remote repo commits and download ","(","try and resolve conflicts",")")),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git clone ","<","url",">"),(0,o.kt)("td",{parentName:"tr",align:"left"},"download entire repository")),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git checkout ","<","branch",">"),(0,o.kt)("td",{parentName:"tr",align:"left"},"checkout and create the branch you want to use")))),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},'# create branch with your feature\ngit checkout -b feature_name\n# check the status of your repositoey\ngit status\n# commit file contents to the local repository\ngit commit -m "My feature is ready"\n\n# specific message\n# push file contents to the remote (i.e. cloud) repository\ngit push origin feature_name\n')),(0,o.kt)("h3",{id:"alternative-options"},"Alternative options"),(0,o.kt)("h4",{id:"vs-code"},"VS Code"),(0,o.kt)("p",null,"Most IDEs have some built in tools for working with Git and VS Code is no exception. Check out ",(0,o.kt)("a",{parentName:"p",href:"https://code.visualstudio.com/docs/sourcecontrol/overview"},"this overview")," of source control in VS Code!"),(0,o.kt)("h4",{id:"github-desktop"},"GitHub Desktop"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://desktop.github.com/"},"GitHub Desktop")," is a GUI application for working with git. It is one of the programs installed as a prerequisite of Honeycomb. Check out ",(0,o.kt)("a",{parentName:"p",href:"https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop"},"this overview")," of source control in GitHub Desktop!"))}d.isMDXComponent=!0},8382:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/add_reviewers-2577687884f77e9065ba4f25a368d878.png"},8264:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/create_pull_request-5270b3148c70e4fb72dab791677df74b.png"},1428:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/git_basics-8ba67841533472790a3ef4038aa47323.png"},3858:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/git_branch-b9459ab613a299a1d693104b5f93f356.png"}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[1485],{3905:(e,t,r)=>{r.d(t,{Zo:()=>p,kt:()=>h});var a=r(7294);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function n(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,a)}return r}function i(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var s=a.createContext({}),c=function(e){var t=a.useContext(s),r=t;return e&&(r="function"==typeof e?e(t):i(i({},t),e)),r},p=function(e){var t=c(e.components);return a.createElement(s.Provider,{value:t},e.children)},m="mdxType",d={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var r=e.components,o=e.mdxType,n=e.originalType,s=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),m=c(r),u=o,h=m["".concat(s,".").concat(u)]||m[u]||d[u]||n;return r?a.createElement(h,i(i({ref:t},p),{},{components:r})):a.createElement(h,i({ref:t},p))}));function h(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var n=r.length,i=new Array(n);i[0]=u;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l[m]="string"==typeof e?e:o,i[1]=l;for(var c=2;c{r.r(t),r.d(t,{assets:()=>s,contentTitle:()=>i,default:()=>d,frontMatter:()=>n,metadata:()=>l,toc:()=>c});var a=r(7462),o=(r(7294),r(3905));const n={id:"version_control",slug:"/version_control",title:"Version Control",description:"Version control basics with Git and GitHub"},i=void 0,l={unversionedId:"further_reading/version_control",id:"version-3.1.x/further_reading/version_control",title:"Version Control",description:"Version control basics with Git and GitHub",source:"@site/versioned_docs/version-3.1.x/further_reading/version_control.mdx",sourceDirName:"further_reading",slug:"/version_control",permalink:"/honeycomb-docs/docs/3.1.x/version_control",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/further_reading/version_control.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"version_control",slug:"/version_control",title:"Version Control",description:"Version control basics with Git and GitHub"},sidebar:"mySidebar",previous:{title:"Continuous Integration",permalink:"/honeycomb-docs/docs/3.1.x/ci"},next:{title:"JavaScript",permalink:"/honeycomb-docs/docs/3.1.x/javascript"}},s={},c=[{value:"Git Overview",id:"git-overview",level:2},{value:"Create a Pull Request",id:"create-a-pull-request",level:2},{value:"Stay up-to-date with Honeycomb template repo",id:"stay-up-to-date-with-honeycomb-template-repo",level:2},{value:"Best Practices",id:"best-practices",level:2},{value:"Git Branches",id:"git-branches",level:3},{value:"Basic Workflow",id:"basic-workflow",level:3},{value:"Comment styles",id:"comment-styles",level:3},{value:"Cheatsheet",id:"cheatsheet",level:2},{value:"Git Commands",id:"git-commands",level:3},{value:"Alternative options",id:"alternative-options",level:3},{value:"VS Code",id:"vs-code",level:4},{value:"GitHub Desktop",id:"github-desktop",level:4}],p={toc:c},m="wrapper";function d(e){let{components:t,...n}=e;return(0,o.kt)(m,(0,a.Z)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h2",{id:"git-overview"},"Git Overview"),(0,o.kt)("p",null,"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."),(0,o.kt)("p",null,"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."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Git basics",src:r(1428).Z,width:"874",height:"509"})),(0,o.kt)("p",null,"If you would like to make any changes to current repository, it is always good to start with creating a feature branch, where you can save all the changes."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Example branch",src:r(3858).Z,width:"773",height:"337"})),(0,o.kt)("h2",{id:"create-a-pull-request"},"Create a Pull Request"),(0,o.kt)("p",null,"Pull requests are useful before you merge your branch with the main branch. You can request a review from your colleagues and check for any conflicts with the main branch. After you pushed all the changes to your branch, you can go to the original GitHub repository and click on the pull request."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"git pr",src:r(8264).Z,width:"2408",height:"1330"})),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"git pr info",src:r(8382).Z,width:"2408",height:"1902"})),(0,o.kt)("h2",{id:"stay-up-to-date-with-honeycomb-template-repo"},"Stay up-to-date with Honeycomb template repo"),(0,o.kt)("p",null,"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:"),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Add Honeycomb as an additional remote as follows:"),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"git remote add honeycomb https://github.com/brown-ccv/honeycomb.git\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Fetch the changes made to Honeycomb"),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"git fetch --all\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Merge the current Honeycomb repo"),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"git merge honeycomb/main --allow-unrelated histories\n")))),(0,o.kt)("admonition",{type:"caution"},(0,o.kt)("p",{parentName:"admonition"},'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')),(0,o.kt)("h2",{id:"best-practices"},"Best Practices"),(0,o.kt)("h3",{id:"git-branches"},"Git Branches"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("inlineCode",{parentName:"p"},"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.")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("p",{parentName:"li"},(0,o.kt)("inlineCode",{parentName:"p"},"topic")," branches are created for new features, fixes, or really any changes. E.g, ",(0,o.kt)("inlineCode",{parentName:"p"},"fix-task-trial2-stuck-button")))),(0,o.kt)("p",null,"This flow is sometimes referred to as ",(0,o.kt)("a",{parentName:"p",href:"https://docs.gitlab.com/ee/gitlab-basics/feature_branch_workflow.html"},"Feature Branch Workflow")),(0,o.kt)("h3",{id:"basic-workflow"},"Basic Workflow"),(0,o.kt)("p",null,"We recommend using a simple flow based on following rules:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"Use topic/feature branches, no direct commits on main."),(0,o.kt)("li",{parentName:"ul"},"Perform tests and code reviews before merges into main, not afterwards."),(0,o.kt)("li",{parentName:"ul"},"Every branch starts from main, and targets main."),(0,o.kt)("li",{parentName:"ul"},"Commit messages reflect intent.")),(0,o.kt)("h3",{id:"comment-styles"},"Comment styles"),(0,o.kt)("p",null,"We encourage using ",(0,o.kt)("a",{parentName:"p",href:"http://commitizen.github.io/cz-cli/"},"Commitizen"),", 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."),(0,o.kt)("h2",{id:"cheatsheet"},"Cheatsheet"),(0,o.kt)("h3",{id:"git-commands"},"Git Commands"),(0,o.kt)("table",null,(0,o.kt)("thead",{parentName:"table"},(0,o.kt)("tr",{parentName:"thead"},(0,o.kt)("th",{parentName:"tr",align:"left"},"Command"),(0,o.kt)("th",{parentName:"tr",align:"left"},"Brief"))),(0,o.kt)("tbody",{parentName:"table"},(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git add ","<","files",">"),(0,o.kt)("td",{parentName:"tr",align:"left"},"add a file to next commit ","(","stage",")")),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git commit -m ","<","message",">"),(0,o.kt)("td",{parentName:"tr",align:"left"},"commit staged files")),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git push"),(0,o.kt)("td",{parentName:"tr",align:"left"},"upload staged commit to repo")),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git pull"),(0,o.kt)("td",{parentName:"tr",align:"left"},"get remote repo commits and download ","(","try and resolve conflicts",")")),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git clone ","<","url",">"),(0,o.kt)("td",{parentName:"tr",align:"left"},"download entire repository")),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:"left"},"git checkout ","<","branch",">"),(0,o.kt)("td",{parentName:"tr",align:"left"},"checkout and create the branch you want to use")))),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},'# create branch with your feature\ngit checkout -b feature_name\n# check the status of your repositoey\ngit status\n# commit file contents to the local repository\ngit commit -m "My feature is ready"\n\n# specific message\n# push file contents to the remote (i.e. cloud) repository\ngit push origin feature_name\n')),(0,o.kt)("h3",{id:"alternative-options"},"Alternative options"),(0,o.kt)("h4",{id:"vs-code"},"VS Code"),(0,o.kt)("p",null,"Most IDEs have some built in tools for working with Git and VS Code is no exception. Check out ",(0,o.kt)("a",{parentName:"p",href:"https://code.visualstudio.com/docs/sourcecontrol/overview"},"this overview")," of source control in VS Code!"),(0,o.kt)("h4",{id:"github-desktop"},"GitHub Desktop"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://desktop.github.com/"},"GitHub Desktop")," is a GUI application for working with git. It is one of the programs installed as a prerequisite of Honeycomb. Check out ",(0,o.kt)("a",{parentName:"p",href:"https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop"},"this overview")," of source control in GitHub Desktop!"))}d.isMDXComponent=!0},8382:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/add_reviewers-2577687884f77e9065ba4f25a368d878.png"},8264:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/create_pull_request-5270b3148c70e4fb72dab791677df74b.png"},1428:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/git_basics-8ba67841533472790a3ef4038aa47323.png"},3858:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/git_branch-b9459ab613a299a1d693104b5f93f356.png"}}]); \ No newline at end of file diff --git a/assets/js/16d466d3.7ea6aac7.js b/assets/js/16d466d3.570f96d0.js similarity index 99% rename from assets/js/16d466d3.7ea6aac7.js rename to assets/js/16d466d3.570f96d0.js index 26c05935..521e717e 100644 --- a/assets/js/16d466d3.7ea6aac7.js +++ b/assets/js/16d466d3.570f96d0.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[1326],{3905:(e,t,a)=>{a.d(t,{Zo:()=>u,kt:()=>h});var n=a(7294);function o(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function i(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function l(e){for(var t=1;t=0||(o[a]=e[a]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(o[a]=e[a])}return o}var s=n.createContext({}),p=function(e){var t=n.useContext(s),a=t;return e&&(a="function"==typeof e?e(t):l(l({},t),e)),a},u=function(e){var t=p(e.components);return n.createElement(s.Provider,{value:t},e.children)},d="mdxType",c={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef((function(e,t){var a=e.components,o=e.mdxType,i=e.originalType,s=e.parentName,u=r(e,["components","mdxType","originalType","parentName"]),d=p(a),m=o,h=d["".concat(s,".").concat(m)]||d[m]||c[m]||i;return a?n.createElement(h,l(l({ref:t},u),{},{components:a})):n.createElement(h,l({ref:t},u))}));function h(e,t){var a=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=a.length,l=new Array(i);l[0]=m;var r={};for(var s in t)hasOwnProperty.call(t,s)&&(r[s]=t[s]);r.originalType=e,r[d]="string"==typeof e?e:o,l[1]=r;for(var p=2;p{a.r(t),a.d(t,{assets:()=>s,contentTitle:()=>l,default:()=>c,frontMatter:()=>i,metadata:()=>r,toc:()=>p});var n=a(7462),o=(a(7294),a(3905));const i={id:"prerequisites",slug:"/prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them"},l=void 0,r={unversionedId:"prerequisites",id:"version-3.1.x/prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them",source:"@site/versioned_docs/version-3.1.x/prerequisites.mdx",sourceDirName:".",slug:"/prerequisites",permalink:"/honeycomb-docs/docs/3.1.x/prerequisites",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/prerequisites.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"prerequisites",slug:"/prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them"},sidebar:"mySidebar",previous:{title:"JavaScript",permalink:"/honeycomb-docs/docs/3.1.x/javascript"},next:{title:"Troubleshooting",permalink:"/honeycomb-docs/docs/3.1.x/troubleshooting"}},s={},p=[{value:"OS Independent",id:"os-independent",level:2},{value:"Git",id:"git",level:3},{value:"Node Version Manager",id:"node-version-manager",level:3},{value:"Python",id:"python",level:3},{value:"Oracle JDk",id:"oracle-jdk",level:3},{value:"Visual Studio Code",id:"visual-studio-code",level:3},{value:"Mac-specific Installs",id:"mac-specific-installs",level:2},{value:"X-Code",id:"x-code",level:3},{value:"Rosetta",id:"rosetta",level:3},{value:"Windows-specific Install",id:"windows-specific-install",level:2},{value:"Visual Studio",id:"visual-studio",level:3},{value:"Manual Installation (macOS)",id:"manual-installation-macos",level:2},{value:"Manual Installation (Windows)",id:"manual-installation-windows",level:2},{value:"Manual Installation (Linux)",id:"manual-installation-linux",level:2},{value:"Further Help",id:"further-help",level:2}],u={toc:p},d="wrapper";function c(e){let{components:t,...a}=e;return(0,o.kt)(d,(0,n.Z)({},u,a,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"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. ",(0,o.kt)("strong",{parentName:"p"},"The ",(0,o.kt)("a",{parentName:"strong",href:"quick_start#installing-prerequisites"},"quick start")," 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."),(0,o.kt)("h2",{id:"os-independent"},"OS Independent"),(0,o.kt)("h3",{id:"git"},"Git"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://git-scm.com"},"git")," is an open-sourced version control system. It is used to track changes, revert mistakes, and enable peer code reviews!"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://desktop.github.com"},"GitHub Desktop")," is a GUI application used to interact with git and GitHub directly from your computer. It is not strictly needed but many folks find it easier to work with than using git directly from the command line."),(0,o.kt)("h3",{id:"node-version-manager"},"Node Version Manager"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://nodejs.org/en"},"NodeJS")," is a cross-platform runtime environment for JavaScript code. Almost every web application today builds on top of node. ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/nvm-sh/nvm"},"Node Version Manager")," manages running multiple versions of node on the same system. The ",(0,o.kt)("inlineCode",{parentName:"p"},".nvmrc")," denotes the version of node that Honeycomb uses."),(0,o.kt)("h3",{id:"python"},"Python"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://www.python.org"},"Python"),' 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.'),(0,o.kt)("admonition",{type:"note"},(0,o.kt)("p",{parentName:"admonition"},"Honeycomb needs version 3.7 or later to run - the installers use version 3.11.")),(0,o.kt)("h3",{id:"oracle-jdk"},"Oracle JDk"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://www.oracle.com/java/"},"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."),(0,o.kt)("admonition",{type:"note"},(0,o.kt)("p",{parentName:"admonition"},"Honeycomb needs version 11 or later to run - the installers use version 18.")),(0,o.kt)("h3",{id:"visual-studio-code"},"Visual Studio Code"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://code.visualstudio.com"},"Visual Studio Code")," is a well-loved and easy to use integrated development environment (IDE). This is the program you'll use to write your task."),(0,o.kt)("h2",{id:"mac-specific-installs"},"Mac-specific Installs"),(0,o.kt)("h3",{id:"x-code"},"X-Code"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://developer.apple.com/xcode/"},"XCode")," is a special IDE for the Apple platform. It comes with everything needed to compile desktop applications from an Apple computer. It must be installed from the terminal:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Installing XCode"',title:'"Installing','XCode"':!0}," xcode-select --install\n")),(0,o.kt)("h3",{id:"rosetta"},"Rosetta"),(0,o.kt)("p",null,"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, ",(0,o.kt)("a",{parentName:"p",href:"https://support.apple.com/en-us/HT211861"},"this guide")," can be used to make sure it is on your Apple silicon system."),(0,o.kt)("h2",{id:"windows-specific-install"},"Windows-specific Install"),(0,o.kt)("h3",{id:"visual-studio"},"Visual Studio"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://visualstudio.microsoft.com"},"Visual Studio")," 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."),(0,o.kt)("admonition",{type:"caution"},(0,o.kt)("p",{parentName:"admonition"},'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!')),(0,o.kt)("h2",{id:"manual-installation-macos"},"Manual Installation (macOS)"),(0,o.kt)("p",null,"The links below will take you to each project installation page should you prefer to manually install the prerequisite software."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/mac"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/nvm-sh/nvm#installing-and-updating"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/macos/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-windows"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://apps.apple.com/us/app/xcode/id497799835?mt=12"},"Xcode"))),(0,o.kt)("h2",{id:"manual-installation-windows"},"Manual Installation (Windows)"),(0,o.kt)("p",null,"The links below will take you to each project installation page should you prefer to manually install the prerequisite software."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/win"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/coreybutler/nvm-windows#installation--upgrades"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/windows/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-mac"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},"Visual Studio:",(0,o.kt)("ul",{parentName:"li"},(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://visualstudio.microsoft.com/vs/community/"},"Visual Studio 2022 Community")),(0,o.kt)("li",{parentName:"ul"},"Install the ",(0,o.kt)("a",{parentName:"li",href:"https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#step-4---choose-workloads-1"},"Native C++ Workflow"))))),(0,o.kt)("h2",{id:"manual-installation-linux"},"Manual Installation (Linux)"),(0,o.kt)("p",null,"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 ",(0,o.kt)("a",{parentName:"p",href:"#os-independent"},"above")," should get you up and running on any Linux distro new enough to support GLIBC_2.28."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/linux"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/nvm-sh/nvm#installing-and-updating"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/source/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-linux"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},"Install ",(0,o.kt)("a",{parentName:"li",href:"https://clang.llvm.org/get_started.html"},"Clang")," or follow installation instructions on the ",(0,o.kt)("a",{parentName:"li",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs")),(0,o.kt)("li",{parentName:"ul"},"Development headers of ",(0,o.kt)("inlineCode",{parentName:"li"},"GTK 3")," and ",(0,o.kt)("inlineCode",{parentName:"li"},"libnotify")," (Follow installation instructions on the ",(0,o.kt)("a",{parentName:"li",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs"),")")),(0,o.kt)("h2",{id:"further-help"},"Further Help"),(0,o.kt)("p",null,"If you are still having issues setting up your computer you can find the full instructions on the ",(0,o.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-gn"},"electron documentation")," for your specific OS."))}c.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[1326],{3905:(e,t,a)=>{a.d(t,{Zo:()=>u,kt:()=>h});var n=a(7294);function o(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function i(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function l(e){for(var t=1;t=0||(o[a]=e[a]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(o[a]=e[a])}return o}var s=n.createContext({}),p=function(e){var t=n.useContext(s),a=t;return e&&(a="function"==typeof e?e(t):l(l({},t),e)),a},u=function(e){var t=p(e.components);return n.createElement(s.Provider,{value:t},e.children)},d="mdxType",c={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef((function(e,t){var a=e.components,o=e.mdxType,i=e.originalType,s=e.parentName,u=r(e,["components","mdxType","originalType","parentName"]),d=p(a),m=o,h=d["".concat(s,".").concat(m)]||d[m]||c[m]||i;return a?n.createElement(h,l(l({ref:t},u),{},{components:a})):n.createElement(h,l({ref:t},u))}));function h(e,t){var a=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=a.length,l=new Array(i);l[0]=m;var r={};for(var s in t)hasOwnProperty.call(t,s)&&(r[s]=t[s]);r.originalType=e,r[d]="string"==typeof e?e:o,l[1]=r;for(var p=2;p{a.r(t),a.d(t,{assets:()=>s,contentTitle:()=>l,default:()=>c,frontMatter:()=>i,metadata:()=>r,toc:()=>p});var n=a(7462),o=(a(7294),a(3905));const i={id:"prerequisites",slug:"/prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them"},l=void 0,r={unversionedId:"prerequisites",id:"version-3.1.x/prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them",source:"@site/versioned_docs/version-3.1.x/prerequisites.mdx",sourceDirName:".",slug:"/prerequisites",permalink:"/honeycomb-docs/docs/3.1.x/prerequisites",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/prerequisites.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"prerequisites",slug:"/prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them"},sidebar:"mySidebar",previous:{title:"JavaScript",permalink:"/honeycomb-docs/docs/3.1.x/javascript"},next:{title:"Troubleshooting",permalink:"/honeycomb-docs/docs/3.1.x/troubleshooting"}},s={},p=[{value:"OS Independent",id:"os-independent",level:2},{value:"Git",id:"git",level:3},{value:"Node Version Manager",id:"node-version-manager",level:3},{value:"Python",id:"python",level:3},{value:"Oracle JDk",id:"oracle-jdk",level:3},{value:"Visual Studio Code",id:"visual-studio-code",level:3},{value:"Mac-specific Installs",id:"mac-specific-installs",level:2},{value:"X-Code",id:"x-code",level:3},{value:"Rosetta",id:"rosetta",level:3},{value:"Windows-specific Install",id:"windows-specific-install",level:2},{value:"Visual Studio",id:"visual-studio",level:3},{value:"Manual Installation (macOS)",id:"manual-installation-macos",level:2},{value:"Manual Installation (Windows)",id:"manual-installation-windows",level:2},{value:"Manual Installation (Linux)",id:"manual-installation-linux",level:2},{value:"Further Help",id:"further-help",level:2}],u={toc:p},d="wrapper";function c(e){let{components:t,...a}=e;return(0,o.kt)(d,(0,n.Z)({},u,a,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"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. ",(0,o.kt)("strong",{parentName:"p"},"The ",(0,o.kt)("a",{parentName:"strong",href:"quick_start#installing-prerequisites"},"quick start")," 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."),(0,o.kt)("h2",{id:"os-independent"},"OS Independent"),(0,o.kt)("h3",{id:"git"},"Git"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://git-scm.com"},"git")," is an open-sourced version control system. It is used to track changes, revert mistakes, and enable peer code reviews!"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://desktop.github.com"},"GitHub Desktop")," is a GUI application used to interact with git and GitHub directly from your computer. It is not strictly needed but many folks find it easier to work with than using git directly from the command line."),(0,o.kt)("h3",{id:"node-version-manager"},"Node Version Manager"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://nodejs.org/en"},"NodeJS")," is a cross-platform runtime environment for JavaScript code. Almost every web application today builds on top of node. ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/nvm-sh/nvm"},"Node Version Manager")," manages running multiple versions of node on the same system. The ",(0,o.kt)("inlineCode",{parentName:"p"},".nvmrc")," denotes the version of node that Honeycomb uses."),(0,o.kt)("h3",{id:"python"},"Python"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://www.python.org"},"Python"),' 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.'),(0,o.kt)("admonition",{type:"note"},(0,o.kt)("p",{parentName:"admonition"},"Honeycomb needs version 3.7 or later to run - the installers use version 3.11.")),(0,o.kt)("h3",{id:"oracle-jdk"},"Oracle JDk"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://www.oracle.com/java/"},"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."),(0,o.kt)("admonition",{type:"note"},(0,o.kt)("p",{parentName:"admonition"},"Honeycomb needs version 11 or later to run - the installers use version 18.")),(0,o.kt)("h3",{id:"visual-studio-code"},"Visual Studio Code"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://code.visualstudio.com"},"Visual Studio Code")," is a well-loved and easy to use integrated development environment (IDE). This is the program you'll use to write your task."),(0,o.kt)("h2",{id:"mac-specific-installs"},"Mac-specific Installs"),(0,o.kt)("h3",{id:"x-code"},"X-Code"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://developer.apple.com/xcode/"},"XCode")," is a special IDE for the Apple platform. It comes with everything needed to compile desktop applications from an Apple computer. It must be installed from the terminal:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Installing XCode"',title:'"Installing','XCode"':!0}," xcode-select --install\n")),(0,o.kt)("h3",{id:"rosetta"},"Rosetta"),(0,o.kt)("p",null,"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, ",(0,o.kt)("a",{parentName:"p",href:"https://support.apple.com/en-us/HT211861"},"this guide")," can be used to make sure it is on your Apple silicon system."),(0,o.kt)("h2",{id:"windows-specific-install"},"Windows-specific Install"),(0,o.kt)("h3",{id:"visual-studio"},"Visual Studio"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://visualstudio.microsoft.com"},"Visual Studio")," 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."),(0,o.kt)("admonition",{type:"caution"},(0,o.kt)("p",{parentName:"admonition"},'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!')),(0,o.kt)("h2",{id:"manual-installation-macos"},"Manual Installation (macOS)"),(0,o.kt)("p",null,"The links below will take you to each project installation page should you prefer to manually install the prerequisite software."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/mac"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/nvm-sh/nvm#installing-and-updating"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/macos/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-windows"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://apps.apple.com/us/app/xcode/id497799835?mt=12"},"Xcode"))),(0,o.kt)("h2",{id:"manual-installation-windows"},"Manual Installation (Windows)"),(0,o.kt)("p",null,"The links below will take you to each project installation page should you prefer to manually install the prerequisite software."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/win"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/coreybutler/nvm-windows#installation--upgrades"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/windows/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-mac"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},"Visual Studio:",(0,o.kt)("ul",{parentName:"li"},(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://visualstudio.microsoft.com/vs/community/"},"Visual Studio 2022 Community")),(0,o.kt)("li",{parentName:"ul"},"Install the ",(0,o.kt)("a",{parentName:"li",href:"https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#step-4---choose-workloads-1"},"Native C++ Workflow"))))),(0,o.kt)("h2",{id:"manual-installation-linux"},"Manual Installation (Linux)"),(0,o.kt)("p",null,"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 ",(0,o.kt)("a",{parentName:"p",href:"#os-independent"},"above")," should get you up and running on any Linux distro new enough to support GLIBC_2.28."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/linux"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/nvm-sh/nvm#installing-and-updating"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/source/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-linux"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},"Install ",(0,o.kt)("a",{parentName:"li",href:"https://clang.llvm.org/get_started.html"},"Clang")," or follow installation instructions on the ",(0,o.kt)("a",{parentName:"li",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs")),(0,o.kt)("li",{parentName:"ul"},"Development headers of ",(0,o.kt)("inlineCode",{parentName:"li"},"GTK 3")," and ",(0,o.kt)("inlineCode",{parentName:"li"},"libnotify")," (Follow installation instructions on the ",(0,o.kt)("a",{parentName:"li",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs"),")")),(0,o.kt)("h2",{id:"further-help"},"Further Help"),(0,o.kt)("p",null,"If you are still having issues setting up your computer you can find the full instructions on the ",(0,o.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-gn"},"electron documentation")," for your specific OS."))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/18d66fd2.703f0abf.js b/assets/js/18d66fd2.835a389b.js similarity index 99% rename from assets/js/18d66fd2.703f0abf.js rename to assets/js/18d66fd2.835a389b.js index 1962a696..1fe903ff 100644 --- a/assets/js/18d66fd2.703f0abf.js +++ b/assets/js/18d66fd2.835a389b.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[689],{3905:(e,t,a)=>{a.d(t,{Zo:()=>u,kt:()=>h});var n=a(7294);function o(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function i(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function l(e){for(var t=1;t=0||(o[a]=e[a]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(o[a]=e[a])}return o}var s=n.createContext({}),p=function(e){var t=n.useContext(s),a=t;return e&&(a="function"==typeof e?e(t):l(l({},t),e)),a},u=function(e){var t=p(e.components);return n.createElement(s.Provider,{value:t},e.children)},d="mdxType",c={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef((function(e,t){var a=e.components,o=e.mdxType,i=e.originalType,s=e.parentName,u=r(e,["components","mdxType","originalType","parentName"]),d=p(a),m=o,h=d["".concat(s,".").concat(m)]||d[m]||c[m]||i;return a?n.createElement(h,l(l({ref:t},u),{},{components:a})):n.createElement(h,l({ref:t},u))}));function h(e,t){var a=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=a.length,l=new Array(i);l[0]=m;var r={};for(var s in t)hasOwnProperty.call(t,s)&&(r[s]=t[s]);r.originalType=e,r[d]="string"==typeof e?e:o,l[1]=r;for(var p=2;p{a.r(t),a.d(t,{assets:()=>s,contentTitle:()=>l,default:()=>c,frontMatter:()=>i,metadata:()=>r,toc:()=>p});var n=a(7462),o=(a(7294),a(3905));const i={id:"prerequisites",slug:"/prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them"},l=void 0,r={unversionedId:"prerequisites",id:"prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them",source:"@site/docs/prerequisites.mdx",sourceDirName:".",slug:"/prerequisites",permalink:"/honeycomb-docs/docs/prerequisites",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/docs/prerequisites.mdx",tags:[],version:"current",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"prerequisites",slug:"/prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them"},sidebar:"mySidebar",previous:{title:"Quick Start",permalink:"/honeycomb-docs/docs/quick_start"},next:{title:"Directory Structure",permalink:"/honeycomb-docs/docs/directory_structure"}},s={},p=[{value:"OS Independent",id:"os-independent",level:2},{value:"Git",id:"git",level:3},{value:"Node Version Manager",id:"node-version-manager",level:3},{value:"Python",id:"python",level:3},{value:"Oracle JDk",id:"oracle-jdk",level:3},{value:"Visual Studio Code",id:"visual-studio-code",level:3},{value:"Mac-specific Installs",id:"mac-specific-installs",level:2},{value:"X-Code",id:"x-code",level:3},{value:"Rosetta",id:"rosetta",level:3},{value:"Windows-specific Install",id:"windows-specific-install",level:2},{value:"Visual Studio",id:"visual-studio",level:3},{value:"Manual Installation (macOS)",id:"manual-installation-macos",level:2},{value:"Manual Installation (Windows)",id:"manual-installation-windows",level:2},{value:"Manual Installation (Linux)",id:"manual-installation-linux",level:2},{value:"Further Help",id:"further-help",level:2}],u={toc:p},d="wrapper";function c(e){let{components:t,...a}=e;return(0,o.kt)(d,(0,n.Z)({},u,a,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"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. ",(0,o.kt)("strong",{parentName:"p"},"The ",(0,o.kt)("a",{parentName:"strong",href:"quick_start#installing-prerequisites"},"quick start")," 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."),(0,o.kt)("h2",{id:"os-independent"},"OS Independent"),(0,o.kt)("h3",{id:"git"},"Git"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://git-scm.com"},"git")," is an open-sourced version control system. It is used to track changes, revert mistakes, and enable peer code reviews!"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://desktop.github.com"},"GitHub Desktop")," is a GUI application used to interact with git and GitHub directly from your computer. It is not strictly needed but many folks find it easier to work with than using git directly from the command line."),(0,o.kt)("h3",{id:"node-version-manager"},"Node Version Manager"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://nodejs.org/en"},"NodeJS")," is a cross-platform runtime environment for JavaScript code. Almost every web application today builds on top of node. ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/nvm-sh/nvm"},"Node Version Manager")," manages running multiple versions of node on the same system. The ",(0,o.kt)("inlineCode",{parentName:"p"},".nvmrc")," denotes the version of node that Honeycomb uses."),(0,o.kt)("h3",{id:"python"},"Python"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://www.python.org"},"Python"),' 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.'),(0,o.kt)("admonition",{type:"note"},(0,o.kt)("p",{parentName:"admonition"},"Honeycomb needs version 3.7 or later to run - the installers use version 3.11.")),(0,o.kt)("h3",{id:"oracle-jdk"},"Oracle JDk"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://www.oracle.com/java/"},"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."),(0,o.kt)("admonition",{type:"note"},(0,o.kt)("p",{parentName:"admonition"},"Honeycomb needs version 11 or later to run - the installers use version 18.")),(0,o.kt)("h3",{id:"visual-studio-code"},"Visual Studio Code"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://code.visualstudio.com"},"Visual Studio Code")," is a well-loved and easy to use integrated development environment (IDE). This is the program you'll use to write your task."),(0,o.kt)("h2",{id:"mac-specific-installs"},"Mac-specific Installs"),(0,o.kt)("h3",{id:"x-code"},"X-Code"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://developer.apple.com/xcode/"},"XCode")," is a special IDE for the Apple platform. It comes with everything needed to compile desktop applications from an Apple computer. It must be installed from the terminal:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Installing XCode"',title:'"Installing','XCode"':!0}," xcode-select --install\n")),(0,o.kt)("h3",{id:"rosetta"},"Rosetta"),(0,o.kt)("p",null,"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, ",(0,o.kt)("a",{parentName:"p",href:"https://support.apple.com/en-us/HT211861"},"this guide")," can be used to make sure it is on your Apple silicon system."),(0,o.kt)("h2",{id:"windows-specific-install"},"Windows-specific Install"),(0,o.kt)("h3",{id:"visual-studio"},"Visual Studio"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://visualstudio.microsoft.com"},"Visual Studio")," 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."),(0,o.kt)("admonition",{type:"caution"},(0,o.kt)("p",{parentName:"admonition"},'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!')),(0,o.kt)("h2",{id:"manual-installation-macos"},"Manual Installation (macOS)"),(0,o.kt)("p",null,"The links below will take you to each project installation page should you prefer to manually install the prerequisite software."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/mac"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/nvm-sh/nvm#installing-and-updating"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/macos/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-windows"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://apps.apple.com/us/app/xcode/id497799835?mt=12"},"Xcode"))),(0,o.kt)("h2",{id:"manual-installation-windows"},"Manual Installation (Windows)"),(0,o.kt)("p",null,"The links below will take you to each project installation page should you prefer to manually install the prerequisite software."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/win"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/coreybutler/nvm-windows#installation--upgrades"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/windows/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-mac"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},"Visual Studio:",(0,o.kt)("ul",{parentName:"li"},(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://visualstudio.microsoft.com/vs/community/"},"Visual Studio 2022 Community")),(0,o.kt)("li",{parentName:"ul"},"Install the ",(0,o.kt)("a",{parentName:"li",href:"https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#step-4---choose-workloads-1"},"Native C++ Workflow"))))),(0,o.kt)("h2",{id:"manual-installation-linux"},"Manual Installation (Linux)"),(0,o.kt)("p",null,"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 ",(0,o.kt)("a",{parentName:"p",href:"#os-independent"},"above")," should get you up and running on any Linux distro new enough to support GLIBC_2.28."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/linux"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/nvm-sh/nvm#installing-and-updating"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/source/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-linux"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},"Install ",(0,o.kt)("a",{parentName:"li",href:"https://clang.llvm.org/get_started.html"},"Clang")," or follow installation instructions on the ",(0,o.kt)("a",{parentName:"li",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs")),(0,o.kt)("li",{parentName:"ul"},"Development headers of ",(0,o.kt)("inlineCode",{parentName:"li"},"GTK 3")," and ",(0,o.kt)("inlineCode",{parentName:"li"},"libnotify")," (Follow installation instructions on the ",(0,o.kt)("a",{parentName:"li",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs"),")")),(0,o.kt)("h2",{id:"further-help"},"Further Help"),(0,o.kt)("p",null,"If you are still having issues setting up your computer you can find the full instructions on the ",(0,o.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-gn"},"electron documentation")," for your specific OS."))}c.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[689],{3905:(e,t,a)=>{a.d(t,{Zo:()=>u,kt:()=>h});var n=a(7294);function o(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function i(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function l(e){for(var t=1;t=0||(o[a]=e[a]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(o[a]=e[a])}return o}var s=n.createContext({}),p=function(e){var t=n.useContext(s),a=t;return e&&(a="function"==typeof e?e(t):l(l({},t),e)),a},u=function(e){var t=p(e.components);return n.createElement(s.Provider,{value:t},e.children)},d="mdxType",c={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef((function(e,t){var a=e.components,o=e.mdxType,i=e.originalType,s=e.parentName,u=r(e,["components","mdxType","originalType","parentName"]),d=p(a),m=o,h=d["".concat(s,".").concat(m)]||d[m]||c[m]||i;return a?n.createElement(h,l(l({ref:t},u),{},{components:a})):n.createElement(h,l({ref:t},u))}));function h(e,t){var a=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=a.length,l=new Array(i);l[0]=m;var r={};for(var s in t)hasOwnProperty.call(t,s)&&(r[s]=t[s]);r.originalType=e,r[d]="string"==typeof e?e:o,l[1]=r;for(var p=2;p{a.r(t),a.d(t,{assets:()=>s,contentTitle:()=>l,default:()=>c,frontMatter:()=>i,metadata:()=>r,toc:()=>p});var n=a(7462),o=(a(7294),a(3905));const i={id:"prerequisites",slug:"/prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them"},l=void 0,r={unversionedId:"prerequisites",id:"prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them",source:"@site/docs/prerequisites.mdx",sourceDirName:".",slug:"/prerequisites",permalink:"/honeycomb-docs/docs/prerequisites",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/docs/prerequisites.mdx",tags:[],version:"current",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"prerequisites",slug:"/prerequisites",title:"Prerequisites",description:"Overview of prerequisite software and how to install them"},sidebar:"mySidebar",previous:{title:"Quick Start",permalink:"/honeycomb-docs/docs/quick_start"},next:{title:"Directory Structure",permalink:"/honeycomb-docs/docs/directory_structure"}},s={},p=[{value:"OS Independent",id:"os-independent",level:2},{value:"Git",id:"git",level:3},{value:"Node Version Manager",id:"node-version-manager",level:3},{value:"Python",id:"python",level:3},{value:"Oracle JDk",id:"oracle-jdk",level:3},{value:"Visual Studio Code",id:"visual-studio-code",level:3},{value:"Mac-specific Installs",id:"mac-specific-installs",level:2},{value:"X-Code",id:"x-code",level:3},{value:"Rosetta",id:"rosetta",level:3},{value:"Windows-specific Install",id:"windows-specific-install",level:2},{value:"Visual Studio",id:"visual-studio",level:3},{value:"Manual Installation (macOS)",id:"manual-installation-macos",level:2},{value:"Manual Installation (Windows)",id:"manual-installation-windows",level:2},{value:"Manual Installation (Linux)",id:"manual-installation-linux",level:2},{value:"Further Help",id:"further-help",level:2}],u={toc:p},d="wrapper";function c(e){let{components:t,...a}=e;return(0,o.kt)(d,(0,n.Z)({},u,a,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"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. ",(0,o.kt)("strong",{parentName:"p"},"The ",(0,o.kt)("a",{parentName:"strong",href:"quick_start#installing-prerequisites"},"quick start")," 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."),(0,o.kt)("h2",{id:"os-independent"},"OS Independent"),(0,o.kt)("h3",{id:"git"},"Git"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://git-scm.com"},"git")," is an open-sourced version control system. It is used to track changes, revert mistakes, and enable peer code reviews!"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://desktop.github.com"},"GitHub Desktop")," is a GUI application used to interact with git and GitHub directly from your computer. It is not strictly needed but many folks find it easier to work with than using git directly from the command line."),(0,o.kt)("h3",{id:"node-version-manager"},"Node Version Manager"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://nodejs.org/en"},"NodeJS")," is a cross-platform runtime environment for JavaScript code. Almost every web application today builds on top of node. ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/nvm-sh/nvm"},"Node Version Manager")," manages running multiple versions of node on the same system. The ",(0,o.kt)("inlineCode",{parentName:"p"},".nvmrc")," denotes the version of node that Honeycomb uses."),(0,o.kt)("h3",{id:"python"},"Python"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://www.python.org"},"Python"),' 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.'),(0,o.kt)("admonition",{type:"note"},(0,o.kt)("p",{parentName:"admonition"},"Honeycomb needs version 3.7 or later to run - the installers use version 3.11.")),(0,o.kt)("h3",{id:"oracle-jdk"},"Oracle JDk"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://www.oracle.com/java/"},"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."),(0,o.kt)("admonition",{type:"note"},(0,o.kt)("p",{parentName:"admonition"},"Honeycomb needs version 11 or later to run - the installers use version 18.")),(0,o.kt)("h3",{id:"visual-studio-code"},"Visual Studio Code"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://code.visualstudio.com"},"Visual Studio Code")," is a well-loved and easy to use integrated development environment (IDE). This is the program you'll use to write your task."),(0,o.kt)("h2",{id:"mac-specific-installs"},"Mac-specific Installs"),(0,o.kt)("h3",{id:"x-code"},"X-Code"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://developer.apple.com/xcode/"},"XCode")," is a special IDE for the Apple platform. It comes with everything needed to compile desktop applications from an Apple computer. It must be installed from the terminal:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Installing XCode"',title:'"Installing','XCode"':!0}," xcode-select --install\n")),(0,o.kt)("h3",{id:"rosetta"},"Rosetta"),(0,o.kt)("p",null,"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, ",(0,o.kt)("a",{parentName:"p",href:"https://support.apple.com/en-us/HT211861"},"this guide")," can be used to make sure it is on your Apple silicon system."),(0,o.kt)("h2",{id:"windows-specific-install"},"Windows-specific Install"),(0,o.kt)("h3",{id:"visual-studio"},"Visual Studio"),(0,o.kt)("p",null,(0,o.kt)("a",{parentName:"p",href:"https://visualstudio.microsoft.com"},"Visual Studio")," 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."),(0,o.kt)("admonition",{type:"caution"},(0,o.kt)("p",{parentName:"admonition"},'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!')),(0,o.kt)("h2",{id:"manual-installation-macos"},"Manual Installation (macOS)"),(0,o.kt)("p",null,"The links below will take you to each project installation page should you prefer to manually install the prerequisite software."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/mac"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/nvm-sh/nvm#installing-and-updating"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/macos/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-windows"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://apps.apple.com/us/app/xcode/id497799835?mt=12"},"Xcode"))),(0,o.kt)("h2",{id:"manual-installation-windows"},"Manual Installation (Windows)"),(0,o.kt)("p",null,"The links below will take you to each project installation page should you prefer to manually install the prerequisite software."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/win"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/coreybutler/nvm-windows#installation--upgrades"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/windows/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-mac"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},"Visual Studio:",(0,o.kt)("ul",{parentName:"li"},(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://visualstudio.microsoft.com/vs/community/"},"Visual Studio 2022 Community")),(0,o.kt)("li",{parentName:"ul"},"Install the ",(0,o.kt)("a",{parentName:"li",href:"https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#step-4---choose-workloads-1"},"Native C++ Workflow"))))),(0,o.kt)("h2",{id:"manual-installation-linux"},"Manual Installation (Linux)"),(0,o.kt)("p",null,"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 ",(0,o.kt)("a",{parentName:"p",href:"#os-independent"},"above")," should get you up and running on any Linux distro new enough to support GLIBC_2.28."),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://git-scm.com/download/linux"},"Git")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://desktop.github.com"},"GitHub Desktop")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://github.com/nvm-sh/nvm#installing-and-updating"},"NVM")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.python.org/downloads/source/"},"Python")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://www.oracle.com/java/technologies/downloads/#jdk20-linux"},"Oracle JDK")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://code.visualstudio.com/download"},"VS Code")),(0,o.kt)("li",{parentName:"ul"},"Install ",(0,o.kt)("a",{parentName:"li",href:"https://clang.llvm.org/get_started.html"},"Clang")," or follow installation instructions on the ",(0,o.kt)("a",{parentName:"li",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs")),(0,o.kt)("li",{parentName:"ul"},"Development headers of ",(0,o.kt)("inlineCode",{parentName:"li"},"GTK 3")," and ",(0,o.kt)("inlineCode",{parentName:"li"},"libnotify")," (Follow installation instructions on the ",(0,o.kt)("a",{parentName:"li",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs"),")")),(0,o.kt)("h2",{id:"further-help"},"Further Help"),(0,o.kt)("p",null,"If you are still having issues setting up your computer you can find the full instructions on the ",(0,o.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-gn"},"electron documentation")," for your specific OS."))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1d5c4879.081fb8a6.js b/assets/js/1d5c4879.8aa00a3e.js similarity index 99% rename from assets/js/1d5c4879.081fb8a6.js rename to assets/js/1d5c4879.8aa00a3e.js index 10f27a16..4a2cf644 100644 --- a/assets/js/1d5c4879.081fb8a6.js +++ b/assets/js/1d5c4879.8aa00a3e.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[2980],{3905:(e,t,n)=>{n.d(t,{Zo:()=>u,kt:()=>h});var r=n(7294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function a(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var p=r.createContext({}),c=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},u=function(e){var t=c(e.components);return r.createElement(p.Provider,{value:t},e.children)},d="mdxType",s={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},m=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,p=e.parentName,u=l(e,["components","mdxType","originalType","parentName"]),d=c(n),m=o,h=d["".concat(p,".").concat(m)]||d[m]||s[m]||i;return n?r.createElement(h,a(a({ref:t},u),{},{components:n})):r.createElement(h,a({ref:t},u))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,a=new Array(i);a[0]=m;var l={};for(var p in t)hasOwnProperty.call(t,p)&&(l[p]=t[p]);l.originalType=e,l[d]="string"==typeof e?e:o,a[1]=l;for(var c=2;c{n.r(t),n.d(t,{assets:()=>p,contentTitle:()=>a,default:()=>s,frontMatter:()=>i,metadata:()=>l,toc:()=>c});var r=n(7462),o=(n(7294),n(3905));const i={id:"npm_scripts",title:"NPM Scripts"},a=void 0,l={unversionedId:"npm_scripts",id:"version-3.0.0/npm_scripts",title:"NPM Scripts",description:"In the project directory, you can run:",source:"@site/versioned_docs/version-3.0.0/npm_scripts.md",sourceDirName:".",slug:"/npm_scripts",permalink:"/honeycomb-docs/docs/3.0.0/npm_scripts",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.0.0/npm_scripts.md",tags:[],version:"3.0.0",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"npm_scripts",title:"NPM Scripts"},sidebar:"someSidebar",previous:{title:"Troubleshooting",permalink:"/honeycomb-docs/docs/3.0.0/troubleshooting"},next:{title:"Setup Details",permalink:"/honeycomb-docs/docs/3.0.0/setup_details"}},p={},c=[{value:"npm run dev",id:"npm-run-dev",level:3},{value:"npm start",id:"npm-start",level:3},{value:"npm test",id:"npm-test",level:3},{value:"npm build",id:"npm-build",level:3},{value:"npm run package:platform",id:"npm-run-packageplatform",level:3},{value:"npm run eject",id:"npm-run-eject",level:3},{value:"Run Electron",id:"run-electron",level:3},{value:"npm run electron",id:"npm-run-electron",level:4},{value:"npm run electron-dev",id:"npm-run-electron-dev",level:4}],u={toc:c},d="wrapper";function s(e){let{components:t,...n}=e;return(0,o.kt)(d,(0,r.Z)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"In the project directory, you can run:"),(0,o.kt)("h3",{id:"npm-run-dev"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm run dev")),(0,o.kt)("p",null,"Runs ",(0,o.kt)("inlineCode",{parentName:"p"},"npm start")," and ",(0,o.kt)("inlineCode",{parentName:"p"},"npm run electron-dev")," concurrently. This may not play nicely with windows. If it doesn't, run ",(0,o.kt)("inlineCode",{parentName:"p"},"npm start")," and ",(0,o.kt)("inlineCode",{parentName:"p"},"npm run electron-dev")," from different terminal windows."),(0,o.kt)("h3",{id:"npm-start"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm start")),(0,o.kt)("p",null,"Runs the app in the development mode."),(0,o.kt)("p",null,"Open ",(0,o.kt)("a",{parentName:"p",href:"http://localhost:3000"},"http://localhost:3000")," to view it in the browser."),(0,o.kt)("p",null,"The page will reload if you make edits."),(0,o.kt)("p",null,"You will also see any lint errors in the console."),(0,o.kt)("h3",{id:"npm-test"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm test")),(0,o.kt)("p",null,"Launches the test runner in the interactive watch mode."),(0,o.kt)("p",null,"See the section about ",(0,o.kt)("a",{parentName:"p",href:"https://facebook.github.io/create-react-app/docs/running-tests"},"running tests")," for more information."),(0,o.kt)("h3",{id:"npm-build"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm build")),(0,o.kt)("p",null,"Creates a production build of the app (renderer). This must be done before running ",(0,o.kt)("inlineCode",{parentName:"p"},"package:platform")," or the psiturk build instructions."),(0,o.kt)("h3",{id:"npm-run-packageplatform"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm run package:platform")),(0,o.kt)("p",null,"Uses Electron to build the app and create a standalone installer for the given platform. Supported platforms are:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"npm run package:windows")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"npm run package:linux")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"npm run package:mac"))),(0,o.kt)("p",null,"The output can be found in the ",(0,o.kt)("inlineCode",{parentName:"p"},"./out")," subfolder."),(0,o.kt)("p",null,"Note: Packaging for windows on a non-windows machine requires ",(0,o.kt)("inlineCode",{parentName:"p"},"mono")," and ",(0,o.kt)("inlineCode",{parentName:"p"},"wine")," to be installed."),(0,o.kt)("h3",{id:"npm-run-eject"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm run eject")),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"Note: this is a one-way operation. Once you ",(0,o.kt)("inlineCode",{parentName:"strong"},"eject"),", you can\u2019t go back!")),(0,o.kt)("p",null,"If you aren\u2019t satisfied with the build tool and configuration choices, you can ",(0,o.kt)("inlineCode",{parentName:"p"},"eject")," at any time. This command will remove the single build dependency from your project."),(0,o.kt)("p",null,"Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except ",(0,o.kt)("inlineCode",{parentName:"p"},"eject")," will still work, but they will point to the copied scripts so you can tweak them. At this point you\u2019re on your own."),(0,o.kt)("p",null,"You don\u2019t have to ever use ",(0,o.kt)("inlineCode",{parentName:"p"},"eject"),". The curated feature set is suitable for small and middle deployments, and you shouldn\u2019t feel obligated to use this feature. However we understand that this tool wouldn\u2019t be useful if you couldn\u2019t customize it when you are ready for it."),(0,o.kt)("h3",{id:"run-electron"},"Run Electron"),(0,o.kt)("h4",{id:"npm-run-electron"},(0,o.kt)("inlineCode",{parentName:"h4"},"npm run electron")),(0,o.kt)("p",null,"Run the built app."),(0,o.kt)("h4",{id:"npm-run-electron-dev"},(0,o.kt)("inlineCode",{parentName:"h4"},"npm run electron-dev")),(0,o.kt)("p",null,"Run the current state of the code (un-built)."))}s.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[2980],{3905:(e,t,n)=>{n.d(t,{Zo:()=>u,kt:()=>h});var r=n(7294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function a(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var p=r.createContext({}),c=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},u=function(e){var t=c(e.components);return r.createElement(p.Provider,{value:t},e.children)},d="mdxType",s={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},m=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,p=e.parentName,u=l(e,["components","mdxType","originalType","parentName"]),d=c(n),m=o,h=d["".concat(p,".").concat(m)]||d[m]||s[m]||i;return n?r.createElement(h,a(a({ref:t},u),{},{components:n})):r.createElement(h,a({ref:t},u))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,a=new Array(i);a[0]=m;var l={};for(var p in t)hasOwnProperty.call(t,p)&&(l[p]=t[p]);l.originalType=e,l[d]="string"==typeof e?e:o,a[1]=l;for(var c=2;c{n.r(t),n.d(t,{assets:()=>p,contentTitle:()=>a,default:()=>s,frontMatter:()=>i,metadata:()=>l,toc:()=>c});var r=n(7462),o=(n(7294),n(3905));const i={id:"npm_scripts",title:"NPM Scripts"},a=void 0,l={unversionedId:"npm_scripts",id:"version-3.0.0/npm_scripts",title:"NPM Scripts",description:"In the project directory, you can run:",source:"@site/versioned_docs/version-3.0.0/npm_scripts.md",sourceDirName:".",slug:"/npm_scripts",permalink:"/honeycomb-docs/docs/3.0.0/npm_scripts",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.0.0/npm_scripts.md",tags:[],version:"3.0.0",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"npm_scripts",title:"NPM Scripts"},sidebar:"someSidebar",previous:{title:"Troubleshooting",permalink:"/honeycomb-docs/docs/3.0.0/troubleshooting"},next:{title:"Setup Details",permalink:"/honeycomb-docs/docs/3.0.0/setup_details"}},p={},c=[{value:"npm run dev",id:"npm-run-dev",level:3},{value:"npm start",id:"npm-start",level:3},{value:"npm test",id:"npm-test",level:3},{value:"npm build",id:"npm-build",level:3},{value:"npm run package:platform",id:"npm-run-packageplatform",level:3},{value:"npm run eject",id:"npm-run-eject",level:3},{value:"Run Electron",id:"run-electron",level:3},{value:"npm run electron",id:"npm-run-electron",level:4},{value:"npm run electron-dev",id:"npm-run-electron-dev",level:4}],u={toc:c},d="wrapper";function s(e){let{components:t,...n}=e;return(0,o.kt)(d,(0,r.Z)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"In the project directory, you can run:"),(0,o.kt)("h3",{id:"npm-run-dev"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm run dev")),(0,o.kt)("p",null,"Runs ",(0,o.kt)("inlineCode",{parentName:"p"},"npm start")," and ",(0,o.kt)("inlineCode",{parentName:"p"},"npm run electron-dev")," concurrently. This may not play nicely with windows. If it doesn't, run ",(0,o.kt)("inlineCode",{parentName:"p"},"npm start")," and ",(0,o.kt)("inlineCode",{parentName:"p"},"npm run electron-dev")," from different terminal windows."),(0,o.kt)("h3",{id:"npm-start"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm start")),(0,o.kt)("p",null,"Runs the app in the development mode."),(0,o.kt)("p",null,"Open ",(0,o.kt)("a",{parentName:"p",href:"http://localhost:3000"},"http://localhost:3000")," to view it in the browser."),(0,o.kt)("p",null,"The page will reload if you make edits."),(0,o.kt)("p",null,"You will also see any lint errors in the console."),(0,o.kt)("h3",{id:"npm-test"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm test")),(0,o.kt)("p",null,"Launches the test runner in the interactive watch mode."),(0,o.kt)("p",null,"See the section about ",(0,o.kt)("a",{parentName:"p",href:"https://facebook.github.io/create-react-app/docs/running-tests"},"running tests")," for more information."),(0,o.kt)("h3",{id:"npm-build"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm build")),(0,o.kt)("p",null,"Creates a production build of the app (renderer). This must be done before running ",(0,o.kt)("inlineCode",{parentName:"p"},"package:platform")," or the psiturk build instructions."),(0,o.kt)("h3",{id:"npm-run-packageplatform"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm run package:platform")),(0,o.kt)("p",null,"Uses Electron to build the app and create a standalone installer for the given platform. Supported platforms are:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"npm run package:windows")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"npm run package:linux")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("inlineCode",{parentName:"li"},"npm run package:mac"))),(0,o.kt)("p",null,"The output can be found in the ",(0,o.kt)("inlineCode",{parentName:"p"},"./out")," subfolder."),(0,o.kt)("p",null,"Note: Packaging for windows on a non-windows machine requires ",(0,o.kt)("inlineCode",{parentName:"p"},"mono")," and ",(0,o.kt)("inlineCode",{parentName:"p"},"wine")," to be installed."),(0,o.kt)("h3",{id:"npm-run-eject"},(0,o.kt)("inlineCode",{parentName:"h3"},"npm run eject")),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"Note: this is a one-way operation. Once you ",(0,o.kt)("inlineCode",{parentName:"strong"},"eject"),", you can\u2019t go back!")),(0,o.kt)("p",null,"If you aren\u2019t satisfied with the build tool and configuration choices, you can ",(0,o.kt)("inlineCode",{parentName:"p"},"eject")," at any time. This command will remove the single build dependency from your project."),(0,o.kt)("p",null,"Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except ",(0,o.kt)("inlineCode",{parentName:"p"},"eject")," will still work, but they will point to the copied scripts so you can tweak them. At this point you\u2019re on your own."),(0,o.kt)("p",null,"You don\u2019t have to ever use ",(0,o.kt)("inlineCode",{parentName:"p"},"eject"),". The curated feature set is suitable for small and middle deployments, and you shouldn\u2019t feel obligated to use this feature. However we understand that this tool wouldn\u2019t be useful if you couldn\u2019t customize it when you are ready for it."),(0,o.kt)("h3",{id:"run-electron"},"Run Electron"),(0,o.kt)("h4",{id:"npm-run-electron"},(0,o.kt)("inlineCode",{parentName:"h4"},"npm run electron")),(0,o.kt)("p",null,"Run the built app."),(0,o.kt)("h4",{id:"npm-run-electron-dev"},(0,o.kt)("inlineCode",{parentName:"h4"},"npm run electron-dev")),(0,o.kt)("p",null,"Run the current state of the code (un-built)."))}s.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/26eac671.815c7f66.js b/assets/js/26eac671.ae5d5f88.js similarity index 98% rename from assets/js/26eac671.815c7f66.js rename to assets/js/26eac671.ae5d5f88.js index 36629699..add9ed07 100644 --- a/assets/js/26eac671.815c7f66.js +++ b/assets/js/26eac671.ae5d5f88.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[8271],{3905:(e,t,r)=>{r.d(t,{Zo:()=>c,kt:()=>m});var n=r(7294);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,n)}return r}function i(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var p=n.createContext({}),u=function(e){var t=n.useContext(p),r=t;return e&&(r="function"==typeof e?e(t):i(i({},t),e)),r},c=function(e){var t=u(e.components);return n.createElement(p.Provider,{value:t},e.children)},l="mdxType",g={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},d=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,a=e.originalType,p=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),l=u(r),d=o,m=l["".concat(p,".").concat(d)]||l[d]||g[d]||a;return r?n.createElement(m,i(i({ref:t},c),{},{components:r})):n.createElement(m,i({ref:t},c))}));function m(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=d;var s={};for(var p in t)hasOwnProperty.call(t,p)&&(s[p]=t[p]);s.originalType=e,s[l]="string"==typeof e?e:o,i[1]=s;for(var u=2;u{r.r(t),r.d(t,{assets:()=>p,contentTitle:()=>i,default:()=>g,frontMatter:()=>a,metadata:()=>s,toc:()=>u});var n=r(7462),o=(r(7294),r(3905));const a={id:"gh_pages",slug:"/gh_pages",title:"GitHub Pages",description:"Guide for deploying a task to GitHub Pages"},i=void 0,s={unversionedId:"deployments/gh_pages",id:"deployments/gh_pages",title:"GitHub Pages",description:"Guide for deploying a task to GitHub Pages",source:"@site/docs/deployments/gh_pages.mdx",sourceDirName:"deployments",slug:"/gh_pages",permalink:"/honeycomb-docs/docs/gh_pages",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/docs/deployments/gh_pages.mdx",tags:[],version:"current",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"gh_pages",slug:"/gh_pages",title:"GitHub Pages",description:"Guide for deploying a task to GitHub Pages"},sidebar:"mySidebar",previous:{title:"PsiTurk",permalink:"/honeycomb-docs/docs/psiturk"},next:{title:"Event Triggers",permalink:"/honeycomb-docs/docs/event_triggers"}},p={},u=[{value:"Setup",id:"setup",level:3}],c={toc:u},l="wrapper";function g(e){let{components:t,...r}=e;return(0,o.kt)(l,(0,n.Z)({},c,r,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"The ",(0,o.kt)("inlineCode",{parentName:"p"},".github/workflows/release.yml")," workflow will automatically deploy your task to GitHub pages if you have it enabled for your repository. It uploads the built website to the ",(0,o.kt)("inlineCode",{parentName:"p"},"gh-pages")," branch. You can then access your task at ",(0,o.kt)("inlineCode",{parentName:"p"},".github.io/"),"."),(0,o.kt)("admonition",{type:"danger"},(0,o.kt)("p",{parentName:"admonition"},"Session data is downloaded to the user's local machine upon completion of the experiment when using GH Pages. Because of this, GH Pages is not suitable for fully online experiments.")),(0,o.kt)("h3",{id:"setup"},"Setup"),(0,o.kt)("p",null,"Please follow the ",(0,o.kt)("a",{parentName:"p",href:"https://docs.github.com/en/pages/quickstart"},"GitHub documentation")," for setting up GH Pages on your repository and make sure the ",(0,o.kt)("a",{parentName:"p",href:"https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site"},"publishing source")," for your repository is configured for ",(0,o.kt)("inlineCode",{parentName:"p"},"gh-pages")," branch."))}g.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[8271],{3905:(e,t,r)=>{r.d(t,{Zo:()=>c,kt:()=>m});var n=r(7294);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,n)}return r}function i(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var p=n.createContext({}),u=function(e){var t=n.useContext(p),r=t;return e&&(r="function"==typeof e?e(t):i(i({},t),e)),r},c=function(e){var t=u(e.components);return n.createElement(p.Provider,{value:t},e.children)},l="mdxType",g={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},d=n.forwardRef((function(e,t){var r=e.components,o=e.mdxType,a=e.originalType,p=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),l=u(r),d=o,m=l["".concat(p,".").concat(d)]||l[d]||g[d]||a;return r?n.createElement(m,i(i({ref:t},c),{},{components:r})):n.createElement(m,i({ref:t},c))}));function m(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=r.length,i=new Array(a);i[0]=d;var s={};for(var p in t)hasOwnProperty.call(t,p)&&(s[p]=t[p]);s.originalType=e,s[l]="string"==typeof e?e:o,i[1]=s;for(var u=2;u{r.r(t),r.d(t,{assets:()=>p,contentTitle:()=>i,default:()=>g,frontMatter:()=>a,metadata:()=>s,toc:()=>u});var n=r(7462),o=(r(7294),r(3905));const a={id:"gh_pages",slug:"/gh_pages",title:"GitHub Pages",description:"Guide for deploying a task to GitHub Pages"},i=void 0,s={unversionedId:"deployments/gh_pages",id:"deployments/gh_pages",title:"GitHub Pages",description:"Guide for deploying a task to GitHub Pages",source:"@site/docs/deployments/gh_pages.mdx",sourceDirName:"deployments",slug:"/gh_pages",permalink:"/honeycomb-docs/docs/gh_pages",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/docs/deployments/gh_pages.mdx",tags:[],version:"current",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"gh_pages",slug:"/gh_pages",title:"GitHub Pages",description:"Guide for deploying a task to GitHub Pages"},sidebar:"mySidebar",previous:{title:"PsiTurk",permalink:"/honeycomb-docs/docs/psiturk"},next:{title:"Event Triggers",permalink:"/honeycomb-docs/docs/event_triggers"}},p={},u=[{value:"Setup",id:"setup",level:3}],c={toc:u},l="wrapper";function g(e){let{components:t,...r}=e;return(0,o.kt)(l,(0,n.Z)({},c,r,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"The ",(0,o.kt)("inlineCode",{parentName:"p"},".github/workflows/release.yml")," workflow will automatically deploy your task to GitHub pages if you have it enabled for your repository. It uploads the built website to the ",(0,o.kt)("inlineCode",{parentName:"p"},"gh-pages")," branch. You can then access your task at ",(0,o.kt)("inlineCode",{parentName:"p"},".github.io/"),"."),(0,o.kt)("admonition",{type:"danger"},(0,o.kt)("p",{parentName:"admonition"},"Session data is downloaded to the user's local machine upon completion of the experiment when using GH Pages. Because of this, GH Pages is not suitable for fully online experiments.")),(0,o.kt)("h3",{id:"setup"},"Setup"),(0,o.kt)("p",null,"Please follow the ",(0,o.kt)("a",{parentName:"p",href:"https://docs.github.com/en/pages/quickstart"},"GitHub documentation")," for setting up GH Pages on your repository and make sure the ",(0,o.kt)("a",{parentName:"p",href:"https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site"},"publishing source")," for your repository is configured for ",(0,o.kt)("inlineCode",{parentName:"p"},"gh-pages")," branch."))}g.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2e3bbbfb.fec2812f.js b/assets/js/2e3bbbfb.6c534b09.js similarity index 98% rename from assets/js/2e3bbbfb.fec2812f.js rename to assets/js/2e3bbbfb.6c534b09.js index 323951ff..4426958e 100644 --- a/assets/js/2e3bbbfb.fec2812f.js +++ b/assets/js/2e3bbbfb.6c534b09.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[5327],{3905:(e,t,n)=>{n.d(t,{Zo:()=>d,kt:()=>m});var o=n(7294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,o)}return n}function a(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var s=o.createContext({}),l=function(e){var t=o.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},d=function(e){var t=l(e.components);return o.createElement(s.Provider,{value:t},e.children)},u="mdxType",p={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},y=o.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,s=e.parentName,d=c(e,["components","mdxType","originalType","parentName"]),u=l(n),y=r,m=u["".concat(s,".").concat(y)]||u[y]||p[y]||i;return n?o.createElement(m,a(a({ref:t},d),{},{components:n})):o.createElement(m,a({ref:t},d))}));function m(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,a=new Array(i);a[0]=y;var c={};for(var s in t)hasOwnProperty.call(t,s)&&(c[s]=t[s]);c.originalType=e,c[u]="string"==typeof e?e:r,a[1]=c;for(var l=2;l{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>a,default:()=>p,frontMatter:()=>i,metadata:()=>c,toc:()=>l});var o=n(7462),r=(n(7294),n(3905));const i={id:"introduction",slug:"/",title:"Introduction",description:"Basic introduction to Honeycomb"},a=void 0,c={unversionedId:"introduction",id:"version-3.1.x/introduction",title:"Introduction",description:"Basic introduction to Honeycomb",source:"@site/versioned_docs/version-3.1.x/introduction.mdx",sourceDirName:".",slug:"/",permalink:"/honeycomb-docs/docs/3.1.x/",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/introduction.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"introduction",slug:"/",title:"Introduction",description:"Basic introduction to Honeycomb"},sidebar:"mySidebar",next:{title:"Quick Start",permalink:"/honeycomb-docs/docs/3.1.x/quick_start"}},s={},l=[{value:"Flexible deployment online and in the lab",id:"flexible-deployment-online-and-in-the-lab",level:3},{value:"Easy-to-install executables",id:"easy-to-install-executables",level:3},{value:"Foundation in jsPsych",id:"foundation-in-jspsych",level:3},{value:"Cite this work",id:"cite-this-work",level:3}],d={toc:l},u="wrapper";function p(e){let{components:t,...n}=e;return(0,r.kt)(u,(0,o.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"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."),(0,r.kt)("h3",{id:"flexible-deployment-online-and-in-the-lab"},"Flexible deployment online and in the lab"),(0,r.kt)("p",null,"Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings."),(0,r.kt)("h3",{id:"easy-to-install-executables"},"Easy-to-install executables"),(0,r.kt)("p",null,"Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites."),(0,r.kt)("h3",{id:"foundation-in-jspsych"},"Foundation in jsPsych"),(0,r.kt)("p",null,"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."),(0,r.kt)("h3",{id:"cite-this-work"},"Cite this work"),(0,r.kt)("p",null,"If you use Honeycomb in your work, please cite"),(0,r.kt)("p",null,(0,r.kt)("a",{parentName:"p",href:"https://doi.org/10.1590/1516-4446-2020-1675"},"Provenza, N.R., Gelin, L.F.F., Mahaphanit, W., McGrath, M.C., Dastin-van Rijn, E.M., Fan, Y., Dhar, R., Frank, M.J., Restrepo, M.I., Goodman, W.K. and Borton, D.A., 2021. Honeycomb: a template for reproducible psychophysiological tasks for clinic, laboratory, and home use. Brazilian Journal of Psychiatry, 44, pp.147-155.")))}p.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[5327],{3905:(e,t,n)=>{n.d(t,{Zo:()=>d,kt:()=>m});var o=n(7294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,o)}return n}function a(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var s=o.createContext({}),l=function(e){var t=o.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},d=function(e){var t=l(e.components);return o.createElement(s.Provider,{value:t},e.children)},u="mdxType",p={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},y=o.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,s=e.parentName,d=c(e,["components","mdxType","originalType","parentName"]),u=l(n),y=r,m=u["".concat(s,".").concat(y)]||u[y]||p[y]||i;return n?o.createElement(m,a(a({ref:t},d),{},{components:n})):o.createElement(m,a({ref:t},d))}));function m(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,a=new Array(i);a[0]=y;var c={};for(var s in t)hasOwnProperty.call(t,s)&&(c[s]=t[s]);c.originalType=e,c[u]="string"==typeof e?e:r,a[1]=c;for(var l=2;l{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>a,default:()=>p,frontMatter:()=>i,metadata:()=>c,toc:()=>l});var o=n(7462),r=(n(7294),n(3905));const i={id:"introduction",slug:"/",title:"Introduction",description:"Basic introduction to Honeycomb"},a=void 0,c={unversionedId:"introduction",id:"version-3.1.x/introduction",title:"Introduction",description:"Basic introduction to Honeycomb",source:"@site/versioned_docs/version-3.1.x/introduction.mdx",sourceDirName:".",slug:"/",permalink:"/honeycomb-docs/docs/3.1.x/",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/introduction.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"introduction",slug:"/",title:"Introduction",description:"Basic introduction to Honeycomb"},sidebar:"mySidebar",next:{title:"Quick Start",permalink:"/honeycomb-docs/docs/3.1.x/quick_start"}},s={},l=[{value:"Flexible deployment online and in the lab",id:"flexible-deployment-online-and-in-the-lab",level:3},{value:"Easy-to-install executables",id:"easy-to-install-executables",level:3},{value:"Foundation in jsPsych",id:"foundation-in-jspsych",level:3},{value:"Cite this work",id:"cite-this-work",level:3}],d={toc:l},u="wrapper";function p(e){let{components:t,...n}=e;return(0,r.kt)(u,(0,o.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"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."),(0,r.kt)("h3",{id:"flexible-deployment-online-and-in-the-lab"},"Flexible deployment online and in the lab"),(0,r.kt)("p",null,"Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings."),(0,r.kt)("h3",{id:"easy-to-install-executables"},"Easy-to-install executables"),(0,r.kt)("p",null,"Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites."),(0,r.kt)("h3",{id:"foundation-in-jspsych"},"Foundation in jsPsych"),(0,r.kt)("p",null,"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."),(0,r.kt)("h3",{id:"cite-this-work"},"Cite this work"),(0,r.kt)("p",null,"If you use Honeycomb in your work, please cite"),(0,r.kt)("p",null,(0,r.kt)("a",{parentName:"p",href:"https://doi.org/10.1590/1516-4446-2020-1675"},"Provenza, N.R., Gelin, L.F.F., Mahaphanit, W., McGrath, M.C., Dastin-van Rijn, E.M., Fan, Y., Dhar, R., Frank, M.J., Restrepo, M.I., Goodman, W.K. and Borton, D.A., 2021. Honeycomb: a template for reproducible psychophysiological tasks for clinic, laboratory, and home use. Brazilian Journal of Psychiatry, 44, pp.147-155.")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2e7e1f7d.5a229109.js b/assets/js/2e7e1f7d.d09346a0.js similarity index 99% rename from assets/js/2e7e1f7d.5a229109.js rename to assets/js/2e7e1f7d.d09346a0.js index bd895317..0fd84113 100644 --- a/assets/js/2e7e1f7d.5a229109.js +++ b/assets/js/2e7e1f7d.d09346a0.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[1356],{3905:(e,t,a)=>{a.d(t,{Zo:()=>c,kt:()=>h});var n=a(7294);function i(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function o(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function r(e){for(var t=1;t=0||(i[a]=e[a]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(i[a]=e[a])}return i}var l=n.createContext({}),p=function(e){var t=n.useContext(l),a=t;return e&&(a="function"==typeof e?e(t):r(r({},t),e)),a},c=function(e){var t=p(e.components);return n.createElement(l.Provider,{value:t},e.children)},d="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef((function(e,t){var a=e.components,i=e.mdxType,o=e.originalType,l=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),d=p(a),m=i,h=d["".concat(l,".").concat(m)]||d[m]||u[m]||o;return a?n.createElement(h,r(r({ref:t},c),{},{components:a})):n.createElement(h,r({ref:t},c))}));function h(e,t){var a=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=a.length,r=new Array(o);r[0]=m;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[d]="string"==typeof e?e:i,r[1]=s;for(var p=2;p{a.r(t),a.d(t,{assets:()=>m,contentTitle:()=>d,default:()=>k,frontMatter:()=>c,metadata:()=>u,toc:()=>h});var n=a(7462),i=(a(7294),a(3905));const o=a.p+"assets/images/firebase-console-settings-0a6f9d645eb45de659a7b4b784467625.png",r=a.p+"assets/images/firebase-web-credentials-84e8e702bcf227614ec4ebb3641f58f9.png",s=a.p+"assets/images/firestore-create-study-1e75d836c67200b199878dcf4772fe50.png",l=a.p+"assets/images/firestore-example-study-8c600c7203ca68515ab663645af36874.png",p=a.p+"assets/images/firebase-actions-e13d5d73602640c80b12e924ea7843b6.png",c={id:"firebase",slug:"/firebase",title:"Firebase",description:"Guide for connecting Honeycomb to a Firebase project"},d=void 0,u={unversionedId:"firebase",id:"version-3.1.x/firebase",title:"Firebase",description:"Guide for connecting Honeycomb to a Firebase project",source:"@site/versioned_docs/version-3.1.x/firebase.mdx",sourceDirName:".",slug:"/firebase",permalink:"/honeycomb-docs/docs/3.1.x/firebase",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/firebase.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"firebase",slug:"/firebase",title:"Firebase",description:"Guide for connecting Honeycomb to a Firebase project"},sidebar:"mySidebar",previous:{title:"Set up event triggers",permalink:"/honeycomb-docs/docs/3.1.x/event_triggers"},next:{title:"Deploy online",permalink:"/honeycomb-docs/docs/3.1.x/deploy_online"}},m={},h=[{value:"Setting up Firebase",id:"setting-up-firebase",level:2},{value:"Adding Products",id:"adding-products",level:3},{value:"Installing the Command Line Interface",id:"installing-the-command-line-interface",level:3},{value:"Connecting Your Firebase Project",id:"connecting-your-firebase-project",level:3},{value:"Registering Studies",id:"registering-studies",level:2},{value:"Developing With Firebase",id:"developing-with-firebase",level:2},{value:"Deploying on Firebase",id:"deploying-on-firebase",level:2},{value:"Downloading Data",id:"downloading-data",level:2},{value:"Setting up a Service Account",id:"setting-up-a-service-account",level:3},{value:"Using the Download Script",id:"using-the-download-script",level:3},{value:"sessionNumber",id:"sessionnumber",level:4},{value:"outputRoot",id:"outputroot",level:4},{value:"Further Reading",id:"further-reading",level:2},{value:"Security Rules",id:"security-rules",level:3}],g={toc:h},b="wrapper";function k(e){let{components:t,...a}=e;return(0,i.kt)(b,(0,n.Z)({},g,a,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"Honeycomb comes with methods and configurations to deploy tasks with ",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/"},"Firebase"),". These tools make it possible to reach a wider audience by hosting your task online."),(0,i.kt)("h2",{id:"setting-up-firebase"},"Setting up Firebase"),(0,i.kt)("admonition",{type:"info"},(0,i.kt)("p",{parentName:"admonition"},"Please have your PI contact ",(0,i.kt)("a",{parentName:"p",href:"mailto:support@ccv.brown.edu"},"support@ccv.brown.edu")," to create a Firebase project for your Honeycomb task before beginning.")),(0,i.kt)("h3",{id:"adding-products"},"Adding Products"),(0,i.kt)("p",null,"First we'll configure ",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/hosting"},"Firebase Hosting")," and ",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/firestore"},"Cloud Firestore")," on your project."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Log in to Firebase with your Google account on the ",(0,i.kt)("a",{parentName:"p",href:"https://console.firebase.google.com/"},"Firebase console"),".")),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Navigate to your project from the console")),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Register a new web app to your project (",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/web/setup#register-app"},"Register your app"),")"),(0,i.kt)("admonition",{parentName:"li",type:"note"},(0,i.kt)("p",{parentName:"admonition"},"We recommend giving your web app the same name as your task's repository"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Add Firestore Database to your project (",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/firestore/quickstart#create"},"Create a Cloud Firestore database"),")"),(0,i.kt)("admonition",{parentName:"li",type:"note"},(0,i.kt)("p",{parentName:"admonition"},"Chose ",(0,i.kt)("inlineCode",{parentName:"p"},"production mode"),' for the starting mode and the default "Cloud Firestore Location"')))),(0,i.kt)("p",null,"The Firebase project is now fully set up! Now we'll connect your task to that project from your computer."),(0,i.kt)("h3",{id:"installing-the-command-line-interface"},"Installing the Command Line Interface"),(0,i.kt)("p",null,"The Firebase CLI can be 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!"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Install the Firebase CLI"',title:'"Install',the:!0,Firebase:!0,'CLI"':!0},"npm install -g firebase-tools\n")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Login to Firebase"',title:'"Login',to:!0,'Firebase"':!0},"firebase login\n")),(0,i.kt)("p",null,(0,i.kt)("em",{parentName:"p"},'A "command not found" error usually indicates ',(0,i.kt)("inlineCode",{parentName:"em"},"firebase-tools")," has not been installed correctly")),(0,i.kt)("h3",{id:"connecting-your-firebase-project"},"Connecting Your Firebase Project"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Change the default project name of your task in ",(0,i.kt)("inlineCode",{parentName:"li"},".firebaserc"))),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-json",metastring:'title=".firebaserc" showLineNumbers',title:'".firebaserc"',showLineNumbers:!0},'{\n "projects": {\n "default": ""\n }\n}\n')),(0,i.kt)("ol",{start:2},(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Copy the web app credentials from the Firebase console to the corresponding variables in ",(0,i.kt)("inlineCode",{parentName:"p"},".env.firebase")),(0,i.kt)("ol",{parentName:"li"},(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Return to your project on the ",(0,i.kt)("a",{parentName:"p",href:"https://console.firebase.google.com/"},"Firebase console"),".")),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Navigate to your project setting"),(0,i.kt)("img",{src:o,alt:"Firebase project settings"})),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Scroll down and copy the auto-generated values from the Firebase console to the corresponding variables in the ",(0,i.kt)("inlineCode",{parentName:"p"},".env.firebase")," file in the ",(0,i.kt)("inlineCode",{parentName:"p"},"env")," folder of your Honeycomb task repo"),(0,i.kt)("img",{src:r,alt:"Firebase web credentials"}),(0,i.kt)("br",null),(0,i.kt)("br",null),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="env/.env.firebase"',title:'"env/.env.firebase"'},'REACT_APP_FIREBASE="true"\nREACT_APP_apiKey=\nREACT_APP_authDomain=\nREACT_APP_projectId=\nREACT_APP_storageBucket=\nREACT_APP_messagingSenderId=\nREACT_APP_appId=\n')),(0,i.kt)("p",{parentName:"li"},(0,i.kt)("em",{parentName:"p"},"Additional variables may be present in the console, they do not need to be copied."))))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Deploy the default ",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/firestore/security/get-started"},"Firestore security rules")))),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Deploy Firestore rules"',title:'"Deploy',Firestore:!0,'rules"':!0},"firebase deploy --only firestore:rules\n")),(0,i.kt)("p",null,"Your task is now connected to an initialized Firebase project!"),(0,i.kt)("h2",{id:"registering-studies"},"Registering Studies"),(0,i.kt)("admonition",{type:"caution"},(0,i.kt)("p",{parentName:"admonition"},"This step must be followed ",(0,i.kt)("strong",{parentName:"p"},"exactly"),". See ",(0,i.kt)("a",{parentName:"p",href:"#security-rules"},"Security Rules")," for more information.")),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Navigate to your Firestore Database in the ",(0,i.kt)("a",{parentName:"li",href:"https://console.firebase.google.com/"},"console"),"."),(0,i.kt)("li",{parentName:"ol"},'Click "Start collection"'),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"registered_studies"),' for the collection id and click "next"'),(0,i.kt)("li",{parentName:"ol"},"Enter the id of your study for the document id"),(0,i.kt)("li",{parentName:"ol"},"Add a field named ",(0,i.kt)("inlineCode",{parentName:"li"},"registered_participants"),' with the type "array"'),(0,i.kt)("li",{parentName:"ol"},"Add the id of each study participant as a string inside the array")),(0,i.kt)("div",{style:{textAlign:"center"}},(0,i.kt)("img",{src:s,alt:"Create a study",style:{maxHeight:"600px"}})),(0,i.kt)("br",null),(0,i.kt)("p",null,"The study should like this when you're finished:"),(0,i.kt)("img",{src:l,alt:"Example study"}),(0,i.kt)("br",null),(0,i.kt)("br",null),(0,i.kt)("p",null,(0,i.kt)("strong",{parentName:"p"},"Additional studies must be created inside the ",(0,i.kt)("inlineCode",{parentName:"strong"},"registered_studies")," collection")),(0,i.kt)("h2",{id:"developing-with-firebase"},"Developing With Firebase"),(0,i.kt)("p",null,(0,i.kt)("em",{parentName:"p"},"Two terminal windows must be used while developing for Firebase. Instructions splitting terminals in VSCode can be found ",(0,i.kt)("a",{parentName:"em",href:"https://code.visualstudio.com/docs/terminal/basics#_groups-split-panes"},"here"),".")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Run Honeycomb with Firebase Enabled"',title:'"Run',Honeycomb:!0,with:!0,Firebase:!0,'Enabled"':!0},"npm run dev:firebase\n")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Start the Firebase Emulators"',title:'"Start',the:!0,Firebase:!0,'Emulators"':!0},"npm run firebase:emulators:start\n")),(0,i.kt)("p",null,"Honeycomb is now running in the browser and connected to data on an emulated instance of Firestore.\nThat data can be viewed at ",(0,i.kt)("a",{parentName:"p",href:"http://localhost:4000/firestore"},"http://localhost:4000/firestore"),"."),(0,i.kt)("admonition",{type:"info"},(0,i.kt)("p",{parentName:"admonition"},"Honeycomb populates the Firestore emulators with the study ",(0,i.kt)("inlineCode",{parentName:"p"},"s1")," and participant ",(0,i.kt)("inlineCode",{parentName:"p"},"p1"),".")),(0,i.kt)("h2",{id:"deploying-on-firebase"},"Deploying on Firebase"),(0,i.kt)("p",null,"Firebase deployments are handled automatically following ",(0,i.kt)("a",{parentName:"p",href:"ci"},"Continuous Integration Continuous Development")," practices using GitHub Actions. Here we will connect create custom actions that are connected to the task's Firebase project."),(0,i.kt)("p",null,"Execute the following command to begin initializing Firebase hosting via GitHub actions. Be sure to follow the instructions below as the prompts appear."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Initialize Firebase hosting via Github actions"',title:'"Initialize',Firebase:!0,hosting:!0,via:!0,Github:!0,'actions"':!0},"firebase init hosting:github\n")),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"The window should log you in automatically. If not, follow the prompts to log in with the same account you used in the console."),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"/")," refers to the name of your repository in Github. Be sure it's typed correctly!"),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"y"),' for the prompt "Set up the workflow to run a build script before every deploy?"'),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"npm install && npm run build:firebase"),' for the prompt "What script should be run before every deploy?"'),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"y")," to overwrite the current workflow file"),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"y"),' for the prompt "Set up automatic deployment to your site\'s live channel when a PR is merged?"'),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"main"),' for the prompt "What is the name of the GitHub branch associated with your site\'s live channel?"'),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"y")," to overwrite the current workflow file")),(0,i.kt)("p",null,"Firebase will update the files ",(0,i.kt)("inlineCode",{parentName:"p"},"firebase-hosting-pull-request.yml")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"firebase-hosting-merge.yml")," inside the ",(0,i.kt)("inlineCode",{parentName:"p"},".github/workflows/")," directory. Ensure the correct run script is present in both files."),(0,i.kt)("img",{src:p,alt:"Github actions created by firebase"}),(0,i.kt)("h2",{id:"downloading-data"},"Downloading Data"),(0,i.kt)("p",null,"Honeycomb ships with a script for downloading data from Firebase onto a computer. A local service account must be created in order to use it."),(0,i.kt)("h3",{id:"setting-up-a-service-account"},"Setting up a Service Account"),(0,i.kt)("p",null,"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."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Return to the project settings your project on the ",(0,i.kt)("a",{parentName:"p",href:"https://console.firebase.google.com/"},"Firebase console"),"."),(0,i.kt)("img",{src:o,alt:"Firebase project settings"})),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},'Click on the "Service accounts" tab')),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},'Near the bottom, click "Generate new Private key" and "Generate Key"')),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Rename the key ",(0,i.kt)("inlineCode",{parentName:"p"},"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!"))),(0,i.kt)("admonition",{type:"danger"},(0,i.kt)("p",{parentName:"admonition"},"A service account has total administrative access to ts Firebase project. The file and keys inside should never be shared and ",(0,i.kt)("strong",{parentName:"p"},"never committed to GitHub."))),(0,i.kt)("h3",{id:"using-the-download-script"},"Using the Download Script"),(0,i.kt)("p",null,"Honeycomb comes with a download script. It will programmatically access Firestore to download the experiment data you choose"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash",metastring:'title="Script Usage"',title:'"Script','Usage"':!0},"npm run firebase:download -- [sessionNumber] [outputRoot]\n")),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"studyID"),": The ID of a given study"),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"participantID"),": The ID of a given participant on the ",(0,i.kt)("inlineCode",{parentName:"li"},"studyID")," study"),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"sessionNumber"),": Optional number to select which session to download, defaults to the most recent session"),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"outputRoot"),": Optional path to the folder where data should be saved, defaults to the current folder")),(0,i.kt)("p",null,"Running the script without ",(0,i.kt)("inlineCode",{parentName:"p"},"sessionNumber")," list all of the available sessions. For example:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre"},"Found 3 sessions:\n 0: 2022-07-26T22:04:55.544Z\n 1: 2022-07-27T14:16:36.301Z\n 2: 2022-07-27T19:56:26.229Z\n")),(0,i.kt)("h4",{id:"sessionnumber"},"sessionNumber"),(0,i.kt)("p",null,"Adding a ",(0,i.kt)("inlineCode",{parentName:"p"},"sessionNumber")," will download that sessions data:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Download data for session 2022-07-26T22:04:55.544Z"',title:'"Download',data:!0,for:!0,session:!0,'2022-07-26T22:04:55.544Z"':!0},"npm run firebase:download -- 0 [outputRoot]\n")),(0,i.kt)("h4",{id:"outputroot"},"outputRoot"),(0,i.kt)("p",null,"Session data is stored in the current directory by default. The folders and file name are chosen to avoid naming collisions: ",(0,i.kt)("inlineCode",{parentName:"p"},"./participant_responses///.json")),(0,i.kt)("p",null,"Adding an ",(0,i.kt)("inlineCode",{parentName:"p"},"outputRoot")," will download that data in a custom location:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Download data for session 2022-07-26T22:04:55.544Z at /path/to/my/data"',title:'"Download',data:!0,for:!0,session:!0,"2022-07-26T22:04:55.544Z":!0,at:!0,'/path/to/my/data"':!0},"npm run firebase:download -- 0 /path/to/my/data\n")),(0,i.kt)("p",null,"This will result in data saved to ",(0,i.kt)("inlineCode",{parentName:"p"},"/path/to/my/data/participant_responses///.json")),(0,i.kt)("h2",{id:"further-reading"},"Further Reading"),(0,i.kt)("p",null,(0,i.kt)("em",{parentName:"p"},"The ",(0,i.kt)("a",{parentName:"em",href:"https://firebase.google.com/docs/emulator-suite"},"Firebase Documentation")," details its Emulator Suite in much greater detail.")),(0,i.kt)("h3",{id:"security-rules"},"Security Rules"),(0,i.kt)("p",null,"Honeycomb uses security rules to authenticate participants and studies for each task. By default participants must be registered to each study in order to complete the task."),(0,i.kt)("p",null,"Firestore rules are defined in the ",(0,i.kt)("inlineCode",{parentName:"p"},"firestore.rules")," file in the home directory. Note the highlighted lines:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-firestore-security-rules",metastring:'title="firestore.rules" showLineNumbers',title:'"firestore.rules"',showLineNumbers:!0},"rules_version = '2';\nservice cloud.firestore {\n //highlight-start\n match /databases/{database}/documents {\n match /participant_responses/{studyID}/participants/{participantID} {\n allow create, read:\n if participantID in get(/databases/$(database)/documents/registered_studies/$(studyID)).data.registered_participants;\n //highlight-end\n // ...\n }\n }\n}\n")),(0,i.kt)("p",null,"Lines 3 and 4 indicate that Honeycomb attempts to connect to a document at ",(0,i.kt)("inlineCode",{parentName:"p"},"/databases/{database}/documents/participant_responses/{studyID}/participants/{participantID}")," where ",(0,i.kt)("inlineCode",{parentName:"p"},"studyID")," is a given study and ",(0,i.kt)("inlineCode",{parentName:"p"},"participantID")," is a given participant within that study."),(0,i.kt)("p",null,"Line 6 defines our rule - it must pass for Honeycomb to connect to the document. ",(0,i.kt)("inlineCode",{parentName:"p"},"participantID")," must be found in an array called ",(0,i.kt)("inlineCode",{parentName:"p"},"registered_participants")," inside of a document at ",(0,i.kt)("inlineCode",{parentName:"p"},"/databases/{database}/documents/registered_studies/{studyID}"),"."),(0,i.kt)("p",null,"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."),(0,i.kt)("admonition",{type:"danger"},(0,i.kt)("p",{parentName:"admonition"},"Firestore rules must define every match pattern in your project. Attempting to connect anywhere other than ",(0,i.kt)("inlineCode",{parentName:"p"},"/participant_responses/{studyID}/participants/{participantID}")," will be automatically denied even if you add other collections to your database. This is why ",(0,i.kt)("inlineCode",{parentName:"p"},"firestore.rules")," contains additional nested rules - these should be left alone.")))}k.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[1356],{3905:(e,t,a)=>{a.d(t,{Zo:()=>c,kt:()=>h});var n=a(7294);function i(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function o(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function r(e){for(var t=1;t=0||(i[a]=e[a]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(i[a]=e[a])}return i}var l=n.createContext({}),p=function(e){var t=n.useContext(l),a=t;return e&&(a="function"==typeof e?e(t):r(r({},t),e)),a},c=function(e){var t=p(e.components);return n.createElement(l.Provider,{value:t},e.children)},d="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},m=n.forwardRef((function(e,t){var a=e.components,i=e.mdxType,o=e.originalType,l=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),d=p(a),m=i,h=d["".concat(l,".").concat(m)]||d[m]||u[m]||o;return a?n.createElement(h,r(r({ref:t},c),{},{components:a})):n.createElement(h,r({ref:t},c))}));function h(e,t){var a=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=a.length,r=new Array(o);r[0]=m;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[d]="string"==typeof e?e:i,r[1]=s;for(var p=2;p{a.r(t),a.d(t,{assets:()=>m,contentTitle:()=>d,default:()=>k,frontMatter:()=>c,metadata:()=>u,toc:()=>h});var n=a(7462),i=(a(7294),a(3905));const o=a.p+"assets/images/firebase-console-settings-0a6f9d645eb45de659a7b4b784467625.png",r=a.p+"assets/images/firebase-web-credentials-84e8e702bcf227614ec4ebb3641f58f9.png",s=a.p+"assets/images/firestore-create-study-1e75d836c67200b199878dcf4772fe50.png",l=a.p+"assets/images/firestore-example-study-8c600c7203ca68515ab663645af36874.png",p=a.p+"assets/images/firebase-actions-e13d5d73602640c80b12e924ea7843b6.png",c={id:"firebase",slug:"/firebase",title:"Firebase",description:"Guide for connecting Honeycomb to a Firebase project"},d=void 0,u={unversionedId:"firebase",id:"version-3.1.x/firebase",title:"Firebase",description:"Guide for connecting Honeycomb to a Firebase project",source:"@site/versioned_docs/version-3.1.x/firebase.mdx",sourceDirName:".",slug:"/firebase",permalink:"/honeycomb-docs/docs/3.1.x/firebase",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/firebase.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"firebase",slug:"/firebase",title:"Firebase",description:"Guide for connecting Honeycomb to a Firebase project"},sidebar:"mySidebar",previous:{title:"Set up event triggers",permalink:"/honeycomb-docs/docs/3.1.x/event_triggers"},next:{title:"Deploy online",permalink:"/honeycomb-docs/docs/3.1.x/deploy_online"}},m={},h=[{value:"Setting up Firebase",id:"setting-up-firebase",level:2},{value:"Adding Products",id:"adding-products",level:3},{value:"Installing the Command Line Interface",id:"installing-the-command-line-interface",level:3},{value:"Connecting Your Firebase Project",id:"connecting-your-firebase-project",level:3},{value:"Registering Studies",id:"registering-studies",level:2},{value:"Developing With Firebase",id:"developing-with-firebase",level:2},{value:"Deploying on Firebase",id:"deploying-on-firebase",level:2},{value:"Downloading Data",id:"downloading-data",level:2},{value:"Setting up a Service Account",id:"setting-up-a-service-account",level:3},{value:"Using the Download Script",id:"using-the-download-script",level:3},{value:"sessionNumber",id:"sessionnumber",level:4},{value:"outputRoot",id:"outputroot",level:4},{value:"Further Reading",id:"further-reading",level:2},{value:"Security Rules",id:"security-rules",level:3}],g={toc:h},b="wrapper";function k(e){let{components:t,...a}=e;return(0,i.kt)(b,(0,n.Z)({},g,a,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("p",null,"Honeycomb comes with methods and configurations to deploy tasks with ",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/"},"Firebase"),". These tools make it possible to reach a wider audience by hosting your task online."),(0,i.kt)("h2",{id:"setting-up-firebase"},"Setting up Firebase"),(0,i.kt)("admonition",{type:"info"},(0,i.kt)("p",{parentName:"admonition"},"Please have your PI contact ",(0,i.kt)("a",{parentName:"p",href:"mailto:support@ccv.brown.edu"},"support@ccv.brown.edu")," to create a Firebase project for your Honeycomb task before beginning.")),(0,i.kt)("h3",{id:"adding-products"},"Adding Products"),(0,i.kt)("p",null,"First we'll configure ",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/hosting"},"Firebase Hosting")," and ",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/firestore"},"Cloud Firestore")," on your project."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Log in to Firebase with your Google account on the ",(0,i.kt)("a",{parentName:"p",href:"https://console.firebase.google.com/"},"Firebase console"),".")),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Navigate to your project from the console")),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Register a new web app to your project (",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/web/setup#register-app"},"Register your app"),")"),(0,i.kt)("admonition",{parentName:"li",type:"note"},(0,i.kt)("p",{parentName:"admonition"},"We recommend giving your web app the same name as your task's repository"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Add Firestore Database to your project (",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/firestore/quickstart#create"},"Create a Cloud Firestore database"),")"),(0,i.kt)("admonition",{parentName:"li",type:"note"},(0,i.kt)("p",{parentName:"admonition"},"Chose ",(0,i.kt)("inlineCode",{parentName:"p"},"production mode"),' for the starting mode and the default "Cloud Firestore Location"')))),(0,i.kt)("p",null,"The Firebase project is now fully set up! Now we'll connect your task to that project from your computer."),(0,i.kt)("h3",{id:"installing-the-command-line-interface"},"Installing the Command Line Interface"),(0,i.kt)("p",null,"The Firebase CLI can be 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!"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Install the Firebase CLI"',title:'"Install',the:!0,Firebase:!0,'CLI"':!0},"npm install -g firebase-tools\n")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Login to Firebase"',title:'"Login',to:!0,'Firebase"':!0},"firebase login\n")),(0,i.kt)("p",null,(0,i.kt)("em",{parentName:"p"},'A "command not found" error usually indicates ',(0,i.kt)("inlineCode",{parentName:"em"},"firebase-tools")," has not been installed correctly")),(0,i.kt)("h3",{id:"connecting-your-firebase-project"},"Connecting Your Firebase Project"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Change the default project name of your task in ",(0,i.kt)("inlineCode",{parentName:"li"},".firebaserc"))),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-json",metastring:'title=".firebaserc" showLineNumbers',title:'".firebaserc"',showLineNumbers:!0},'{\n "projects": {\n "default": ""\n }\n}\n')),(0,i.kt)("ol",{start:2},(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Copy the web app credentials from the Firebase console to the corresponding variables in ",(0,i.kt)("inlineCode",{parentName:"p"},".env.firebase")),(0,i.kt)("ol",{parentName:"li"},(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Return to your project on the ",(0,i.kt)("a",{parentName:"p",href:"https://console.firebase.google.com/"},"Firebase console"),".")),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Navigate to your project setting"),(0,i.kt)("img",{src:o,alt:"Firebase project settings"})),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Scroll down and copy the auto-generated values from the Firebase console to the corresponding variables in the ",(0,i.kt)("inlineCode",{parentName:"p"},".env.firebase")," file in the ",(0,i.kt)("inlineCode",{parentName:"p"},"env")," folder of your Honeycomb task repo"),(0,i.kt)("img",{src:r,alt:"Firebase web credentials"}),(0,i.kt)("br",null),(0,i.kt)("br",null),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="env/.env.firebase"',title:'"env/.env.firebase"'},'REACT_APP_FIREBASE="true"\nREACT_APP_apiKey=\nREACT_APP_authDomain=\nREACT_APP_projectId=\nREACT_APP_storageBucket=\nREACT_APP_messagingSenderId=\nREACT_APP_appId=\n')),(0,i.kt)("p",{parentName:"li"},(0,i.kt)("em",{parentName:"p"},"Additional variables may be present in the console, they do not need to be copied."))))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Deploy the default ",(0,i.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/firestore/security/get-started"},"Firestore security rules")))),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Deploy Firestore rules"',title:'"Deploy',Firestore:!0,'rules"':!0},"firebase deploy --only firestore:rules\n")),(0,i.kt)("p",null,"Your task is now connected to an initialized Firebase project!"),(0,i.kt)("h2",{id:"registering-studies"},"Registering Studies"),(0,i.kt)("admonition",{type:"caution"},(0,i.kt)("p",{parentName:"admonition"},"This step must be followed ",(0,i.kt)("strong",{parentName:"p"},"exactly"),". See ",(0,i.kt)("a",{parentName:"p",href:"#security-rules"},"Security Rules")," for more information.")),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"Navigate to your Firestore Database in the ",(0,i.kt)("a",{parentName:"li",href:"https://console.firebase.google.com/"},"console"),"."),(0,i.kt)("li",{parentName:"ol"},'Click "Start collection"'),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"registered_studies"),' for the collection id and click "next"'),(0,i.kt)("li",{parentName:"ol"},"Enter the id of your study for the document id"),(0,i.kt)("li",{parentName:"ol"},"Add a field named ",(0,i.kt)("inlineCode",{parentName:"li"},"registered_participants"),' with the type "array"'),(0,i.kt)("li",{parentName:"ol"},"Add the id of each study participant as a string inside the array")),(0,i.kt)("div",{style:{textAlign:"center"}},(0,i.kt)("img",{src:s,alt:"Create a study",style:{maxHeight:"600px"}})),(0,i.kt)("br",null),(0,i.kt)("p",null,"The study should like this when you're finished:"),(0,i.kt)("img",{src:l,alt:"Example study"}),(0,i.kt)("br",null),(0,i.kt)("br",null),(0,i.kt)("p",null,(0,i.kt)("strong",{parentName:"p"},"Additional studies must be created inside the ",(0,i.kt)("inlineCode",{parentName:"strong"},"registered_studies")," collection")),(0,i.kt)("h2",{id:"developing-with-firebase"},"Developing With Firebase"),(0,i.kt)("p",null,(0,i.kt)("em",{parentName:"p"},"Two terminal windows must be used while developing for Firebase. Instructions splitting terminals in VSCode can be found ",(0,i.kt)("a",{parentName:"em",href:"https://code.visualstudio.com/docs/terminal/basics#_groups-split-panes"},"here"),".")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Run Honeycomb with Firebase Enabled"',title:'"Run',Honeycomb:!0,with:!0,Firebase:!0,'Enabled"':!0},"npm run dev:firebase\n")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Start the Firebase Emulators"',title:'"Start',the:!0,Firebase:!0,'Emulators"':!0},"npm run firebase:emulators:start\n")),(0,i.kt)("p",null,"Honeycomb is now running in the browser and connected to data on an emulated instance of Firestore.\nThat data can be viewed at ",(0,i.kt)("a",{parentName:"p",href:"http://localhost:4000/firestore"},"http://localhost:4000/firestore"),"."),(0,i.kt)("admonition",{type:"info"},(0,i.kt)("p",{parentName:"admonition"},"Honeycomb populates the Firestore emulators with the study ",(0,i.kt)("inlineCode",{parentName:"p"},"s1")," and participant ",(0,i.kt)("inlineCode",{parentName:"p"},"p1"),".")),(0,i.kt)("h2",{id:"deploying-on-firebase"},"Deploying on Firebase"),(0,i.kt)("p",null,"Firebase deployments are handled automatically following ",(0,i.kt)("a",{parentName:"p",href:"ci"},"Continuous Integration Continuous Development")," practices using GitHub Actions. Here we will connect create custom actions that are connected to the task's Firebase project."),(0,i.kt)("p",null,"Execute the following command to begin initializing Firebase hosting via GitHub actions. Be sure to follow the instructions below as the prompts appear."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Initialize Firebase hosting via Github actions"',title:'"Initialize',Firebase:!0,hosting:!0,via:!0,Github:!0,'actions"':!0},"firebase init hosting:github\n")),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},"The window should log you in automatically. If not, follow the prompts to log in with the same account you used in the console."),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"/")," refers to the name of your repository in Github. Be sure it's typed correctly!"),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"y"),' for the prompt "Set up the workflow to run a build script before every deploy?"'),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"npm install && npm run build:firebase"),' for the prompt "What script should be run before every deploy?"'),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"y")," to overwrite the current workflow file"),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"y"),' for the prompt "Set up automatic deployment to your site\'s live channel when a PR is merged?"'),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"main"),' for the prompt "What is the name of the GitHub branch associated with your site\'s live channel?"'),(0,i.kt)("li",{parentName:"ol"},"Enter ",(0,i.kt)("inlineCode",{parentName:"li"},"y")," to overwrite the current workflow file")),(0,i.kt)("p",null,"Firebase will update the files ",(0,i.kt)("inlineCode",{parentName:"p"},"firebase-hosting-pull-request.yml")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"firebase-hosting-merge.yml")," inside the ",(0,i.kt)("inlineCode",{parentName:"p"},".github/workflows/")," directory. Ensure the correct run script is present in both files."),(0,i.kt)("img",{src:p,alt:"Github actions created by firebase"}),(0,i.kt)("h2",{id:"downloading-data"},"Downloading Data"),(0,i.kt)("p",null,"Honeycomb ships with a script for downloading data from Firebase onto a computer. A local service account must be created in order to use it."),(0,i.kt)("h3",{id:"setting-up-a-service-account"},"Setting up a Service Account"),(0,i.kt)("p",null,"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."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Return to the project settings your project on the ",(0,i.kt)("a",{parentName:"p",href:"https://console.firebase.google.com/"},"Firebase console"),"."),(0,i.kt)("img",{src:o,alt:"Firebase project settings"})),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},'Click on the "Service accounts" tab')),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},'Near the bottom, click "Generate new Private key" and "Generate Key"')),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Rename the key ",(0,i.kt)("inlineCode",{parentName:"p"},"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!"))),(0,i.kt)("admonition",{type:"danger"},(0,i.kt)("p",{parentName:"admonition"},"A service account has total administrative access to ts Firebase project. The file and keys inside should never be shared and ",(0,i.kt)("strong",{parentName:"p"},"never committed to GitHub."))),(0,i.kt)("h3",{id:"using-the-download-script"},"Using the Download Script"),(0,i.kt)("p",null,"Honeycomb comes with a download script. It will programmatically access Firestore to download the experiment data you choose"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash",metastring:'title="Script Usage"',title:'"Script','Usage"':!0},"npm run firebase:download -- [sessionNumber] [outputRoot]\n")),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"studyID"),": The ID of a given study"),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"participantID"),": The ID of a given participant on the ",(0,i.kt)("inlineCode",{parentName:"li"},"studyID")," study"),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"sessionNumber"),": Optional number to select which session to download, defaults to the most recent session"),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"outputRoot"),": Optional path to the folder where data should be saved, defaults to the current folder")),(0,i.kt)("p",null,"Running the script without ",(0,i.kt)("inlineCode",{parentName:"p"},"sessionNumber")," list all of the available sessions. For example:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre"},"Found 3 sessions:\n 0: 2022-07-26T22:04:55.544Z\n 1: 2022-07-27T14:16:36.301Z\n 2: 2022-07-27T19:56:26.229Z\n")),(0,i.kt)("h4",{id:"sessionnumber"},"sessionNumber"),(0,i.kt)("p",null,"Adding a ",(0,i.kt)("inlineCode",{parentName:"p"},"sessionNumber")," will download that sessions data:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Download data for session 2022-07-26T22:04:55.544Z"',title:'"Download',data:!0,for:!0,session:!0,'2022-07-26T22:04:55.544Z"':!0},"npm run firebase:download -- 0 [outputRoot]\n")),(0,i.kt)("h4",{id:"outputroot"},"outputRoot"),(0,i.kt)("p",null,"Session data is stored in the current directory by default. The folders and file name are chosen to avoid naming collisions: ",(0,i.kt)("inlineCode",{parentName:"p"},"./participant_responses///.json")),(0,i.kt)("p",null,"Adding an ",(0,i.kt)("inlineCode",{parentName:"p"},"outputRoot")," will download that data in a custom location:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Download data for session 2022-07-26T22:04:55.544Z at /path/to/my/data"',title:'"Download',data:!0,for:!0,session:!0,"2022-07-26T22:04:55.544Z":!0,at:!0,'/path/to/my/data"':!0},"npm run firebase:download -- 0 /path/to/my/data\n")),(0,i.kt)("p",null,"This will result in data saved to ",(0,i.kt)("inlineCode",{parentName:"p"},"/path/to/my/data/participant_responses///.json")),(0,i.kt)("h2",{id:"further-reading"},"Further Reading"),(0,i.kt)("p",null,(0,i.kt)("em",{parentName:"p"},"The ",(0,i.kt)("a",{parentName:"em",href:"https://firebase.google.com/docs/emulator-suite"},"Firebase Documentation")," details its Emulator Suite in much greater detail.")),(0,i.kt)("h3",{id:"security-rules"},"Security Rules"),(0,i.kt)("p",null,"Honeycomb uses security rules to authenticate participants and studies for each task. By default participants must be registered to each study in order to complete the task."),(0,i.kt)("p",null,"Firestore rules are defined in the ",(0,i.kt)("inlineCode",{parentName:"p"},"firestore.rules")," file in the home directory. Note the highlighted lines:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-firestore-security-rules",metastring:'title="firestore.rules" showLineNumbers',title:'"firestore.rules"',showLineNumbers:!0},"rules_version = '2';\nservice cloud.firestore {\n //highlight-start\n match /databases/{database}/documents {\n match /participant_responses/{studyID}/participants/{participantID} {\n allow create, read:\n if participantID in get(/databases/$(database)/documents/registered_studies/$(studyID)).data.registered_participants;\n //highlight-end\n // ...\n }\n }\n}\n")),(0,i.kt)("p",null,"Lines 3 and 4 indicate that Honeycomb attempts to connect to a document at ",(0,i.kt)("inlineCode",{parentName:"p"},"/databases/{database}/documents/participant_responses/{studyID}/participants/{participantID}")," where ",(0,i.kt)("inlineCode",{parentName:"p"},"studyID")," is a given study and ",(0,i.kt)("inlineCode",{parentName:"p"},"participantID")," is a given participant within that study."),(0,i.kt)("p",null,"Line 6 defines our rule - it must pass for Honeycomb to connect to the document. ",(0,i.kt)("inlineCode",{parentName:"p"},"participantID")," must be found in an array called ",(0,i.kt)("inlineCode",{parentName:"p"},"registered_participants")," inside of a document at ",(0,i.kt)("inlineCode",{parentName:"p"},"/databases/{database}/documents/registered_studies/{studyID}"),"."),(0,i.kt)("p",null,"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."),(0,i.kt)("admonition",{type:"danger"},(0,i.kt)("p",{parentName:"admonition"},"Firestore rules must define every match pattern in your project. Attempting to connect anywhere other than ",(0,i.kt)("inlineCode",{parentName:"p"},"/participant_responses/{studyID}/participants/{participantID}")," will be automatically denied even if you add other collections to your database. This is why ",(0,i.kt)("inlineCode",{parentName:"p"},"firestore.rules")," contains additional nested rules - these should be left alone.")))}k.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/2f756f52.002f0cca.js b/assets/js/2f756f52.84d05b98.js similarity index 99% rename from assets/js/2f756f52.002f0cca.js rename to assets/js/2f756f52.84d05b98.js index 3aa4efa6..b41de2ab 100644 --- a/assets/js/2f756f52.002f0cca.js +++ b/assets/js/2f756f52.84d05b98.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[7044],{3905:(e,t,n)=>{n.d(t,{Zo:()=>m,kt:()=>h});var a=n(7294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function l(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var s=a.createContext({}),p=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},m=function(e){var t=p(e.components);return a.createElement(s.Provider,{value:t},e.children)},c="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},d=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,s=e.parentName,m=i(e,["components","mdxType","originalType","parentName"]),c=p(n),d=r,h=c["".concat(s,".").concat(d)]||c[d]||u[d]||o;return n?a.createElement(h,l(l({ref:t},m),{},{components:n})):a.createElement(h,l({ref:t},m))}));function h(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,l=new Array(o);l[0]=d;var i={};for(var s in t)hasOwnProperty.call(t,s)&&(i[s]=t[s]);i.originalType=e,i[c]="string"==typeof e?e:r,l[1]=i;for(var p=2;p{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>l,default:()=>u,frontMatter:()=>o,metadata:()=>i,toc:()=>p});var a=n(7462),r=(n(7294),n(3905));const o={id:"quick_start",title:"Quick Start"},l=void 0,i={unversionedId:"quick_start",id:"version-2.x/quick_start",title:"Quick Start",description:"To start a new task locally, in development mode follow these steps:",source:"@site/versioned_docs/version-2.x/quick_start.md",sourceDirName:".",slug:"/quick_start",permalink:"/honeycomb-docs/docs/2.x/quick_start",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-2.x/quick_start.md",tags:[],version:"2.x",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"quick_start",title:"Quick Start"},sidebar:"version-2.x/someSidebar",previous:{title:"Project Organization",permalink:"/honeycomb-docs/docs/2.x/folders"},next:{title:"Version Control",permalink:"/honeycomb-docs/docs/2.x/version_control"}},s={},p=[{value:"1. Start your new task from our template repository",id:"1-start-your-new-task-from-our-template-repository",level:3},{value:"2. Change name and description",id:"2-change-name-and-description",level:3},{value:"3. Install the dependencies.",id:"3-install-the-dependencies",level:3},{value:"Windows",id:"windows",level:4},{value:"Note: restart computer after all installs are complete",id:"note-restart-computer-after-all-installs-are-complete",level:5},{value:"MacOS",id:"macos",level:4},{value:"Linux",id:"linux",level:4},{value:"4. Run the task in dev mode",id:"4-run-the-task-in-dev-mode",level:3},{value:"5. Run the task with preset environment variables",id:"5-run-the-task-with-preset-environment-variables",level:3},{value:"6. Check out the data",id:"6-check-out-the-data",level:3},{value:"7. Quit The Task",id:"7-quit-the-task",level:3},{value:"7. Merge updates from honeycomb template repo",id:"7-merge-updates-from-honeycomb-template-repo",level:3},{value:"8. Run automated tests",id:"8-run-automated-tests",level:3},{value:"Linux",id:"linux-1",level:4}],m={toc:p},c="wrapper";function u(e){let{components:t,...n}=e;return(0,r.kt)(c,(0,a.Z)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"To start a new task locally, in development mode follow these steps:"),(0,r.kt)("h3",{id:"1-start-your-new-task-from-our-template-repository"},"1. Start your new task from our template repository"),(0,r.kt)("p",null,"The simplest way to get started is creating a new repository using Honeycomb as a template."),(0,r.kt)("p",null,"Go to ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/brown-ccv/honeycomb"},"https://github.com/brown-ccv/honeycomb")," and click on ",(0,r.kt)("inlineCode",{parentName:"p"},"Use this template")," on the top right. Then select the organization and the name of your repository and click on ",(0,r.kt)("inlineCode",{parentName:"p"},"create repository from template")),(0,r.kt)("p",null,"Alternatively, you can use GitHub CLI to create a new project based on the Honeycomb template repository. First, install GitHub CLI (",(0,r.kt)("a",{parentName:"p",href:"https://cli.github.com/"},"https://cli.github.com/"),"), then simply run on your terminal: "),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"gh repo create your-new-task-name --template brown-ccv/honeycomb\n")),(0,r.kt)("p",null,"You can now move into the directory that was just created"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"cd your-new-task-name\n")),(0,r.kt)("h3",{id:"2-change-name-and-description"},"2. Change name and description"),(0,r.kt)("p",null,"Update the ",(0,r.kt)("inlineCode",{parentName:"p"},"package.json")," fields to reflect your app name and description, e.g. ",(0,r.kt)("inlineCode",{parentName:"p"},"name"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"author"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"repository")),(0,r.kt)("h3",{id:"3-install-the-dependencies"},"3. Install the dependencies."),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"Electron Dependencies"),"\nHoneycomb relies on Electron to package the cross-platform desktop applications. Before starting, you will need to install Electron's pre-requisites below. You can find the full instructions on the ",(0,r.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-gn"},"electron documentation")," for your specific OS."),(0,r.kt)("h4",{id:"windows"},"Windows"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Visual Studio:\nInstall the latest version of ",(0,r.kt)("a",{parentName:"p",href:"https://visualstudio.microsoft.com/downloads/"},"Visual Studio")," with the Desktop Development for C++ Workflow.\nTo add the workflow, follow ",(0,r.kt)("a",{parentName:"p",href:"https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#:~:text=If%20you%20have%20Visual%20Studio,Then%2C%20choose%20Modify"},"these instructions"),".")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Node.js:\nInstall ",(0,r.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"Node.js"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},'Git bash (Git 2.20.0 or later with support for "--show-current"):\nInstall ',(0,r.kt)("a",{parentName:"p",href:"https://git-scm.com/downloads"},"git bash")))),(0,r.kt)("h5",{id:"note-restart-computer-after-all-installs-are-complete"},"Note: restart computer after all installs are complete"),(0,r.kt)("h4",{id:"macos"},"MacOS"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Command Line Tools: Type in the terminal")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"xcode-select --install\n")),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Node.js:\nInstall ",(0,r.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"Node.js"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},'Git 2.20.0 or later (with support for "--show-current"):\nInstall ',(0,r.kt)("a",{parentName:"p",href:"https://git-scm.com/downloads/"},"git"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Python 3.7 or later (with support for TLS 1.2):\nFollow the guide on electron docs to ",(0,r.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-macos#python"},"install and configure python and its modules")," "))),(0,r.kt)("h4",{id:"linux"},"Linux"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Node.js:\nDowload ",(0,r.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"Node.js source code")," and compile it: ")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},'Git 2.20.0 or later (with support for "--show-current"):\nInstall ',(0,r.kt)("a",{parentName:"p",href:"https://git-scm.com/downloads/"},"git"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Python 3.7 or later (with support for TLS 1.2):\nInstall ",(0,r.kt)("a",{parentName:"p",href:"https://www.python.org/downloads/"},"Python"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Clang:\nInstall ",(0,r.kt)("a",{parentName:"p",href:"https://clang.llvm.org/get_started.html"},"Clang")," or follow installation instructions on the ",(0,r.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Development headers of GTK 3 and libnotify:\nFollow installation instructions on the ",(0,r.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs")))),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"Honeycomb npm packages"),"\nOnce ",(0,r.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"Node.js")," is installed you will able to use ",(0,r.kt)("inlineCode",{parentName:"p"},"npm")," commands in the terminal. To install the dependencies for HoneyComb run the following command at the terminal (remember you need ",(0,r.kt)("inlineCode",{parentName:"p"},"cd your-new-task-name")," before)"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm install\n")),(0,r.kt)("h3",{id:"4-run-the-task-in-dev-mode"},"4. Run the task in dev mode"),(0,r.kt)("p",null,"To launch an electron window with the task with the inspector open to the console and will hot-reload when changes are made to the app"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"For Mac and Linux:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre"},"npm run dev\n"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"For Windows:\nYou will need to open 2 terminals. In the first -and make sure you are in the ",(0,r.kt)("inlineCode",{parentName:"p"},"task-")," repo directory- run the command:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre"},"npm start\n")),(0,r.kt)("p",{parentName:"li"}," In the second terminal - make sure you are in the ",(0,r.kt)("inlineCode",{parentName:"p"},"task-")," repo directory-, run:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre"},"npm run electron-dev\n")))),(0,r.kt)("h3",{id:"5-run-the-task-with-preset-environment-variables"},"5. Run the task with preset environment variables"),(0,r.kt)("p",null,"We have provided various ",(0,r.kt)("inlineCode",{parentName:"p"},".env")," files and npm scripts to run the task in common settings like home or clinic. Here are the possible commands:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm run dev:home\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm run dev:home:video\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm run dev:clinic\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm run dev:clinic:video\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm run dev:firebase\n")),(0,r.kt)("h3",{id:"6-check-out-the-data"},"6. Check out the data"),(0,r.kt)("p",null,"The data is saved throughout the task to the users's app directory. This is logged at the beginning of the task wherever you ran ",(0,r.kt)("inlineCode",{parentName:"p"},"npm run dev")," (for windows, instead in two different terminals ran ",(0,r.kt)("inlineCode",{parentName:"p"},"npm start")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"npm run electron-dev"),"). It is also stored in a folder that is generated by the app, which should be found on the desktop."),(0,r.kt)("h3",{id:"7-quit-the-task"},"7. Quit The Task"),(0,r.kt)("p",null,"If you want to quit in the middle of the task, you can use these keyboard shortcuts:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"Ctrl+W (for PC/Windows)\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"Cmd+Q (for Mac)\n")),(0,r.kt)("p",null,"Partial data will be saved."),(0,r.kt)("h3",{id:"7-merge-updates-from-honeycomb-template-repo"},"7. Merge updates from honeycomb template repo"),(0,r.kt)("p",null,"Honeycomb is an active project, and will be updated with new features over time. To merge the honeycomb template repository updates with your task, follow the following steps:\nFirst time only:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"git remote add honeycomb https://github.com/brown-ccv/honeycomb.git\n")),(0,r.kt)("p",null,"Every time: "),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"git fetch --all\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"git merge honeycomb/main --allow-unrelated histories\n")),(0,r.kt)("p",null,"If there are any conflicts:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"git stash\n")),(0,r.kt)("p",null,"To merge:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},'git commit -a -m "merge honeycomb latest"\n')),(0,r.kt)("h3",{id:"8-run-automated-tests"},"8. Run automated tests"),(0,r.kt)("p",null,"When getting started, merging updates, or making custom changes, it's a good idea to run automated tests. These can tell you if things are working or if recent changes broke something that previously worked."),(0,r.kt)("p",null,"To run the tests interactively:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm test\n")),(0,r.kt)("p",null,"Or non-interactively:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"CI=true npm test\n")),(0,r.kt)("h4",{id:"linux-1"},"Linux"),(0,r.kt)("p",null,"When running ",(0,r.kt)("inlineCode",{parentName:"p"},"npm test")," on Linux, you might get an error that mentions ",(0,r.kt)("inlineCode",{parentName:"p"},"ENOSPC"),'. This is because the test runer creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.'),(0,r.kt)("p",null,'This is a "known issue" with some test runners on Linux, as in discussions ',(0,r.kt)("a",{parentName:"p",href:"https://stackoverflow.com/questions/55763428/react-native-error-enospc-system-limit-for-number-of-file-watchers-reached"},"here")," and ",(0,r.kt)("a",{parentName:"p",href:"https://stackoverflow.com/questions/62206460/jest-watch-error-enospc-system-limit-for-number-of-file-watchers-reached"},"here"),"."),(0,r.kt)("p",null,"One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Command that initially fails with ",(0,r.kt)("inlineCode",{parentName:"li"},"ENOSPC"),": ",(0,r.kt)("inlineCode",{parentName:"li"},"npm test")),(0,r.kt)("li",{parentName:"ul"},'Check the configured limit on "watchers": ',(0,r.kt)("inlineCode",{parentName:"li"},"cat /proc/sys/fs/inotify/max_user_watches")),(0,r.kt)("li",{parentName:"ul"},"Edit the relevant Linux config file: ",(0,r.kt)("inlineCode",{parentName:"li"},"sudo vim /etc/sysctl.conf")),(0,r.kt)("li",{parentName:"ul"},"Add a line at the end of the config file: ",(0,r.kt)("inlineCode",{parentName:"li"},"fs.inotify.max_user_watches=100000")),(0,r.kt)("li",{parentName:"ul"},"Save, exit, and reload the config file: ",(0,r.kt)("inlineCode",{parentName:"li"},"sudo sysctl -p")),(0,r.kt)("li",{parentName:"ul"},"Check that the limit has changed: ",(0,r.kt)("inlineCode",{parentName:"li"},"cat /proc/sys/fs/inotify/max_user_watches")),(0,r.kt)("li",{parentName:"ul"},"Retry the initial command, which should now succeed: ",(0,r.kt)("inlineCode",{parentName:"li"},"npm test"))))}u.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[7044],{3905:(e,t,n)=>{n.d(t,{Zo:()=>m,kt:()=>h});var a=n(7294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function l(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var s=a.createContext({}),p=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},m=function(e){var t=p(e.components);return a.createElement(s.Provider,{value:t},e.children)},c="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},d=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,s=e.parentName,m=i(e,["components","mdxType","originalType","parentName"]),c=p(n),d=r,h=c["".concat(s,".").concat(d)]||c[d]||u[d]||o;return n?a.createElement(h,l(l({ref:t},m),{},{components:n})):a.createElement(h,l({ref:t},m))}));function h(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,l=new Array(o);l[0]=d;var i={};for(var s in t)hasOwnProperty.call(t,s)&&(i[s]=t[s]);i.originalType=e,i[c]="string"==typeof e?e:r,l[1]=i;for(var p=2;p{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>l,default:()=>u,frontMatter:()=>o,metadata:()=>i,toc:()=>p});var a=n(7462),r=(n(7294),n(3905));const o={id:"quick_start",title:"Quick Start"},l=void 0,i={unversionedId:"quick_start",id:"version-2.x/quick_start",title:"Quick Start",description:"To start a new task locally, in development mode follow these steps:",source:"@site/versioned_docs/version-2.x/quick_start.md",sourceDirName:".",slug:"/quick_start",permalink:"/honeycomb-docs/docs/2.x/quick_start",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-2.x/quick_start.md",tags:[],version:"2.x",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"quick_start",title:"Quick Start"},sidebar:"version-2.x/someSidebar",previous:{title:"Project Organization",permalink:"/honeycomb-docs/docs/2.x/folders"},next:{title:"Version Control",permalink:"/honeycomb-docs/docs/2.x/version_control"}},s={},p=[{value:"1. Start your new task from our template repository",id:"1-start-your-new-task-from-our-template-repository",level:3},{value:"2. Change name and description",id:"2-change-name-and-description",level:3},{value:"3. Install the dependencies.",id:"3-install-the-dependencies",level:3},{value:"Windows",id:"windows",level:4},{value:"Note: restart computer after all installs are complete",id:"note-restart-computer-after-all-installs-are-complete",level:5},{value:"MacOS",id:"macos",level:4},{value:"Linux",id:"linux",level:4},{value:"4. Run the task in dev mode",id:"4-run-the-task-in-dev-mode",level:3},{value:"5. Run the task with preset environment variables",id:"5-run-the-task-with-preset-environment-variables",level:3},{value:"6. Check out the data",id:"6-check-out-the-data",level:3},{value:"7. Quit The Task",id:"7-quit-the-task",level:3},{value:"7. Merge updates from honeycomb template repo",id:"7-merge-updates-from-honeycomb-template-repo",level:3},{value:"8. Run automated tests",id:"8-run-automated-tests",level:3},{value:"Linux",id:"linux-1",level:4}],m={toc:p},c="wrapper";function u(e){let{components:t,...n}=e;return(0,r.kt)(c,(0,a.Z)({},m,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"To start a new task locally, in development mode follow these steps:"),(0,r.kt)("h3",{id:"1-start-your-new-task-from-our-template-repository"},"1. Start your new task from our template repository"),(0,r.kt)("p",null,"The simplest way to get started is creating a new repository using Honeycomb as a template."),(0,r.kt)("p",null,"Go to ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/brown-ccv/honeycomb"},"https://github.com/brown-ccv/honeycomb")," and click on ",(0,r.kt)("inlineCode",{parentName:"p"},"Use this template")," on the top right. Then select the organization and the name of your repository and click on ",(0,r.kt)("inlineCode",{parentName:"p"},"create repository from template")),(0,r.kt)("p",null,"Alternatively, you can use GitHub CLI to create a new project based on the Honeycomb template repository. First, install GitHub CLI (",(0,r.kt)("a",{parentName:"p",href:"https://cli.github.com/"},"https://cli.github.com/"),"), then simply run on your terminal: "),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"gh repo create your-new-task-name --template brown-ccv/honeycomb\n")),(0,r.kt)("p",null,"You can now move into the directory that was just created"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"cd your-new-task-name\n")),(0,r.kt)("h3",{id:"2-change-name-and-description"},"2. Change name and description"),(0,r.kt)("p",null,"Update the ",(0,r.kt)("inlineCode",{parentName:"p"},"package.json")," fields to reflect your app name and description, e.g. ",(0,r.kt)("inlineCode",{parentName:"p"},"name"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"author"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"repository")),(0,r.kt)("h3",{id:"3-install-the-dependencies"},"3. Install the dependencies."),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"Electron Dependencies"),"\nHoneycomb relies on Electron to package the cross-platform desktop applications. Before starting, you will need to install Electron's pre-requisites below. You can find the full instructions on the ",(0,r.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-gn"},"electron documentation")," for your specific OS."),(0,r.kt)("h4",{id:"windows"},"Windows"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Visual Studio:\nInstall the latest version of ",(0,r.kt)("a",{parentName:"p",href:"https://visualstudio.microsoft.com/downloads/"},"Visual Studio")," with the Desktop Development for C++ Workflow.\nTo add the workflow, follow ",(0,r.kt)("a",{parentName:"p",href:"https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#:~:text=If%20you%20have%20Visual%20Studio,Then%2C%20choose%20Modify"},"these instructions"),".")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Node.js:\nInstall ",(0,r.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"Node.js"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},'Git bash (Git 2.20.0 or later with support for "--show-current"):\nInstall ',(0,r.kt)("a",{parentName:"p",href:"https://git-scm.com/downloads"},"git bash")))),(0,r.kt)("h5",{id:"note-restart-computer-after-all-installs-are-complete"},"Note: restart computer after all installs are complete"),(0,r.kt)("h4",{id:"macos"},"MacOS"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Command Line Tools: Type in the terminal")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"xcode-select --install\n")),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Node.js:\nInstall ",(0,r.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"Node.js"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},'Git 2.20.0 or later (with support for "--show-current"):\nInstall ',(0,r.kt)("a",{parentName:"p",href:"https://git-scm.com/downloads/"},"git"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Python 3.7 or later (with support for TLS 1.2):\nFollow the guide on electron docs to ",(0,r.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-macos#python"},"install and configure python and its modules")," "))),(0,r.kt)("h4",{id:"linux"},"Linux"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Node.js:\nDowload ",(0,r.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"Node.js source code")," and compile it: ")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},'Git 2.20.0 or later (with support for "--show-current"):\nInstall ',(0,r.kt)("a",{parentName:"p",href:"https://git-scm.com/downloads/"},"git"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Python 3.7 or later (with support for TLS 1.2):\nInstall ",(0,r.kt)("a",{parentName:"p",href:"https://www.python.org/downloads/"},"Python"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Clang:\nInstall ",(0,r.kt)("a",{parentName:"p",href:"https://clang.llvm.org/get_started.html"},"Clang")," or follow installation instructions on the ",(0,r.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"Development headers of GTK 3 and libnotify:\nFollow installation instructions on the ",(0,r.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development/build-instructions-linux#prerequisites"},"electron docs")))),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"Honeycomb npm packages"),"\nOnce ",(0,r.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"Node.js")," is installed you will able to use ",(0,r.kt)("inlineCode",{parentName:"p"},"npm")," commands in the terminal. To install the dependencies for HoneyComb run the following command at the terminal (remember you need ",(0,r.kt)("inlineCode",{parentName:"p"},"cd your-new-task-name")," before)"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm install\n")),(0,r.kt)("h3",{id:"4-run-the-task-in-dev-mode"},"4. Run the task in dev mode"),(0,r.kt)("p",null,"To launch an electron window with the task with the inspector open to the console and will hot-reload when changes are made to the app"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"For Mac and Linux:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre"},"npm run dev\n"))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"For Windows:\nYou will need to open 2 terminals. In the first -and make sure you are in the ",(0,r.kt)("inlineCode",{parentName:"p"},"task-")," repo directory- run the command:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre"},"npm start\n")),(0,r.kt)("p",{parentName:"li"}," In the second terminal - make sure you are in the ",(0,r.kt)("inlineCode",{parentName:"p"},"task-")," repo directory-, run:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre"},"npm run electron-dev\n")))),(0,r.kt)("h3",{id:"5-run-the-task-with-preset-environment-variables"},"5. Run the task with preset environment variables"),(0,r.kt)("p",null,"We have provided various ",(0,r.kt)("inlineCode",{parentName:"p"},".env")," files and npm scripts to run the task in common settings like home or clinic. Here are the possible commands:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm run dev:home\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm run dev:home:video\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm run dev:clinic\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm run dev:clinic:video\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm run dev:firebase\n")),(0,r.kt)("h3",{id:"6-check-out-the-data"},"6. Check out the data"),(0,r.kt)("p",null,"The data is saved throughout the task to the users's app directory. This is logged at the beginning of the task wherever you ran ",(0,r.kt)("inlineCode",{parentName:"p"},"npm run dev")," (for windows, instead in two different terminals ran ",(0,r.kt)("inlineCode",{parentName:"p"},"npm start")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"npm run electron-dev"),"). It is also stored in a folder that is generated by the app, which should be found on the desktop."),(0,r.kt)("h3",{id:"7-quit-the-task"},"7. Quit The Task"),(0,r.kt)("p",null,"If you want to quit in the middle of the task, you can use these keyboard shortcuts:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"Ctrl+W (for PC/Windows)\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"Cmd+Q (for Mac)\n")),(0,r.kt)("p",null,"Partial data will be saved."),(0,r.kt)("h3",{id:"7-merge-updates-from-honeycomb-template-repo"},"7. Merge updates from honeycomb template repo"),(0,r.kt)("p",null,"Honeycomb is an active project, and will be updated with new features over time. To merge the honeycomb template repository updates with your task, follow the following steps:\nFirst time only:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"git remote add honeycomb https://github.com/brown-ccv/honeycomb.git\n")),(0,r.kt)("p",null,"Every time: "),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"git fetch --all\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"git merge honeycomb/main --allow-unrelated histories\n")),(0,r.kt)("p",null,"If there are any conflicts:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"git stash\n")),(0,r.kt)("p",null,"To merge:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},'git commit -a -m "merge honeycomb latest"\n')),(0,r.kt)("h3",{id:"8-run-automated-tests"},"8. Run automated tests"),(0,r.kt)("p",null,"When getting started, merging updates, or making custom changes, it's a good idea to run automated tests. These can tell you if things are working or if recent changes broke something that previously worked."),(0,r.kt)("p",null,"To run the tests interactively:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"npm test\n")),(0,r.kt)("p",null,"Or non-interactively:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"CI=true npm test\n")),(0,r.kt)("h4",{id:"linux-1"},"Linux"),(0,r.kt)("p",null,"When running ",(0,r.kt)("inlineCode",{parentName:"p"},"npm test")," on Linux, you might get an error that mentions ",(0,r.kt)("inlineCode",{parentName:"p"},"ENOSPC"),'. This is because the test runer creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.'),(0,r.kt)("p",null,'This is a "known issue" with some test runners on Linux, as in discussions ',(0,r.kt)("a",{parentName:"p",href:"https://stackoverflow.com/questions/55763428/react-native-error-enospc-system-limit-for-number-of-file-watchers-reached"},"here")," and ",(0,r.kt)("a",{parentName:"p",href:"https://stackoverflow.com/questions/62206460/jest-watch-error-enospc-system-limit-for-number-of-file-watchers-reached"},"here"),"."),(0,r.kt)("p",null,"One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Command that initially fails with ",(0,r.kt)("inlineCode",{parentName:"li"},"ENOSPC"),": ",(0,r.kt)("inlineCode",{parentName:"li"},"npm test")),(0,r.kt)("li",{parentName:"ul"},'Check the configured limit on "watchers": ',(0,r.kt)("inlineCode",{parentName:"li"},"cat /proc/sys/fs/inotify/max_user_watches")),(0,r.kt)("li",{parentName:"ul"},"Edit the relevant Linux config file: ",(0,r.kt)("inlineCode",{parentName:"li"},"sudo vim /etc/sysctl.conf")),(0,r.kt)("li",{parentName:"ul"},"Add a line at the end of the config file: ",(0,r.kt)("inlineCode",{parentName:"li"},"fs.inotify.max_user_watches=100000")),(0,r.kt)("li",{parentName:"ul"},"Save, exit, and reload the config file: ",(0,r.kt)("inlineCode",{parentName:"li"},"sudo sysctl -p")),(0,r.kt)("li",{parentName:"ul"},"Check that the limit has changed: ",(0,r.kt)("inlineCode",{parentName:"li"},"cat /proc/sys/fs/inotify/max_user_watches")),(0,r.kt)("li",{parentName:"ul"},"Retry the initial command, which should now succeed: ",(0,r.kt)("inlineCode",{parentName:"li"},"npm test"))))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/31f23339.6ba8aaa0.js b/assets/js/31f23339.ec923ffe.js similarity index 99% rename from assets/js/31f23339.6ba8aaa0.js rename to assets/js/31f23339.ec923ffe.js index 02534520..db117c5a 100644 --- a/assets/js/31f23339.6ba8aaa0.js +++ b/assets/js/31f23339.ec923ffe.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[5445],{3905:(e,t,n)=>{n.d(t,{Zo:()=>c,kt:()=>h});var r=n(7294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function i(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var p=r.createContext({}),s=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},c=function(e){var t=s(e.components);return r.createElement(p.Provider,{value:t},e.children)},d="mdxType",m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},u=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,p=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),d=s(n),u=o,h=d["".concat(p,".").concat(u)]||d[u]||m[u]||a;return n?r.createElement(h,i(i({ref:t},c),{},{components:n})):r.createElement(h,i({ref:t},c))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=u;var l={};for(var p in t)hasOwnProperty.call(t,p)&&(l[p]=t[p]);l.originalType=e,l[d]="string"==typeof e?e:o,i[1]=l;for(var s=2;s{n.r(t),n.d(t,{assets:()=>p,contentTitle:()=>i,default:()=>m,frontMatter:()=>a,metadata:()=>l,toc:()=>s});var r=n(7462),o=(n(7294),n(3905));const a={id:"quick_start",title:"Quick Start"},i=void 0,l={unversionedId:"quick_start",id:"version-1.1.0/quick_start",title:"Quick Start",description:"To start a new task locally, in development mode follow these steps:",source:"@site/versioned_docs/version-1.1.0/quick_start.md",sourceDirName:".",slug:"/quick_start",permalink:"/honeycomb-docs/docs/1.1.0/quick_start",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-1.1.0/quick_start.md",tags:[],version:"1.1.0",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"quick_start",title:"Quick Start"},sidebar:"version-1.1.0/someSidebar",previous:{title:"Project Organization",permalink:"/honeycomb-docs/docs/1.1.0/folders"},next:{title:"Version Control",permalink:"/honeycomb-docs/docs/1.1.0/version_control"}},p={},s=[{value:"1. Start your new task from our template repository",id:"1-start-your-new-task-from-our-template-repository",level:3},{value:"2. Change name and description",id:"2-change-name-and-description",level:3},{value:"3. Install the dependencies.",id:"3-install-the-dependencies",level:3},{value:"4. Run the task in dev mode",id:"4-run-the-task-in-dev-mode",level:3},{value:"5. Check out the data",id:"5-check-out-the-data",level:3},{value:"6. Quit The Task",id:"6-quit-the-task",level:3},{value:"7. Merge updates from honeycomb template repo",id:"7-merge-updates-from-honeycomb-template-repo",level:3}],c={toc:s},d="wrapper";function m(e){let{components:t,...n}=e;return(0,o.kt)(d,(0,r.Z)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"To start a new task locally, in development mode follow these steps:"),(0,o.kt)("h3",{id:"1-start-your-new-task-from-our-template-repository"},"1. Start your new task from our template repository"),(0,o.kt)("p",null,"The simplest way to get started is creating a new repository using Honeycomb as a template."),(0,o.kt)("p",null,"Go to ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/brown-ccv/honeycomb"},"https://github.com/brown-ccv/honeycomb")," and click on ",(0,o.kt)("inlineCode",{parentName:"p"},"Use this template")," on the top right. Then select the organization and the name of your repository and click on ",(0,o.kt)("inlineCode",{parentName:"p"},"create repository from template")),(0,o.kt)("p",null,"Alternatively, you can use GitHub CLI to create a new project based on the Honeycomb template repository. First, install GitHub CLI (",(0,o.kt)("a",{parentName:"p",href:"https://cli.github.com/"},"https://cli.github.com/"),"), then simply run on your terminal: "),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"gh repo create your-new-task-name --template brown-ccv/honeycomb\n")),(0,o.kt)("p",null,"You can now move into the directory that was just created"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"cd your-new-task-name\n")),(0,o.kt)("h3",{id:"2-change-name-and-description"},"2. Change name and description"),(0,o.kt)("p",null,"Update the ",(0,o.kt)("inlineCode",{parentName:"p"},"package.json")," fields to reflect your app name and description, e.g. ",(0,o.kt)("inlineCode",{parentName:"p"},"name"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"author"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"repository")),(0,o.kt)("h3",{id:"3-install-the-dependencies"},"3. Install the dependencies."),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"Electron Dependencies"),"\nHoneycomb relies on Electron to package the cross-platform desktop applications. Before starting, you will need to install Electron's pre-requisites. You can find instructions ",(0,o.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development"},"here")," for your specific OS"),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"Honeycomb npm packages"),"\nOnce ",(0,o.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"Node.js")," is installed you will able to use ",(0,o.kt)("inlineCode",{parentName:"p"},"npm")," commands in the terminal. To install the dependencies for HoneyComb run the following command at the terminal (remember you need ",(0,o.kt)("inlineCode",{parentName:"p"},"cd your-new-task-name")," before)"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"npm install\n")),(0,o.kt)("h3",{id:"4-run-the-task-in-dev-mode"},"4. Run the task in dev mode"),(0,o.kt)("p",null,"To launch an electron window with the task with the inspector open to the console and will hot-reload when changes are made to the app"),(0,o.kt)("p",null,"**For Mac and Linux:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"npm run dev\n")),(0,o.kt)("p",null,"**For Windows:\nYou will need to open 2 terminals. In the first -and make sure you are in the ",(0,o.kt)("inlineCode",{parentName:"p"},"task-")," repo directory- run the command:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"npm start\n")),(0,o.kt)("p",null,"In the second terminal - make sure you are in the ",(0,o.kt)("inlineCode",{parentName:"p"},"task-")," repo directory-, run:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"npm run electron-dev\n")),(0,o.kt)("h3",{id:"5-check-out-the-data"},"5. Check out the data"),(0,o.kt)("p",null,"The data is saved throughout the task to the users's app directory. This is logged at the beginning of the task wherever you ran ",(0,o.kt)("inlineCode",{parentName:"p"},"npm run dev")," (for windows, instead in two different terminals ran ",(0,o.kt)("inlineCode",{parentName:"p"},"npm start")," and ",(0,o.kt)("inlineCode",{parentName:"p"},"npm run electron-dev"),"). It is also stored in a folder that is generated by the app, which should be found on the desktop."),(0,o.kt)("h3",{id:"6-quit-the-task"},"6. Quit The Task"),(0,o.kt)("p",null,"If you want to quit in the middle of the task, you can use these keyboard shortcuts:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"Ctrl+W (for PC/Windows)\n")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"Cmd+Q (for Mac)\n")),(0,o.kt)("p",null,"Partial data will be saved."),(0,o.kt)("h3",{id:"7-merge-updates-from-honeycomb-template-repo"},"7. Merge updates from honeycomb template repo"),(0,o.kt)("p",null,"Honeycomb is an active project, and will be updated with new features over time. To merge the honeycomb template repository updates with your task, follow the following steps:\nFirst time only:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"git remote add honeycomb https://github.com/brown-ccv/honeycomb.git\n")),(0,o.kt)("p",null,"Every time: "),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"git fetch --all\n")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"git merge honeycomb/main --allow-unrelated histories\n")),(0,o.kt)("p",null,"If there are any conflicts:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"git stash\n")),(0,o.kt)("p",null,"To merge:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},'git commit -a -m "merge honeycomb latest"\n')))}m.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[5445],{3905:(e,t,n)=>{n.d(t,{Zo:()=>c,kt:()=>h});var r=n(7294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function i(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var p=r.createContext({}),s=function(e){var t=r.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},c=function(e){var t=s(e.components);return r.createElement(p.Provider,{value:t},e.children)},d="mdxType",m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},u=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,p=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),d=s(n),u=o,h=d["".concat(p,".").concat(u)]||d[u]||m[u]||a;return n?r.createElement(h,i(i({ref:t},c),{},{components:n})):r.createElement(h,i({ref:t},c))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=u;var l={};for(var p in t)hasOwnProperty.call(t,p)&&(l[p]=t[p]);l.originalType=e,l[d]="string"==typeof e?e:o,i[1]=l;for(var s=2;s{n.r(t),n.d(t,{assets:()=>p,contentTitle:()=>i,default:()=>m,frontMatter:()=>a,metadata:()=>l,toc:()=>s});var r=n(7462),o=(n(7294),n(3905));const a={id:"quick_start",title:"Quick Start"},i=void 0,l={unversionedId:"quick_start",id:"version-1.1.0/quick_start",title:"Quick Start",description:"To start a new task locally, in development mode follow these steps:",source:"@site/versioned_docs/version-1.1.0/quick_start.md",sourceDirName:".",slug:"/quick_start",permalink:"/honeycomb-docs/docs/1.1.0/quick_start",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-1.1.0/quick_start.md",tags:[],version:"1.1.0",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"quick_start",title:"Quick Start"},sidebar:"version-1.1.0/someSidebar",previous:{title:"Project Organization",permalink:"/honeycomb-docs/docs/1.1.0/folders"},next:{title:"Version Control",permalink:"/honeycomb-docs/docs/1.1.0/version_control"}},p={},s=[{value:"1. Start your new task from our template repository",id:"1-start-your-new-task-from-our-template-repository",level:3},{value:"2. Change name and description",id:"2-change-name-and-description",level:3},{value:"3. Install the dependencies.",id:"3-install-the-dependencies",level:3},{value:"4. Run the task in dev mode",id:"4-run-the-task-in-dev-mode",level:3},{value:"5. Check out the data",id:"5-check-out-the-data",level:3},{value:"6. Quit The Task",id:"6-quit-the-task",level:3},{value:"7. Merge updates from honeycomb template repo",id:"7-merge-updates-from-honeycomb-template-repo",level:3}],c={toc:s},d="wrapper";function m(e){let{components:t,...n}=e;return(0,o.kt)(d,(0,r.Z)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"To start a new task locally, in development mode follow these steps:"),(0,o.kt)("h3",{id:"1-start-your-new-task-from-our-template-repository"},"1. Start your new task from our template repository"),(0,o.kt)("p",null,"The simplest way to get started is creating a new repository using Honeycomb as a template."),(0,o.kt)("p",null,"Go to ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/brown-ccv/honeycomb"},"https://github.com/brown-ccv/honeycomb")," and click on ",(0,o.kt)("inlineCode",{parentName:"p"},"Use this template")," on the top right. Then select the organization and the name of your repository and click on ",(0,o.kt)("inlineCode",{parentName:"p"},"create repository from template")),(0,o.kt)("p",null,"Alternatively, you can use GitHub CLI to create a new project based on the Honeycomb template repository. First, install GitHub CLI (",(0,o.kt)("a",{parentName:"p",href:"https://cli.github.com/"},"https://cli.github.com/"),"), then simply run on your terminal: "),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"gh repo create your-new-task-name --template brown-ccv/honeycomb\n")),(0,o.kt)("p",null,"You can now move into the directory that was just created"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"cd your-new-task-name\n")),(0,o.kt)("h3",{id:"2-change-name-and-description"},"2. Change name and description"),(0,o.kt)("p",null,"Update the ",(0,o.kt)("inlineCode",{parentName:"p"},"package.json")," fields to reflect your app name and description, e.g. ",(0,o.kt)("inlineCode",{parentName:"p"},"name"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"author"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"repository")),(0,o.kt)("h3",{id:"3-install-the-dependencies"},"3. Install the dependencies."),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"Electron Dependencies"),"\nHoneycomb relies on Electron to package the cross-platform desktop applications. Before starting, you will need to install Electron's pre-requisites. You can find instructions ",(0,o.kt)("a",{parentName:"p",href:"https://www.electronjs.org/docs/development"},"here")," for your specific OS"),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"Honeycomb npm packages"),"\nOnce ",(0,o.kt)("a",{parentName:"p",href:"https://nodejs.org/en/download/"},"Node.js")," is installed you will able to use ",(0,o.kt)("inlineCode",{parentName:"p"},"npm")," commands in the terminal. To install the dependencies for HoneyComb run the following command at the terminal (remember you need ",(0,o.kt)("inlineCode",{parentName:"p"},"cd your-new-task-name")," before)"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"npm install\n")),(0,o.kt)("h3",{id:"4-run-the-task-in-dev-mode"},"4. Run the task in dev mode"),(0,o.kt)("p",null,"To launch an electron window with the task with the inspector open to the console and will hot-reload when changes are made to the app"),(0,o.kt)("p",null,"**For Mac and Linux:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"npm run dev\n")),(0,o.kt)("p",null,"**For Windows:\nYou will need to open 2 terminals. In the first -and make sure you are in the ",(0,o.kt)("inlineCode",{parentName:"p"},"task-")," repo directory- run the command:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"npm start\n")),(0,o.kt)("p",null,"In the second terminal - make sure you are in the ",(0,o.kt)("inlineCode",{parentName:"p"},"task-")," repo directory-, run:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"npm run electron-dev\n")),(0,o.kt)("h3",{id:"5-check-out-the-data"},"5. Check out the data"),(0,o.kt)("p",null,"The data is saved throughout the task to the users's app directory. This is logged at the beginning of the task wherever you ran ",(0,o.kt)("inlineCode",{parentName:"p"},"npm run dev")," (for windows, instead in two different terminals ran ",(0,o.kt)("inlineCode",{parentName:"p"},"npm start")," and ",(0,o.kt)("inlineCode",{parentName:"p"},"npm run electron-dev"),"). It is also stored in a folder that is generated by the app, which should be found on the desktop."),(0,o.kt)("h3",{id:"6-quit-the-task"},"6. Quit The Task"),(0,o.kt)("p",null,"If you want to quit in the middle of the task, you can use these keyboard shortcuts:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"Ctrl+W (for PC/Windows)\n")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"Cmd+Q (for Mac)\n")),(0,o.kt)("p",null,"Partial data will be saved."),(0,o.kt)("h3",{id:"7-merge-updates-from-honeycomb-template-repo"},"7. Merge updates from honeycomb template repo"),(0,o.kt)("p",null,"Honeycomb is an active project, and will be updated with new features over time. To merge the honeycomb template repository updates with your task, follow the following steps:\nFirst time only:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"git remote add honeycomb https://github.com/brown-ccv/honeycomb.git\n")),(0,o.kt)("p",null,"Every time: "),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"git fetch --all\n")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"git merge honeycomb/main --allow-unrelated histories\n")),(0,o.kt)("p",null,"If there are any conflicts:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},"git stash\n")),(0,o.kt)("p",null,"To merge:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre"},'git commit -a -m "merge honeycomb latest"\n')))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/320598df.fafafca2.js b/assets/js/320598df.bec75318.js similarity index 99% rename from assets/js/320598df.fafafca2.js rename to assets/js/320598df.bec75318.js index 1440d918..177d9845 100644 --- a/assets/js/320598df.fafafca2.js +++ b/assets/js/320598df.bec75318.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[4825],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>m});var i=n(7294);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);t&&(i=i.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,i)}return n}function r(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(i=0;i=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var l=i.createContext({}),d=function(e){var t=i.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):r(r({},t),e)),n},p=function(e){var t=d(e.components);return i.createElement(l.Provider,{value:t},e.children)},c="mdxType",h={inlineCode:"code",wrapper:function(e){var t=e.children;return i.createElement(i.Fragment,{},t)}},u=i.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,l=e.parentName,p=s(e,["components","mdxType","originalType","parentName"]),c=d(n),u=a,m=c["".concat(l,".").concat(u)]||c[u]||h[u]||o;return n?i.createElement(m,r(r({ref:t},p),{},{components:n})):i.createElement(m,r({ref:t},p))}));function m(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,r=new Array(o);r[0]=u;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[c]="string"==typeof e?e:a,r[1]=s;for(var d=2;d{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>o,metadata:()=>s,toc:()=>d});var i=n(7462),a=(n(7294),n(3905));const o={id:"folders",title:"Project Organization"},r=void 0,s={unversionedId:"folders",id:"version-3.0.0/folders",title:"Project Organization",description:"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 definitely not mutated), 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. Below are descriptions of the main files and folders.",source:"@site/versioned_docs/version-3.0.0/folders.md",sourceDirName:".",slug:"/folders",permalink:"/honeycomb-docs/docs/3.0.0/folders",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.0.0/folders.md",tags:[],version:"3.0.0",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"folders",title:"Project Organization"},sidebar:"someSidebar",previous:{title:"Introduction",permalink:"/honeycomb-docs/docs/3.0.0/"},next:{title:"Quick Start",permalink:"/honeycomb-docs/docs/3.0.0/quick_start"}},l={},d=[{value:"package.json",id:"packagejson",level:3},{value:"assets/",id:"assets",level:3},{value:"env/",id:"env",level:3},{value:".github/workflows/",id:"githubworkflows",level:3},{value:"public/",id:"public",level:3},{value:"electron.js",id:"electronjs",level:4},{value:"config/",id:"config",level:4},{value:"src/",id:"src",level:3},{value:"App.jsx",id:"appjsx",level:4},{value:"App.css",id:"appcss",level:4},{value:"components/",id:"components",level:4},{value:"language/",id:"language",level:4},{value:"lib/",id:"lib",level:4},{value:"lib/markup",id:"libmarkup",level:4},{value:"timelines",id:"timelines",level:4},{value:"trials",id:"trials",level:4}],p={toc:d},c="wrapper";function h(e){let{components:t,...n}=e;return(0,a.kt)(c,(0,i.Z)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"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 definitely not mutated), 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. Below are descriptions of the main files and folders."),(0,a.kt)("h3",{id:"packagejson"},(0,a.kt)("inlineCode",{parentName:"h3"},"package.json")),(0,a.kt)("p",null,"The ",(0,a.kt)("inlineCode",{parentName:"p"},"package.json")," file contains metadata about your project and scripts to run tasks related to your task. The ",(0,a.kt)("inlineCode",{parentName:"p"},"name")," should be updated to your task's name and ",(0,a.kt)("inlineCode",{parentName:"p"},"scripts")," can be added as desired, but otherwise this file should not be edited manually. To remove or add a dependency use ",(0,a.kt)("inlineCode",{parentName:"p"},"npm install")," or ",(0,a.kt)("inlineCode",{parentName:"p"},"npm uninstall")," with the ",(0,a.kt)("inlineCode",{parentName:"p"},"-D")," flag if installing a dev dependency."),(0,a.kt)("p",null,"The ",(0,a.kt)("inlineCode",{parentName:"p"},"package-lock.json")," contains metadata about the package installation. It should never be manually updated."),(0,a.kt)("h3",{id:"assets"},(0,a.kt)("inlineCode",{parentName:"h3"},"assets/")),(0,a.kt)("p",null,"This folder contains any static files that are used by the app, such as the images used as icons for the installed applications."),(0,a.kt)("h3",{id:"env"},(0,a.kt)("inlineCode",{parentName:"h3"},"env/")),(0,a.kt)("p",null,"This folder contains different .env files with presets for common use cases. These files can be loaded with ",(0,a.kt)("inlineCode",{parentName:"p"},"dotenv"),", which is explained in greater detail in the ",(0,a.kt)("a",{parentName:"p",href:"/honeycomb-docs/docs/3.0.0/configuration"},"Configuration")," section."),(0,a.kt)("h3",{id:"githubworkflows"},(0,a.kt)("inlineCode",{parentName:"h3"},".github/workflows/")),(0,a.kt)("p",null,"This folder contains different .yaml files which are used to configure the build tests (",(0,a.kt)("inlineCode",{parentName:"p"},"build.yaml"),") following a push and to create task executables either in a single instance (",(0,a.kt)("inlineCode",{parentName:"p"},"package.yaml"),") or for a full release (",(0,a.kt)("inlineCode",{parentName:"p"},"release.yaml"),")."),(0,a.kt)("h3",{id:"public"},(0,a.kt)("inlineCode",{parentName:"h3"},"public/")),(0,a.kt)("p",null,"The ",(0,a.kt)("inlineCode",{parentName:"p"},"public")," directory contains files that are used as assets in the built app. The ",(0,a.kt)("inlineCode",{parentName:"p"},"favicon.ico")," is the small icon you can see in the browser tab (on Chrome) - it is set to Brown's logo in the project. The ",(0,a.kt)("inlineCode",{parentName:"p"},"index.html")," contains the shell of your website - the name displayed on the tab can be changed here, otherwise it shouldn't need to be edited. The scripts included in the file are for ",(0,a.kt)("inlineCode",{parentName:"p"},"psiturk")," as are the files in the ",(0,a.kt)("inlineCode",{parentName:"p"},"lib/")," directory."),(0,a.kt)("h4",{id:"electronjs"},(0,a.kt)("inlineCode",{parentName:"h4"},"electron.js")),(0,a.kt)("p",null,"This file contains all of the code relating to the Electron app. This includes the event-marker, throwing errors via dialog windows, saving data, and reading files."),(0,a.kt)("h4",{id:"config"},(0,a.kt)("inlineCode",{parentName:"h4"},"config/")),(0,a.kt)("p",null,"The ",(0,a.kt)("inlineCode",{parentName:"p"},"config")," directory contains the config files needed for the electron app. This includes the event-marker details and event codes."),(0,a.kt)("p",null,"In the ",(0,a.kt)("inlineCode",{parentName:"p"},"config/")," directory, there are ",(0,a.kt)("inlineCode",{parentName:"p"},".js")," files which contain settings for the different parts of the task. Every task should have a ",(0,a.kt)("inlineCode",{parentName:"p"},"main")," config and a ",(0,a.kt)("inlineCode",{parentName:"p"},"trigger")," config (assuming use of the event marker). The ",(0,a.kt)("inlineCode",{parentName:"p"},"main")," config has all global settings for the task (such as whether it is in mturk mode or not), load the appropriate language file, and set up a default (or only) configuration object for the task. Different in-task features can be loaded from .env files and is set in the ",(0,a.kt)("inlineCode",{parentName:"p"},"main")," config. For example, we have included some of these files in the ",(0,a.kt)("inlineCode",{parentName:"p"},"env")," directory (e.g. ",(0,a.kt)("inlineCode",{parentName:"p"},"env.clinic")," file enables event marker, photodiode and volume adjustment). The ",(0,a.kt)("inlineCode",{parentName:"p"},"trigger")," config has settings specific to the event marker and uses a slightly different style of javascript as it is imported both in the React app as well as the electron process."),(0,a.kt)("p",null,"Other config files can be used to add settings for specific blocks or sub-sections of the experiment. Also, ",(0,a.kt)("em",{parentName:"p"},"note that the productId can be overwritten by the environment variable EVENT_MARKER_PRODUCT_ID"),"."),(0,a.kt)("h3",{id:"src"},(0,a.kt)("inlineCode",{parentName:"h3"},"src/")),(0,a.kt)("p",null,"This folder contains the code for the app, the vast majority of changes and code should go here."),(0,a.kt)("h4",{id:"appjsx"},(0,a.kt)("inlineCode",{parentName:"h4"},"App.jsx")),(0,a.kt)("p",null,"This is the starting point for the app. The ",(0,a.kt)("inlineCode",{parentName:"p"},"")," component handles user authentication in the different use cases and the ",(0,a.kt)("inlineCode",{parentName:"p"},"")," component initializes the ",(0,a.kt)("inlineCode",{parentName:"p"},"jspsych")," 7 experiment. This is also where communication is set up with the ",(0,a.kt)("inlineCode",{parentName:"p"},"electron")," and ",(0,a.kt)("inlineCode",{parentName:"p"},"psiturk")," processes."),(0,a.kt)("h4",{id:"appcss"},(0,a.kt)("inlineCode",{parentName:"h4"},"App.css")),(0,a.kt)("p",null,"This is where styling for the app is housed. If colors, fonts, spacing, etc. need to be set, do it here."),(0,a.kt)("h4",{id:"components"},(0,a.kt)("inlineCode",{parentName:"h4"},"components/")),(0,a.kt)("p",null,"This folder contains the components referenced in ",(0,a.kt)("inlineCode",{parentName:"p"},"App.jsx"),". This includes the Honeycomb ",(0,a.kt)("inlineCode",{parentName:"p"},"")," component which connects the Honyecomb login page to your ",(0,a.kt)("inlineCode",{parentName:"p"},"jspsych")," 7 experiment."),(0,a.kt)("h4",{id:"language"},(0,a.kt)("inlineCode",{parentName:"h4"},"language/")),(0,a.kt)("p",null,"Any language that is displayed in the experiment should be stored in this folder. Usage of language json files allows for easy internationalization of the task (e.g. English and Spanish) as well as allows for mturk-specific language. This also makes it easy to re-use common phrases in many places in the task."),(0,a.kt)("h4",{id:"lib"},(0,a.kt)("inlineCode",{parentName:"h4"},"lib/")),(0,a.kt)("p",null,"The ",(0,a.kt)("inlineCode",{parentName:"p"},"lib/")," directory contains utility functions and markup that is used in the tasks. This allows for functions and html to be re-used wherever needed. The ",(0,a.kt)("inlineCode",{parentName:"p"},"lib/utils.js")," file contains functions that are generally useful across many tasks, whereas ",(0,a.kt)("inlineCode",{parentName:"p"},"lib/taskUtils.js")," contains functions specific to this task."),(0,a.kt)("h4",{id:"libmarkup"},(0,a.kt)("inlineCode",{parentName:"h4"},"lib/markup")),(0,a.kt)("p",null,(0,a.kt)("inlineCode",{parentName:"p"},"markup")," files should contain primarily templates for HTML that are used throughout the task. Typically this will be a function that takes in some parameters and then returns a string with html."),(0,a.kt)("h4",{id:"timelines"},(0,a.kt)("inlineCode",{parentName:"h4"},"timelines")),(0,a.kt)("p",null,(0,a.kt)("inlineCode",{parentName:"p"},"jspsych")," uses ",(0,a.kt)("inlineCode",{parentName:"p"},"timelines")," to control what ",(0,a.kt)("inlineCode",{parentName:"p"},"trials")," are displayed in what order. ",(0,a.kt)("inlineCode",{parentName:"p"},"timelines")," can contain other ",(0,a.kt)("inlineCode",{parentName:"p"},"timelines"),", which is why there may be several files in this directory. The ",(0,a.kt)("inlineCode",{parentName:"p"},"main.js")," file should have the timeline that is called by ",(0,a.kt)("inlineCode",{parentName:"p"},"App.jsx")," in the ",(0,a.kt)("inlineCode",{parentName:"p"},"")," component."),(0,a.kt)("h4",{id:"trials"},(0,a.kt)("inlineCode",{parentName:"h4"},"trials")),(0,a.kt)("p",null,(0,a.kt)("inlineCode",{parentName:"p"},"jspsych")," uses ",(0,a.kt)("inlineCode",{parentName:"p"},"trials")," as its base unit of an experiment. These trials do things such as display some stimulus or request a response."))}h.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[4825],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>m});var i=n(7294);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);t&&(i=i.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,i)}return n}function r(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(i=0;i=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var l=i.createContext({}),d=function(e){var t=i.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):r(r({},t),e)),n},p=function(e){var t=d(e.components);return i.createElement(l.Provider,{value:t},e.children)},c="mdxType",h={inlineCode:"code",wrapper:function(e){var t=e.children;return i.createElement(i.Fragment,{},t)}},u=i.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,l=e.parentName,p=s(e,["components","mdxType","originalType","parentName"]),c=d(n),u=a,m=c["".concat(l,".").concat(u)]||c[u]||h[u]||o;return n?i.createElement(m,r(r({ref:t},p),{},{components:n})):i.createElement(m,r({ref:t},p))}));function m(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,r=new Array(o);r[0]=u;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[c]="string"==typeof e?e:a,r[1]=s;for(var d=2;d{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>o,metadata:()=>s,toc:()=>d});var i=n(7462),a=(n(7294),n(3905));const o={id:"folders",title:"Project Organization"},r=void 0,s={unversionedId:"folders",id:"version-3.0.0/folders",title:"Project Organization",description:"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 definitely not mutated), 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. Below are descriptions of the main files and folders.",source:"@site/versioned_docs/version-3.0.0/folders.md",sourceDirName:".",slug:"/folders",permalink:"/honeycomb-docs/docs/3.0.0/folders",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.0.0/folders.md",tags:[],version:"3.0.0",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"folders",title:"Project Organization"},sidebar:"someSidebar",previous:{title:"Introduction",permalink:"/honeycomb-docs/docs/3.0.0/"},next:{title:"Quick Start",permalink:"/honeycomb-docs/docs/3.0.0/quick_start"}},l={},d=[{value:"package.json",id:"packagejson",level:3},{value:"assets/",id:"assets",level:3},{value:"env/",id:"env",level:3},{value:".github/workflows/",id:"githubworkflows",level:3},{value:"public/",id:"public",level:3},{value:"electron.js",id:"electronjs",level:4},{value:"config/",id:"config",level:4},{value:"src/",id:"src",level:3},{value:"App.jsx",id:"appjsx",level:4},{value:"App.css",id:"appcss",level:4},{value:"components/",id:"components",level:4},{value:"language/",id:"language",level:4},{value:"lib/",id:"lib",level:4},{value:"lib/markup",id:"libmarkup",level:4},{value:"timelines",id:"timelines",level:4},{value:"trials",id:"trials",level:4}],p={toc:d},c="wrapper";function h(e){let{components:t,...n}=e;return(0,a.kt)(c,(0,i.Z)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"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 definitely not mutated), 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. Below are descriptions of the main files and folders."),(0,a.kt)("h3",{id:"packagejson"},(0,a.kt)("inlineCode",{parentName:"h3"},"package.json")),(0,a.kt)("p",null,"The ",(0,a.kt)("inlineCode",{parentName:"p"},"package.json")," file contains metadata about your project and scripts to run tasks related to your task. The ",(0,a.kt)("inlineCode",{parentName:"p"},"name")," should be updated to your task's name and ",(0,a.kt)("inlineCode",{parentName:"p"},"scripts")," can be added as desired, but otherwise this file should not be edited manually. To remove or add a dependency use ",(0,a.kt)("inlineCode",{parentName:"p"},"npm install")," or ",(0,a.kt)("inlineCode",{parentName:"p"},"npm uninstall")," with the ",(0,a.kt)("inlineCode",{parentName:"p"},"-D")," flag if installing a dev dependency."),(0,a.kt)("p",null,"The ",(0,a.kt)("inlineCode",{parentName:"p"},"package-lock.json")," contains metadata about the package installation. It should never be manually updated."),(0,a.kt)("h3",{id:"assets"},(0,a.kt)("inlineCode",{parentName:"h3"},"assets/")),(0,a.kt)("p",null,"This folder contains any static files that are used by the app, such as the images used as icons for the installed applications."),(0,a.kt)("h3",{id:"env"},(0,a.kt)("inlineCode",{parentName:"h3"},"env/")),(0,a.kt)("p",null,"This folder contains different .env files with presets for common use cases. These files can be loaded with ",(0,a.kt)("inlineCode",{parentName:"p"},"dotenv"),", which is explained in greater detail in the ",(0,a.kt)("a",{parentName:"p",href:"/honeycomb-docs/docs/3.0.0/configuration"},"Configuration")," section."),(0,a.kt)("h3",{id:"githubworkflows"},(0,a.kt)("inlineCode",{parentName:"h3"},".github/workflows/")),(0,a.kt)("p",null,"This folder contains different .yaml files which are used to configure the build tests (",(0,a.kt)("inlineCode",{parentName:"p"},"build.yaml"),") following a push and to create task executables either in a single instance (",(0,a.kt)("inlineCode",{parentName:"p"},"package.yaml"),") or for a full release (",(0,a.kt)("inlineCode",{parentName:"p"},"release.yaml"),")."),(0,a.kt)("h3",{id:"public"},(0,a.kt)("inlineCode",{parentName:"h3"},"public/")),(0,a.kt)("p",null,"The ",(0,a.kt)("inlineCode",{parentName:"p"},"public")," directory contains files that are used as assets in the built app. The ",(0,a.kt)("inlineCode",{parentName:"p"},"favicon.ico")," is the small icon you can see in the browser tab (on Chrome) - it is set to Brown's logo in the project. The ",(0,a.kt)("inlineCode",{parentName:"p"},"index.html")," contains the shell of your website - the name displayed on the tab can be changed here, otherwise it shouldn't need to be edited. The scripts included in the file are for ",(0,a.kt)("inlineCode",{parentName:"p"},"psiturk")," as are the files in the ",(0,a.kt)("inlineCode",{parentName:"p"},"lib/")," directory."),(0,a.kt)("h4",{id:"electronjs"},(0,a.kt)("inlineCode",{parentName:"h4"},"electron.js")),(0,a.kt)("p",null,"This file contains all of the code relating to the Electron app. This includes the event-marker, throwing errors via dialog windows, saving data, and reading files."),(0,a.kt)("h4",{id:"config"},(0,a.kt)("inlineCode",{parentName:"h4"},"config/")),(0,a.kt)("p",null,"The ",(0,a.kt)("inlineCode",{parentName:"p"},"config")," directory contains the config files needed for the electron app. This includes the event-marker details and event codes."),(0,a.kt)("p",null,"In the ",(0,a.kt)("inlineCode",{parentName:"p"},"config/")," directory, there are ",(0,a.kt)("inlineCode",{parentName:"p"},".js")," files which contain settings for the different parts of the task. Every task should have a ",(0,a.kt)("inlineCode",{parentName:"p"},"main")," config and a ",(0,a.kt)("inlineCode",{parentName:"p"},"trigger")," config (assuming use of the event marker). The ",(0,a.kt)("inlineCode",{parentName:"p"},"main")," config has all global settings for the task (such as whether it is in mturk mode or not), load the appropriate language file, and set up a default (or only) configuration object for the task. Different in-task features can be loaded from .env files and is set in the ",(0,a.kt)("inlineCode",{parentName:"p"},"main")," config. For example, we have included some of these files in the ",(0,a.kt)("inlineCode",{parentName:"p"},"env")," directory (e.g. ",(0,a.kt)("inlineCode",{parentName:"p"},"env.clinic")," file enables event marker, photodiode and volume adjustment). The ",(0,a.kt)("inlineCode",{parentName:"p"},"trigger")," config has settings specific to the event marker and uses a slightly different style of javascript as it is imported both in the React app as well as the electron process."),(0,a.kt)("p",null,"Other config files can be used to add settings for specific blocks or sub-sections of the experiment. Also, ",(0,a.kt)("em",{parentName:"p"},"note that the productId can be overwritten by the environment variable EVENT_MARKER_PRODUCT_ID"),"."),(0,a.kt)("h3",{id:"src"},(0,a.kt)("inlineCode",{parentName:"h3"},"src/")),(0,a.kt)("p",null,"This folder contains the code for the app, the vast majority of changes and code should go here."),(0,a.kt)("h4",{id:"appjsx"},(0,a.kt)("inlineCode",{parentName:"h4"},"App.jsx")),(0,a.kt)("p",null,"This is the starting point for the app. The ",(0,a.kt)("inlineCode",{parentName:"p"},"")," component handles user authentication in the different use cases and the ",(0,a.kt)("inlineCode",{parentName:"p"},"")," component initializes the ",(0,a.kt)("inlineCode",{parentName:"p"},"jspsych")," 7 experiment. This is also where communication is set up with the ",(0,a.kt)("inlineCode",{parentName:"p"},"electron")," and ",(0,a.kt)("inlineCode",{parentName:"p"},"psiturk")," processes."),(0,a.kt)("h4",{id:"appcss"},(0,a.kt)("inlineCode",{parentName:"h4"},"App.css")),(0,a.kt)("p",null,"This is where styling for the app is housed. If colors, fonts, spacing, etc. need to be set, do it here."),(0,a.kt)("h4",{id:"components"},(0,a.kt)("inlineCode",{parentName:"h4"},"components/")),(0,a.kt)("p",null,"This folder contains the components referenced in ",(0,a.kt)("inlineCode",{parentName:"p"},"App.jsx"),". This includes the Honeycomb ",(0,a.kt)("inlineCode",{parentName:"p"},"")," component which connects the Honyecomb login page to your ",(0,a.kt)("inlineCode",{parentName:"p"},"jspsych")," 7 experiment."),(0,a.kt)("h4",{id:"language"},(0,a.kt)("inlineCode",{parentName:"h4"},"language/")),(0,a.kt)("p",null,"Any language that is displayed in the experiment should be stored in this folder. Usage of language json files allows for easy internationalization of the task (e.g. English and Spanish) as well as allows for mturk-specific language. This also makes it easy to re-use common phrases in many places in the task."),(0,a.kt)("h4",{id:"lib"},(0,a.kt)("inlineCode",{parentName:"h4"},"lib/")),(0,a.kt)("p",null,"The ",(0,a.kt)("inlineCode",{parentName:"p"},"lib/")," directory contains utility functions and markup that is used in the tasks. This allows for functions and html to be re-used wherever needed. The ",(0,a.kt)("inlineCode",{parentName:"p"},"lib/utils.js")," file contains functions that are generally useful across many tasks, whereas ",(0,a.kt)("inlineCode",{parentName:"p"},"lib/taskUtils.js")," contains functions specific to this task."),(0,a.kt)("h4",{id:"libmarkup"},(0,a.kt)("inlineCode",{parentName:"h4"},"lib/markup")),(0,a.kt)("p",null,(0,a.kt)("inlineCode",{parentName:"p"},"markup")," files should contain primarily templates for HTML that are used throughout the task. Typically this will be a function that takes in some parameters and then returns a string with html."),(0,a.kt)("h4",{id:"timelines"},(0,a.kt)("inlineCode",{parentName:"h4"},"timelines")),(0,a.kt)("p",null,(0,a.kt)("inlineCode",{parentName:"p"},"jspsych")," uses ",(0,a.kt)("inlineCode",{parentName:"p"},"timelines")," to control what ",(0,a.kt)("inlineCode",{parentName:"p"},"trials")," are displayed in what order. ",(0,a.kt)("inlineCode",{parentName:"p"},"timelines")," can contain other ",(0,a.kt)("inlineCode",{parentName:"p"},"timelines"),", which is why there may be several files in this directory. The ",(0,a.kt)("inlineCode",{parentName:"p"},"main.js")," file should have the timeline that is called by ",(0,a.kt)("inlineCode",{parentName:"p"},"App.jsx")," in the ",(0,a.kt)("inlineCode",{parentName:"p"},"")," component."),(0,a.kt)("h4",{id:"trials"},(0,a.kt)("inlineCode",{parentName:"h4"},"trials")),(0,a.kt)("p",null,(0,a.kt)("inlineCode",{parentName:"p"},"jspsych")," uses ",(0,a.kt)("inlineCode",{parentName:"p"},"trials")," as its base unit of an experiment. These trials do things such as display some stimulus or request a response."))}h.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/345c7eb3.6d58b5ed.js b/assets/js/345c7eb3.05955795.js similarity index 99% rename from assets/js/345c7eb3.6d58b5ed.js rename to assets/js/345c7eb3.05955795.js index 97f8f2e8..161d5e16 100644 --- a/assets/js/345c7eb3.6d58b5ed.js +++ b/assets/js/345c7eb3.05955795.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[7107],{5162:(e,t,a)=>{a.d(t,{Z:()=>r});var n=a(7294),i=a(6010);const l={tabItem:"tabItem_Ymn6"};function r(e){let{children:t,hidden:a,className:r}=e;return n.createElement("div",{role:"tabpanel",className:(0,i.Z)(l.tabItem,r),hidden:a},t)}},4866:(e,t,a)=>{a.d(t,{Z:()=>N});var n=a(7462),i=a(7294),l=a(6010),r=a(2466),o=a(6550),s=a(1980),p=a(7392),u=a(12);function m(e){return function(e){return i.Children.map(e,(e=>{if(!e||(0,i.isValidElement)(e)&&function(e){const{props:t}=e;return!!t&&"object"==typeof t&&"value"in t}(e))return e;throw new Error(`Docusaurus error: Bad child <${"string"==typeof e.type?e.type:e.type.name}>: all children of the component should be , and every should have a unique "value" prop.`)}))?.filter(Boolean)??[]}(e).map((e=>{let{props:{value:t,label:a,attributes:n,default:i}}=e;return{value:t,label:a,attributes:n,default:i}}))}function d(e){const{values:t,children:a}=e;return(0,i.useMemo)((()=>{const e=t??m(a);return function(e){const t=(0,p.l)(e,((e,t)=>e.value===t.value));if(t.length>0)throw new Error(`Docusaurus error: Duplicate values "${t.map((e=>e.value)).join(", ")}" found in . Every value needs to be unique.`)}(e),e}),[t,a])}function c(e){let{value:t,tabValues:a}=e;return a.some((e=>e.value===t))}function h(e){let{queryString:t=!1,groupId:a}=e;const n=(0,o.k6)(),l=function(e){let{queryString:t=!1,groupId:a}=e;if("string"==typeof t)return t;if(!1===t)return null;if(!0===t&&!a)throw new Error('Docusaurus error: The component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".');return a??null}({queryString:t,groupId:a});return[(0,s._X)(l),(0,i.useCallback)((e=>{if(!l)return;const t=new URLSearchParams(n.location.search);t.set(l,e),n.replace({...n.location,search:t.toString()})}),[l,n])]}function k(e){const{defaultValue:t,queryString:a=!1,groupId:n}=e,l=d(e),[r,o]=(0,i.useState)((()=>function(e){let{defaultValue:t,tabValues:a}=e;if(0===a.length)throw new Error("Docusaurus error: the component requires at least one children component");if(t){if(!c({value:t,tabValues:a}))throw new Error(`Docusaurus error: The has a defaultValue "${t}" but none of its children has the corresponding value. Available values are: ${a.map((e=>e.value)).join(", ")}. If you intend to show no default tab, use defaultValue={null} instead.`);return t}const n=a.find((e=>e.default))??a[0];if(!n)throw new Error("Unexpected error: 0 tabValues");return n.value}({defaultValue:t,tabValues:l}))),[s,p]=h({queryString:a,groupId:n}),[m,k]=function(e){let{groupId:t}=e;const a=function(e){return e?`docusaurus.tab.${e}`:null}(t),[n,l]=(0,u.Nk)(a);return[n,(0,i.useCallback)((e=>{a&&l.set(e)}),[a,l])]}({groupId:n}),g=(()=>{const e=s??m;return c({value:e,tabValues:l})?e:null})();(0,i.useLayoutEffect)((()=>{g&&o(g)}),[g]);return{selectedValue:r,selectValue:(0,i.useCallback)((e=>{if(!c({value:e,tabValues:l}))throw new Error(`Can't select invalid tab value=${e}`);o(e),p(e),k(e)}),[p,k,l]),tabValues:l}}var g=a(2389);const b={tabList:"tabList__CuJ",tabItem:"tabItem_LNqP"};function y(e){let{className:t,block:a,selectedValue:o,selectValue:s,tabValues:p}=e;const u=[],{blockElementScrollPositionUntilNextRender:m}=(0,r.o5)(),d=e=>{const t=e.currentTarget,a=u.indexOf(t),n=p[a].value;n!==o&&(m(t),s(n))},c=e=>{let t=null;switch(e.key){case"Enter":d(e);break;case"ArrowRight":{const a=u.indexOf(e.currentTarget)+1;t=u[a]??u[0];break}case"ArrowLeft":{const a=u.indexOf(e.currentTarget)-1;t=u[a]??u[u.length-1];break}}t?.focus()};return i.createElement("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,l.Z)("tabs",{"tabs--block":a},t)},p.map((e=>{let{value:t,label:a,attributes:r}=e;return i.createElement("li",(0,n.Z)({role:"tab",tabIndex:o===t?0:-1,"aria-selected":o===t,key:t,ref:e=>u.push(e),onKeyDown:c,onClick:d},r,{className:(0,l.Z)("tabs__item",b.tabItem,r?.className,{"tabs__item--active":o===t})}),a??t)})))}function f(e){let{lazy:t,children:a,selectedValue:n}=e;const l=(Array.isArray(a)?a:[a]).filter(Boolean);if(t){const e=l.find((e=>e.props.value===n));return e?(0,i.cloneElement)(e,{className:"margin-top--md"}):null}return i.createElement("div",{className:"margin-top--md"},l.map(((e,t)=>(0,i.cloneElement)(e,{key:t,hidden:e.props.value!==n}))))}function v(e){const t=k(e);return i.createElement("div",{className:(0,l.Z)("tabs-container",b.tabList)},i.createElement(y,(0,n.Z)({},e,t)),i.createElement(f,(0,n.Z)({},e,t)))}function N(e){const t=(0,g.Z)();return i.createElement(v,(0,n.Z)({key:String(t)},e))}},5340:(e,t,a)=>{a.r(t),a.d(t,{assets:()=>h,contentTitle:()=>d,default:()=>y,frontMatter:()=>m,metadata:()=>c,toc:()=>k});var n=a(7462),i=(a(7294),a(3905)),l=a(4866),r=a(5162),o=a(614);const s=a.p+"assets/images/clone-code-button-e90c329a7e167ff0f79391cd79af8cc1.webp",p="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAXQAAACFCAYAAABL2gNbAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAAEnQAABJ0Ad5mH3gAABXESURBVHhe7d0PWFRlvgfwr6GojISwCP4DScAdrER9HL1JFlqxPSt2V9y6aIusqdlqulqrm6WV5WZP7Zrprj4ZZkKFm1fcFCOp/JNBq7i4WOqkkCDqCiHIxVFE3L3ve84ZHGBE0YE5Hr6fZ2fnPefAzAF3v/Ob3/ueoV1wcPB/QEREt7zbtHsiIrrFMdCJiAyCgU5EZBAMdCIig2CgExEZhO4D3ce/I+4bG4zIEYHaHiIickbXyxZlkN83to+2BVSWVSNvdwm+2nRc20NERHa6DPQ+Zh888mQ/UZ13Ura/2lSk3NvDXQb75tVHUGStVLaJiEhngS7bK488+VMl0KW83aex5d2jyliSx2XrxR7s8ris1ivLLirbRERtmS4CvWFQX6sCdwx+tmGIiFRuD3THPnlzw1l9EQhWWjMMdiJq69wW6A3bK7JPfiNh7Ky6T37tgLhnG4aI2ha3BXrC/AHoE+GjtFU2r/7+pgPYMdjlY6aIUCciakvctg49WFTm9uC9njCXgS1vsqKXNzl2JB9DVvhFhyvVqr+ddoCIqI3Q5YVFC5JHYOZSi7al9tlnLh2q3BKeH6Dc1G1LXcuGiKit0/2VovZJU9kbV/vsRcpyRVndy8lQdb16/WqdiKgtclsP/YV1I3D8e+e9blmhywBf8UwOZv7JAp9unbDi2b2o/LF+a0ZW6rJCd5xQtffmFyfuBlrsJ4vFnDfuR892p7Br3lv4IvQBPD42GmE/6YT2HuLw5WqUF+diy5pN+K5a/Y5OP3saLz3YB+0hvmfhW0jX9tcXgEfnzcXQbkDVgTV4JcUq9onnelM8l/w+8Vy7Bo7FlDFD0dO7vfIdtVWnsHdLEjbtr1K2+0Qn4rH7zAjQjuNiFU7lpiMpLRfqV1wxeNIrGN+/M6oPpWJhag3GTovD8N7eyrFT2+firQxlqPIZjNi4BzA41A/eHbXHvlyLqjOFyN3yDtLlqRKRW+m+Qj+r9dcj7w1s1F6Rk6kyzGXf3F06DJmMedMehvknIuRqa+V/AI9O8AsZjsR5iRisfhmqtx1AofKj9ER4jHoFbCP9HkCoCHOgFN9+3jghO4+Zg+cnDEdPT/FUF8VzXQbae/fE8AlzMNnSCX0emYOnRt+FAK8rx9HRGz3vGY85ifYzcaYLYp96vC7MFR20e6FP9DS8OH887u8foIS58tjyJl6evAPCEN6PExZEeuDh4+PzsjZuVUob5cxFHNhdou25Qh67eL4We7edQpH1LIb9rJeourvWrWKR94HBJnQVlbtce15y3KZ9p7o2Xe7/6m8tuR69H+55KATe7Tqjx08DUGvdhOV/fh+bM7/El1/uxjEvMwYGe+O2jn64/bYs7C2QKV+EjqH3IUIEv3dncd7ZVlw5a5X553GICuyI2qK/I2l7vghMSTxXjHgudEZgr444uXMN/rR6A7ZtF8+VY0PPu8MR0Lkz/IMtiAj3R23+Z3j/7XexQZ7LF3+HLXgwIvw7omNAILp8mw3rOeVBFT0GjcTd3Tqg9j++6N3tEvI//wgr30lF+uef4+/fa180OBGz4szi5xAvSieysWH5cnyQIR5bPr94/DPe4fC79A32X7mgl4jcRPcVuly9suKZvWolbq1UWjGydx45orsS7hOfHyDug7Wvbm2iKj/5Gd5Ym43SuhZKNfI/WYVdRZfEuL14V/GgulvIzsrH/8mBqGqjuiu7HAxGVKiskGtx0vqZeJSGRGVc+DmSMvKvHKvMxrq/WdXH9PaGd+V3+PidL5Ff9wVVyP5wL5RTgR963eW8ku4UcDtOfPoW1nxhbdCWCcDYB+7C7WJUe3IXkt7ehNx6b4aqkJsmvm+rtklEbqX7QLe3WWSPXPbbZV9dBrw95NVwD3TTMsVaFOZtdxK+1cg9rcQsYPJGmDoCDu3B8bNyEICw4QHKrjr3WBBiEvfVhcj9Qt1VXzUKc3c3fq5Dx+peTMqtGWjUqKnORYnynO3RwUvZ05itEDm7G/8UsgVkVk6zFHvXp4v3GESkZ7oOdLl6RU5yyircMbBl1S5vst0iJz5lqLtHKU5+7XzmtbRGm8D19FIqXJUVGYfVFlNA+P0i1q8YflcvyJ+i6sguZKu7GihHyT5nz3VO7duLqC8t+lHZU18pLtQ0PTtcWyZeRLRxPebuoq4XKk7g29PKHiLSMV0Hugxt+/LEMVPClWrdfoGRrMrlRwfIoJfLGFtuRYtrlWYXiIgV/MNwf13b5T7cHdxZ3DufDL1uchL0BtTaKrTRVZyvQr42JCL90n3LZfO73yuhLnvmVy4oGooxU/spAS976o4fsat7pzPwbZEsqf0QNkprxjw4AH1EeV5b9C0y9FgJe3RQ3j0Qkb7dEpOisne+5d0jyk1W4+rnoBfV9dQdddX9RUbV+Mx6EnKe0i/EgjARlQ+be6GDnAw9urNxj9ydKs6rK238eyGaiU6ke24L9OOi6pYV9pip4UoL5Vpkv1zeZDUub8rntojHsJOPoTyWspRR5y2YL3JRdEHc+4bA0v9BRPRpr06GbtNVnAO7v0WhPKX2fTB0/FBW6UQ657ZAd2yl2Jce2gNeKjysLM24LvbPepGP5coWTCdLIl58/U28uSARQ12aZtnIOSYT3Q8hMeHK5OjVJ0PdKRuf5ZxSqnTv/mMxZ9IDCHP8PXQKwNC4OZg8WtsmIrdyW6A7tlIkuaZc9shlKEsHditTh02SE6PyYwKUi5S0z3pp2IK5Gf3vCoO3vJTf5y5EjXTtusjcPQXKmm+/Xj3R/mYnQ1tQ0eZV2LS/XIR6e/j1fxjTXn0TSxYvUW8vz8Wj9/TE7R5uWTNKRA24vYcu2yjyD1LY++P23rhjO6UhZTmjCH85MSrZg/xG/kBGUw59l48quXKk8jtk7XBxD+dQBg6XaePSfGTpdllgNfZ+tASvfbQL1tNV6scNdGyv3FBbhdIDnyFj1y2yxIjI4HTxN0Ubsi9LlPcypGU177hfVuSSDH1X/HEMIiIj0G2gN/wj0JI9yOW+pv6INBFRW6TLQLeTk51qpa7OxNnD3dWtFSIiI9B1oEuyWg+J6FrXfiEiIud0H+hERHR9dH+lKBERXR8GOhGRQTDQiYgMgoFORGQQDHQiIoNgoBMRGQQDnYjIILgOXSd69FA/1qChf/2Lf5qZiK4PK3QiIoNgoBMRGQQDnYjIIBjoREQGwUAnIjIIBjoRkUEw0ImIDIKBTkRkEAx0IiKD4JWiDXj85E5EjxqKMD9PsVWFg2kf4esf1WMtiVeK3jjf6OlY+EQMzP7y38yGnD8+hpe2X+t/1r6Injwb40dFIshXfp/mQgWKrVnYuGodMk/YtJ0tQ573AnHeEXXn/She3g44PfOpy/Hp2DBt4zr8kIafP52kbbiOPOe5E6LQv4cvPD3UfTUVxcjbnopla3aiQt1FbsIK3c77Dtz73wmY8st7tTAnvTMNiMei1Rvw4bxYLcyvkykGL6z7EPPGWeqHudTZF0GDYjF71WosiDFpO13L8bzVML8VmBAz9z2sFec8sPeVMJc8fYNgGTcPa9+eArO2j9yDFbp3TwyOioalj7e6fe44Dp7xx519vMQGK3Q9Mg2IxdTJiYgJ1wLXVoCcU91hUbavVaGbEL/0Q0w0iyCtKUHellQkfZKJgjJxyD8Uwx+aiKn/Y0GgzFlbHlY+9jzS/+Oa/4tc+7ybqNDFuUUGddE2rsLTginz4hDaWTza/pV49IV07cDNC5q8AsvHhaKjGNcU7kTye+8ibV8FfMNjMP7pqYjVfqaKPcswbVEmzilb1NrafIXeNWKEGub/rkHZd5n4KDUD1qrL2lHSo/4/j9dCsQYle5Ix/9czsaP8KkHYkGk8omSYCyXbX8Tza7Qwl8oKkJ36Ep7eWqA+likYA+9VjrhE/9Hj8VCj877OFwtxbnn785q8XRwWhb4izMVPhqwPtirf5hqxmP6wGuY4lYn5M95QwlyqOJqJlb9diLQfapRt32HjMPGOdsqYWl+bD/Sz/8zD8fLj+DotGRuzjqHq39oBaiGxeO3jT/Hpp+KWvAAWba8zQbPeU7/u0w1YMlq8ndT256zfKUK4AOlvPIFJi9Yjrzmt7mG90V0bnrtQrI3qs5WdE5EreaJDB2XgEjmpO1DwozzvSVfO2zXFvxCLxBGByu+oxroNSVaXPTBMCaMQoRTgNuRtWobGD21FUso+qK9NQbA8GqnspdbHHnqNFRkbMnDwDKvy1pGO7CPaG3L/CPxsmDpsLBLxAwPVYVke0kTBWZcjhUmYOXEmVu4UZXlz/XC2rh0QFDERJifFpMUcLKJcOoeKY8rANcR5z0qU5+36qcOgGbGIVEK3Avv+uh7nXJfnGDOor/r7qDyEbY7/DnamSEz8ZST8tN9lYMhwqA0Yam0MdGp16VvytNUQvoh8JBbtnL1DHzYGkYHqgYrD25CjjFygcCNyTqhDT3McVsyNqRc+vqNfxuwRvmqlezQLaYUuTMYWE4vf3B+sjGR1/tYeZegiwxGmTCgIpcXYqY7qyAne11YuQfydDr9F30BEaUNqXQx0an170pFXog5N/aIwuq6ZcoVlVAR8ld3FyFq/T9nnGsVYuTQN+efl2BOB0bPxYdIixA8IQvTsd7B2xlDxMiNU5CF5VRKO3wJ5HjRDvPgp86U25KWniP92pe4wdVJHtvJ8daAxj3sNq/8wEQO7iY2aElgLtWf28YP68kKtjYFObpCH1H3F2sRjBKJ+oex0EIu4wWqVjB9ykOzqKtmahFlPrUT2Ka1T3tOCia+/g3kxQUprwXY0HYunzUeaVTmsc7GYHh2k/q5O7MCaHa5+BfJDF2Wi1ZEZcS+txeuTB8LXQ2Z5NlZOmYSFB85ox8ldGOjkFsXvZ8F6UY48ETEioX7PdbR4m6/sqIF1TypsLVElXyhHeYVNm/ysz+QfgYF3X2OJoE4ETY25MmH5yUoUt/Q7Cv9YvPDe65gyLFD8y8nVOkl4btJipJeJM7js7LdJrYmBTu5h24i8H5REh2ffgRjnkOhx90aoAW87jO0pNtctBNGYBkzH8nULEHunLzwv21CwdRlm/nYZ0vaXqAHvG4rYhWuxNMHspBmkJ9GYPDJUnbA8lYV1ziYsb1o5zl3QhoGPYG3SdER1F894uQJ5a57DpEVpsL+RGR7op43IXRjo5CY2JG8/rPZ7Pc2wTDBp4RmPKLOy4hm2I1lw3aUxGlMcFiyMRZi8bqwiByufeAwz/5KJgqOZSHphEh5/bj2sykmZYB7/e8wdpt9ID5o6DpFd5fmJdzK7kuqC1bXKUaMV3qYQs3rBVVkekl94EvM31n/G7ibtVbmyHPW77dRaGOjkPlszcahSHYZaEhEkssmUMBR9lTwXFeBmV14cozJNiNaW99mQ99FL2Ppj/ZrWdiAZz/wxW1tTHYjImHuU/foTjSmjtIt9yvYh9YOWujZzJ4pLtaFgO7ge838zH+sPNJx6jURoE6thqHUw0MmNdiL9QIXaJugdidiQLhg3qK92RWIOkve6voFg6WG/rKgcxSJ1nD7DntPiqMo3sL82ck5ezj/7Dyuw9KUpiPbXdrYCU8IYRPrIUQ0Kdq/Dvmb+qppz3tuO2C/AEi+y/5vs/EIuh2WmxUcylXtqfQx0cquc1CxtIi8IkWMmYmBftcor3r+xRSb4av5tn7gLRMQEbXVIA6axoeiuHagoOaQOnAmZgiWLpiNmUCjMw+Iw7+0FiHb2gC5nwewHzWrv3HYY297VVgxdr2aed/HWHBSokwsYkjAF5kZfa8aUhCHqhUU1VmStc34FLrU8BvptnvDy9oa34629/aPkPOBhcjzmBU/+xlyrcAsOnFDjKGhUDJQ8l6HwfhMhZQqCeVAkIh1ucp7OnjOe3QY4HDMjyGHCNTs7X1un7YnQsUuxfEYMzL21L/APRczkJfhzYiTUNS4lyMv8Rhk59VAkQtV2v8o3EiNHNpGMzs7b4fs9u0ViQN2x+uftyJQwHkO6qc9TvHNV8+cZmnvehUnY+A/1nZRn3zi8uky8GIQrq/WVD+ea/variFP/4VCwdTVSXHmZKjULP22x272YEHcntM9avIaW+/TFtvxpi6aEP+HD8RFqxSnUWJPxi2fWa1tOjHoZG3439DovL2/4KYYmDJ+1FPMeVtecX50N1tSFeDbFevUXltFL8PEMe/hLxUif8RRWHrvKd4xahI9/Z3H4+qZc7dMXLViQvAjDZZvEloekSc8jrbkB2tzzVogqfNkSxPVzfCWor+KbZXjy1UztBZPcgfUmuZ0tJQuH7UvjRBwc/vKv2rgl2JC9fBomvZiEzIMlsNU9r6qmsgQFe9Kw7Mlf45mmwlzauhhJO47DJj8G6HKFeAF4C6uaDMWbZ0qIxxCt512Sk4ZNN1IN39B5W5E0+1eYvy4bxRUO680v18BWYkX6G4/jcYa527FC1wl+HjoR3SxW6EREBsFAJyIyCAY6EZFBMNCJiAyCgU5EZBAMdCIig2CgExEZBAOdiMggGOhERAbBK0WpVXl5yb8sQUQtgRU6EZFBMNCJiAyCgU5EZBDsoVOrathDP3/+vDYiopvFCp2IyCAY6EREBsFAJyIyCAY6EZFBMNCJiAyCq1w0Xv1jkPBYLIaFBsCrg7az+ixOHtyOv/7lY+zlYgyX4CoXopbDQEdXxMx+BQn/FQB7jjdSXYiti+cjJZ+vfTeLgU7UcthyGf10XZif/2EHUl5/CvHx8Yif8To+/kcpLsmv6RSCmKm/Qi85JiLSKQ8fH5+XtXHbdHQfzt5xD3pY38HcNzbj0Olqdf+F0zicfQBdhoxEv64e8OjaFV2OZGBviXqYbkyHDvXfB126pLxkEpELsELHeex4cxaeXb1XjBo6iZSDJ7VxAHrdDbTTtoiI9IaB3hz8bRGRjjGirsHLw94iOI+zxQCnRYlIrxjoTeqF+Lu1qdDzx5C7Ux0SEekRA70J4QkzEd1L7ZqX7t+CTGVERKRPDPSr8Ir+PZ4dHQJPufFjFt778z+V/UREesVAd8Kr/xNY+MQgdJUb8qKit1fgn2yeE5HOMdAbkGH+4vwY3CFL80v2K0TVY0REesZAd+BlmYZXRJiHyIUtsjJf9Bwv9yeiWwYDXSPD/NVZI9HbHuaszInoFsNAF5TKXIR5L+UDXY4ibTErcyK69bT5T1u0V+ZqmBci84MU7ClTjzljO3kQhWe0DWo2ftoiUctp84Ee9bs1mDnEpG1dW+HW8XguhdX7jWKgE7UctlyIiAyCf+CCWhUrdKKWwwqdiMggGOhERAbBQCciMggGOhGRQTDQiYgMgqtcqFU1XOVCRK7DCp2IyCAY6EREBsFAJyIyCPbQiYgMghU6EZFBMNCJiAyCgU5EZBAMdCIig2CgExEZBAOdiMggGOhERAbBQCciMggGOhGRQTDQiYgMgoFORGQQDHQiIoNgoBMRGQQDnYjIEID/B504qs9kmFTXAAAAAElFTkSuQmCC",u=a.p+"assets/images/workflow-permissions-e7b2dd2b9b729493bc61a15033a45d45.png",m={id:"quick_start",slug:"/quick_start",title:"Quick Start",description:"Quick start guide for Honeycomb"},d=void 0,c={unversionedId:"quick_start",id:"version-3.1.x/quick_start",title:"Quick Start",description:"Quick start guide for Honeycomb",source:"@site/versioned_docs/version-3.1.x/quick_start.mdx",sourceDirName:".",slug:"/quick_start",permalink:"/honeycomb-docs/docs/3.1.x/quick_start",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/quick_start.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"quick_start",slug:"/quick_start",title:"Quick Start",description:"Quick start guide for Honeycomb"},sidebar:"mySidebar",previous:{title:"Introduction",permalink:"/honeycomb-docs/docs/3.1.x/"},next:{title:"Project Organization",permalink:"/honeycomb-docs/docs/3.1.x/project_organization"}},h={},k=[{value:"Creating Your Task Repository",id:"creating-your-task-repository",level:2},{value:"Cloning the Repository",id:"cloning-the-repository",level:2},{value:"Installing Prerequisites",id:"installing-prerequisites",level:2},{value:"Initial Install",id:"initial-install",level:3},{value:"Setting Up Node",id:"setting-up-node",level:3},{value:"Install Dependencies",id:"install-dependencies",level:2},{value:"Run the Task in Development Mode",id:"run-the-task-in-development-mode",level:2},{value:"Saving data",id:"saving-data",level:3},{value:"Edit the Task",id:"edit-the-task",level:2},{value:"Next Steps",id:"next-steps",level:2}],g={toc:k},b="wrapper";function y(e){let{components:t,...m}=e;return(0,i.kt)(b,(0,n.Z)({},g,m,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("h2",{id:"creating-your-task-repository"},"Creating Your Task Repository"),(0,i.kt)("p",null,"The Honeycomb repository is a template and serves as the starting point for all tasks. Creating your repository from the template starts your project with the same directory structure and files as an existing repository."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Go to the ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/brown-ccv/honeycomb"},"Honeycomb repository"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Click on ",(0,i.kt)("inlineCode",{parentName:"p"},"Use this template")," and select ",(0,i.kt)("inlineCode",{parentName:"p"},"Create a new repository"),".\n",(0,i.kt)("img",{alt:"Use this template",src:a(8867).Z,width:"2408",height:"1212"}))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Enter the owner, name, and description of your repository and click on ",(0,i.kt)("inlineCode",{parentName:"p"},"Create repository from template"),".\n",(0,i.kt)("img",{alt:"Create repository",src:a(1203).Z,width:"2408",height:"1212"})),(0,i.kt)("admonition",{parentName:"li",type:"note"},(0,i.kt)("p",{parentName:"admonition"},"We recommend creating a public repository and leaving ",(0,i.kt)("inlineCode",{parentName:"p"},"Include all branches")," unchecked"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},'Ensure the repositories workflow permissions are set to "Read and write permissions"'),(0,i.kt)("p",{parentName:"li"},(0,i.kt)("em",{parentName:"p"},(0,i.kt)("inlineCode",{parentName:"em"},"Settings -> Actions -> General -> Workflow permissions"))),(0,i.kt)("img",{src:u,alt:"GitHub workflow permissions settings"}))),(0,i.kt)("p",null,(0,i.kt)("em",{parentName:"p"},"Additional details about template repositories can be found on the ",(0,i.kt)("a",{parentName:"em",href:"https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template"},"Github Docs"),".")),(0,i.kt)("h2",{id:"cloning-the-repository"},"Cloning the Repository"),(0,i.kt)("p",null,"With the repository now setup it can be cloned onto your computer."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Navigate to the repository on ",(0,i.kt)("a",{parentName:"p",href:"https://github.com"},"GitHub"),".")),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Click the ",(0,i.kt)("inlineCode",{parentName:"p"},"Code")," button and copy the URL"),(0,i.kt)("img",{src:s,alt:"GitHub clone repo button"})),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Open a terminal and navigate to where you want the cloned directory"))),(0,i.kt)(l.Z,{groupId:"os",queryString:!0,defaultValue:"mac",mdxType:"Tabs"},(0,i.kt)(r.Z,{value:"win",label:"Windows",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Powershell"',title:'"Powershell"'},"cd 'path/to/directory'\n"))),(0,i.kt)(r.Z,{value:"mac",label:"macOS",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Terminal.app"',title:'"Terminal.app"'},"cd 'path/to/directory'\n")))),(0,i.kt)("ol",{start:4},(0,i.kt)("li",{parentName:"ol"},"Clone the repo with the following command")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:"title='Paste the URL you copied earlier'",title:"'Paste",the:!0,URL:!0,you:!0,copied:!0,"earlier'":!0}," git clone https://github.com//\n")),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"Git can be downloaded ",(0,i.kt)("a",{parentName:"p",href:"https://git-scm.com/book/en/v2/Getting-Started-Installing-Git"},"here")," if it is not already on your system.")),(0,i.kt)("p",null,(0,i.kt)("em",{parentName:"p"},"Additional details and alternative methods for cloning a repository can be found on the ",(0,i.kt)("a",{parentName:"em",href:"https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository?tool=webui"},"Github Docs"),".")),(0,i.kt)("h2",{id:"installing-prerequisites"},"Installing Prerequisites"),(0,i.kt)("p",null,"All of the needed programs for Honeycomb must be installed before we can develop our task. We will use a ",(0,i.kt)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Package_manager"},"package manager")," to automatically install them."),(0,i.kt)("p",null,"See ",(0,i.kt)("a",{parentName:"p",href:"prerequisites"},"Prerequisites")," for more information about these programs."),(0,i.kt)("h3",{id:"initial-install"},"Initial Install"),(0,i.kt)(l.Z,{groupId:"os",queryString:!0,defaultValue:"mac",mdxType:"Tabs"},(0,i.kt)(r.Z,{value:"win",label:"Windows",mdxType:"TabItem"},(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Run Powershell as an admin from the start menu"),(0,i.kt)("p",{parentName:"li"},(0,i.kt)("img",{alt:"Powershell admin launcher",src:a(5440).Z,width:"783",height:"679"}))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Navigate to the root directory of your cloned repository")),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Paste the following command and follow the prompts to install the listed programs:"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"./winget.ps1\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},'The "Visual Studio Installer" will open a GUI during installation. Make sure "Desktop Development with C++" is checked before continuing.')))),(0,i.kt)(r.Z,{value:"mac",label:"macOS",mdxType:"TabItem"},(0,i.kt)("p",null,"The most commonly used package manager on macOS is ",(0,i.kt)("a",{parentName:"p",href:"https://brew.sh"},"Homebrew"),"."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Paste the following command in a macOS Terminal and follow the prompts to install Homebrew."),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"/bin/bash -c '$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)'\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Paste the following command and follow the prompts to install the listed programs:"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"brew bundle\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Install Xcode (not available on Homebrew)"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"xcode-select --install\n")))))),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"If you are running into issues after installing the packages please restart your terminal and/or reboot your computer. This should resolve most issues.")),(0,i.kt)("h3",{id:"setting-up-node"},"Setting Up Node"),(0,i.kt)("p",null,"NVM (Node Version Manager) is a tool for installing and using multiple versions on node on your computer. It must first be installed:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Install NVM"),(0,i.kt)(l.Z,{groupId:"os",queryString:!0,defaultValue:"mac",mdxType:"Tabs"},(0,i.kt)(r.Z,{value:"win",label:"Windows",mdxType:"TabItem"},(0,i.kt)("em",null,"The previous step installs"," ",(0,i.kt)("a",{href:"https://github.com/coreybutler/nvm-windows"},"NVM for Windows")," via the winget package manager. Note that this is a different tool than NVM with slight differences needed for compatibility with Windows.")),(0,i.kt)(r.Z,{value:"mac",label:"macOS",mdxType:"TabItem"},(0,i.kt)(o.Z,{language:"sh",mdxType:"CodeBlock"},"curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.4/install.sh | bash")))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Copy the version number listed in ",(0,i.kt)("inlineCode",{parentName:"p"},".nvmrc"),". ",(0,i.kt)("em",{parentName:"p"},"The version may be different than the screenshot below.")),(0,i.kt)("img",{src:p,alt:".nvmrc file"})),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Install that version."),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"nvm install [version]\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Use the needed version. This will automatically check the version listed in the ",(0,i.kt)("inlineCode",{parentName:"p"},".nvmrc")," file."),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"nvm use\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Set the current version as your default"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"nvm alias default node\n")))),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"You can skip step 4 if you've already set a default node version in a different project.")),(0,i.kt)("h2",{id:"install-dependencies"},"Install Dependencies"),(0,i.kt)("p",null,"There are many node packages used by Honeycomb that also need to be installed. Node (installed in the previous step) comes with its own package manager to install, update, and maintain these dependencies throughout the development lifecycle."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Install Honeycomb\'s dependencies"',title:'"Install',"Honeycomb's":!0,'dependencies"':!0},"npm install\n")),(0,i.kt)("p",null,"Certain dependencies are best installed globally within node. These tools will be available from the command line anywhere on your system."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Install Honeycomb\'s global dependencies"',title:'"Install',"Honeycomb's":!0,global:!0,'dependencies"':!0},"npm install -g electron firebase-tools dotenv-cli\n")),(0,i.kt)("h2",{id:"run-the-task-in-development-mode"},"Run the Task in Development Mode"),(0,i.kt)("p",null,"Running the task in development mode causes it to hot-reload whenever changes are made to the app. This is how you'll run the project while building your task."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Run the task in dev mode"',title:'"Run',the:!0,task:!0,in:!0,dev:!0,'mode"':!0},"npm run dev\n")),(0,i.kt)("p",null,"This script launches an electron window with the task and inspector open."),(0,i.kt)("p",null,"You can quit the task in the middle of development if needed:"),(0,i.kt)(l.Z,{groupId:"os",queryString:!0,defaultValue:"mac",mdxType:"Tabs"},(0,i.kt)(r.Z,{value:"win",label:"Windows",mdxType:"TabItem"},(0,i.kt)("kbd",null,"Control")," + W"),(0,i.kt)(r.Z,{value:"mac",label:"macOS",mdxType:"TabItem"},(0,i.kt)("kbd",null,"\u2318")," + Q"),(0,i.kt)(r.Z,{value:"linux",label:"Linux",mdxType:"TabItem"},(0,i.kt)("kbd",null,"Control")," + W")),(0,i.kt)("h3",{id:"saving-data"},"Saving data"),(0,i.kt)("p",null,"Data is saved throughout the task, even when running in development mode. The location of the task is logged at the beginning of the task wherever you ran ",(0,i.kt)("inlineCode",{parentName:"p"},"npm run dev"),"."),(0,i.kt)("p",null,"Note how the data is organized by study and participant. Every run through of the task will save the data somewhere within this folder!"),(0,i.kt)("h2",{id:"edit-the-task"},"Edit the Task"),(0,i.kt)("p",null,"Now that the task is up and running we can make our first changes to the code! We'll edit the ",(0,i.kt)("inlineCode",{parentName:"p"},"package.json")," file to reflect your information."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Create a new branch"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"git checkout -b \n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Open ",(0,i.kt)("inlineCode",{parentName:"p"},"package.json")," and edit it to reflect your app:"),(0,i.kt)("ol",{parentName:"li"},(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"name")," is your task's name, generally this is the name of our repository"),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"description")," should be rewritten to better match your task"),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"author")," is your lab (or PIs) name, email, and website"),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"version")," should be reset to 1.0.0"),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"repository")," is the link the GitHub repository you created ",(0,i.kt)("a",{parentName:"li",href:"#2-start-your-new-task-from-our-template-repository"},"earlier"),"."))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Save your changes and commit them to git:"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},'git commit -m "Commit message goes here!"\n'))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Create a ",(0,i.kt)("a",{parentName:"p",href:"version_control#create-a-pull-request"},"pull request")," to bring your changes into the ",(0,i.kt)("inlineCode",{parentName:"p"},"main")," branch"))),(0,i.kt)("h2",{id:"next-steps"},"Next Steps"),(0,i.kt)("p",null,"Honeycomb tasks can be configured to run as a web app in Firebase, or as desktop application via electron. The desktop application can receive port signals from EEG, cameras, foot pedals, and more."),(0,i.kt)("p",null,"The ",(0,i.kt)("a",{parentName:"p",href:"firebase"},"Firebase")," page explains how to set up your task with Firebase."),(0,i.kt)("p",null,"To learn more about how to configure your task for these different scenarios, see ",(0,i.kt)("a",{parentName:"p",href:"environment_variables"},"Environment Variables"),"."),(0,i.kt)("p",null,"The ",(0,i.kt)("a",{parentName:"p",href:"npm_scripts"},"NPM Scripts")," page lists every script you can run and which environment they use."))}y.isMDXComponent=!0},5440:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/powershell_admin-33d18a547790e540d5630c7626b766c6.png"},8867:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/template_0-a1b5129c7526d910bfd8ca1b78464793.png"},1203:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/template_1-e2b5ed212b0dc62bd3a18b45337a1872.png"}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[7107],{5162:(e,t,a)=>{a.d(t,{Z:()=>r});var n=a(7294),i=a(6010);const l={tabItem:"tabItem_Ymn6"};function r(e){let{children:t,hidden:a,className:r}=e;return n.createElement("div",{role:"tabpanel",className:(0,i.Z)(l.tabItem,r),hidden:a},t)}},4866:(e,t,a)=>{a.d(t,{Z:()=>N});var n=a(7462),i=a(7294),l=a(6010),r=a(2466),o=a(6550),s=a(1980),p=a(7392),u=a(12);function m(e){return function(e){return i.Children.map(e,(e=>{if(!e||(0,i.isValidElement)(e)&&function(e){const{props:t}=e;return!!t&&"object"==typeof t&&"value"in t}(e))return e;throw new Error(`Docusaurus error: Bad child <${"string"==typeof e.type?e.type:e.type.name}>: all children of the component should be , and every should have a unique "value" prop.`)}))?.filter(Boolean)??[]}(e).map((e=>{let{props:{value:t,label:a,attributes:n,default:i}}=e;return{value:t,label:a,attributes:n,default:i}}))}function d(e){const{values:t,children:a}=e;return(0,i.useMemo)((()=>{const e=t??m(a);return function(e){const t=(0,p.l)(e,((e,t)=>e.value===t.value));if(t.length>0)throw new Error(`Docusaurus error: Duplicate values "${t.map((e=>e.value)).join(", ")}" found in . Every value needs to be unique.`)}(e),e}),[t,a])}function c(e){let{value:t,tabValues:a}=e;return a.some((e=>e.value===t))}function h(e){let{queryString:t=!1,groupId:a}=e;const n=(0,o.k6)(),l=function(e){let{queryString:t=!1,groupId:a}=e;if("string"==typeof t)return t;if(!1===t)return null;if(!0===t&&!a)throw new Error('Docusaurus error: The component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".');return a??null}({queryString:t,groupId:a});return[(0,s._X)(l),(0,i.useCallback)((e=>{if(!l)return;const t=new URLSearchParams(n.location.search);t.set(l,e),n.replace({...n.location,search:t.toString()})}),[l,n])]}function k(e){const{defaultValue:t,queryString:a=!1,groupId:n}=e,l=d(e),[r,o]=(0,i.useState)((()=>function(e){let{defaultValue:t,tabValues:a}=e;if(0===a.length)throw new Error("Docusaurus error: the component requires at least one children component");if(t){if(!c({value:t,tabValues:a}))throw new Error(`Docusaurus error: The has a defaultValue "${t}" but none of its children has the corresponding value. Available values are: ${a.map((e=>e.value)).join(", ")}. If you intend to show no default tab, use defaultValue={null} instead.`);return t}const n=a.find((e=>e.default))??a[0];if(!n)throw new Error("Unexpected error: 0 tabValues");return n.value}({defaultValue:t,tabValues:l}))),[s,p]=h({queryString:a,groupId:n}),[m,k]=function(e){let{groupId:t}=e;const a=function(e){return e?`docusaurus.tab.${e}`:null}(t),[n,l]=(0,u.Nk)(a);return[n,(0,i.useCallback)((e=>{a&&l.set(e)}),[a,l])]}({groupId:n}),g=(()=>{const e=s??m;return c({value:e,tabValues:l})?e:null})();(0,i.useLayoutEffect)((()=>{g&&o(g)}),[g]);return{selectedValue:r,selectValue:(0,i.useCallback)((e=>{if(!c({value:e,tabValues:l}))throw new Error(`Can't select invalid tab value=${e}`);o(e),p(e),k(e)}),[p,k,l]),tabValues:l}}var g=a(2389);const b={tabList:"tabList__CuJ",tabItem:"tabItem_LNqP"};function y(e){let{className:t,block:a,selectedValue:o,selectValue:s,tabValues:p}=e;const u=[],{blockElementScrollPositionUntilNextRender:m}=(0,r.o5)(),d=e=>{const t=e.currentTarget,a=u.indexOf(t),n=p[a].value;n!==o&&(m(t),s(n))},c=e=>{let t=null;switch(e.key){case"Enter":d(e);break;case"ArrowRight":{const a=u.indexOf(e.currentTarget)+1;t=u[a]??u[0];break}case"ArrowLeft":{const a=u.indexOf(e.currentTarget)-1;t=u[a]??u[u.length-1];break}}t?.focus()};return i.createElement("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,l.Z)("tabs",{"tabs--block":a},t)},p.map((e=>{let{value:t,label:a,attributes:r}=e;return i.createElement("li",(0,n.Z)({role:"tab",tabIndex:o===t?0:-1,"aria-selected":o===t,key:t,ref:e=>u.push(e),onKeyDown:c,onClick:d},r,{className:(0,l.Z)("tabs__item",b.tabItem,r?.className,{"tabs__item--active":o===t})}),a??t)})))}function f(e){let{lazy:t,children:a,selectedValue:n}=e;const l=(Array.isArray(a)?a:[a]).filter(Boolean);if(t){const e=l.find((e=>e.props.value===n));return e?(0,i.cloneElement)(e,{className:"margin-top--md"}):null}return i.createElement("div",{className:"margin-top--md"},l.map(((e,t)=>(0,i.cloneElement)(e,{key:t,hidden:e.props.value!==n}))))}function v(e){const t=k(e);return i.createElement("div",{className:(0,l.Z)("tabs-container",b.tabList)},i.createElement(y,(0,n.Z)({},e,t)),i.createElement(f,(0,n.Z)({},e,t)))}function N(e){const t=(0,g.Z)();return i.createElement(v,(0,n.Z)({key:String(t)},e))}},5340:(e,t,a)=>{a.r(t),a.d(t,{assets:()=>h,contentTitle:()=>d,default:()=>y,frontMatter:()=>m,metadata:()=>c,toc:()=>k});var n=a(7462),i=(a(7294),a(3905)),l=a(4866),r=a(5162),o=a(614);const s=a.p+"assets/images/clone-code-button-e90c329a7e167ff0f79391cd79af8cc1.webp",p="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAXQAAACFCAYAAABL2gNbAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAAEnQAABJ0Ad5mH3gAABXESURBVHhe7d0PWFRlvgfwr6GojISwCP4DScAdrER9HL1JFlqxPSt2V9y6aIusqdlqulqrm6WV5WZP7Zrprj4ZZkKFm1fcFCOp/JNBq7i4WOqkkCDqCiHIxVFE3L3ve84ZHGBE0YE5Hr6fZ2fnPefAzAF3v/Ob3/ueoV1wcPB/QEREt7zbtHsiIrrFMdCJiAyCgU5EZBAMdCIig2CgExEZhO4D3ce/I+4bG4zIEYHaHiIickbXyxZlkN83to+2BVSWVSNvdwm+2nRc20NERHa6DPQ+Zh888mQ/UZ13Ura/2lSk3NvDXQb75tVHUGStVLaJiEhngS7bK488+VMl0KW83aex5d2jyliSx2XrxR7s8ris1ivLLirbRERtmS4CvWFQX6sCdwx+tmGIiFRuD3THPnlzw1l9EQhWWjMMdiJq69wW6A3bK7JPfiNh7Ky6T37tgLhnG4aI2ha3BXrC/AHoE+GjtFU2r/7+pgPYMdjlY6aIUCciakvctg49WFTm9uC9njCXgS1vsqKXNzl2JB9DVvhFhyvVqr+ddoCIqI3Q5YVFC5JHYOZSi7al9tlnLh2q3BKeH6Dc1G1LXcuGiKit0/2VovZJU9kbV/vsRcpyRVndy8lQdb16/WqdiKgtclsP/YV1I3D8e+e9blmhywBf8UwOZv7JAp9unbDi2b2o/LF+a0ZW6rJCd5xQtffmFyfuBlrsJ4vFnDfuR892p7Br3lv4IvQBPD42GmE/6YT2HuLw5WqUF+diy5pN+K5a/Y5OP3saLz3YB+0hvmfhW0jX9tcXgEfnzcXQbkDVgTV4JcUq9onnelM8l/w+8Vy7Bo7FlDFD0dO7vfIdtVWnsHdLEjbtr1K2+0Qn4rH7zAjQjuNiFU7lpiMpLRfqV1wxeNIrGN+/M6oPpWJhag3GTovD8N7eyrFT2+firQxlqPIZjNi4BzA41A/eHbXHvlyLqjOFyN3yDtLlqRKRW+m+Qj+r9dcj7w1s1F6Rk6kyzGXf3F06DJmMedMehvknIuRqa+V/AI9O8AsZjsR5iRisfhmqtx1AofKj9ER4jHoFbCP9HkCoCHOgFN9+3jghO4+Zg+cnDEdPT/FUF8VzXQbae/fE8AlzMNnSCX0emYOnRt+FAK8rx9HRGz3vGY85ifYzcaYLYp96vC7MFR20e6FP9DS8OH887u8foIS58tjyJl6evAPCEN6PExZEeuDh4+PzsjZuVUob5cxFHNhdou25Qh67eL4We7edQpH1LIb9rJeourvWrWKR94HBJnQVlbtce15y3KZ9p7o2Xe7/6m8tuR69H+55KATe7Tqjx08DUGvdhOV/fh+bM7/El1/uxjEvMwYGe+O2jn64/bYs7C2QKV+EjqH3IUIEv3dncd7ZVlw5a5X553GICuyI2qK/I2l7vghMSTxXjHgudEZgr444uXMN/rR6A7ZtF8+VY0PPu8MR0Lkz/IMtiAj3R23+Z3j/7XexQZ7LF3+HLXgwIvw7omNAILp8mw3rOeVBFT0GjcTd3Tqg9j++6N3tEvI//wgr30lF+uef4+/fa180OBGz4szi5xAvSieysWH5cnyQIR5bPr94/DPe4fC79A32X7mgl4jcRPcVuly9suKZvWolbq1UWjGydx45orsS7hOfHyDug7Wvbm2iKj/5Gd5Ym43SuhZKNfI/WYVdRZfEuL14V/GgulvIzsrH/8mBqGqjuiu7HAxGVKiskGtx0vqZeJSGRGVc+DmSMvKvHKvMxrq/WdXH9PaGd+V3+PidL5Ff9wVVyP5wL5RTgR963eW8ku4UcDtOfPoW1nxhbdCWCcDYB+7C7WJUe3IXkt7ehNx6b4aqkJsmvm+rtklEbqX7QLe3WWSPXPbbZV9dBrw95NVwD3TTMsVaFOZtdxK+1cg9rcQsYPJGmDoCDu3B8bNyEICw4QHKrjr3WBBiEvfVhcj9Qt1VXzUKc3c3fq5Dx+peTMqtGWjUqKnORYnynO3RwUvZ05itEDm7G/8UsgVkVk6zFHvXp4v3GESkZ7oOdLl6RU5yyircMbBl1S5vst0iJz5lqLtHKU5+7XzmtbRGm8D19FIqXJUVGYfVFlNA+P0i1q8YflcvyJ+i6sguZKu7GihHyT5nz3VO7duLqC8t+lHZU18pLtQ0PTtcWyZeRLRxPebuoq4XKk7g29PKHiLSMV0Hugxt+/LEMVPClWrdfoGRrMrlRwfIoJfLGFtuRYtrlWYXiIgV/MNwf13b5T7cHdxZ3DufDL1uchL0BtTaKrTRVZyvQr42JCL90n3LZfO73yuhLnvmVy4oGooxU/spAS976o4fsat7pzPwbZEsqf0QNkprxjw4AH1EeV5b9C0y9FgJe3RQ3j0Qkb7dEpOisne+5d0jyk1W4+rnoBfV9dQdddX9RUbV+Mx6EnKe0i/EgjARlQ+be6GDnAw9urNxj9ydKs6rK238eyGaiU6ke24L9OOi6pYV9pip4UoL5Vpkv1zeZDUub8rntojHsJOPoTyWspRR5y2YL3JRdEHc+4bA0v9BRPRpr06GbtNVnAO7v0WhPKX2fTB0/FBW6UQ657ZAd2yl2Jce2gNeKjysLM24LvbPepGP5coWTCdLIl58/U28uSARQ12aZtnIOSYT3Q8hMeHK5OjVJ0PdKRuf5ZxSqnTv/mMxZ9IDCHP8PXQKwNC4OZg8WtsmIrdyW6A7tlIkuaZc9shlKEsHditTh02SE6PyYwKUi5S0z3pp2IK5Gf3vCoO3vJTf5y5EjXTtusjcPQXKmm+/Xj3R/mYnQ1tQ0eZV2LS/XIR6e/j1fxjTXn0TSxYvUW8vz8Wj9/TE7R5uWTNKRA24vYcu2yjyD1LY++P23rhjO6UhZTmjCH85MSrZg/xG/kBGUw59l48quXKk8jtk7XBxD+dQBg6XaePSfGTpdllgNfZ+tASvfbQL1tNV6scNdGyv3FBbhdIDnyFj1y2yxIjI4HTxN0Ubsi9LlPcypGU177hfVuSSDH1X/HEMIiIj0G2gN/wj0JI9yOW+pv6INBFRW6TLQLeTk51qpa7OxNnD3dWtFSIiI9B1oEuyWg+J6FrXfiEiIud0H+hERHR9dH+lKBERXR8GOhGRQTDQiYgMgoFORGQQDHQiIoNgoBMRGQQDnYjIILgOXSd69FA/1qChf/2Lf5qZiK4PK3QiIoNgoBMRGQQDnYjIIBjoREQGwUAnIjIIBjoRkUEw0ImIDIKBTkRkEAx0IiKD4JWiDXj85E5EjxqKMD9PsVWFg2kf4esf1WMtiVeK3jjf6OlY+EQMzP7y38yGnD8+hpe2X+t/1r6Injwb40dFIshXfp/mQgWKrVnYuGodMk/YtJ0tQ573AnHeEXXn/She3g44PfOpy/Hp2DBt4zr8kIafP52kbbiOPOe5E6LQv4cvPD3UfTUVxcjbnopla3aiQt1FbsIK3c77Dtz73wmY8st7tTAnvTMNiMei1Rvw4bxYLcyvkykGL6z7EPPGWeqHudTZF0GDYjF71WosiDFpO13L8bzVML8VmBAz9z2sFec8sPeVMJc8fYNgGTcPa9+eArO2j9yDFbp3TwyOioalj7e6fe44Dp7xx519vMQGK3Q9Mg2IxdTJiYgJ1wLXVoCcU91hUbavVaGbEL/0Q0w0iyCtKUHellQkfZKJgjJxyD8Uwx+aiKn/Y0GgzFlbHlY+9jzS/+Oa/4tc+7ybqNDFuUUGddE2rsLTginz4hDaWTza/pV49IV07cDNC5q8AsvHhaKjGNcU7kTye+8ibV8FfMNjMP7pqYjVfqaKPcswbVEmzilb1NrafIXeNWKEGub/rkHZd5n4KDUD1qrL2lHSo/4/j9dCsQYle5Ix/9czsaP8KkHYkGk8omSYCyXbX8Tza7Qwl8oKkJ36Ep7eWqA+likYA+9VjrhE/9Hj8VCj877OFwtxbnn785q8XRwWhb4izMVPhqwPtirf5hqxmP6wGuY4lYn5M95QwlyqOJqJlb9diLQfapRt32HjMPGOdsqYWl+bD/Sz/8zD8fLj+DotGRuzjqHq39oBaiGxeO3jT/Hpp+KWvAAWba8zQbPeU7/u0w1YMlq8ndT256zfKUK4AOlvPIFJi9Yjrzmt7mG90V0bnrtQrI3qs5WdE5EreaJDB2XgEjmpO1DwozzvSVfO2zXFvxCLxBGByu+oxroNSVaXPTBMCaMQoRTgNuRtWobGD21FUso+qK9NQbA8GqnspdbHHnqNFRkbMnDwDKvy1pGO7CPaG3L/CPxsmDpsLBLxAwPVYVke0kTBWZcjhUmYOXEmVu4UZXlz/XC2rh0QFDERJifFpMUcLKJcOoeKY8rANcR5z0qU5+36qcOgGbGIVEK3Avv+uh7nXJfnGDOor/r7qDyEbY7/DnamSEz8ZST8tN9lYMhwqA0Yam0MdGp16VvytNUQvoh8JBbtnL1DHzYGkYHqgYrD25CjjFygcCNyTqhDT3McVsyNqRc+vqNfxuwRvmqlezQLaYUuTMYWE4vf3B+sjGR1/tYeZegiwxGmTCgIpcXYqY7qyAne11YuQfydDr9F30BEaUNqXQx0an170pFXog5N/aIwuq6ZcoVlVAR8ld3FyFq/T9nnGsVYuTQN+efl2BOB0bPxYdIixA8IQvTsd7B2xlDxMiNU5CF5VRKO3wJ5HjRDvPgp86U25KWniP92pe4wdVJHtvJ8daAxj3sNq/8wEQO7iY2aElgLtWf28YP68kKtjYFObpCH1H3F2sRjBKJ+oex0EIu4wWqVjB9ykOzqKtmahFlPrUT2Ka1T3tOCia+/g3kxQUprwXY0HYunzUeaVTmsc7GYHh2k/q5O7MCaHa5+BfJDF2Wi1ZEZcS+txeuTB8LXQ2Z5NlZOmYSFB85ox8ldGOjkFsXvZ8F6UY48ETEioX7PdbR4m6/sqIF1TypsLVElXyhHeYVNm/ysz+QfgYF3X2OJoE4ETY25MmH5yUoUt/Q7Cv9YvPDe65gyLFD8y8nVOkl4btJipJeJM7js7LdJrYmBTu5h24i8H5REh2ffgRjnkOhx90aoAW87jO0pNtctBNGYBkzH8nULEHunLzwv21CwdRlm/nYZ0vaXqAHvG4rYhWuxNMHspBmkJ9GYPDJUnbA8lYV1ziYsb1o5zl3QhoGPYG3SdER1F894uQJ5a57DpEVpsL+RGR7op43IXRjo5CY2JG8/rPZ7Pc2wTDBp4RmPKLOy4hm2I1lw3aUxGlMcFiyMRZi8bqwiByufeAwz/5KJgqOZSHphEh5/bj2sykmZYB7/e8wdpt9ID5o6DpFd5fmJdzK7kuqC1bXKUaMV3qYQs3rBVVkekl94EvM31n/G7ibtVbmyHPW77dRaGOjkPlszcahSHYZaEhEkssmUMBR9lTwXFeBmV14cozJNiNaW99mQ99FL2Ppj/ZrWdiAZz/wxW1tTHYjImHuU/foTjSmjtIt9yvYh9YOWujZzJ4pLtaFgO7ge838zH+sPNJx6jURoE6thqHUw0MmNdiL9QIXaJugdidiQLhg3qK92RWIOkve6voFg6WG/rKgcxSJ1nD7DntPiqMo3sL82ck5ezj/7Dyuw9KUpiPbXdrYCU8IYRPrIUQ0Kdq/Dvmb+qppz3tuO2C/AEi+y/5vs/EIuh2WmxUcylXtqfQx0cquc1CxtIi8IkWMmYmBftcor3r+xRSb4av5tn7gLRMQEbXVIA6axoeiuHagoOaQOnAmZgiWLpiNmUCjMw+Iw7+0FiHb2gC5nwewHzWrv3HYY297VVgxdr2aed/HWHBSokwsYkjAF5kZfa8aUhCHqhUU1VmStc34FLrU8BvptnvDy9oa34629/aPkPOBhcjzmBU/+xlyrcAsOnFDjKGhUDJQ8l6HwfhMhZQqCeVAkIh1ucp7OnjOe3QY4HDMjyGHCNTs7X1un7YnQsUuxfEYMzL21L/APRczkJfhzYiTUNS4lyMv8Rhk59VAkQtV2v8o3EiNHNpGMzs7b4fs9u0ViQN2x+uftyJQwHkO6qc9TvHNV8+cZmnvehUnY+A/1nZRn3zi8uky8GIQrq/WVD+ea/variFP/4VCwdTVSXHmZKjULP22x272YEHcntM9avIaW+/TFtvxpi6aEP+HD8RFqxSnUWJPxi2fWa1tOjHoZG3439DovL2/4KYYmDJ+1FPMeVtecX50N1tSFeDbFevUXltFL8PEMe/hLxUif8RRWHrvKd4xahI9/Z3H4+qZc7dMXLViQvAjDZZvEloekSc8jrbkB2tzzVogqfNkSxPVzfCWor+KbZXjy1UztBZPcgfUmuZ0tJQuH7UvjRBwc/vKv2rgl2JC9fBomvZiEzIMlsNU9r6qmsgQFe9Kw7Mlf45mmwlzauhhJO47DJj8G6HKFeAF4C6uaDMWbZ0qIxxCt512Sk4ZNN1IN39B5W5E0+1eYvy4bxRUO680v18BWYkX6G4/jcYa527FC1wl+HjoR3SxW6EREBsFAJyIyCAY6EZFBMNCJiAyCgU5EZBAMdCIig2CgExEZBAOdiMggGOhERAbBK0WpVXl5yb8sQUQtgRU6EZFBMNCJiAyCgU5EZBDsoVOrathDP3/+vDYiopvFCp2IyCAY6EREBsFAJyIyCAY6EZFBMNCJiAyCq1w0Xv1jkPBYLIaFBsCrg7az+ixOHtyOv/7lY+zlYgyX4CoXopbDQEdXxMx+BQn/FQB7jjdSXYiti+cjJZ+vfTeLgU7UcthyGf10XZif/2EHUl5/CvHx8Yif8To+/kcpLsmv6RSCmKm/Qi85JiLSKQ8fH5+XtXHbdHQfzt5xD3pY38HcNzbj0Olqdf+F0zicfQBdhoxEv64e8OjaFV2OZGBviXqYbkyHDvXfB126pLxkEpELsELHeex4cxaeXb1XjBo6iZSDJ7VxAHrdDbTTtoiI9IaB3hz8bRGRjjGirsHLw94iOI+zxQCnRYlIrxjoTeqF+Lu1qdDzx5C7Ux0SEekRA70J4QkzEd1L7ZqX7t+CTGVERKRPDPSr8Ir+PZ4dHQJPufFjFt778z+V/UREesVAd8Kr/xNY+MQgdJUb8qKit1fgn2yeE5HOMdAbkGH+4vwY3CFL80v2K0TVY0REesZAd+BlmYZXRJiHyIUtsjJf9Bwv9yeiWwYDXSPD/NVZI9HbHuaszInoFsNAF5TKXIR5L+UDXY4ibTErcyK69bT5T1u0V+ZqmBci84MU7ClTjzljO3kQhWe0DWo2ftoiUctp84Ee9bs1mDnEpG1dW+HW8XguhdX7jWKgE7UctlyIiAyCf+CCWhUrdKKWwwqdiMggGOhERAbBQCciMggGOhGRQTDQiYgMgqtcqFU1XOVCRK7DCp2IyCAY6EREBsFAJyIyCPbQiYgMghU6EZFBMNCJiAyCgU5EZBAMdCIig2CgExEZBAOdiMggGOhERAbBQCciMggGOhGRQTDQiYgMgoFORGQQDHQiIoNgoBMRGQQDnYjIEID/B504qs9kmFTXAAAAAElFTkSuQmCC",u=a.p+"assets/images/workflow-permissions-e7b2dd2b9b729493bc61a15033a45d45.png",m={id:"quick_start",slug:"/quick_start",title:"Quick Start",description:"Quick start guide for Honeycomb"},d=void 0,c={unversionedId:"quick_start",id:"version-3.1.x/quick_start",title:"Quick Start",description:"Quick start guide for Honeycomb",source:"@site/versioned_docs/version-3.1.x/quick_start.mdx",sourceDirName:".",slug:"/quick_start",permalink:"/honeycomb-docs/docs/3.1.x/quick_start",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/quick_start.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"quick_start",slug:"/quick_start",title:"Quick Start",description:"Quick start guide for Honeycomb"},sidebar:"mySidebar",previous:{title:"Introduction",permalink:"/honeycomb-docs/docs/3.1.x/"},next:{title:"Project Organization",permalink:"/honeycomb-docs/docs/3.1.x/project_organization"}},h={},k=[{value:"Creating Your Task Repository",id:"creating-your-task-repository",level:2},{value:"Cloning the Repository",id:"cloning-the-repository",level:2},{value:"Installing Prerequisites",id:"installing-prerequisites",level:2},{value:"Initial Install",id:"initial-install",level:3},{value:"Setting Up Node",id:"setting-up-node",level:3},{value:"Install Dependencies",id:"install-dependencies",level:2},{value:"Run the Task in Development Mode",id:"run-the-task-in-development-mode",level:2},{value:"Saving data",id:"saving-data",level:3},{value:"Edit the Task",id:"edit-the-task",level:2},{value:"Next Steps",id:"next-steps",level:2}],g={toc:k},b="wrapper";function y(e){let{components:t,...m}=e;return(0,i.kt)(b,(0,n.Z)({},g,m,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("h2",{id:"creating-your-task-repository"},"Creating Your Task Repository"),(0,i.kt)("p",null,"The Honeycomb repository is a template and serves as the starting point for all tasks. Creating your repository from the template starts your project with the same directory structure and files as an existing repository."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Go to the ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/brown-ccv/honeycomb"},"Honeycomb repository"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Click on ",(0,i.kt)("inlineCode",{parentName:"p"},"Use this template")," and select ",(0,i.kt)("inlineCode",{parentName:"p"},"Create a new repository"),".\n",(0,i.kt)("img",{alt:"Use this template",src:a(8867).Z,width:"2408",height:"1212"}))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Enter the owner, name, and description of your repository and click on ",(0,i.kt)("inlineCode",{parentName:"p"},"Create repository from template"),".\n",(0,i.kt)("img",{alt:"Create repository",src:a(1203).Z,width:"2408",height:"1212"})),(0,i.kt)("admonition",{parentName:"li",type:"note"},(0,i.kt)("p",{parentName:"admonition"},"We recommend creating a public repository and leaving ",(0,i.kt)("inlineCode",{parentName:"p"},"Include all branches")," unchecked"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},'Ensure the repositories workflow permissions are set to "Read and write permissions"'),(0,i.kt)("p",{parentName:"li"},(0,i.kt)("em",{parentName:"p"},(0,i.kt)("inlineCode",{parentName:"em"},"Settings -> Actions -> General -> Workflow permissions"))),(0,i.kt)("img",{src:u,alt:"GitHub workflow permissions settings"}))),(0,i.kt)("p",null,(0,i.kt)("em",{parentName:"p"},"Additional details about template repositories can be found on the ",(0,i.kt)("a",{parentName:"em",href:"https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template"},"Github Docs"),".")),(0,i.kt)("h2",{id:"cloning-the-repository"},"Cloning the Repository"),(0,i.kt)("p",null,"With the repository now setup it can be cloned onto your computer."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Navigate to the repository on ",(0,i.kt)("a",{parentName:"p",href:"https://github.com"},"GitHub"),".")),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Click the ",(0,i.kt)("inlineCode",{parentName:"p"},"Code")," button and copy the URL"),(0,i.kt)("img",{src:s,alt:"GitHub clone repo button"})),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Open a terminal and navigate to where you want the cloned directory"))),(0,i.kt)(l.Z,{groupId:"os",queryString:!0,defaultValue:"mac",mdxType:"Tabs"},(0,i.kt)(r.Z,{value:"win",label:"Windows",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Powershell"',title:'"Powershell"'},"cd 'path/to/directory'\n"))),(0,i.kt)(r.Z,{value:"mac",label:"macOS",mdxType:"TabItem"},(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Terminal.app"',title:'"Terminal.app"'},"cd 'path/to/directory'\n")))),(0,i.kt)("ol",{start:4},(0,i.kt)("li",{parentName:"ol"},"Clone the repo with the following command")),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:"title='Paste the URL you copied earlier'",title:"'Paste",the:!0,URL:!0,you:!0,copied:!0,"earlier'":!0}," git clone https://github.com//\n")),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"Git can be downloaded ",(0,i.kt)("a",{parentName:"p",href:"https://git-scm.com/book/en/v2/Getting-Started-Installing-Git"},"here")," if it is not already on your system.")),(0,i.kt)("p",null,(0,i.kt)("em",{parentName:"p"},"Additional details and alternative methods for cloning a repository can be found on the ",(0,i.kt)("a",{parentName:"em",href:"https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository?tool=webui"},"Github Docs"),".")),(0,i.kt)("h2",{id:"installing-prerequisites"},"Installing Prerequisites"),(0,i.kt)("p",null,"All of the needed programs for Honeycomb must be installed before we can develop our task. We will use a ",(0,i.kt)("a",{parentName:"p",href:"https://en.wikipedia.org/wiki/Package_manager"},"package manager")," to automatically install them."),(0,i.kt)("p",null,"See ",(0,i.kt)("a",{parentName:"p",href:"prerequisites"},"Prerequisites")," for more information about these programs."),(0,i.kt)("h3",{id:"initial-install"},"Initial Install"),(0,i.kt)(l.Z,{groupId:"os",queryString:!0,defaultValue:"mac",mdxType:"Tabs"},(0,i.kt)(r.Z,{value:"win",label:"Windows",mdxType:"TabItem"},(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Run Powershell as an admin from the start menu"),(0,i.kt)("p",{parentName:"li"},(0,i.kt)("img",{alt:"Powershell admin launcher",src:a(5440).Z,width:"783",height:"679"}))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Navigate to the root directory of your cloned repository")),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Paste the following command and follow the prompts to install the listed programs:"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"./winget.ps1\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},'The "Visual Studio Installer" will open a GUI during installation. Make sure "Desktop Development with C++" is checked before continuing.')))),(0,i.kt)(r.Z,{value:"mac",label:"macOS",mdxType:"TabItem"},(0,i.kt)("p",null,"The most commonly used package manager on macOS is ",(0,i.kt)("a",{parentName:"p",href:"https://brew.sh"},"Homebrew"),"."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Paste the following command in a macOS Terminal and follow the prompts to install Homebrew."),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"/bin/bash -c '$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)'\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Paste the following command and follow the prompts to install the listed programs:"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"brew bundle\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Install Xcode (not available on Homebrew)"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"xcode-select --install\n")))))),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"If you are running into issues after installing the packages please restart your terminal and/or reboot your computer. This should resolve most issues.")),(0,i.kt)("h3",{id:"setting-up-node"},"Setting Up Node"),(0,i.kt)("p",null,"NVM (Node Version Manager) is a tool for installing and using multiple versions on node on your computer. It must first be installed:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Install NVM"),(0,i.kt)(l.Z,{groupId:"os",queryString:!0,defaultValue:"mac",mdxType:"Tabs"},(0,i.kt)(r.Z,{value:"win",label:"Windows",mdxType:"TabItem"},(0,i.kt)("em",null,"The previous step installs"," ",(0,i.kt)("a",{href:"https://github.com/coreybutler/nvm-windows"},"NVM for Windows")," via the winget package manager. Note that this is a different tool than NVM with slight differences needed for compatibility with Windows.")),(0,i.kt)(r.Z,{value:"mac",label:"macOS",mdxType:"TabItem"},(0,i.kt)(o.Z,{language:"sh",mdxType:"CodeBlock"},"curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.4/install.sh | bash")))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Copy the version number listed in ",(0,i.kt)("inlineCode",{parentName:"p"},".nvmrc"),". ",(0,i.kt)("em",{parentName:"p"},"The version may be different than the screenshot below.")),(0,i.kt)("img",{src:p,alt:".nvmrc file"})),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Install that version."),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"nvm install [version]\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Use the needed version. This will automatically check the version listed in the ",(0,i.kt)("inlineCode",{parentName:"p"},".nvmrc")," file."),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"nvm use\n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Set the current version as your default"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"nvm alias default node\n")))),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"You can skip step 4 if you've already set a default node version in a different project.")),(0,i.kt)("h2",{id:"install-dependencies"},"Install Dependencies"),(0,i.kt)("p",null,"There are many node packages used by Honeycomb that also need to be installed. Node (installed in the previous step) comes with its own package manager to install, update, and maintain these dependencies throughout the development lifecycle."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Install Honeycomb\'s dependencies"',title:'"Install',"Honeycomb's":!0,'dependencies"':!0},"npm install\n")),(0,i.kt)("p",null,"Certain dependencies are best installed globally within node. These tools will be available from the command line anywhere on your system."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Install Honeycomb\'s global dependencies"',title:'"Install',"Honeycomb's":!0,global:!0,'dependencies"':!0},"npm install -g electron firebase-tools dotenv-cli\n")),(0,i.kt)("h2",{id:"run-the-task-in-development-mode"},"Run the Task in Development Mode"),(0,i.kt)("p",null,"Running the task in development mode causes it to hot-reload whenever changes are made to the app. This is how you'll run the project while building your task."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Run the task in dev mode"',title:'"Run',the:!0,task:!0,in:!0,dev:!0,'mode"':!0},"npm run dev\n")),(0,i.kt)("p",null,"This script launches an electron window with the task and inspector open."),(0,i.kt)("p",null,"You can quit the task in the middle of development if needed:"),(0,i.kt)(l.Z,{groupId:"os",queryString:!0,defaultValue:"mac",mdxType:"Tabs"},(0,i.kt)(r.Z,{value:"win",label:"Windows",mdxType:"TabItem"},(0,i.kt)("kbd",null,"Control")," + W"),(0,i.kt)(r.Z,{value:"mac",label:"macOS",mdxType:"TabItem"},(0,i.kt)("kbd",null,"\u2318")," + Q"),(0,i.kt)(r.Z,{value:"linux",label:"Linux",mdxType:"TabItem"},(0,i.kt)("kbd",null,"Control")," + W")),(0,i.kt)("h3",{id:"saving-data"},"Saving data"),(0,i.kt)("p",null,"Data is saved throughout the task, even when running in development mode. The location of the task is logged at the beginning of the task wherever you ran ",(0,i.kt)("inlineCode",{parentName:"p"},"npm run dev"),"."),(0,i.kt)("p",null,"Note how the data is organized by study and participant. Every run through of the task will save the data somewhere within this folder!"),(0,i.kt)("h2",{id:"edit-the-task"},"Edit the Task"),(0,i.kt)("p",null,"Now that the task is up and running we can make our first changes to the code! We'll edit the ",(0,i.kt)("inlineCode",{parentName:"p"},"package.json")," file to reflect your information."),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Create a new branch"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"git checkout -b \n"))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Open ",(0,i.kt)("inlineCode",{parentName:"p"},"package.json")," and edit it to reflect your app:"),(0,i.kt)("ol",{parentName:"li"},(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"name")," is your task's name, generally this is the name of our repository"),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"description")," should be rewritten to better match your task"),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"author")," is your lab (or PIs) name, email, and website"),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"version")," should be reset to 1.0.0"),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("inlineCode",{parentName:"li"},"repository")," is the link the GitHub repository you created ",(0,i.kt)("a",{parentName:"li",href:"#2-start-your-new-task-from-our-template-repository"},"earlier"),"."))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Save your changes and commit them to git:"),(0,i.kt)("pre",{parentName:"li"},(0,i.kt)("code",{parentName:"pre",className:"language-shell"},'git commit -m "Commit message goes here!"\n'))),(0,i.kt)("li",{parentName:"ol"},(0,i.kt)("p",{parentName:"li"},"Create a ",(0,i.kt)("a",{parentName:"p",href:"version_control#create-a-pull-request"},"pull request")," to bring your changes into the ",(0,i.kt)("inlineCode",{parentName:"p"},"main")," branch"))),(0,i.kt)("h2",{id:"next-steps"},"Next Steps"),(0,i.kt)("p",null,"Honeycomb tasks can be configured to run as a web app in Firebase, or as desktop application via electron. The desktop application can receive port signals from EEG, cameras, foot pedals, and more."),(0,i.kt)("p",null,"The ",(0,i.kt)("a",{parentName:"p",href:"firebase"},"Firebase")," page explains how to set up your task with Firebase."),(0,i.kt)("p",null,"To learn more about how to configure your task for these different scenarios, see ",(0,i.kt)("a",{parentName:"p",href:"environment_variables"},"Environment Variables"),"."),(0,i.kt)("p",null,"The ",(0,i.kt)("a",{parentName:"p",href:"npm_scripts"},"NPM Scripts")," page lists every script you can run and which environment they use."))}y.isMDXComponent=!0},5440:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/powershell_admin-33d18a547790e540d5630c7626b766c6.png"},8867:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/template_0-a1b5129c7526d910bfd8ca1b78464793.png"},1203:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/template_1-e2b5ed212b0dc62bd3a18b45337a1872.png"}}]); \ No newline at end of file diff --git a/assets/js/3875cc13.1b4acc4d.js b/assets/js/3875cc13.dd9d897e.js similarity index 99% rename from assets/js/3875cc13.1b4acc4d.js rename to assets/js/3875cc13.dd9d897e.js index 8c1a2e0d..d3bad464 100644 --- a/assets/js/3875cc13.1b4acc4d.js +++ b/assets/js/3875cc13.dd9d897e.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[420],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>h});var r=n(7294);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function a(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var l=r.createContext({}),c=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},p=function(e){var t=c(e.components);return r.createElement(l.Provider,{value:t},e.children)},u="mdxType",d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},m=r.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,l=e.parentName,p=s(e,["components","mdxType","originalType","parentName"]),u=c(n),m=i,h=u["".concat(l,".").concat(m)]||u[m]||d[m]||o;return n?r.createElement(h,a(a({ref:t},p),{},{components:n})):r.createElement(h,a({ref:t},p))}));function h(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,a=new Array(o);a[0]=m;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[u]="string"==typeof e?e:i,a[1]=s;for(var c=2;c{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>a,default:()=>d,frontMatter:()=>o,metadata:()=>s,toc:()=>c});var r=n(7462),i=(n(7294),n(3905));const o={id:"troubleshooting",slug:"/troubleshooting",title:"Troubleshooting",description:"Guide to troubleshooting some known errors and contacting the CCV with questions"},a=void 0,s={unversionedId:"troubleshooting",id:"version-3.1.x/troubleshooting",title:"Troubleshooting",description:"Guide to troubleshooting some known errors and contacting the CCV with questions",source:"@site/versioned_docs/version-3.1.x/troubleshooting.mdx",sourceDirName:".",slug:"/troubleshooting",permalink:"/honeycomb-docs/docs/3.1.x/troubleshooting",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/troubleshooting.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"troubleshooting",slug:"/troubleshooting",title:"Troubleshooting",description:"Guide to troubleshooting some known errors and contacting the CCV with questions"},sidebar:"mySidebar",previous:{title:"Prerequisites",permalink:"/honeycomb-docs/docs/3.1.x/prerequisites"}},l={},c=[{value:"Inspecting Errors",id:"inspecting-errors",level:2},{value:"Testing in Linux",id:"testing-in-linux",level:2},{value:"Common issues",id:"common-issues",level:2},{value:"Installing Dependencies",id:"installing-dependencies",level:3},{value:"Brew Not Available",id:"brew-not-available",level:4},{value:"NPM Errors",id:"npm-errors",level:3}],p={toc:c},u="wrapper";function d(e){let{components:t,...n}=e;return(0,i.kt)(u,(0,r.Z)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("h2",{id:"inspecting-errors"},"Inspecting Errors"),(0,i.kt)("p",null,"When developing Electron apps there are two processes: ",(0,i.kt)("inlineCode",{parentName:"p"},"main"),", and ",(0,i.kt)("inlineCode",{parentName:"p"},"renderer"),". In this case ",(0,i.kt)("inlineCode",{parentName:"p"},"main")," corresponds to ",(0,i.kt)("inlineCode",{parentName:"p"},"electron-starter.js")," and its console is wherever you called ",(0,i.kt)("inlineCode",{parentName:"p"},"npm run dev")," or ",(0,i.kt)("inlineCode",{parentName:"p"},"electron .")," from. ",(0,i.kt)("inlineCode",{parentName:"p"},"renderer")," corresponds to the React App - this is everything else. The React app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running ",(0,i.kt)("inlineCode",{parentName:"p"},"npm run dev"),", it should open by default."),(0,i.kt)("p",null,"In case you want to find out where the error is coming from when running the app locally:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"Try reviewing logs in the terminal"),(0,i.kt)("li",{parentName:"ul"},"Inspect element in your browser by opening your developer tools. For instance, in Chrome, this can be done via the menu View -> Developer or right-clicking and pressing inspect.")),(0,i.kt)("h2",{id:"testing-in-linux"},"Testing in Linux"),(0,i.kt)("p",null,"When running ",(0,i.kt)("inlineCode",{parentName:"p"},"npm test")," on Linux, you might get an error that mentions ",(0,i.kt)("inlineCode",{parentName:"p"},"ENOSPC"),'. This is because the test runner creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.'),(0,i.kt)("p",null,'This is a "known issue" with some test runners on Linux, as in discussions ',(0,i.kt)("a",{parentName:"p",href:"https://stackoverflow.com/questions/55763428/react-native-error-enospc-system-limit-for-number-of-file-watchers-reached"},"here")," and ",(0,i.kt)("a",{parentName:"p",href:"https://stackoverflow.com/questions/62206460/jest-watch-error-enospc-system-limit-for-number-of-file-watchers-reached"},"here"),"."),(0,i.kt)("p",null,"One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"Command that initially fails with ",(0,i.kt)("inlineCode",{parentName:"li"},"ENOSPC"),": ",(0,i.kt)("inlineCode",{parentName:"li"},"npm test")),(0,i.kt)("li",{parentName:"ul"},'Check the configured limit on "watchers": ',(0,i.kt)("inlineCode",{parentName:"li"},"cat /proc/sys/fs/inotify/max_user_watches")),(0,i.kt)("li",{parentName:"ul"},"Edit the relevant Linux config file: ",(0,i.kt)("inlineCode",{parentName:"li"},"sudo vim /etc/sysctl.conf")),(0,i.kt)("li",{parentName:"ul"},"Add a line at the end of the config file: ",(0,i.kt)("inlineCode",{parentName:"li"},"fs.inotify.max_user_watches=100000")),(0,i.kt)("li",{parentName:"ul"},"Save, exit, and reload the config file: ",(0,i.kt)("inlineCode",{parentName:"li"},"sudo sysctl -p")),(0,i.kt)("li",{parentName:"ul"},"Check that the limit has changed: ",(0,i.kt)("inlineCode",{parentName:"li"},"cat /proc/sys/fs/inotify/max_user_watches")),(0,i.kt)("li",{parentName:"ul"},"Retry the initial command, which should now succeed: ",(0,i.kt)("inlineCode",{parentName:"li"},"npm test"))),(0,i.kt)("h2",{id:"common-issues"},"Common issues"),(0,i.kt)("h3",{id:"installing-dependencies"},"Installing Dependencies"),(0,i.kt)("h4",{id:"brew-not-available"},"Brew Not Available"),(0,i.kt)("p",null,"If you run into issues installing Homebrew in step 1 of ",(0,i.kt)("a",{parentName:"p",href:"quick_start?os=mac#installing-prerequisites"},"Installing Prerequisites")," it may be because Homebrew is not available on your shell. Older versions of macOS (under 10.14) do not do this automatically."),(0,i.kt)("p",null,"Run the following command to manually add the Homebrew installation location to your ",(0,i.kt)("inlineCode",{parentName:"p"},"PATH")," so it is available in your shell."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"echo 'PATH=\"/usr/local/bin:$PATH\"' >> ~/.bash_profile\n")),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"If you're using ",(0,i.kt)("inlineCode",{parentName:"p"},"zsh"),", also add to your ",(0,i.kt)("inlineCode",{parentName:"p"},"~/.zshrc")," file.")),(0,i.kt)("h3",{id:"npm-errors"},"NPM Errors"),(0,i.kt)("p",null,"Try deleting your ",(0,i.kt)("inlineCode",{parentName:"p"},"node_modules")," folder and the ",(0,i.kt)("inlineCode",{parentName:"p"},"package-lock.json")," then running ",(0,i.kt)("inlineCode",{parentName:"p"},"npm install")," then ",(0,i.kt)("inlineCode",{parentName:"p"},"npm run rebuild"),". This should fix most issues."))}d.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[420],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>h});var r=n(7294);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function a(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var l=r.createContext({}),c=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},p=function(e){var t=c(e.components);return r.createElement(l.Provider,{value:t},e.children)},u="mdxType",d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},m=r.forwardRef((function(e,t){var n=e.components,i=e.mdxType,o=e.originalType,l=e.parentName,p=s(e,["components","mdxType","originalType","parentName"]),u=c(n),m=i,h=u["".concat(l,".").concat(m)]||u[m]||d[m]||o;return n?r.createElement(h,a(a({ref:t},p),{},{components:n})):r.createElement(h,a({ref:t},p))}));function h(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var o=n.length,a=new Array(o);a[0]=m;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[u]="string"==typeof e?e:i,a[1]=s;for(var c=2;c{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>a,default:()=>d,frontMatter:()=>o,metadata:()=>s,toc:()=>c});var r=n(7462),i=(n(7294),n(3905));const o={id:"troubleshooting",slug:"/troubleshooting",title:"Troubleshooting",description:"Guide to troubleshooting some known errors and contacting the CCV with questions"},a=void 0,s={unversionedId:"troubleshooting",id:"version-3.1.x/troubleshooting",title:"Troubleshooting",description:"Guide to troubleshooting some known errors and contacting the CCV with questions",source:"@site/versioned_docs/version-3.1.x/troubleshooting.mdx",sourceDirName:".",slug:"/troubleshooting",permalink:"/honeycomb-docs/docs/3.1.x/troubleshooting",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.1.x/troubleshooting.mdx",tags:[],version:"3.1.x",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"troubleshooting",slug:"/troubleshooting",title:"Troubleshooting",description:"Guide to troubleshooting some known errors and contacting the CCV with questions"},sidebar:"mySidebar",previous:{title:"Prerequisites",permalink:"/honeycomb-docs/docs/3.1.x/prerequisites"}},l={},c=[{value:"Inspecting Errors",id:"inspecting-errors",level:2},{value:"Testing in Linux",id:"testing-in-linux",level:2},{value:"Common issues",id:"common-issues",level:2},{value:"Installing Dependencies",id:"installing-dependencies",level:3},{value:"Brew Not Available",id:"brew-not-available",level:4},{value:"NPM Errors",id:"npm-errors",level:3}],p={toc:c},u="wrapper";function d(e){let{components:t,...n}=e;return(0,i.kt)(u,(0,r.Z)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("h2",{id:"inspecting-errors"},"Inspecting Errors"),(0,i.kt)("p",null,"When developing Electron apps there are two processes: ",(0,i.kt)("inlineCode",{parentName:"p"},"main"),", and ",(0,i.kt)("inlineCode",{parentName:"p"},"renderer"),". In this case ",(0,i.kt)("inlineCode",{parentName:"p"},"main")," corresponds to ",(0,i.kt)("inlineCode",{parentName:"p"},"electron-starter.js")," and its console is wherever you called ",(0,i.kt)("inlineCode",{parentName:"p"},"npm run dev")," or ",(0,i.kt)("inlineCode",{parentName:"p"},"electron .")," from. ",(0,i.kt)("inlineCode",{parentName:"p"},"renderer")," corresponds to the React App - this is everything else. The React app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running ",(0,i.kt)("inlineCode",{parentName:"p"},"npm run dev"),", it should open by default."),(0,i.kt)("p",null,"In case you want to find out where the error is coming from when running the app locally:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"Try reviewing logs in the terminal"),(0,i.kt)("li",{parentName:"ul"},"Inspect element in your browser by opening your developer tools. For instance, in Chrome, this can be done via the menu View -> Developer or right-clicking and pressing inspect.")),(0,i.kt)("h2",{id:"testing-in-linux"},"Testing in Linux"),(0,i.kt)("p",null,"When running ",(0,i.kt)("inlineCode",{parentName:"p"},"npm test")," on Linux, you might get an error that mentions ",(0,i.kt)("inlineCode",{parentName:"p"},"ENOSPC"),'. This is because the test runner creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.'),(0,i.kt)("p",null,'This is a "known issue" with some test runners on Linux, as in discussions ',(0,i.kt)("a",{parentName:"p",href:"https://stackoverflow.com/questions/55763428/react-native-error-enospc-system-limit-for-number-of-file-watchers-reached"},"here")," and ",(0,i.kt)("a",{parentName:"p",href:"https://stackoverflow.com/questions/62206460/jest-watch-error-enospc-system-limit-for-number-of-file-watchers-reached"},"here"),"."),(0,i.kt)("p",null,"One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"Command that initially fails with ",(0,i.kt)("inlineCode",{parentName:"li"},"ENOSPC"),": ",(0,i.kt)("inlineCode",{parentName:"li"},"npm test")),(0,i.kt)("li",{parentName:"ul"},'Check the configured limit on "watchers": ',(0,i.kt)("inlineCode",{parentName:"li"},"cat /proc/sys/fs/inotify/max_user_watches")),(0,i.kt)("li",{parentName:"ul"},"Edit the relevant Linux config file: ",(0,i.kt)("inlineCode",{parentName:"li"},"sudo vim /etc/sysctl.conf")),(0,i.kt)("li",{parentName:"ul"},"Add a line at the end of the config file: ",(0,i.kt)("inlineCode",{parentName:"li"},"fs.inotify.max_user_watches=100000")),(0,i.kt)("li",{parentName:"ul"},"Save, exit, and reload the config file: ",(0,i.kt)("inlineCode",{parentName:"li"},"sudo sysctl -p")),(0,i.kt)("li",{parentName:"ul"},"Check that the limit has changed: ",(0,i.kt)("inlineCode",{parentName:"li"},"cat /proc/sys/fs/inotify/max_user_watches")),(0,i.kt)("li",{parentName:"ul"},"Retry the initial command, which should now succeed: ",(0,i.kt)("inlineCode",{parentName:"li"},"npm test"))),(0,i.kt)("h2",{id:"common-issues"},"Common issues"),(0,i.kt)("h3",{id:"installing-dependencies"},"Installing Dependencies"),(0,i.kt)("h4",{id:"brew-not-available"},"Brew Not Available"),(0,i.kt)("p",null,"If you run into issues installing Homebrew in step 1 of ",(0,i.kt)("a",{parentName:"p",href:"quick_start?os=mac#installing-prerequisites"},"Installing Prerequisites")," it may be because Homebrew is not available on your shell. Older versions of macOS (under 10.14) do not do this automatically."),(0,i.kt)("p",null,"Run the following command to manually add the Homebrew installation location to your ",(0,i.kt)("inlineCode",{parentName:"p"},"PATH")," so it is available in your shell."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-shell"},"echo 'PATH=\"/usr/local/bin:$PATH\"' >> ~/.bash_profile\n")),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"If you're using ",(0,i.kt)("inlineCode",{parentName:"p"},"zsh"),", also add to your ",(0,i.kt)("inlineCode",{parentName:"p"},"~/.zshrc")," file.")),(0,i.kt)("h3",{id:"npm-errors"},"NPM Errors"),(0,i.kt)("p",null,"Try deleting your ",(0,i.kt)("inlineCode",{parentName:"p"},"node_modules")," folder and the ",(0,i.kt)("inlineCode",{parentName:"p"},"package-lock.json")," then running ",(0,i.kt)("inlineCode",{parentName:"p"},"npm install")," then ",(0,i.kt)("inlineCode",{parentName:"p"},"npm run rebuild"),". This should fix most issues."))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/399eddc3.e2f86dd6.js b/assets/js/399eddc3.06e04276.js similarity index 98% rename from assets/js/399eddc3.e2f86dd6.js rename to assets/js/399eddc3.06e04276.js index ac4847b8..ee852e46 100644 --- a/assets/js/399eddc3.e2f86dd6.js +++ b/assets/js/399eddc3.06e04276.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[6990],{3905:(e,t,n)=>{n.d(t,{Zo:()=>d,kt:()=>m});var o=n(7294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,o)}return n}function a(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var c=o.createContext({}),l=function(e){var t=o.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},d=function(e){var t=l(e.components);return o.createElement(c.Provider,{value:t},e.children)},p="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},y=o.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,c=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),p=l(n),y=r,m=p["".concat(c,".").concat(y)]||p[y]||u[y]||i;return n?o.createElement(m,a(a({ref:t},d),{},{components:n})):o.createElement(m,a({ref:t},d))}));function m(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,a=new Array(i);a[0]=y;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s[p]="string"==typeof e?e:r,a[1]=s;for(var l=2;l{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>a,default:()=>u,frontMatter:()=>i,metadata:()=>s,toc:()=>l});var o=n(7462),r=(n(7294),n(3905));const i={id:"intro",title:"Introduction",sidebar_label:"Introduction",slug:"/"},a=void 0,s={unversionedId:"intro",id:"version-3.0.0/intro",title:"Introduction",description:"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.",source:"@site/versioned_docs/version-3.0.0/intro.md",sourceDirName:".",slug:"/",permalink:"/honeycomb-docs/docs/3.0.0/",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.0.0/intro.md",tags:[],version:"3.0.0",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"intro",title:"Introduction",sidebar_label:"Introduction",slug:"/"},sidebar:"someSidebar",next:{title:"Project Organization",permalink:"/honeycomb-docs/docs/3.0.0/folders"}},c={},l=[{value:"Flexible deployment online and in the lab",id:"flexible-deployment-online-and-in-the-lab",level:3},{value:"Easy to install executables",id:"easy-to-install-executables",level:3},{value:"Foundation in jsPsych",id:"foundation-in-jspsych",level:3},{value:"Cite this work",id:"cite-this-work",level:3}],d={toc:l},p="wrapper";function u(e){let{components:t,...n}=e;return(0,r.kt)(p,(0,o.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"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."),(0,r.kt)("h3",{id:"flexible-deployment-online-and-in-the-lab"},"Flexible deployment online and in the lab"),(0,r.kt)("p",null,"Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings."),(0,r.kt)("h3",{id:"easy-to-install-executables"},"Easy to install executables"),(0,r.kt)("p",null,"Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites."),(0,r.kt)("h3",{id:"foundation-in-jspsych"},"Foundation in jsPsych"),(0,r.kt)("p",null,"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."),(0,r.kt)("h3",{id:"cite-this-work"},"Cite this work"),(0,r.kt)("p",null,"If you use Honeycomb in your work, please cite"),(0,r.kt)("p",null,(0,r.kt)("a",{parentName:"p",href:"https://doi.org/10.1590/1516-4446-2020-1675"},"Provenza, N.R., Gelin, L.F.F., Mahaphanit, W., McGrath, M.C., Dastin-van Rijn, E.M., Fan, Y., Dhar, R., Frank, M.J., Restrepo, M.I., Goodman, W.K. and Borton, D.A., 2021. Honeycomb: a template for reproducible psychophysiological tasks for clinic, laboratory, and home use. Brazilian Journal of Psychiatry, 44, pp.147-155.")))}u.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[6990],{3905:(e,t,n)=>{n.d(t,{Zo:()=>d,kt:()=>m});var o=n(7294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,o)}return n}function a(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var c=o.createContext({}),l=function(e){var t=o.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},d=function(e){var t=l(e.components);return o.createElement(c.Provider,{value:t},e.children)},p="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},y=o.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,c=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),p=l(n),y=r,m=p["".concat(c,".").concat(y)]||p[y]||u[y]||i;return n?o.createElement(m,a(a({ref:t},d),{},{components:n})):o.createElement(m,a({ref:t},d))}));function m(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,a=new Array(i);a[0]=y;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s[p]="string"==typeof e?e:r,a[1]=s;for(var l=2;l{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>a,default:()=>u,frontMatter:()=>i,metadata:()=>s,toc:()=>l});var o=n(7462),r=(n(7294),n(3905));const i={id:"intro",title:"Introduction",sidebar_label:"Introduction",slug:"/"},a=void 0,s={unversionedId:"intro",id:"version-3.0.0/intro",title:"Introduction",description:"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.",source:"@site/versioned_docs/version-3.0.0/intro.md",sourceDirName:".",slug:"/",permalink:"/honeycomb-docs/docs/3.0.0/",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-3.0.0/intro.md",tags:[],version:"3.0.0",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"intro",title:"Introduction",sidebar_label:"Introduction",slug:"/"},sidebar:"someSidebar",next:{title:"Project Organization",permalink:"/honeycomb-docs/docs/3.0.0/folders"}},c={},l=[{value:"Flexible deployment online and in the lab",id:"flexible-deployment-online-and-in-the-lab",level:3},{value:"Easy to install executables",id:"easy-to-install-executables",level:3},{value:"Foundation in jsPsych",id:"foundation-in-jspsych",level:3},{value:"Cite this work",id:"cite-this-work",level:3}],d={toc:l},p="wrapper";function u(e){let{components:t,...n}=e;return(0,r.kt)(p,(0,o.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"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."),(0,r.kt)("h3",{id:"flexible-deployment-online-and-in-the-lab"},"Flexible deployment online and in the lab"),(0,r.kt)("p",null,"Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings."),(0,r.kt)("h3",{id:"easy-to-install-executables"},"Easy to install executables"),(0,r.kt)("p",null,"Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites."),(0,r.kt)("h3",{id:"foundation-in-jspsych"},"Foundation in jsPsych"),(0,r.kt)("p",null,"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."),(0,r.kt)("h3",{id:"cite-this-work"},"Cite this work"),(0,r.kt)("p",null,"If you use Honeycomb in your work, please cite"),(0,r.kt)("p",null,(0,r.kt)("a",{parentName:"p",href:"https://doi.org/10.1590/1516-4446-2020-1675"},"Provenza, N.R., Gelin, L.F.F., Mahaphanit, W., McGrath, M.C., Dastin-van Rijn, E.M., Fan, Y., Dhar, R., Frank, M.J., Restrepo, M.I., Goodman, W.K. and Borton, D.A., 2021. Honeycomb: a template for reproducible psychophysiological tasks for clinic, laboratory, and home use. Brazilian Journal of Psychiatry, 44, pp.147-155.")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/41ba2ed4.f6ff7350.js b/assets/js/41ba2ed4.09a19979.js similarity index 99% rename from assets/js/41ba2ed4.f6ff7350.js rename to assets/js/41ba2ed4.09a19979.js index 7047e6a4..dc10548c 100644 --- a/assets/js/41ba2ed4.f6ff7350.js +++ b/assets/js/41ba2ed4.09a19979.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[1382],{3905:(e,t,r)=>{r.d(t,{Zo:()=>p,kt:()=>m});var n=r(7294);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function i(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,n)}return r}function o(e){for(var t=1;t=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var l=n.createContext({}),c=function(e){var t=n.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):o(o({},t),e)),r},p=function(e){var t=c(e.components);return n.createElement(l.Provider,{value:t},e.children)},d="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,a=e.mdxType,i=e.originalType,l=e.parentName,p=s(e,["components","mdxType","originalType","parentName"]),d=c(r),f=a,m=d["".concat(l,".").concat(f)]||d[f]||u[f]||i;return r?n.createElement(m,o(o({ref:t},p),{},{components:r})):n.createElement(m,o({ref:t},p))}));function m(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var i=r.length,o=new Array(i);o[0]=f;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[d]="string"==typeof e?e:a,o[1]=s;for(var c=2;c{r.r(t),r.d(t,{assets:()=>l,contentTitle:()=>o,default:()=>u,frontMatter:()=>i,metadata:()=>s,toc:()=>c});var n=r(7462),a=(r(7294),r(3905));const i={id:"firebase",title:"Set up Firebase"},o=void 0,s={unversionedId:"firebase",id:"version-2.x/firebase",title:"Set up Firebase",description:"Honeycomb comes with methods and configurations for easy Firebase and Cloud Firestore set up. Please use this section to configure Firebase Hosting services and firestore cloud storage.",source:"@site/versioned_docs/version-2.x/firebase.md",sourceDirName:".",slug:"/firebase",permalink:"/honeycomb-docs/docs/2.x/firebase",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-2.x/firebase.md",tags:[],version:"2.x",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"firebase",title:"Set up Firebase"},sidebar:"version-2.x/someSidebar",previous:{title:"Version Control",permalink:"/honeycomb-docs/docs/2.x/version_control"},next:{title:"Automated Builds",permalink:"/honeycomb-docs/docs/2.x/ci"}},l={},c=[{value:"Getting Started",id:"getting-started",level:2},{value:"1. Initializing firebase account and project",id:"1-initializing-firebase-account-and-project",level:4},{value:"2. Linking firebase to task",id:"2-linking-firebase-to-task",level:4},{value:"3. Copying web app credentials.",id:"3-copying-web-app-credentials",level:4},{value:"Setting up firestore.",id:"setting-up-firestore",level:2},{value:"Firestore security rules.",id:"firestore-security-rules",level:3}],p={toc:c},d="wrapper";function u(e){let{components:t,...i}=e;return(0,a.kt)(d,(0,n.Z)({},p,i,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"Honeycomb comes with methods and configurations for easy ",(0,a.kt)("a",{parentName:"p",href:"https://firebase.google.com/"},"Firebase")," and ",(0,a.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/firestore"},"Cloud Firestore")," set up. Please use this section to configure ",(0,a.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/hosting"},"Firebase Hosting")," services and firestore cloud storage."),(0,a.kt)("h2",{id:"getting-started"},"Getting Started"),(0,a.kt)("p",null,"Follow these steps to create a firebase project and link it with the current task."),(0,a.kt)("h4",{id:"1-initializing-firebase-account-and-project"},"1. Initializing firebase account and project"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Create and login to a firebase account on ",(0,a.kt)("a",{parentName:"li",href:"https://firebase.google.com/"},"the Firebase website"),"."),(0,a.kt)("li",{parentName:"ul"},"Create a firebase project by clicking add project and enter a Project Name.")),(0,a.kt)("h4",{id:"2-linking-firebase-to-task"},"2. Linking firebase to task"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Install ",(0,a.kt)("a",{parentName:"li",href:"https://firebase.google.com/docs/cli"},"Firebase CLI")," on your local computer."),(0,a.kt)("li",{parentName:"ul"},"Login to firebase using ",(0,a.kt)("inlineCode",{parentName:"li"},"firebase login")," command in the terminal."),(0,a.kt)("li",{parentName:"ul"},"Navigate to the ",(0,a.kt)("inlineCode",{parentName:"li"},".firebaserc")," file home directory and edit the ",(0,a.kt)("inlineCode",{parentName:"li"},'"default"')," field with the project name given in part 1.",(0,a.kt)("pre",{parentName:"li"},(0,a.kt)("code",{parentName:"pre"},'{\n "projects": {\n "default": ""\n }\n} \n')))),(0,a.kt)("h4",{id:"3-copying-web-app-credentials"},"3. Copying web app credentials."),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Navigate to the ",(0,a.kt)("a",{parentName:"li",href:"https://console.firebase.google.com/"},"firebase console")," and select the project."),(0,a.kt)("li",{parentName:"ul"},"Create a new Web App by clicking on ",(0,a.kt)("inlineCode",{parentName:"li"},"Add App")," or the ",(0,a.kt)("inlineCode",{parentName:"li"},"")," code symbol and following the prompts."),(0,a.kt)("li",{parentName:"ul"},"Enter the a name for the Firebase app (could be the same as your Honeycomb task repo name)."),(0,a.kt)("li",{parentName:"ul"},'Check "Also set up Firebase Hosting for this app."'),(0,a.kt)("li",{parentName:"ul"},"Click ",(0,a.kt)("inlineCode",{parentName:"li"},"Register App"),". This should auto-generate a script with several values that you need to copy into the next step."),(0,a.kt)("li",{parentName:"ul"},"Copy the auto-generated values from the Firebase console to the corresponding variables in the ",(0,a.kt)("inlineCode",{parentName:"li"},".env.firebase")," file in the ",(0,a.kt)("inlineCode",{parentName:"li"},"env")," folder of your Honeycomb task repo:",(0,a.kt)("pre",{parentName:"li"},(0,a.kt)("code",{parentName:"pre"}," REACT_APP_apiKey=\n REACT_APP_authDomain=\n REACT_APP_projectId=\n REACT_APP_storageBucket=\n REACT_APP_messagingSenderId=\n REACT_APP_appId=\n"))),(0,a.kt)("li",{parentName:"ul"},"You can skip running ",(0,a.kt)("inlineCode",{parentName:"li"},"firebase init")," if prompted to do so. The results of ",(0,a.kt)("inlineCode",{parentName:"li"},"firebase init")," are already saved into the Honeycomb template repo.")),(0,a.kt)("p",null,"Firebase is now set up!"),(0,a.kt)("h2",{id:"setting-up-firestore"},"Setting up firestore."),(0,a.kt)("p",null,"Honeycomb includes cloud storage for task data using Firestore. Follow these steps to initialize firestore:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Navigate to the current project in the developer console and select ",(0,a.kt)("inlineCode",{parentName:"li"},"Firestore Database")," from the sidebar."),(0,a.kt)("li",{parentName:"ul"},"Click ",(0,a.kt)("inlineCode",{parentName:"li"},"Create Database"),", select ",(0,a.kt)("inlineCode",{parentName:"li"},"production mode")," and choose the current location for the cloud storage bucket.")),(0,a.kt)("h3",{id:"firestore-security-rules"},"Firestore security rules."),(0,a.kt)("p",null,(0,a.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/firestore/security/get-started"},"Firestore Security Rules")," provides easy server-side authorization to the database. For a honeycomb task, we use the security rules to allow access to only authorized participants for a specified study. Honeycomb's default set of rules is included in the ",(0,a.kt)("inlineCode",{parentName:"p"},"firestore.rules")," file in the home directory. This file can be edited to change the rules. To deploy the rules in the file, type the following line of code in the terminal:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"firebase deploy --only firestore:rules\n")),(0,a.kt)("p",null,"Alternatively, Editing the rules directly in the console is also possible. To do so, navigate to the ",(0,a.kt)("inlineCode",{parentName:"p"},"Rules")," tab in the ",(0,a.kt)("inlineCode",{parentName:"p"},"Firestore Database")," section from the firebase console sidebar then copy and paste the code that is in the ",(0,a.kt)("inlineCode",{parentName:"p"},"firestore.rules")," file."),(0,a.kt)("p",null,"Firestore database and rules are now both deployed. For Honeycomb's default set of rules, to add an authorized participant for a study, create a collection named ",(0,a.kt)("inlineCode",{parentName:"p"},"registered_studies"),", add a study with the study ID as the document name in that collection. For each registered study, add an array field named ",(0,a.kt)("inlineCode",{parentName:"p"},"registered_participants")," where each element in the array will be an authorized participant for that study."),(0,a.kt)("p",null,(0,a.kt)("img",{src:r(5472).Z,width:"2266",height:"1152"})))}u.isMDXComponent=!0},5472:(e,t,r)=>{r.d(t,{Z:()=>n});const n=r.p+"assets/images/test-task-e68ca81cee4c093ba7e4974575f118f9.png"}}]); \ No newline at end of file +"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[1382],{3905:(e,t,r)=>{r.d(t,{Zo:()=>p,kt:()=>m});var n=r(7294);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function i(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,n)}return r}function o(e){for(var t=1;t=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var l=n.createContext({}),c=function(e){var t=n.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):o(o({},t),e)),r},p=function(e){var t=c(e.components);return n.createElement(l.Provider,{value:t},e.children)},d="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},f=n.forwardRef((function(e,t){var r=e.components,a=e.mdxType,i=e.originalType,l=e.parentName,p=s(e,["components","mdxType","originalType","parentName"]),d=c(r),f=a,m=d["".concat(l,".").concat(f)]||d[f]||u[f]||i;return r?n.createElement(m,o(o({ref:t},p),{},{components:r})):n.createElement(m,o({ref:t},p))}));function m(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var i=r.length,o=new Array(i);o[0]=f;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s[d]="string"==typeof e?e:a,o[1]=s;for(var c=2;c{r.r(t),r.d(t,{assets:()=>l,contentTitle:()=>o,default:()=>u,frontMatter:()=>i,metadata:()=>s,toc:()=>c});var n=r(7462),a=(r(7294),r(3905));const i={id:"firebase",title:"Set up Firebase"},o=void 0,s={unversionedId:"firebase",id:"version-2.x/firebase",title:"Set up Firebase",description:"Honeycomb comes with methods and configurations for easy Firebase and Cloud Firestore set up. Please use this section to configure Firebase Hosting services and firestore cloud storage.",source:"@site/versioned_docs/version-2.x/firebase.md",sourceDirName:".",slug:"/firebase",permalink:"/honeycomb-docs/docs/2.x/firebase",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/versioned_docs/version-2.x/firebase.md",tags:[],version:"2.x",lastUpdatedAt:1695238280,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"firebase",title:"Set up Firebase"},sidebar:"version-2.x/someSidebar",previous:{title:"Version Control",permalink:"/honeycomb-docs/docs/2.x/version_control"},next:{title:"Automated Builds",permalink:"/honeycomb-docs/docs/2.x/ci"}},l={},c=[{value:"Getting Started",id:"getting-started",level:2},{value:"1. Initializing firebase account and project",id:"1-initializing-firebase-account-and-project",level:4},{value:"2. Linking firebase to task",id:"2-linking-firebase-to-task",level:4},{value:"3. Copying web app credentials.",id:"3-copying-web-app-credentials",level:4},{value:"Setting up firestore.",id:"setting-up-firestore",level:2},{value:"Firestore security rules.",id:"firestore-security-rules",level:3}],p={toc:c},d="wrapper";function u(e){let{components:t,...i}=e;return(0,a.kt)(d,(0,n.Z)({},p,i,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"Honeycomb comes with methods and configurations for easy ",(0,a.kt)("a",{parentName:"p",href:"https://firebase.google.com/"},"Firebase")," and ",(0,a.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/firestore"},"Cloud Firestore")," set up. Please use this section to configure ",(0,a.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/hosting"},"Firebase Hosting")," services and firestore cloud storage."),(0,a.kt)("h2",{id:"getting-started"},"Getting Started"),(0,a.kt)("p",null,"Follow these steps to create a firebase project and link it with the current task."),(0,a.kt)("h4",{id:"1-initializing-firebase-account-and-project"},"1. Initializing firebase account and project"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Create and login to a firebase account on ",(0,a.kt)("a",{parentName:"li",href:"https://firebase.google.com/"},"the Firebase website"),"."),(0,a.kt)("li",{parentName:"ul"},"Create a firebase project by clicking add project and enter a Project Name.")),(0,a.kt)("h4",{id:"2-linking-firebase-to-task"},"2. Linking firebase to task"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Install ",(0,a.kt)("a",{parentName:"li",href:"https://firebase.google.com/docs/cli"},"Firebase CLI")," on your local computer."),(0,a.kt)("li",{parentName:"ul"},"Login to firebase using ",(0,a.kt)("inlineCode",{parentName:"li"},"firebase login")," command in the terminal."),(0,a.kt)("li",{parentName:"ul"},"Navigate to the ",(0,a.kt)("inlineCode",{parentName:"li"},".firebaserc")," file home directory and edit the ",(0,a.kt)("inlineCode",{parentName:"li"},'"default"')," field with the project name given in part 1.",(0,a.kt)("pre",{parentName:"li"},(0,a.kt)("code",{parentName:"pre"},'{\n "projects": {\n "default": ""\n }\n} \n')))),(0,a.kt)("h4",{id:"3-copying-web-app-credentials"},"3. Copying web app credentials."),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Navigate to the ",(0,a.kt)("a",{parentName:"li",href:"https://console.firebase.google.com/"},"firebase console")," and select the project."),(0,a.kt)("li",{parentName:"ul"},"Create a new Web App by clicking on ",(0,a.kt)("inlineCode",{parentName:"li"},"Add App")," or the ",(0,a.kt)("inlineCode",{parentName:"li"},"")," code symbol and following the prompts."),(0,a.kt)("li",{parentName:"ul"},"Enter the a name for the Firebase app (could be the same as your Honeycomb task repo name)."),(0,a.kt)("li",{parentName:"ul"},'Check "Also set up Firebase Hosting for this app."'),(0,a.kt)("li",{parentName:"ul"},"Click ",(0,a.kt)("inlineCode",{parentName:"li"},"Register App"),". This should auto-generate a script with several values that you need to copy into the next step."),(0,a.kt)("li",{parentName:"ul"},"Copy the auto-generated values from the Firebase console to the corresponding variables in the ",(0,a.kt)("inlineCode",{parentName:"li"},".env.firebase")," file in the ",(0,a.kt)("inlineCode",{parentName:"li"},"env")," folder of your Honeycomb task repo:",(0,a.kt)("pre",{parentName:"li"},(0,a.kt)("code",{parentName:"pre"}," REACT_APP_apiKey=\n REACT_APP_authDomain=\n REACT_APP_projectId=\n REACT_APP_storageBucket=\n REACT_APP_messagingSenderId=\n REACT_APP_appId=\n"))),(0,a.kt)("li",{parentName:"ul"},"You can skip running ",(0,a.kt)("inlineCode",{parentName:"li"},"firebase init")," if prompted to do so. The results of ",(0,a.kt)("inlineCode",{parentName:"li"},"firebase init")," are already saved into the Honeycomb template repo.")),(0,a.kt)("p",null,"Firebase is now set up!"),(0,a.kt)("h2",{id:"setting-up-firestore"},"Setting up firestore."),(0,a.kt)("p",null,"Honeycomb includes cloud storage for task data using Firestore. Follow these steps to initialize firestore:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Navigate to the current project in the developer console and select ",(0,a.kt)("inlineCode",{parentName:"li"},"Firestore Database")," from the sidebar."),(0,a.kt)("li",{parentName:"ul"},"Click ",(0,a.kt)("inlineCode",{parentName:"li"},"Create Database"),", select ",(0,a.kt)("inlineCode",{parentName:"li"},"production mode")," and choose the current location for the cloud storage bucket.")),(0,a.kt)("h3",{id:"firestore-security-rules"},"Firestore security rules."),(0,a.kt)("p",null,(0,a.kt)("a",{parentName:"p",href:"https://firebase.google.com/docs/firestore/security/get-started"},"Firestore Security Rules")," provides easy server-side authorization to the database. For a honeycomb task, we use the security rules to allow access to only authorized participants for a specified study. Honeycomb's default set of rules is included in the ",(0,a.kt)("inlineCode",{parentName:"p"},"firestore.rules")," file in the home directory. This file can be edited to change the rules. To deploy the rules in the file, type the following line of code in the terminal:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"firebase deploy --only firestore:rules\n")),(0,a.kt)("p",null,"Alternatively, Editing the rules directly in the console is also possible. To do so, navigate to the ",(0,a.kt)("inlineCode",{parentName:"p"},"Rules")," tab in the ",(0,a.kt)("inlineCode",{parentName:"p"},"Firestore Database")," section from the firebase console sidebar then copy and paste the code that is in the ",(0,a.kt)("inlineCode",{parentName:"p"},"firestore.rules")," file."),(0,a.kt)("p",null,"Firestore database and rules are now both deployed. For Honeycomb's default set of rules, to add an authorized participant for a study, create a collection named ",(0,a.kt)("inlineCode",{parentName:"p"},"registered_studies"),", add a study with the study ID as the document name in that collection. For each registered study, add an array field named ",(0,a.kt)("inlineCode",{parentName:"p"},"registered_participants")," where each element in the array will be an authorized participant for that study."),(0,a.kt)("p",null,(0,a.kt)("img",{src:r(5472).Z,width:"2266",height:"1152"})))}u.isMDXComponent=!0},5472:(e,t,r)=>{r.d(t,{Z:()=>n});const n=r.p+"assets/images/test-task-e68ca81cee4c093ba7e4974575f118f9.png"}}]); \ No newline at end of file diff --git a/assets/js/4cfc1f6d.9ae9c555.js b/assets/js/4cfc1f6d.a3884173.js similarity index 99% rename from assets/js/4cfc1f6d.9ae9c555.js rename to assets/js/4cfc1f6d.a3884173.js index 67389ad5..2aa377b5 100644 --- a/assets/js/4cfc1f6d.9ae9c555.js +++ b/assets/js/4cfc1f6d.a3884173.js @@ -1 +1 @@ -"use strict";(self.webpackChunkhoneycomb=self.webpackChunkhoneycomb||[]).push([[3586],{3905:(e,t,n)=>{n.d(t,{Zo:()=>d,kt:()=>h});var i=n(7294);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);t&&(i=i.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,i)}return n}function l(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(i=0;i=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var p=i.createContext({}),s=function(e){var t=i.useContext(p),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},d=function(e){var t=s(e.components);return i.createElement(p.Provider,{value:t},e.children)},u="mdxType",m={inlineCode:"code",wrapper:function(e){var t=e.children;return i.createElement(i.Fragment,{},t)}},c=i.forwardRef((function(e,t){var n=e.components,a=e.mdxType,r=e.originalType,p=e.parentName,d=o(e,["components","mdxType","originalType","parentName"]),u=s(n),c=a,h=u["".concat(p,".").concat(c)]||u[c]||m[c]||r;return n?i.createElement(h,l(l({ref:t},d),{},{components:n})):i.createElement(h,l({ref:t},d))}));function h(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var r=n.length,l=new Array(r);l[0]=c;var o={};for(var p in t)hasOwnProperty.call(t,p)&&(o[p]=t[p]);o.originalType=e,o[u]="string"==typeof e?e:a,l[1]=o;for(var s=2;s{n.r(t),n.d(t,{assets:()=>p,contentTitle:()=>l,default:()=>m,frontMatter:()=>r,metadata:()=>o,toc:()=>s});var i=n(7462),a=(n(7294),n(3905));const r={id:"npm_scripts",slug:"/npm_scripts",title:"NPM Scripts",description:"Guide to using the npm scripts needed for Honeycomb"},l=void 0,o={unversionedId:"project_organization/npm_scripts",id:"project_organization/npm_scripts",title:"NPM Scripts",description:"Guide to using the npm scripts needed for Honeycomb",source:"@site/docs/project_organization/npm_scripts.mdx",sourceDirName:"project_organization",slug:"/npm_scripts",permalink:"/honeycomb-docs/docs/npm_scripts",draft:!1,editUrl:"https://github.com/brown-ccv/honeycomb-docs/edit/main/docs/project_organization/npm_scripts.mdx",tags:[],version:"current",lastUpdatedAt:1695237946,formattedLastUpdatedAt:"Sep 20, 2023",frontMatter:{id:"npm_scripts",slug:"/npm_scripts",title:"NPM Scripts",description:"Guide to using the npm scripts needed for Honeycomb"},sidebar:"mySidebar",previous:{title:"Directory Structure",permalink:"/honeycomb-docs/docs/directory_structure"},next:{title:"Environment Variables",permalink:"/honeycomb-docs/docs/environment_variables"}},p={},s=[{value:"Start",id:"start",level:2},{value:"Firebase",id:"firebase",level:2},{value:"Dev",id:"dev",level:2},{value:"Firebase",id:"firebase-1",level:3},{value:"Build",id:"build",level:2},{value:"Package",id:"package",level:2},{value:"Miscellaneous",id:"miscellaneous",level:2}],d={toc:s},u="wrapper";function m(e){let{components:t,...n}=e;return(0,a.kt)(u,(0,i.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"Custom scripts for common shell commands can be written in ",(0,a.kt)("inlineCode",{parentName:"p"},"package.json")," and run the node package manager (NPM). All of the commands needed to develop, build, and deploy Honeycomb are written as scripts."),(0,a.kt)("p",null,"Additional scripts can be created if desired but we generally recommend against changing or deleting the scripts Honeycomb ships with."),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-shell",metastring:'title="Executing an NPM Script"',title:'"Executing',an:!0,NPM:!0,'Script"':!0},"npm run
-
Version: 1.1.0

Automated Builds

Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings on demand or automatically as the code is pushed to the repository. In this section, we provide a short introduction to definitions. We explain the GitHub Actions included with Honeycomb. These workflows should provide a foundation but can easily be modified or extended to meet more needs.

What is CI/CD:​

Continuous Integration, Continuous Deployment: CI/CD or CICD refers to continuous integration and either continuous delivery or continuous deployment. CI/CD enforces the automated building of bundled executables so that tasks can be easily installed without dependencies. In Honeycomb, CI/CD is managed by GitHub Actions.

What are Github Actions​

GitHub Actions automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in GitHub's documentation.

GitHub Actions are written as YAML files inside a .github/worflows/ folder in your repository.

Building the executables​

Honeycomb includes workflows to build and create installers for Windows, Mac, and Linux. These workflows exist for two configurations of the tasks:

  • Home: The app does not expect event code triggers and photodiode spots.
  • Clinic: The app expects event code triggers and photodiode spots.

More specifically, the following workflows are included:

  • build.yaml: Every time an Pull Request (PR) is opened, or a push is made to the main branch, the software is built and tests are run for all platforms and home and clinic settings. This workflow does not build and upload desktop installers
  • package.yaml: Create installers for any/all platforms for the home and clinic setting on demand 1. The installers/executables are uploaded as artifacts and are available for download from the GitHub Actions tab. This also builds PsiTurk version when linux or all operating systems are selected
  • release.yml: Every time a Tag is released, installers are created and uploaded as packages. This also builds PsiTurk version, and deploys to GitHub pages a web version of the application.
1 On-demand workflows are triggered manually from the GitHub Actions tab. Each GitHub organization/individual has a quota on storage on private repositories. Uploading artifacts counts against your quota. You may consider configuring your workflows to only upload what you need.

Download your bundled executable to install and run your task​

You can download the executable file from either the tagged release page or the GitHub actions page. To install, unzip the downloaded file and allow to run.

The executable does not require installation of any additional software.

Uninstall the task​

Windows​

Go to System Settings: Add or remove programs. Look for the name of your task in the installed programs list, and Uninstall.

- +
Version: 1.1.0

Automated Builds

Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings on demand or automatically as the code is pushed to the repository. In this section, we provide a short introduction to definitions. We explain the GitHub Actions included with Honeycomb. These workflows should provide a foundation but can easily be modified or extended to meet more needs.

What is CI/CD:​

Continuous Integration, Continuous Deployment: CI/CD or CICD refers to continuous integration and either continuous delivery or continuous deployment. CI/CD enforces the automated building of bundled executables so that tasks can be easily installed without dependencies. In Honeycomb, CI/CD is managed by GitHub Actions.

What are Github Actions​

GitHub Actions automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in GitHub's documentation.

GitHub Actions are written as YAML files inside a .github/worflows/ folder in your repository.

Building the executables​

Honeycomb includes workflows to build and create installers for Windows, Mac, and Linux. These workflows exist for two configurations of the tasks:

  • Home: The app does not expect event code triggers and photodiode spots.
  • Clinic: The app expects event code triggers and photodiode spots.

More specifically, the following workflows are included:

  • build.yaml: Every time an Pull Request (PR) is opened, or a push is made to the main branch, the software is built and tests are run for all platforms and home and clinic settings. This workflow does not build and upload desktop installers
  • package.yaml: Create installers for any/all platforms for the home and clinic setting on demand 1. The installers/executables are uploaded as artifacts and are available for download from the GitHub Actions tab. This also builds PsiTurk version when linux or all operating systems are selected
  • release.yml: Every time a Tag is released, installers are created and uploaded as packages. This also builds PsiTurk version, and deploys to GitHub pages a web version of the application.
1 On-demand workflows are triggered manually from the GitHub Actions tab. Each GitHub organization/individual has a quota on storage on private repositories. Uploading artifacts counts against your quota. You may consider configuring your workflows to only upload what you need.

Download your bundled executable to install and run your task​

You can download the executable file from either the tagged release page or the GitHub actions page. To install, unzip the downloaded file and allow to run.

The executable does not require installation of any additional software.

Uninstall the task​

Windows​

Go to System Settings: Add or remove programs. Look for the name of your task in the installed programs list, and Uninstall.

+ \ No newline at end of file diff --git a/docs/1.1.0/configuration/index.html b/docs/1.1.0/configuration/index.html index e47943f8..6de7b538 100644 --- a/docs/1.1.0/configuration/index.html +++ b/docs/1.1.0/configuration/index.html @@ -4,13 +4,13 @@ Configuration | Honeycomb - +
-
Version: 1.1.0

Configuration

Environment Variables​

Honeycomb uses environment variables during build and run time to control the different configurations. Below we list the environment variables used by the app and indicate whether they are mandatory, optional and needed during build (npm build) or run time (using the application executable or npm run dev)

  • ELECTRON_START_URL : URL (e.g. http://localhost:3000) where the front end of the app is being hosted - also used in electron.js to indicate the app is running in dev mode
  • EVENT_MARKER_PRODUCT_ID: The product ID of the event marker (e.g. 0487). If not set, it will use the productID set in public/config/trigger.js if available, or attempt to connect using the com name.
  • EVENT_MARKER_COM_NAME : The com name of the event marker (e.g. COM3). If not set, it will use the comName set in public/config/trigger.js. If the productID is set (not an empty string), this field will be ignored.
  • REACT_APP_AT_HOME: whether the app is being used in home mode (true) or clinic mode (false). During development and build time, you can run npm run dev:home/npm run dev:clinic or npm run build:home/npm run build:clinic to have the npm script set the variable for you. When running the production desktop application, you need to define it. Not defining this variable is equivalent to setting it to false. Build-time and run-time values need to be the same.
  • REACT_APP_PATIENT_ID : The default patient id to show when requesting a patient ID in userID. If not set, no default is shown (blank input box).
- +
Version: 1.1.0

Configuration

Environment Variables​

Honeycomb uses environment variables during build and run time to control the different configurations. Below we list the environment variables used by the app and indicate whether they are mandatory, optional and needed during build (npm build) or run time (using the application executable or npm run dev)

  • ELECTRON_START_URL : URL (e.g. http://localhost:3000) where the front end of the app is being hosted - also used in electron.js to indicate the app is running in dev mode
  • EVENT_MARKER_PRODUCT_ID: The product ID of the event marker (e.g. 0487). If not set, it will use the productID set in public/config/trigger.js if available, or attempt to connect using the com name.
  • EVENT_MARKER_COM_NAME : The com name of the event marker (e.g. COM3). If not set, it will use the comName set in public/config/trigger.js. If the productID is set (not an empty string), this field will be ignored.
  • REACT_APP_AT_HOME: whether the app is being used in home mode (true) or clinic mode (false). During development and build time, you can run npm run dev:home/npm run dev:clinic or npm run build:home/npm run build:clinic to have the npm script set the variable for you. When running the production desktop application, you need to define it. Not defining this variable is equivalent to setting it to false. Build-time and run-time values need to be the same.
  • REACT_APP_PATIENT_ID : The default patient id to show when requesting a patient ID in userID. If not set, no default is shown (blank input box).
+ \ No newline at end of file diff --git a/docs/1.1.0/event_triggers/index.html b/docs/1.1.0/event_triggers/index.html index 1e8d278c..541f472e 100644 --- a/docs/1.1.0/event_triggers/index.html +++ b/docs/1.1.0/event_triggers/index.html @@ -4,15 +4,15 @@ Set up event triggers | Honeycomb - +
Version: 1.1.0

Set up event triggers

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:

COMNAME

and set to 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 pdSpotEncodewith the proper eventCode (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.

- +./trigger and export as eventCodes

Whenever you would like to send an event code in a trial, load eventCodes from ../config/main/, and call pdSpotEncodewith the proper eventCode (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.

+ \ No newline at end of file diff --git a/docs/1.1.0/folders/index.html b/docs/1.1.0/folders/index.html index cf9ede22..86e4ca20 100644 --- a/docs/1.1.0/folders/index.html +++ b/docs/1.1.0/folders/index.html @@ -4,13 +4,13 @@ Project Organization | Honeycomb - +
-
Version: 1.1.0

Project Organization

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 definitely not mutated), 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. Below are descriptions of the main files and folders.

package.json​

The package.json file contains metadata about your project and scripts to run tasks related to your task. The name should be updated to your task's name and scripts can be added as desired, but otherwise this file should not be edited manually. To remove or add a dependency use npm install or npm uninstall with the -D flag if installing a dev dependency.

The package-lock.json contains metadata about the package installation. It should never be manually updated.

assets/​

The icons used for the installed applications are put here.

public/​

The public directory contains files that are used as assets in the built app. The favicon.ico is the small icon you can see in the browser tab (on Chrome) - it is set to Brown's logo in the project. The index.html contains the shell of your website - the name displayed on the tab can be changed here, otherwise it shouldn't need to be edited. The scripts included in the file are for psiturk as are the files in the lib/ directory.

electron.js​

This file contains all of the code relating to the electron app. This includes the event-marker, throwing errors via dialog windows, saving data, and reading files.

config/​

The config directory contains the config files needed for the electron app. This includes the event-marker details and event codes.

Note: the productId can be overwritten by the environment variable EVENT_MARKER_PRODUCT_ID

src/​

This folder contains the code for the app, the vast majority of changes and code should go here.

App.js​

This is the starting point for the app. The <Experiment> component initializes a jspsych experiment. This is also where communication is set up with the electron and psiturk processes.

App.css​

This is where styling for the app is housed. If colors, fonts, spacing, etc. need to be set, do it here.

assets/​

This folder contains any static files that are used by the app, such as images.

config/​

In the config/ directory, there are .js files which contain settings for the different parts of the task. Every task should have a main config and a trigger config (assuming use of the event marker). The main config has all global settings for the task (such as whether it is in mturk mode or not), load the appropriate language file, and set up a default (or only) configuration object for the task. The trigger config has settings specific to the event marker and uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.

Other config files can be used to add settings for specific blocks or sub-sections of the experiment.

language/​

Any language that is displayed in the experiment should be stored in this folder. Usage of language json files allows for easy internationalization of the task (e.g. english and spanish) as well as allows for mturk specific language. This also makes it easy to re-use common phrases in many places in the task.

lib/​

The lib/ directory contains utility functions and markup that is used in the tasks. This allows for functions and html to be re-used wherever needed. The lib/utils.js file contains functions that are generally useful across many tasks, whereas lib/taskUtils.js contains functions specific to this task.

lib/markup​

markup files should contain primarily templates for HTML that is used throughout the task. Typically this will be a function that takes in some parameters and then returns a string with html.

timelines​

jspsych uses timelines to control what trials are displayed in what order. timelines can contain other timelines, which is why there may be several files in this directory. The main.js file should have the timeline that is called by App.js.

trials​

jspsych uses trials as its base unit of an experiment. These trials do things such as display some stimulus or request a response.

- +
Version: 1.1.0

Project Organization

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 definitely not mutated), 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. Below are descriptions of the main files and folders.

package.json​

The package.json file contains metadata about your project and scripts to run tasks related to your task. The name should be updated to your task's name and scripts can be added as desired, but otherwise this file should not be edited manually. To remove or add a dependency use npm install or npm uninstall with the -D flag if installing a dev dependency.

The package-lock.json contains metadata about the package installation. It should never be manually updated.

assets/​

The icons used for the installed applications are put here.

public/​

The public directory contains files that are used as assets in the built app. The favicon.ico is the small icon you can see in the browser tab (on Chrome) - it is set to Brown's logo in the project. The index.html contains the shell of your website - the name displayed on the tab can be changed here, otherwise it shouldn't need to be edited. The scripts included in the file are for psiturk as are the files in the lib/ directory.

electron.js​

This file contains all of the code relating to the electron app. This includes the event-marker, throwing errors via dialog windows, saving data, and reading files.

config/​

The config directory contains the config files needed for the electron app. This includes the event-marker details and event codes.

Note: the productId can be overwritten by the environment variable EVENT_MARKER_PRODUCT_ID

src/​

This folder contains the code for the app, the vast majority of changes and code should go here.

App.js​

This is the starting point for the app. The <Experiment> component initializes a jspsych experiment. This is also where communication is set up with the electron and psiturk processes.

App.css​

This is where styling for the app is housed. If colors, fonts, spacing, etc. need to be set, do it here.

assets/​

This folder contains any static files that are used by the app, such as images.

config/​

In the config/ directory, there are .js files which contain settings for the different parts of the task. Every task should have a main config and a trigger config (assuming use of the event marker). The main config has all global settings for the task (such as whether it is in mturk mode or not), load the appropriate language file, and set up a default (or only) configuration object for the task. The trigger config has settings specific to the event marker and uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.

Other config files can be used to add settings for specific blocks or sub-sections of the experiment.

language/​

Any language that is displayed in the experiment should be stored in this folder. Usage of language json files allows for easy internationalization of the task (e.g. english and spanish) as well as allows for mturk specific language. This also makes it easy to re-use common phrases in many places in the task.

lib/​

The lib/ directory contains utility functions and markup that is used in the tasks. This allows for functions and html to be re-used wherever needed. The lib/utils.js file contains functions that are generally useful across many tasks, whereas lib/taskUtils.js contains functions specific to this task.

lib/markup​

markup files should contain primarily templates for HTML that is used throughout the task. Typically this will be a function that takes in some parameters and then returns a string with html.

timelines​

jspsych uses timelines to control what trials are displayed in what order. timelines can contain other timelines, which is why there may be several files in this directory. The main.js file should have the timeline that is called by App.js.

trials​

jspsych uses trials as its base unit of an experiment. These trials do things such as display some stimulus or request a response.

+ \ No newline at end of file diff --git a/docs/1.1.0/index.html b/docs/1.1.0/index.html index 18d66edd..f670924c 100644 --- a/docs/1.1.0/index.html +++ b/docs/1.1.0/index.html @@ -4,13 +4,13 @@ Introduction | Honeycomb - +
-
Version: 1.1.0

Introduction

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.

Flexible deployment online and in the lab​

Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings.

Easy to install executables​

Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites.

Foundation in jsPsych​

jsPsych tasks can be converted to the Honeycomb structure to take advantage of the flexible deployment and automated GitHub Actions workflow that Honeycomb provides.

- +
Version: 1.1.0

Introduction

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.

Flexible deployment online and in the lab​

Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings.

Easy to install executables​

Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites.

Foundation in jsPsych​

jsPsych tasks can be converted to the Honeycomb structure to take advantage of the flexible deployment and automated GitHub Actions workflow that Honeycomb provides.

+ \ No newline at end of file diff --git a/docs/1.1.0/npm_scripts/index.html b/docs/1.1.0/npm_scripts/index.html index bab6958f..b3f4b9ec 100644 --- a/docs/1.1.0/npm_scripts/index.html +++ b/docs/1.1.0/npm_scripts/index.html @@ -4,14 +4,14 @@ NPM Scripts | Honeycomb - +
Version: 1.1.0

NPM Scripts

In the project directory, you can run:

npm run dev​

Runs npm start and npm run electron-dev concurrently. This may not play nicely with windows. If it doesn't, run npm start and npm run electron-dev from different terminal windows.

npm start​

Runs the app in the development mode.

Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.

You will also see any lint errors in the console.

npm test​

Launches the test runner in the interactive watch mode.

See the section about running tests for more information.

npm build​

Creates a production build of the app (renderer). This must be done before running package:platform or the psiturk build instructions.

npm run package:platform​

It correctly bundles creates electron packages for the given platform. It then creates an installer for that platform. The output can be found in /dist -platforms: windows, mac, linux.

Prerequisites​

If not running this command on a windows machine, must have mono and wine installed.

npm run eject​

Note: this is a one-way operation. Once you eject, you can’t go back!

If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.

Run Electron​

npm run electron​

Run the built app.

npm run electron-dev​

Run the current state of the code (un-built).

- +platforms: windows, mac, linux.

Prerequisites​

If not running this command on a windows machine, must have mono and wine installed.

npm run eject​

Note: this is a one-way operation. Once you eject, you can’t go back!

If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.

Run Electron​

npm run electron​

Run the built app.

npm run electron-dev​

Run the current state of the code (un-built).

+ \ No newline at end of file diff --git a/docs/1.1.0/online_integration/index.html b/docs/1.1.0/online_integration/index.html index 3493eb66..b4212b2c 100644 --- a/docs/1.1.0/online_integration/index.html +++ b/docs/1.1.0/online_integration/index.html @@ -4,7 +4,7 @@ Deploy online | Honeycomb - + @@ -13,8 +13,8 @@ PsiTurk is a Python package used to manage HITs in Mechanical Turk. Before using the provided script, install PsiTurk.

You'll need to follow these steps (the path to the PsiTurk project should be a directory you wish to be created):

  • Build the application: npm run build

  • Move to the psiturkit directory: cd psiturkit

  • If it's the first time you're running the script:
    ./psiturk-it -p <PATH_TO_NEW_PSITURK_PROJECT>

  • To update an existing PsiTurk project (the path to the PsiTurk project should already exist from the previous steps):
    ./psiturk-it -u -p <PATH_TO_NEW_PSITURK_PROJECT>

Running psiturk​

After that, just navigate to your newly created PsiTurk project directory.

shell> psiturk #start psiturk
psiturk> server on #start server
psiturk> debug #debug mode

Running on the Web​

Running npm run build generates static content into the build directory that can be served using any static contents hosting service. The workflow .github/workflows/release-home-all.yml uploads the build directory to the gh-branch to serve the application on GitHub pages as an example. After a creating a tag, the workflow will run and your application will be served at <githubuser>.github.io/<repository>. -For this step to succeed you will need to create a deploy key and enable GitHub Pages for your repository.

  1. Generate a new SSH key.
  2. By default, your public key should have been created in ~/.ssh/id_rsa.pub or use the name you've provided.
  3. Copy key to clipboard with xclip -sel clip < ~/.ssh/id_rsa.pub and paste it as a deploy key in your repository. Copy file content if the command line doesn't work for you. Check the box for Allow write access before saving your deployment key.
  4. You'll need your private key as a GitHub secret to allow the workflow to run the deployment for you.
  5. To create the secret copy your private key e.g. xclip -sel clip < ~/.ssh/id_rsa and paste a GitHub secret with name GH_PAGES_DEPLOY. Copy file content if the command line doesn't work for you. Save your secret.
  6. Make sure the publishing source for your repository is configured for gh-pages branch.
- +For this step to succeed you will need to create a deploy key and enable GitHub Pages for your repository.

  1. Generate a new SSH key.
  2. By default, your public key should have been created in ~/.ssh/id_rsa.pub or use the name you've provided.
  3. Copy key to clipboard with xclip -sel clip < ~/.ssh/id_rsa.pub and paste it as a deploy key in your repository. Copy file content if the command line doesn't work for you. Check the box for Allow write access before saving your deployment key.
  4. You'll need your private key as a GitHub secret to allow the workflow to run the deployment for you.
  5. To create the secret copy your private key e.g. xclip -sel clip < ~/.ssh/id_rsa and paste a GitHub secret with name GH_PAGES_DEPLOY. Copy file content if the command line doesn't work for you. Save your secret.
  6. Make sure the publishing source for your repository is configured for gh-pages branch.
+ \ No newline at end of file diff --git a/docs/1.1.0/quick_start/index.html b/docs/1.1.0/quick_start/index.html index 948e092e..bc1cc07e 100644 --- a/docs/1.1.0/quick_start/index.html +++ b/docs/1.1.0/quick_start/index.html @@ -4,7 +4,7 @@ Quick Start | Honeycomb - + @@ -13,8 +13,8 @@ Honeycomb relies on Electron to package the cross-platform desktop applications. Before starting, you will need to install Electron's pre-requisites. You can find instructions here for your specific OS

Honeycomb npm packages Once Node.js is installed you will able to use npm commands in the terminal. To install the dependencies for HoneyComb run the following command at the terminal (remember you need cd your-new-task-name before)

npm install

4. Run the task in dev mode​

To launch an electron window with the task with the inspector open to the console and will hot-reload when changes are made to the app

**For Mac and Linux:

npm run dev

**For Windows: You will need to open 2 terminals. In the first -and make sure you are in the task-<TASK NAME> repo directory- run the command:

npm start

In the second terminal - make sure you are in the task-<TASK NAME> repo directory-, run:

npm run electron-dev

5. Check out the data​

The data is saved throughout the task to the users's app directory. This is logged at the beginning of the task wherever you ran npm run dev (for windows, instead in two different terminals ran npm start and npm run electron-dev). It is also stored in a folder that is generated by the app, which should be found on the desktop.

6. Quit The Task​

If you want to quit in the middle of the task, you can use these keyboard shortcuts:

Ctrl+W (for PC/Windows)
Cmd+Q (for Mac)

Partial data will be saved.

7. Merge updates from honeycomb template repo​

Honeycomb is an active project, and will be updated with new features over time. To merge the honeycomb template repository updates with your task, follow the following steps: -First time only:

git remote add honeycomb https://github.com/brown-ccv/honeycomb.git

Every time: 

git fetch --all
git merge honeycomb/main --allow-unrelated histories

If there are any conflicts:

git stash

To merge:

git commit -a -m "merge honeycomb latest"
- +First time only:

git remote add honeycomb https://github.com/brown-ccv/honeycomb.git

Every time: 

git fetch --all
git merge honeycomb/main --allow-unrelated histories

If there are any conflicts:

git stash

To merge:

git commit -a -m "merge honeycomb latest"
+ \ No newline at end of file diff --git a/docs/1.1.0/software_prerecs/index.html b/docs/1.1.0/software_prerecs/index.html index 5884847c..7c25cb6b 100644 --- a/docs/1.1.0/software_prerecs/index.html +++ b/docs/1.1.0/software_prerecs/index.html @@ -4,15 +4,15 @@ Software Prerequisites | Honeycomb - +
Version: 1.1.0

Software Prerequisites

Windows​

Visual Studio​

Install the latest version of Visual Studio (https://visualstudio.microsoft.com/downloads/) with the Desktop Development for C++ Workflow. To add the workflow, follow the instructions linked below: -https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#:~:text=If%20you%20have%20Visual%20Studio,Then%2C%20choose%20Modify.

Python​

Install Python. For new Python users, we recommend installing via Anaconda: https://docs.anaconda.com/anaconda/install/windows/

Node.js​

Install Node.js: https://nodejs.org/en/download/

Git bash​

Install git bash: https://git-scm.com/downloads

Note: restart computer after all installs are complete​

- +https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#:~:text=If%20you%20have%20Visual%20Studio,Then%2C%20choose%20Modify.

Python​

Install Python. For new Python users, we recommend installing via Anaconda: https://docs.anaconda.com/anaconda/install/windows/

Node.js​

Install Node.js: https://nodejs.org/en/download/

Git bash​

Install git bash: https://git-scm.com/downloads

Note: restart computer after all installs are complete​

+ \ No newline at end of file diff --git a/docs/1.1.0/troubleshooting/index.html b/docs/1.1.0/troubleshooting/index.html index bd49cca7..52a168c9 100644 --- a/docs/1.1.0/troubleshooting/index.html +++ b/docs/1.1.0/troubleshooting/index.html @@ -4,13 +4,13 @@ Troubleshooting | Honeycomb - +
-
Version: 1.1.0

Troubleshooting

When developing electron apps there are two processes: main, and renderer. In this case main corresponds to electron-starter.js and its console is wherever you called npm run dev or electron . from. renderer corresponds to the React App - this is everything else. The react app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running npm run dev, it should open by default.

Potential Issues​

Try deleting your node_modules folder and the package-lock.json then running npm install then npm run rebuild.

- +
Version: 1.1.0

Troubleshooting

When developing electron apps there are two processes: main, and renderer. In this case main corresponds to electron-starter.js and its console is wherever you called npm run dev or electron . from. renderer corresponds to the React App - this is everything else. The react app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running npm run dev, it should open by default.

Potential Issues​

Try deleting your node_modules folder and the package-lock.json then running npm install then npm run rebuild.

+ \ No newline at end of file diff --git a/docs/1.1.0/version_control/index.html b/docs/1.1.0/version_control/index.html index accf83f3..25b1afc5 100644 --- a/docs/1.1.0/version_control/index.html +++ b/docs/1.1.0/version_control/index.html @@ -4,13 +4,13 @@ Version Control | Honeycomb - +
-
Version: 1.1.0

Version Control

Git Overview​

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.

Git creates a hidden .git folder (in the current folder) to store the details of the file system - this folder contains all the data required to track your files and is known as a repository, or repo.

Git tracks file changes by the user creating a save point, or in Git terms a commit. Each commit takes a snapshot of the current file system. Commits are uniquely identified by a SHA–1 hash. This is a 40 character string which may along the lines of ded7a0db6422d59e9893e975e32275fc36f853daThis hash can be used to track a particular commit within the repository.

Nearly all operations that are performed by Git are in you 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. In summary, a typical flow consists of making changes to your files, staging them via git add, marking a save point via git commit, then finally syncing to your remote (e.g., GitHub) via git push. If you are pushing changes to your remote from multiple places, you can bring changes your most recent version using git pull, which is the equivalent of doing git fetch followed by a git merge operation

Cheatsheet​

CommandBrief
git add <files>add a file to next commit (stage)
git commit -m <message>commit staged files
git pushupload staged commit to repo
git pullget remote repo commits and download (try and resolve conflicts)
git clone <url>download entire repository

Best Practices​

Workflow​

We recommend 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.
  • Everyone starts from main, and targets main.
  • Commit messages reflect intent.

Branches​

  • main is the default branch and where releases are made off. 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

Comment styles​

We encourage using Commitizen, a great tool for writing angular commits - this will create a standardized commit format which makes for easier change logging and more sane messages.

- +
Version: 1.1.0

Version Control

Git Overview​

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.

Git creates a hidden .git folder (in the current folder) to store the details of the file system - this folder contains all the data required to track your files and is known as a repository, or repo.

Git tracks file changes by the user creating a save point, or in Git terms a commit. Each commit takes a snapshot of the current file system. Commits are uniquely identified by a SHA–1 hash. This is a 40 character string which may along the lines of ded7a0db6422d59e9893e975e32275fc36f853daThis hash can be used to track a particular commit within the repository.

Nearly all operations that are performed by Git are in you 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. In summary, a typical flow consists of making changes to your files, staging them via git add, marking a save point via git commit, then finally syncing to your remote (e.g., GitHub) via git push. If you are pushing changes to your remote from multiple places, you can bring changes your most recent version using git pull, which is the equivalent of doing git fetch followed by a git merge operation

Cheatsheet​

CommandBrief
git add <files>add a file to next commit (stage)
git commit -m <message>commit staged files
git pushupload staged commit to repo
git pullget remote repo commits and download (try and resolve conflicts)
git clone <url>download entire repository

Best Practices​

Workflow​

We recommend 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.
  • Everyone starts from main, and targets main.
  • Commit messages reflect intent.

Branches​

  • main is the default branch and where releases are made off. 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

Comment styles​

We encourage using Commitizen, a great tool for writing angular commits - this will create a standardized commit format which makes for easier change logging and more sane messages.

+ \ No newline at end of file diff --git a/docs/2.x/ci/index.html b/docs/2.x/ci/index.html index 5b4203ad..3165f694 100644 --- a/docs/2.x/ci/index.html +++ b/docs/2.x/ci/index.html @@ -4,13 +4,13 @@ Automated Builds | Honeycomb - +
-
Version: 2.x

Automated Builds

Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings on demand or automatically as the code is pushed to the repository. In this section, we provide a short introduction to definitions. We explain the GitHub Actions included with Honeycomb. These workflows should provide a foundation but can easily be modified or extended to meet more needs.

What is CI/CD:​

Continuous Integration, Continuous Deployment: CI/CD or CICD refers to continuous integration and either continuous delivery or continuous deployment. CI/CD enforces the automated building of bundled executables so that tasks can be easily installed without dependencies. In Honeycomb, CI/CD is managed by GitHub Actions.

What are Github Actions​

GitHub Actions automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in GitHub's documentation

GitHub Actions are written as YML files inside a .github/worflows/ folder in your repository.

Building the executables​

Honeycomb includes workflows to build and create installers for Windows. Mac and Linux. These workflows exist for two configurations of the tasks:

  • Home: The app does not expect event code triggers and photodiode spots.
  • Clinic: The app expects event code triggers and photodiode spots.

More specifically, the following workflows are included:

  • build.yaml: Every time an Pull Request (PR) is opened, or a push is made to the main branch, the software is built and tests are run for all platforms and home and clinic settings. This workflow does not build and upload desktop installers
  • package.yaml: Create installers for any/all platforms for the home and clinic setting on demand 1. The installers/executables are uploaded as artifacts and are available for download from the GitHub Actions tab. This also builds PsiTurk version when linux or all operating systems are selected
  • release.yml: Every time a Tag is released, installers are created and uploaded as packages. This also builds PsiTurk version, and deploys to GitHub pages a web version of the application.
1 On-demand workflows are triggered manually from the GitHub Actions tab. Each GitHub organization/individual has a quota on storage on 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).

Github Actions for firebase hosting​

Automatic deployment on a firebase hosting site can also be setup with github actions. Before proceeding with the follwing steps, please make sure that firebase is configured by following the Getting started with firebase section under Set Up Firebase

  • Run firebase init hosting:github in the terminal and follow the CLI prompts to start setting up the github actions.
    • For the github directory question, select your task github directory.
    • When prompted with the npm command, type npm install && npm run build:firebase

There should be two new .yml files, firebase-hosting-pull-request.yml and firebase-hosting-merge.yml, created in the .github/workflows directory for a deployment preview for each pull request and the official deployment when merged onto the main branch.

Download your bundled executable to install and run your task​

You can download the executable file from either the tagged release page or the GitHub actions page. To install, unzip the downloaded file, install and run.

The executable does not require installation of any additional software.

Uninstall the task​

Windows​

Go to System Settings: Add or remove programs. Look for the name of your task in the installed programs list, and uninstall.

- +
Version: 2.x

Automated Builds

Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings on demand or automatically as the code is pushed to the repository. In this section, we provide a short introduction to definitions. We explain the GitHub Actions included with Honeycomb. These workflows should provide a foundation but can easily be modified or extended to meet more needs.

What is CI/CD:​

Continuous Integration, Continuous Deployment: CI/CD or CICD refers to continuous integration and either continuous delivery or continuous deployment. CI/CD enforces the automated building of bundled executables so that tasks can be easily installed without dependencies. In Honeycomb, CI/CD is managed by GitHub Actions.

What are Github Actions​

GitHub Actions automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in GitHub's documentation

GitHub Actions are written as YML files inside a .github/worflows/ folder in your repository.

Building the executables​

Honeycomb includes workflows to build and create installers for Windows. Mac and Linux. These workflows exist for two configurations of the tasks:

  • Home: The app does not expect event code triggers and photodiode spots.
  • Clinic: The app expects event code triggers and photodiode spots.

More specifically, the following workflows are included:

  • build.yaml: Every time an Pull Request (PR) is opened, or a push is made to the main branch, the software is built and tests are run for all platforms and home and clinic settings. This workflow does not build and upload desktop installers
  • package.yaml: Create installers for any/all platforms for the home and clinic setting on demand 1. The installers/executables are uploaded as artifacts and are available for download from the GitHub Actions tab. This also builds PsiTurk version when linux or all operating systems are selected
  • release.yml: Every time a Tag is released, installers are created and uploaded as packages. This also builds PsiTurk version, and deploys to GitHub pages a web version of the application.
1 On-demand workflows are triggered manually from the GitHub Actions tab. Each GitHub organization/individual has a quota on storage on 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).

Github Actions for firebase hosting​

Automatic deployment on a firebase hosting site can also be setup with github actions. Before proceeding with the follwing steps, please make sure that firebase is configured by following the Getting started with firebase section under Set Up Firebase

  • Run firebase init hosting:github in the terminal and follow the CLI prompts to start setting up the github actions.
    • For the github directory question, select your task github directory.
    • When prompted with the npm command, type npm install && npm run build:firebase

There should be two new .yml files, firebase-hosting-pull-request.yml and firebase-hosting-merge.yml, created in the .github/workflows directory for a deployment preview for each pull request and the official deployment when merged onto the main branch.

Download your bundled executable to install and run your task​

You can download the executable file from either the tagged release page or the GitHub actions page. To install, unzip the downloaded file, install and run.

The executable does not require installation of any additional software.

Uninstall the task​

Windows​

Go to System Settings: Add or remove programs. Look for the name of your task in the installed programs list, and uninstall.

+ \ No newline at end of file diff --git a/docs/2.x/configuration/index.html b/docs/2.x/configuration/index.html index 4ac47ff1..40f669f4 100644 --- a/docs/2.x/configuration/index.html +++ b/docs/2.x/configuration/index.html @@ -4,13 +4,13 @@ Configuration | Honeycomb - +
-
Version: 2.x

Configuration

Environment Variables​

Honeycomb uses environment variables during build and run time to control the different configurations. Below we list the environment variables used by the app and indicate whether they are mandatory, optional and needed during build (npm build) or run time (using the application executable or npm run dev)

  • ELECTRON_START_URL stringoptional: URL (e.g. http://localhost:3000) where the front end of the app is being hosted - also used in electron.js to indicate the app is running in dev mode.
  • EVENT_MARKER_PRODUCT_IDstringoptionalruntime: The product ID of the event marker (e.g. 0487). If not set, it will use the productID set in public/config/trigger.js if available, or attempt to connect using the com name.
  • EVENT_MARKER_COM_NAME stringoptionalruntime: The com name of the event marker (e.g. COM3). If not set, it will use the comName set in public/config/trigger.js. If the productID is set (not an empty string), this field will be ignored.
  • REACT_APP_VOLUMEbooleandefault falsebuildtime: whether the participant is being asked to adjust volume. This can be used on both the desktop (electron) and online settings.
  • REACT_APP_VIDEObooleandefault falsebuildtime: whether the participant is being video recorded. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_EEGbooleandefault falsebuildtime: whether the event marker/EEG is available. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_PHOTODIODEbooleandefault falsebuildtime: whether the photodiode is in use. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_PARTICIPANT_ID stringoptionalruntime: The default participant id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.
  • REACT_APP_STUDY_ID stringoptionalruntime: The default study id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.

Here are details on some of the badges:

  • runtime: Run-time environment variable. Set at the system level. See this tutorial for OS specific instructions.

  • buildtime: Build-time environment variable. Set in a .env file before building. Can also be defined in a separate file under the env/ directory and called with the dotenv-cli before building. NOTE: The dotenv command will not work directly from the command line. Instead, to set build-time environment variables, either run an existing npm script (e.g., npm run build:clinic, which sets clinic variables) or add a new script to package.json with the following format:

"[build|dev]:<script name>": "dotenv -e env/<your env file> npm run [build|dev]"

Or, to add your new variables to an existing environment configuration, e.g. .env.clinic, create a script in the following format:

"[build|dev]:<script name>": "dotenv -e env/<your env file> npm run [build|dev]:clinic"

Then run the script like so: npm run [build|dev]:<script name>.

- +
Version: 2.x

Configuration

Environment Variables​

Honeycomb uses environment variables during build and run time to control the different configurations. Below we list the environment variables used by the app and indicate whether they are mandatory, optional and needed during build (npm build) or run time (using the application executable or npm run dev)

  • ELECTRON_START_URL stringoptional: URL (e.g. http://localhost:3000) where the front end of the app is being hosted - also used in electron.js to indicate the app is running in dev mode.
  • EVENT_MARKER_PRODUCT_IDstringoptionalruntime: The product ID of the event marker (e.g. 0487). If not set, it will use the productID set in public/config/trigger.js if available, or attempt to connect using the com name.
  • EVENT_MARKER_COM_NAME stringoptionalruntime: The com name of the event marker (e.g. COM3). If not set, it will use the comName set in public/config/trigger.js. If the productID is set (not an empty string), this field will be ignored.
  • REACT_APP_VOLUMEbooleandefault falsebuildtime: whether the participant is being asked to adjust volume. This can be used on both the desktop (electron) and online settings.
  • REACT_APP_VIDEObooleandefault falsebuildtime: whether the participant is being video recorded. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_EEGbooleandefault falsebuildtime: whether the event marker/EEG is available. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_PHOTODIODEbooleandefault falsebuildtime: whether the photodiode is in use. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_PARTICIPANT_ID stringoptionalruntime: The default participant id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.
  • REACT_APP_STUDY_ID stringoptionalruntime: The default study id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.

Here are details on some of the badges:

  • runtime: Run-time environment variable. Set at the system level. See this tutorial for OS specific instructions.

  • buildtime: Build-time environment variable. Set in a .env file before building. Can also be defined in a separate file under the env/ directory and called with the dotenv-cli before building. NOTE: The dotenv command will not work directly from the command line. Instead, to set build-time environment variables, either run an existing npm script (e.g., npm run build:clinic, which sets clinic variables) or add a new script to package.json with the following format:

"[build|dev]:<script name>": "dotenv -e env/<your env file> npm run [build|dev]"

Or, to add your new variables to an existing environment configuration, e.g. .env.clinic, create a script in the following format:

"[build|dev]:<script name>": "dotenv -e env/<your env file> npm run [build|dev]:clinic"

Then run the script like so: npm run [build|dev]:<script name>.

+ \ No newline at end of file diff --git a/docs/2.x/event_triggers/index.html b/docs/2.x/event_triggers/index.html index cd6c7c86..7efc1e65 100644 --- a/docs/2.x/event_triggers/index.html +++ b/docs/2.x/event_triggers/index.html @@ -4,15 +4,15 @@ Set up event triggers | Honeycomb - +
Version: 2.x

Set up event triggers

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:

COMNAME

and set to 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 pdSpotEncodewith the proper eventCode (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.

- +./trigger and export as eventCodes

Whenever you would like to send an event code in a trial, load eventCodes from ../config/main/, and call pdSpotEncodewith the proper eventCode (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.

+ \ No newline at end of file diff --git a/docs/2.x/firebase/index.html b/docs/2.x/firebase/index.html index 94af11f5..27478271 100644 --- a/docs/2.x/firebase/index.html +++ b/docs/2.x/firebase/index.html @@ -4,13 +4,13 @@ Set up Firebase | Honeycomb - +
-
Version: 2.x

Set up Firebase

Honeycomb comes with methods and configurations for easy Firebase and Cloud Firestore set up. Please use this section to configure Firebase Hosting services and firestore cloud storage.

Getting Started​

Follow these steps to create a firebase project and link it with the current task.

1. Initializing firebase account and project​

  • Create and login to a firebase account on the Firebase website.
  • Create a firebase project by clicking add project and enter a Project Name.

2. Linking firebase to task​

  • Install Firebase CLI on your local computer.
  • Login to firebase using firebase login command in the terminal.
  • Navigate to the .firebaserc file home directory and edit the "default" field with the project name given in part 1.
    {
        "projects": {
            "default": "<your project name>"
        }
    }

3. Copying web app credentials.​

  • Navigate to the firebase console and select the project.
  • Create a new Web App by clicking on Add App or the </> code symbol and following the prompts.
  • Enter the a name for the Firebase app (could be the same as your Honeycomb task repo name).
  • Check "Also set up Firebase Hosting for this app."
  • Click Register App. This should auto-generate a script with several values that you need to copy into the next step.
  • Copy the auto-generated values from the Firebase console to the corresponding variables in the .env.firebase file in the env folder of your Honeycomb task repo:
      REACT_APP_apiKey=
      REACT_APP_authDomain=
      REACT_APP_projectId=
      REACT_APP_storageBucket=
      REACT_APP_messagingSenderId=
      REACT_APP_appId=
  • You can skip running firebase init if prompted to do so. The results of firebase init are already saved into the Honeycomb template repo.

Firebase is now set up!

Setting up firestore.​

Honeycomb includes cloud storage for task data using Firestore. Follow these steps to initialize firestore:

  • Navigate to the current project in the developer console and select Firestore Database from the sidebar.
  • Click Create Database, select production mode and choose the current location for the cloud storage bucket.

Firestore security rules.​

Firestore Security Rules provides easy server-side authorization to the database. For a honeycomb task, we use the security rules to allow access to only authorized participants for a specified study. Honeycomb's default set of rules is included in the firestore.rules file in the home directory. This file can be edited to change the rules. To deploy the rules in the file, type the following line of code in the terminal:

firebase deploy --only firestore:rules

Alternatively, Editing the rules directly in the console is also possible. To do so, navigate to the Rules tab in the Firestore Database section from the firebase console sidebar then copy and paste the code that is in the firestore.rules file.

Firestore database and rules are now both deployed. For Honeycomb's default set of rules, to add an authorized participant for a study, create a collection named registered_studies, add a study with the study ID as the document name in that collection. For each registered study, add an array field named registered_participants where each element in the array will be an authorized participant for that study.

- +
Version: 2.x

Set up Firebase

Honeycomb comes with methods and configurations for easy Firebase and Cloud Firestore set up. Please use this section to configure Firebase Hosting services and firestore cloud storage.

Getting Started​

Follow these steps to create a firebase project and link it with the current task.

1. Initializing firebase account and project​

  • Create and login to a firebase account on the Firebase website.
  • Create a firebase project by clicking add project and enter a Project Name.

2. Linking firebase to task​

  • Install Firebase CLI on your local computer.
  • Login to firebase using firebase login command in the terminal.
  • Navigate to the .firebaserc file home directory and edit the "default" field with the project name given in part 1.
    {
        "projects": {
            "default": "<your project name>"
        }
    }

3. Copying web app credentials.​

  • Navigate to the firebase console and select the project.
  • Create a new Web App by clicking on Add App or the </> code symbol and following the prompts.
  • Enter the a name for the Firebase app (could be the same as your Honeycomb task repo name).
  • Check "Also set up Firebase Hosting for this app."
  • Click Register App. This should auto-generate a script with several values that you need to copy into the next step.
  • Copy the auto-generated values from the Firebase console to the corresponding variables in the .env.firebase file in the env folder of your Honeycomb task repo:
      REACT_APP_apiKey=
      REACT_APP_authDomain=
      REACT_APP_projectId=
      REACT_APP_storageBucket=
      REACT_APP_messagingSenderId=
      REACT_APP_appId=
  • You can skip running firebase init if prompted to do so. The results of firebase init are already saved into the Honeycomb template repo.

Firebase is now set up!

Setting up firestore.​

Honeycomb includes cloud storage for task data using Firestore. Follow these steps to initialize firestore:

  • Navigate to the current project in the developer console and select Firestore Database from the sidebar.
  • Click Create Database, select production mode and choose the current location for the cloud storage bucket.

Firestore security rules.​

Firestore Security Rules provides easy server-side authorization to the database. For a honeycomb task, we use the security rules to allow access to only authorized participants for a specified study. Honeycomb's default set of rules is included in the firestore.rules file in the home directory. This file can be edited to change the rules. To deploy the rules in the file, type the following line of code in the terminal:

firebase deploy --only firestore:rules

Alternatively, Editing the rules directly in the console is also possible. To do so, navigate to the Rules tab in the Firestore Database section from the firebase console sidebar then copy and paste the code that is in the firestore.rules file.

Firestore database and rules are now both deployed. For Honeycomb's default set of rules, to add an authorized participant for a study, create a collection named registered_studies, add a study with the study ID as the document name in that collection. For each registered study, add an array field named registered_participants where each element in the array will be an authorized participant for that study.

+ \ No newline at end of file diff --git a/docs/2.x/folders/index.html b/docs/2.x/folders/index.html index 70c90926..512e2b6d 100644 --- a/docs/2.x/folders/index.html +++ b/docs/2.x/folders/index.html @@ -4,13 +4,13 @@ Project Organization | Honeycomb - +
-
Version: 2.x

Project Organization

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 definitely not mutated), 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. Below are descriptions of the main files and folders.

package.json​

The package.json file contains metadata about your project and scripts to run tasks related to your task. The name should be updated to your task's name and scripts can be added as desired, but otherwise this file should not be edited manually. To remove or add a dependency use npm install or npm uninstall with the -D flag if installing a dev dependency.

The package-lock.json contains metadata about the package installation. It should never be manually updated.

assets/​

The icons used for the installed applications are put here.

env/​

This folder contains different .env files with presets for common use cases. These files can be loaded with dotenv, which is explained in greater detail in the Configuration section.

public/​

The public directory contains files that are used as assets in the built app. The favicon.ico is the small icon you can see in the browser tab (on Chrome) - it is set to Brown's logo in the project. The index.html contains the shell of your website - the name displayed on the tab can be changed here, otherwise it shouldn't need to be edited. The scripts included in the file are for psiturk as are the files in the lib/ directory.

electron.js​

This file contains all of the code relating to the electron app. This includes the event-marker, throwing errors via dialog windows, saving data, and reading files.

config/​

The config directory contains the config files needed for the electron app. This includes the event-marker details and event codes.

Note: the productId can be overwritten by the environment variable EVENT_MARKER_PRODUCT_ID

src/​

This folder contains the code for the app, the vast majority of changes and code should go here.

App.jsx​

This is the starting point for the app. The <Login> component handles user authentication in the different use cases and the <JsPsychExperiment> component initializes the jspsych experiment. This is also where communication is set up with the electron and psiturk processes.

App.css​

This is where styling for the app is housed. If colors, fonts, spacing, etc. need to be set, do it here.

assets/​

This folder contains any static files that are used by the app, such as images.

components/​

This folder contains the components referenced in App.jsx.

config/​

In the config/ directory, there are .js files which contain settings for the different parts of the task. Every task should have a main config and a trigger config (assuming use of the event marker). The main config has all global settings for the task (such as whether it is in mturk mode or not), load the appropriate language file, and set up a default (or only) configuration object for the task. Different in-task features can be loaded from .env files and is set in the main config. For example, we have included some of these files in the env directory (e.g. env.clinic file enables event marker, photodiode and volume adjustment). The trigger config has settings specific to the event marker and uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.

Other config files can be used to add settings for specific blocks or sub-sections of the experiment.

language/​

Any language that is displayed in the experiment should be stored in this folder. Usage of language json files allows for easy internationalization of the task (e.g. english and spanish) as well as allows for mturk specific language. This also makes it easy to re-use common phrases in many places in the task.

lib/​

The lib/ directory contains utility functions and markup that is used in the tasks. This allows for functions and html to be re-used wherever needed. The lib/utils.js file contains functions that are generally useful across many tasks, whereas lib/taskUtils.js contains functions specific to this task.

lib/markup​

markup files should contain primarily templates for HTML that is used throughout the task. Typically this will be a function that takes in some parameters and then returns a string with html.

timelines​

jspsych uses timelines to control what trials are displayed in what order. timelines can contain other timelines, which is why there may be several files in this directory. The main.js file should have the timeline that is called by App.jsx in the <JsPsychExperiment> component.

trials​

jspsych uses trials as its base unit of an experiment. These trials do things such as display some stimulus or request a response.

- +
Version: 2.x

Project Organization

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 definitely not mutated), 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. Below are descriptions of the main files and folders.

package.json​

The package.json file contains metadata about your project and scripts to run tasks related to your task. The name should be updated to your task's name and scripts can be added as desired, but otherwise this file should not be edited manually. To remove or add a dependency use npm install or npm uninstall with the -D flag if installing a dev dependency.

The package-lock.json contains metadata about the package installation. It should never be manually updated.

assets/​

The icons used for the installed applications are put here.

env/​

This folder contains different .env files with presets for common use cases. These files can be loaded with dotenv, which is explained in greater detail in the Configuration section.

public/​

The public directory contains files that are used as assets in the built app. The favicon.ico is the small icon you can see in the browser tab (on Chrome) - it is set to Brown's logo in the project. The index.html contains the shell of your website - the name displayed on the tab can be changed here, otherwise it shouldn't need to be edited. The scripts included in the file are for psiturk as are the files in the lib/ directory.

electron.js​

This file contains all of the code relating to the electron app. This includes the event-marker, throwing errors via dialog windows, saving data, and reading files.

config/​

The config directory contains the config files needed for the electron app. This includes the event-marker details and event codes.

Note: the productId can be overwritten by the environment variable EVENT_MARKER_PRODUCT_ID

src/​

This folder contains the code for the app, the vast majority of changes and code should go here.

App.jsx​

This is the starting point for the app. The <Login> component handles user authentication in the different use cases and the <JsPsychExperiment> component initializes the jspsych experiment. This is also where communication is set up with the electron and psiturk processes.

App.css​

This is where styling for the app is housed. If colors, fonts, spacing, etc. need to be set, do it here.

assets/​

This folder contains any static files that are used by the app, such as images.

components/​

This folder contains the components referenced in App.jsx.

config/​

In the config/ directory, there are .js files which contain settings for the different parts of the task. Every task should have a main config and a trigger config (assuming use of the event marker). The main config has all global settings for the task (such as whether it is in mturk mode or not), load the appropriate language file, and set up a default (or only) configuration object for the task. Different in-task features can be loaded from .env files and is set in the main config. For example, we have included some of these files in the env directory (e.g. env.clinic file enables event marker, photodiode and volume adjustment). The trigger config has settings specific to the event marker and uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.

Other config files can be used to add settings for specific blocks or sub-sections of the experiment.

language/​

Any language that is displayed in the experiment should be stored in this folder. Usage of language json files allows for easy internationalization of the task (e.g. english and spanish) as well as allows for mturk specific language. This also makes it easy to re-use common phrases in many places in the task.

lib/​

The lib/ directory contains utility functions and markup that is used in the tasks. This allows for functions and html to be re-used wherever needed. The lib/utils.js file contains functions that are generally useful across many tasks, whereas lib/taskUtils.js contains functions specific to this task.

lib/markup​

markup files should contain primarily templates for HTML that is used throughout the task. Typically this will be a function that takes in some parameters and then returns a string with html.

timelines​

jspsych uses timelines to control what trials are displayed in what order. timelines can contain other timelines, which is why there may be several files in this directory. The main.js file should have the timeline that is called by App.jsx in the <JsPsychExperiment> component.

trials​

jspsych uses trials as its base unit of an experiment. These trials do things such as display some stimulus or request a response.

+ \ No newline at end of file diff --git a/docs/2.x/index.html b/docs/2.x/index.html index 695bc25e..922bf16e 100644 --- a/docs/2.x/index.html +++ b/docs/2.x/index.html @@ -4,13 +4,13 @@ Introduction | Honeycomb - +
-
Version: 2.x

Introduction

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.

Flexible deployment online and in the lab​

Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings.

Easy to install executables​

Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites.

Foundation in jsPsych​

jsPsych tasks can be converted to the Honeycomb structure to take advantage of the flexible deployment and automated GitHub Actions workflow that Honeycomb provides.

- +
Version: 2.x

Introduction

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.

Flexible deployment online and in the lab​

Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings.

Easy to install executables​

Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites.

Foundation in jsPsych​

jsPsych tasks can be converted to the Honeycomb structure to take advantage of the flexible deployment and automated GitHub Actions workflow that Honeycomb provides.

+ \ No newline at end of file diff --git a/docs/2.x/npm_scripts/index.html b/docs/2.x/npm_scripts/index.html index 99da0756..070f7712 100644 --- a/docs/2.x/npm_scripts/index.html +++ b/docs/2.x/npm_scripts/index.html @@ -4,14 +4,14 @@ NPM Scripts | Honeycomb - +
Version: 2.x

NPM Scripts

In the project directory, you can run:

npm run dev​

Runs npm start and npm run electron-dev concurrently. This may not play nicely with windows. If it doesn't, run npm start and npm run electron-dev from different terminal windows.

npm start​

Runs the app in the development mode.

Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.

You will also see any lint errors in the console.

npm test​

Launches the test runner in the interactive watch mode.

See the section about running tests for more information.

npm build​

Creates a production build of the app (renderer). This must be done before running package:platform or the psiturk build instructions.

npm run package:platform​

It correctly bundles creates electron packages for the given platform. It then creates an installer for that platform. The output can be found in /dist -platforms: windows, mac, linux.

Prerequisites​

If not running this command on a windows machine, must have mono and wine installed.

npm run eject​

Note: this is a one-way operation. Once you eject, you can’t go back!

If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.

Run Electron​

npm run electron​

Run the built app.

npm run electron-dev​

Run the current state of the code (un-built).

- +platforms: windows, mac, linux.

Prerequisites​

If not running this command on a windows machine, must have mono and wine installed.

npm run eject​

Note: this is a one-way operation. Once you eject, you can’t go back!

If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.

Run Electron​

npm run electron​

Run the built app.

npm run electron-dev​

Run the current state of the code (un-built).

+ \ No newline at end of file diff --git a/docs/2.x/online_integration/index.html b/docs/2.x/online_integration/index.html index c837c7a1..9a2b1def 100644 --- a/docs/2.x/online_integration/index.html +++ b/docs/2.x/online_integration/index.html @@ -4,7 +4,7 @@ Deploy online | Honeycomb - + @@ -13,8 +13,8 @@ PsiTurk is a Python package used to manage HITs in Mechanical Turk. Before using the provided script, install PsiTurk.

You'll need to follow these steps (the path to the PsiTurk project should be a directory you wish to be created):

  • Build the application: npm run build

  • Move to the psiturkit directory: cd psiturkit

  • If it's the first time you're running the script:
    ./psiturk-it -p <PATH_TO_NEW_PSITURK_PROJECT>

  • To update an existing PsiTurk project (the path to the PsiTurk project should already exist from the previous steps):
    ./psiturk-it -u -p <PATH_TO_NEW_PSITURK_PROJECT>

Running psiturk​

After that, just navigate to your newly created PsiTurk project directory.

shell> psiturk #start psiturk
psiturk> server on #start server
psiturk> debug #debug mode

Running on the Web​

Using Github Pages​

Running npm run build generates static content into the build directory that can be served using any static contents hosting service. The workflow .github/workflows/release-home-all.yml uploads the build directory to the gh-branch to serve the application on GitHub pages as an example. After a creating a tag, the workflow will run and your application will be served at <githubuser>.github.io/<repository>. -For this step to succeed you will need to create a deploy key and enable GitHub Pages for your repository.

  1. Generate a new SSH key.
  2. By default, your public key should have been created in ~/.ssh/id_rsa.pub or use the name you've provided.
  3. Copy key to clipboard with xclip -sel clip < ~/.ssh/id_rsa.pub and paste it as a deploy key in your repository. Copy file content if the command line doesn't work for you. Check the box for Allow write access before saving your deployment key.
  4. You'll need your private key as a GitHub secret to allow the workflow to run the deployment for you.
  5. To create the secret copy your private key e.g. xclip -sel clip < ~/.ssh/id_rsa and paste a GitHub secret with name GH_PAGES_DEPLOY. Copy file content if the command line doesn't work for you. Save your secret.
  6. Make sure the publishing source for your repository is configured for gh-pages branch.

Using Firebase​

We have included methods and configurations for close integration with firebase. Before proceeding with the follwing steps, please make sure that firebase is configured by following the Getting started with firebase section under Set Up Firebase.

  1. Run npm run build:firebase in the terminal to create a production build for firebase.
  2. Run firebase deploy in the terminal to deploy the production build.
  3. The production build is now deployed to the firebase project domain.

To automate firebase deployments, we have included instructions on setting up firebase github actions on our Automated Builds page

- +For this step to succeed you will need to create a deploy key and enable GitHub Pages for your repository.

  1. Generate a new SSH key.
  2. By default, your public key should have been created in ~/.ssh/id_rsa.pub or use the name you've provided.
  3. Copy key to clipboard with xclip -sel clip < ~/.ssh/id_rsa.pub and paste it as a deploy key in your repository. Copy file content if the command line doesn't work for you. Check the box for Allow write access before saving your deployment key.
  4. You'll need your private key as a GitHub secret to allow the workflow to run the deployment for you.
  5. To create the secret copy your private key e.g. xclip -sel clip < ~/.ssh/id_rsa and paste a GitHub secret with name GH_PAGES_DEPLOY. Copy file content if the command line doesn't work for you. Save your secret.
  6. Make sure the publishing source for your repository is configured for gh-pages branch.

Using Firebase​

We have included methods and configurations for close integration with firebase. Before proceeding with the follwing steps, please make sure that firebase is configured by following the Getting started with firebase section under Set Up Firebase.

  1. Run npm run build:firebase in the terminal to create a production build for firebase.
  2. Run firebase deploy in the terminal to deploy the production build.
  3. The production build is now deployed to the firebase project domain.

To automate firebase deployments, we have included instructions on setting up firebase github actions on our Automated Builds page

+ \ No newline at end of file diff --git a/docs/2.x/quick_start/index.html b/docs/2.x/quick_start/index.html index c7cad07e..88e6088d 100644 --- a/docs/2.x/quick_start/index.html +++ b/docs/2.x/quick_start/index.html @@ -4,7 +4,7 @@ Quick Start | Honeycomb - + @@ -25,8 +25,8 @@ Follow installation instructions on the electron docs

Honeycomb npm packages Once Node.js is installed you will able to use npm commands in the terminal. To install the dependencies for HoneyComb run the following command at the terminal (remember you need cd your-new-task-name before)

npm install

4. Run the task in dev mode​

To launch an electron window with the task with the inspector open to the console and will hot-reload when changes are made to the app

  • For Mac and Linux:

    npm run dev

  • For Windows: You will need to open 2 terminals. In the first -and make sure you are in the task-<TASK NAME> repo directory- run the command:

    npm start

    In the second terminal - make sure you are in the task-<TASK NAME> repo directory-, run:

    npm run electron-dev

5. Run the task with preset environment variables​

We have provided various .env files and npm scripts to run the task in common settings like home or clinic. Here are the possible commands:

npm run dev:home
npm run dev:home:video
npm run dev:clinic
npm run dev:clinic:video
npm run dev:firebase

6. Check out the data​

The data is saved throughout the task to the users's app directory. This is logged at the beginning of the task wherever you ran npm run dev (for windows, instead in two different terminals ran npm start and npm run electron-dev). It is also stored in a folder that is generated by the app, which should be found on the desktop.

7. Quit The Task​

If you want to quit in the middle of the task, you can use these keyboard shortcuts:

Ctrl+W (for PC/Windows)
Cmd+Q (for Mac)

Partial data will be saved.

7. Merge updates from honeycomb template repo​

Honeycomb is an active project, and will be updated with new features over time. To merge the honeycomb template repository updates with your task, follow the following steps: -First time only:

git remote add honeycomb https://github.com/brown-ccv/honeycomb.git

Every time: 

git fetch --all
git merge honeycomb/main --allow-unrelated histories

If there are any conflicts:

git stash

To merge:

git commit -a -m "merge honeycomb latest"

8. Run automated tests​

When getting started, merging updates, or making custom changes, it's a good idea to run automated tests. These can tell you if things are working or if recent changes broke something that previously worked.

To run the tests interactively:

npm test

Or non-interactively:

CI=true npm test

Linux​

When running npm test on Linux, you might get an error that mentions ENOSPC. This is because the test runer creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.

This is a "known issue" with some test runners on Linux, as in discussions here and here.

One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):

  • Command that initially fails with ENOSPC: npm test
  • Check the configured limit on "watchers": cat /proc/sys/fs/inotify/max_user_watches
  • Edit the relevant Linux config file: sudo vim /etc/sysctl.conf
  • Add a line at the end of the config file: fs.inotify.max_user_watches=100000
  • Save, exit, and reload the config file: sudo sysctl -p
  • Check that the limit has changed: cat /proc/sys/fs/inotify/max_user_watches
  • Retry the initial command, which should now succeed: npm test
- +First time only:

git remote add honeycomb https://github.com/brown-ccv/honeycomb.git

Every time: 

git fetch --all
git merge honeycomb/main --allow-unrelated histories

If there are any conflicts:

git stash

To merge:

git commit -a -m "merge honeycomb latest"

8. Run automated tests​

When getting started, merging updates, or making custom changes, it's a good idea to run automated tests. These can tell you if things are working or if recent changes broke something that previously worked.

To run the tests interactively:

npm test

Or non-interactively:

CI=true npm test

Linux​

When running npm test on Linux, you might get an error that mentions ENOSPC. This is because the test runer creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.

This is a "known issue" with some test runners on Linux, as in discussions here and here.

One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):

  • Command that initially fails with ENOSPC: npm test
  • Check the configured limit on "watchers": cat /proc/sys/fs/inotify/max_user_watches
  • Edit the relevant Linux config file: sudo vim /etc/sysctl.conf
  • Add a line at the end of the config file: fs.inotify.max_user_watches=100000
  • Save, exit, and reload the config file: sudo sysctl -p
  • Check that the limit has changed: cat /proc/sys/fs/inotify/max_user_watches
  • Retry the initial command, which should now succeed: npm test
+ \ No newline at end of file diff --git a/docs/2.x/software_prerecs/index.html b/docs/2.x/software_prerecs/index.html index d6f4f576..09211da5 100644 --- a/docs/2.x/software_prerecs/index.html +++ b/docs/2.x/software_prerecs/index.html @@ -4,15 +4,15 @@ Software Prerequisites | Honeycomb - +
Version: 2.x

Software Prerequisites

Windows​

Visual Studio​

Install the latest version of Visual Studio (https://visualstudio.microsoft.com/downloads/) with the Desktop Development for C++ Workflow. To add the workflow, follow the instructions linked below: -https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#:~:text=If%20you%20have%20Visual%20Studio,Then%2C%20choose%20Modify.

Python​

Install Python. For new Python users, we recommend installing via Anaconda: https://docs.anaconda.com/anaconda/install/windows/

Node.js​

Install Node.js: https://nodejs.org/en/download/

Git bash​

Install git bash: https://git-scm.com/downloads

Note: restart computer after all installs are complete​

- +https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#:~:text=If%20you%20have%20Visual%20Studio,Then%2C%20choose%20Modify.

Python​

Install Python. For new Python users, we recommend installing via Anaconda: https://docs.anaconda.com/anaconda/install/windows/

Node.js​

Install Node.js: https://nodejs.org/en/download/

Git bash​

Install git bash: https://git-scm.com/downloads

Note: restart computer after all installs are complete​

+ \ No newline at end of file diff --git a/docs/2.x/troubleshooting/index.html b/docs/2.x/troubleshooting/index.html index c505ce9f..e236b636 100644 --- a/docs/2.x/troubleshooting/index.html +++ b/docs/2.x/troubleshooting/index.html @@ -4,13 +4,13 @@ Troubleshooting | Honeycomb - +
-
Version: 2.x

Troubleshooting

When developing electron apps there are two processes: main, and renderer. In this case main corresponds to electron-starter.js and its console is wherever you called npm run dev or electron . from. renderer corresponds to the React App - this is everything else. The react app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running npm run dev, it should open by default.

Potential Issues​

Try deleting your node_modules folder and the package-lock.json then running npm install then npm run rebuild.

Inspecting Errors​

In case you want to find out where the error is coming from when running the app locally:

  • Try reviewing logs in the terminal
  • Inspect element in your browser by openning your developer tools. For instance, in Chrome, this can be done via the menu View -> Developer or right-clicking and pressing inspect.
- +
Version: 2.x

Troubleshooting

When developing electron apps there are two processes: main, and renderer. In this case main corresponds to electron-starter.js and its console is wherever you called npm run dev or electron . from. renderer corresponds to the React App - this is everything else. The react app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running npm run dev, it should open by default.

Potential Issues​

Try deleting your node_modules folder and the package-lock.json then running npm install then npm run rebuild.

Inspecting Errors​

In case you want to find out where the error is coming from when running the app locally:

  • Try reviewing logs in the terminal
  • Inspect element in your browser by openning your developer tools. For instance, in Chrome, this can be done via the menu View -> Developer or right-clicking and pressing inspect.
+ \ No newline at end of file diff --git a/docs/2.x/version_control/index.html b/docs/2.x/version_control/index.html index 2197faef..f576ed17 100644 --- a/docs/2.x/version_control/index.html +++ b/docs/2.x/version_control/index.html @@ -4,13 +4,13 @@ Version Control | Honeycomb - +
-
Version: 2.x

Version Control

Git Overview​

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.

Git creates a hidden .git folder (in the current folder) to store the details of the file system - this folder contains all the data required to track your files and is known as a repository, or repo.

Git tracks file changes by the user creating a save point, or in Git terms a commit. Each commit takes a snapshot of the current file system. Commits are uniquely identified by a SHA–1 hash. This is a 40 character string which may along the lines of ded7a0db6422d59e9893e975e32275fc36f853daThis hash can be used to track a particular commit within the repository.

Nearly all operations that are performed by Git are in you 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. In summary, a typical flow consists of making changes to your files, staging them via git add, marking a save point via git commit, then finally syncing to your remote (e.g., GitHub) via git push. If you are pushing changes to your remote from multiple places, you can bring changes your most recent version using git pull, which is the equivalent of doing git fetch followed by a git merge operation

Cheatsheet​

CommandBrief
git add <files>add a file to next commit (stage)
git commit -m <message>commit staged files
git pushupload staged commit to repo
git pullget remote repo commits and download (try and resolve conflicts)
git clone <url>download entire repository

Best Practices​

Workflow​

We recommend 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.
  • Everyone starts from main, and targets main.
  • Commit messages reflect intent.

Branches​

  • main is the default branch and where releases are made off. 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

Comment styles​

We encourage using Commitizen, a great tool for writing angular commits - this will create a standardized commit format which makes for easier change logging and more sane messages.

- +
Version: 2.x

Version Control

Git Overview​

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.

Git creates a hidden .git folder (in the current folder) to store the details of the file system - this folder contains all the data required to track your files and is known as a repository, or repo.

Git tracks file changes by the user creating a save point, or in Git terms a commit. Each commit takes a snapshot of the current file system. Commits are uniquely identified by a SHA–1 hash. This is a 40 character string which may along the lines of ded7a0db6422d59e9893e975e32275fc36f853daThis hash can be used to track a particular commit within the repository.

Nearly all operations that are performed by Git are in you 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. In summary, a typical flow consists of making changes to your files, staging them via git add, marking a save point via git commit, then finally syncing to your remote (e.g., GitHub) via git push. If you are pushing changes to your remote from multiple places, you can bring changes your most recent version using git pull, which is the equivalent of doing git fetch followed by a git merge operation

Cheatsheet​

CommandBrief
git add <files>add a file to next commit (stage)
git commit -m <message>commit staged files
git pushupload staged commit to repo
git pullget remote repo commits and download (try and resolve conflicts)
git clone <url>download entire repository

Best Practices​

Workflow​

We recommend 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.
  • Everyone starts from main, and targets main.
  • Commit messages reflect intent.

Branches​

  • main is the default branch and where releases are made off. 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

Comment styles​

We encourage using Commitizen, a great tool for writing angular commits - this will create a standardized commit format which makes for easier change logging and more sane messages.

+ \ No newline at end of file diff --git a/docs/3.0.0/ci/index.html b/docs/3.0.0/ci/index.html index abce1189..754dd2ce 100644 --- a/docs/3.0.0/ci/index.html +++ b/docs/3.0.0/ci/index.html @@ -4,13 +4,13 @@ Automated Builds | Honeycomb - +
-
Version: 3.0.0

Automated Builds

Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings on demand or automatically as the code is pushed to the repository. In this section, we provide a short introduction to definitions. We explain the GitHub Actions included with Honeycomb. These workflows should provide a foundation but can easily be modified or extended to meet more needs.

What is CI/CD?​

CI/CD refers to Continuous Integration and either Continuous Delivery or Continuous Deployment. CI/CD enforces the automated building of bundled executables so that tasks can be easily installed without dependencies. In Honeycomb, CI/CD is managed by GitHub Actions.

What are Github Actions​

GitHub Actions automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in GitHub's documentation

GitHub Actions are written as YML files inside a .github/worflows/ folder in your repository.

Building the executables​

Honeycomb includes workflows to build and create installers for Windows. Mac and Linux. These workflows exist for two configurations of the tasks:

  • Home: The app does not expect event code triggers and photodiode spots.
  • Clinic: The app expects event code triggers and photodiode spots.

More specifically, the following workflows are included:

  • build.yaml: Every time an Pull Request (PR) is opened, or a push is made to the main branch, the software is built and tests are run for all platforms and home and clinic settings. This workflow does not build and upload desktop installers
  • package.yaml: Create installers for any/all platforms for the home and clinic setting on demand 1. The installers/executables are uploaded as artifacts and are available for download from the GitHub Actions tab. This also builds PsiTurk version when linux or all operating systems are selected
  • release.yml: Every time a Tag is released, installers are created and uploaded as packages. This also builds PsiTurk version, and deploys to GitHub pages a web version of the application.
1 On-demand workflows are triggered manually from the GitHub Actions tab. Each GitHub organization/individual has a quota on storage on 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).

Download your bundled executable to install and run your task​

You can download the executable file from either the tagged release page or the GitHub actions page. To install, unzip the downloaded file, install and run.

The executable does not require installation of any additional software.

Uninstall the task​

Windows​

Go to System Settings: Add or remove programs. Look for the name of your task in the installed programs list, and Uninstall.

The executable does not require installation of any additional software.

Firebase Hosting​

Automatic deployment on a firebase hosting site can also be setup with github actions. Before proceeding with the following steps, please make sure that firebase is configured by following the Getting started with firebase section under Set Up Firebase. Then run the following command in the terminal:

firebase init hosting:github

  • Be sure to type "<username>/<repository name>" exactly as it appears in GitHub when the prompt "For which GitHub repository would you like to set up a GitHub workflow?" appears.

  • When you see the prompt "Set up the workflow to run a build script before every deploy?" enter y

  • Enter the following command for the prompt "What script should be run before every deploy?":

    npm install && npm run build:firebase

  • When you see the prompt "Set up automatic deployment to your site's live channel when a PR is merged?" enter y

  • Enter "main" for the prompt "What is the name of the GitHub branch associated with your site's live channel?"

There should be two new .yml files, firebase-hosting-pull-request.yml and firebase-hosting-merge.yml, created in the .github/workflows directory for a deployment preview for each pull request and the official deployment when merged onto the main branch. Double check that the correct run script is present in both files.

Firebase actions

- +
Version: 3.0.0

Automated Builds

Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings on demand or automatically as the code is pushed to the repository. In this section, we provide a short introduction to definitions. We explain the GitHub Actions included with Honeycomb. These workflows should provide a foundation but can easily be modified or extended to meet more needs.

What is CI/CD?​

CI/CD refers to Continuous Integration and either Continuous Delivery or Continuous Deployment. CI/CD enforces the automated building of bundled executables so that tasks can be easily installed without dependencies. In Honeycomb, CI/CD is managed by GitHub Actions.

What are Github Actions​

GitHub Actions automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in GitHub's documentation

GitHub Actions are written as YML files inside a .github/worflows/ folder in your repository.

Building the executables​

Honeycomb includes workflows to build and create installers for Windows. Mac and Linux. These workflows exist for two configurations of the tasks:

  • Home: The app does not expect event code triggers and photodiode spots.
  • Clinic: The app expects event code triggers and photodiode spots.

More specifically, the following workflows are included:

  • build.yaml: Every time an Pull Request (PR) is opened, or a push is made to the main branch, the software is built and tests are run for all platforms and home and clinic settings. This workflow does not build and upload desktop installers
  • package.yaml: Create installers for any/all platforms for the home and clinic setting on demand 1. The installers/executables are uploaded as artifacts and are available for download from the GitHub Actions tab. This also builds PsiTurk version when linux or all operating systems are selected
  • release.yml: Every time a Tag is released, installers are created and uploaded as packages. This also builds PsiTurk version, and deploys to GitHub pages a web version of the application.
1 On-demand workflows are triggered manually from the GitHub Actions tab. Each GitHub organization/individual has a quota on storage on 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).

Download your bundled executable to install and run your task​

You can download the executable file from either the tagged release page or the GitHub actions page. To install, unzip the downloaded file, install and run.

The executable does not require installation of any additional software.

Uninstall the task​

Windows​

Go to System Settings: Add or remove programs. Look for the name of your task in the installed programs list, and Uninstall.

The executable does not require installation of any additional software.

Firebase Hosting​

Automatic deployment on a firebase hosting site can also be setup with github actions. Before proceeding with the following steps, please make sure that firebase is configured by following the Getting started with firebase section under Set Up Firebase. Then run the following command in the terminal:

firebase init hosting:github

  • Be sure to type "<username>/<repository name>" exactly as it appears in GitHub when the prompt "For which GitHub repository would you like to set up a GitHub workflow?" appears.

  • When you see the prompt "Set up the workflow to run a build script before every deploy?" enter y

  • Enter the following command for the prompt "What script should be run before every deploy?":

    npm install && npm run build:firebase

  • When you see the prompt "Set up automatic deployment to your site's live channel when a PR is merged?" enter y

  • Enter "main" for the prompt "What is the name of the GitHub branch associated with your site's live channel?"

There should be two new .yml files, firebase-hosting-pull-request.yml and firebase-hosting-merge.yml, created in the .github/workflows directory for a deployment preview for each pull request and the official deployment when merged onto the main branch. Double check that the correct run script is present in both files.

Firebase actions

+ \ No newline at end of file diff --git a/docs/3.0.0/configuration/index.html b/docs/3.0.0/configuration/index.html index a246d435..61c5e4ae 100644 --- a/docs/3.0.0/configuration/index.html +++ b/docs/3.0.0/configuration/index.html @@ -4,13 +4,13 @@ Configuration | Honeycomb - +
-
Version: 3.0.0

Configuration

Environment Variables​

Honeycomb uses environment variables during build and run time to control the different configurations. Below we list the environment variables used by the app and indicate their properties via badges and text. Optional variables are labeled with the optional badge and mandatory variables are labeled with the default <default-value> badge with their default value specified. The buildtime badge indicates the variable is used during the build/compilation phase (npm build) while the runtime badge indicates the variable is used during the executable run (npm run dev).

Dev Mode Only​

  • ELECTRON_START_URL stringoptional: URL (e.g. http://localhost:3000) where the front end of the app is being hosted - also used in electron.js to indicate the app is running in dev mode.

Desktop Only​

  • EVENT_MARKER_PRODUCT_IDstringoptionalruntime: The product ID of the event marker (e.g. 0487). If not set, it will use the productID set in public/config/trigger.js if available, or attempt to connect using the com name.
  • EVENT_MARKER_COM_NAME stringoptionalruntime: The com name of the event marker (e.g. COM3). If not set, it will use the comName set in public/config/trigger.js. If the productID is set (not an empty string), this field will be ignored.
  • REACT_APP_VIDEObooleandefault falsebuildtime: whether the participant is being video recorded. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_EEGbooleandefault falsebuildtime: whether the event marker/EEG is available. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_PHOTODIODEbooleandefault falsebuildtime: whether the photodiode is in use. This can be used when the task is running as a desktop app (electron).

Desktop and Online​

  • REACT_APP_VOLUMEbooleandefault falsebuildtime: whether the participant is being asked to adjust volume. This can be used on both the desktop (electron) and online settings.
  • REACT_APP_PARTICIPANT_ID stringoptionalruntime: The default participant id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.
  • REACT_APP_STUDY_ID stringoptionalruntime: The default study id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.

Understanding Build Time and Run Time Variables​

  • runtime: Run-time environment variables allow for quick changes before running the task. They are convenient since they don't require building a whole different executable. For a Desktop Application, these are set at the system level and must be available at the time where the task runs. See this tutorial for OS specific instructions.. For a Firebase Application, these must be stored in the Firestore.

  • build time: Build-time environment variable are configured before the application is built and cannot be changed at run-time. They are configured via .env files before building. Instead of using a single .env file, we prefer to defined separate files under the env/ directory, and use a package called dotenv-cli before building`.

The dotenv-cli comes with the dotenv command that can be used to properly load the needed variables. This command does not run directly from the command line (terminal). Instead, to set build-time environment variables, we need to add a script to package.json with the following format:

"[build|dev]:<script name>": "dotenv -e env/<your env file> npm run [build|dev]"

Honeycomb includes so scripts for common scenarios. For instance, you can run:

npm run dev:home
npm run dev:home:video
npm run dev:clinic
npm run dev:clinic:video
npm run dev:firebase
- +
Version: 3.0.0

Configuration

Environment Variables​

Honeycomb uses environment variables during build and run time to control the different configurations. Below we list the environment variables used by the app and indicate their properties via badges and text. Optional variables are labeled with the optional badge and mandatory variables are labeled with the default <default-value> badge with their default value specified. The buildtime badge indicates the variable is used during the build/compilation phase (npm build) while the runtime badge indicates the variable is used during the executable run (npm run dev).

Dev Mode Only​

  • ELECTRON_START_URL stringoptional: URL (e.g. http://localhost:3000) where the front end of the app is being hosted - also used in electron.js to indicate the app is running in dev mode.

Desktop Only​

  • EVENT_MARKER_PRODUCT_IDstringoptionalruntime: The product ID of the event marker (e.g. 0487). If not set, it will use the productID set in public/config/trigger.js if available, or attempt to connect using the com name.
  • EVENT_MARKER_COM_NAME stringoptionalruntime: The com name of the event marker (e.g. COM3). If not set, it will use the comName set in public/config/trigger.js. If the productID is set (not an empty string), this field will be ignored.
  • REACT_APP_VIDEObooleandefault falsebuildtime: whether the participant is being video recorded. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_EEGbooleandefault falsebuildtime: whether the event marker/EEG is available. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_PHOTODIODEbooleandefault falsebuildtime: whether the photodiode is in use. This can be used when the task is running as a desktop app (electron).

Desktop and Online​

  • REACT_APP_VOLUMEbooleandefault falsebuildtime: whether the participant is being asked to adjust volume. This can be used on both the desktop (electron) and online settings.
  • REACT_APP_PARTICIPANT_ID stringoptionalruntime: The default participant id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.
  • REACT_APP_STUDY_ID stringoptionalruntime: The default study id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.

Understanding Build Time and Run Time Variables​

  • runtime: Run-time environment variables allow for quick changes before running the task. They are convenient since they don't require building a whole different executable. For a Desktop Application, these are set at the system level and must be available at the time where the task runs. See this tutorial for OS specific instructions.. For a Firebase Application, these must be stored in the Firestore.

  • build time: Build-time environment variable are configured before the application is built and cannot be changed at run-time. They are configured via .env files before building. Instead of using a single .env file, we prefer to defined separate files under the env/ directory, and use a package called dotenv-cli before building`.

The dotenv-cli comes with the dotenv command that can be used to properly load the needed variables. This command does not run directly from the command line (terminal). Instead, to set build-time environment variables, we need to add a script to package.json with the following format:

"[build|dev]:<script name>": "dotenv -e env/<your env file> npm run [build|dev]"

Honeycomb includes so scripts for common scenarios. For instance, you can run:

npm run dev:home
npm run dev:home:video
npm run dev:clinic
npm run dev:clinic:video
npm run dev:firebase
+ \ No newline at end of file diff --git a/docs/3.0.0/event_triggers/index.html b/docs/3.0.0/event_triggers/index.html index 39ba1099..4f35f4c1 100644 --- a/docs/3.0.0/event_triggers/index.html +++ b/docs/3.0.0/event_triggers/index.html @@ -4,13 +4,13 @@ Set up event triggers | Honeycomb - +
-
Version: 3.0.0

Set up event triggers

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:

COMNAME

and set to 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.

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 pdSpotEncodewith the proper eventCode (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.

- +
Version: 3.0.0

Set up event triggers

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:

COMNAME

and set to 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.

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 pdSpotEncodewith the proper eventCode (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.

+ \ No newline at end of file diff --git a/docs/3.0.0/firebase/index.html b/docs/3.0.0/firebase/index.html index 08db2373..0b9d0241 100644 --- a/docs/3.0.0/firebase/index.html +++ b/docs/3.0.0/firebase/index.html @@ -4,13 +4,13 @@ Set up Firebase | Honeycomb - +
-
Version: 3.0.0

Set up Firebase

Honeycomb comes with methods and configurations for easy Firebase and Cloud Firestore set up. Please use this section to configure Firebase Hosting services and Firestore cloud storage.

Setting up Firebase​

0. Installing the Firebase Command Line Interface​

To check if firebase has been installed, type firebase into a terminal window.

firebase

If a list of options are printed on the terminal then the firebase tool has already been installed. If not, you will get an error - something along the lines of "Command not found." The firebase-cli can then be installed using npm:

npm install -g firebase-tools

The -g flag installs an npm package globally on your system, as opposed to the current project

1. Initializing Firebase account and project​

  • Create and login to a Firebase account on the Firebase website.

  • Create a Firebase project by clicking add project and enter a Project Name.

2. Linking firebase to task​

  • Login to Firebase using firebase login command in the terminal.

  • Navigate to the .firebaserc file home directory and edit the "default" field with the project name given in part 1.

{
    "projects": {
        "default": "<your project name>"
    }
}

3. Copying web app credentials​

  • Navigate to the firebase console and select the project.
  • Create a new Web App by clicking on Add App or the </> code symbol and following the prompts.
  • Enter the a name for the Firebase app (could be the same as your Honeycomb task repo name).
  • Check "Also set up Firebase Hosting for this app."
  • Click Register App. This should auto-generate a script with several values that you need to copy into the next step.
  • Copy the auto-generated values from the Firebase console to the corresponding variables in the .env.firebase file in the env folder of your Honeycomb task repo:
REACT_APP_FIREBASE="true"
REACT_APP_apiKey=
REACT_APP_authDomain=
REACT_APP_projectId=
REACT_APP_storageBucket=
REACT_APP_messagingSenderId=
REACT_APP_appId=
  • Copy the auto-generated values from the Firebase console to the corresponding variables in the .env.firebase you just created.
    • You only need to copy the variables referenced here. If you enabled Google Analytics during project creation, additional variables may be printed in the console. You don't need to copy those.

Firebase is now set up!

Setting up Firestore​

Honeycomb includes cloud storage for task data using Firestore. Follow these steps to initialize Firestore:

  • Navigate to the current project in the developer console and select Firestore Database from the sidebar.
  • Click Create Database, select production mode and choose the current location for the cloud storage bucket.

Firestore security rules​

Firestore Security Rules provides easy server-side authorization to the database. For a honeycomb task, we use the security rules to allow access to only authorized participants for a specified study. Honeycomb's default set of rules is included in the firestore.rules file in the home directory. This file can be edited to change the rules. To deploy the rules in the file, type the following line of code in the terminal:

firebase deploy --only firestore:rules

Alternatively, Editing the rules directly in the console is also possible. To do so, navigate to the Rules tab in the Firestore Database section from the firebase console sidebar then copy and paste the code that is in the firestore.rules file.

Firestore database and rules are now both deployed. For Honeycomb's default set of rules, to add an authorized participant for a study, create a collection named registered_studies, add a study with the study ID as the document name in that collection. For each registered study, add an array field named registered_participants where each element in the array will be an authorized participant for that study.

Example Task

- +
Version: 3.0.0

Set up Firebase

Honeycomb comes with methods and configurations for easy Firebase and Cloud Firestore set up. Please use this section to configure Firebase Hosting services and Firestore cloud storage.

Setting up Firebase​

0. Installing the Firebase Command Line Interface​

To check if firebase has been installed, type firebase into a terminal window.

firebase

If a list of options are printed on the terminal then the firebase tool has already been installed. If not, you will get an error - something along the lines of "Command not found." The firebase-cli can then be installed using npm:

npm install -g firebase-tools

The -g flag installs an npm package globally on your system, as opposed to the current project

1. Initializing Firebase account and project​

  • Create and login to a Firebase account on the Firebase website.

  • Create a Firebase project by clicking add project and enter a Project Name.

2. Linking firebase to task​

  • Login to Firebase using firebase login command in the terminal.

  • Navigate to the .firebaserc file home directory and edit the "default" field with the project name given in part 1.

{
    "projects": {
        "default": "<your project name>"
    }
}

3. Copying web app credentials​

  • Navigate to the firebase console and select the project.
  • Create a new Web App by clicking on Add App or the </> code symbol and following the prompts.
  • Enter the a name for the Firebase app (could be the same as your Honeycomb task repo name).
  • Check "Also set up Firebase Hosting for this app."
  • Click Register App. This should auto-generate a script with several values that you need to copy into the next step.
  • Copy the auto-generated values from the Firebase console to the corresponding variables in the .env.firebase file in the env folder of your Honeycomb task repo:
REACT_APP_FIREBASE="true"
REACT_APP_apiKey=
REACT_APP_authDomain=
REACT_APP_projectId=
REACT_APP_storageBucket=
REACT_APP_messagingSenderId=
REACT_APP_appId=
  • Copy the auto-generated values from the Firebase console to the corresponding variables in the .env.firebase you just created.
    • You only need to copy the variables referenced here. If you enabled Google Analytics during project creation, additional variables may be printed in the console. You don't need to copy those.

Firebase is now set up!

Setting up Firestore​

Honeycomb includes cloud storage for task data using Firestore. Follow these steps to initialize Firestore:

  • Navigate to the current project in the developer console and select Firestore Database from the sidebar.
  • Click Create Database, select production mode and choose the current location for the cloud storage bucket.

Firestore security rules​

Firestore Security Rules provides easy server-side authorization to the database. For a honeycomb task, we use the security rules to allow access to only authorized participants for a specified study. Honeycomb's default set of rules is included in the firestore.rules file in the home directory. This file can be edited to change the rules. To deploy the rules in the file, type the following line of code in the terminal:

firebase deploy --only firestore:rules

Alternatively, Editing the rules directly in the console is also possible. To do so, navigate to the Rules tab in the Firestore Database section from the firebase console sidebar then copy and paste the code that is in the firestore.rules file.

Firestore database and rules are now both deployed. For Honeycomb's default set of rules, to add an authorized participant for a study, create a collection named registered_studies, add a study with the study ID as the document name in that collection. For each registered study, add an array field named registered_participants where each element in the array will be an authorized participant for that study.

Example Task

+ \ No newline at end of file diff --git a/docs/3.0.0/folders/index.html b/docs/3.0.0/folders/index.html index 4e519b50..fa54d627 100644 --- a/docs/3.0.0/folders/index.html +++ b/docs/3.0.0/folders/index.html @@ -4,13 +4,13 @@ Project Organization | Honeycomb - +
-
Version: 3.0.0

Project Organization

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 definitely not mutated), 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. Below are descriptions of the main files and folders.

package.json​

The package.json file contains metadata about your project and scripts to run tasks related to your task. The name should be updated to your task's name and scripts can be added as desired, but otherwise this file should not be edited manually. To remove or add a dependency use npm install or npm uninstall with the -D flag if installing a dev dependency.

The package-lock.json contains metadata about the package installation. It should never be manually updated.

assets/​

This folder contains any static files that are used by the app, such as the images used as icons for the installed applications.

env/​

This folder contains different .env files with presets for common use cases. These files can be loaded with dotenv, which is explained in greater detail in the Configuration section.

.github/workflows/​

This folder contains different .yaml files which are used to configure the build tests (build.yaml) following a push and to create task executables either in a single instance (package.yaml) or for a full release (release.yaml).

public/​

The public directory contains files that are used as assets in the built app. The favicon.ico is the small icon you can see in the browser tab (on Chrome) - it is set to Brown's logo in the project. The index.html contains the shell of your website - the name displayed on the tab can be changed here, otherwise it shouldn't need to be edited. The scripts included in the file are for psiturk as are the files in the lib/ directory.

electron.js​

This file contains all of the code relating to the Electron app. This includes the event-marker, throwing errors via dialog windows, saving data, and reading files.

config/​

The config directory contains the config files needed for the electron app. This includes the event-marker details and event codes.

In the config/ directory, there are .js files which contain settings for the different parts of the task. Every task should have a main config and a trigger config (assuming use of the event marker). The main config has all global settings for the task (such as whether it is in mturk mode or not), load the appropriate language file, and set up a default (or only) configuration object for the task. Different in-task features can be loaded from .env files and is set in the main config. For example, we have included some of these files in the env directory (e.g. env.clinic file enables event marker, photodiode and volume adjustment). The trigger config has settings specific to the event marker and uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.

Other config files can be used to add settings for specific blocks or sub-sections of the experiment. Also, note that the productId can be overwritten by the environment variable EVENT_MARKER_PRODUCT_ID.

src/​

This folder contains the code for the app, the vast majority of changes and code should go here.

App.jsx​

This is the starting point for the app. The <Login> component handles user authentication in the different use cases and the <JsPsychExperiment> component initializes the jspsych 7 experiment. This is also where communication is set up with the electron and psiturk processes.

App.css​

This is where styling for the app is housed. If colors, fonts, spacing, etc. need to be set, do it here.

components/​

This folder contains the components referenced in App.jsx. This includes the Honeycomb <JsPsychExperiment> component which connects the Honyecomb login page to your jspsych 7 experiment.

language/​

Any language that is displayed in the experiment should be stored in this folder. Usage of language json files allows for easy internationalization of the task (e.g. English and Spanish) as well as allows for mturk-specific language. This also makes it easy to re-use common phrases in many places in the task.

lib/​

The lib/ directory contains utility functions and markup that is used in the tasks. This allows for functions and html to be re-used wherever needed. The lib/utils.js file contains functions that are generally useful across many tasks, whereas lib/taskUtils.js contains functions specific to this task.

lib/markup​

markup files should contain primarily templates for HTML that are used throughout the task. Typically this will be a function that takes in some parameters and then returns a string with html.

timelines​

jspsych uses timelines to control what trials are displayed in what order. timelines can contain other timelines, which is why there may be several files in this directory. The main.js file should have the timeline that is called by App.jsx in the <JsPsychExperiment> component.

trials​

jspsych uses trials as its base unit of an experiment. These trials do things such as display some stimulus or request a response.

- +
Version: 3.0.0

Project Organization

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 definitely not mutated), 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. Below are descriptions of the main files and folders.

package.json​

The package.json file contains metadata about your project and scripts to run tasks related to your task. The name should be updated to your task's name and scripts can be added as desired, but otherwise this file should not be edited manually. To remove or add a dependency use npm install or npm uninstall with the -D flag if installing a dev dependency.

The package-lock.json contains metadata about the package installation. It should never be manually updated.

assets/​

This folder contains any static files that are used by the app, such as the images used as icons for the installed applications.

env/​

This folder contains different .env files with presets for common use cases. These files can be loaded with dotenv, which is explained in greater detail in the Configuration section.

.github/workflows/​

This folder contains different .yaml files which are used to configure the build tests (build.yaml) following a push and to create task executables either in a single instance (package.yaml) or for a full release (release.yaml).

public/​

The public directory contains files that are used as assets in the built app. The favicon.ico is the small icon you can see in the browser tab (on Chrome) - it is set to Brown's logo in the project. The index.html contains the shell of your website - the name displayed on the tab can be changed here, otherwise it shouldn't need to be edited. The scripts included in the file are for psiturk as are the files in the lib/ directory.

electron.js​

This file contains all of the code relating to the Electron app. This includes the event-marker, throwing errors via dialog windows, saving data, and reading files.

config/​

The config directory contains the config files needed for the electron app. This includes the event-marker details and event codes.

In the config/ directory, there are .js files which contain settings for the different parts of the task. Every task should have a main config and a trigger config (assuming use of the event marker). The main config has all global settings for the task (such as whether it is in mturk mode or not), load the appropriate language file, and set up a default (or only) configuration object for the task. Different in-task features can be loaded from .env files and is set in the main config. For example, we have included some of these files in the env directory (e.g. env.clinic file enables event marker, photodiode and volume adjustment). The trigger config has settings specific to the event marker and uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.

Other config files can be used to add settings for specific blocks or sub-sections of the experiment. Also, note that the productId can be overwritten by the environment variable EVENT_MARKER_PRODUCT_ID.

src/​

This folder contains the code for the app, the vast majority of changes and code should go here.

App.jsx​

This is the starting point for the app. The <Login> component handles user authentication in the different use cases and the <JsPsychExperiment> component initializes the jspsych 7 experiment. This is also where communication is set up with the electron and psiturk processes.

App.css​

This is where styling for the app is housed. If colors, fonts, spacing, etc. need to be set, do it here.

components/​

This folder contains the components referenced in App.jsx. This includes the Honeycomb <JsPsychExperiment> component which connects the Honyecomb login page to your jspsych 7 experiment.

language/​

Any language that is displayed in the experiment should be stored in this folder. Usage of language json files allows for easy internationalization of the task (e.g. English and Spanish) as well as allows for mturk-specific language. This also makes it easy to re-use common phrases in many places in the task.

lib/​

The lib/ directory contains utility functions and markup that is used in the tasks. This allows for functions and html to be re-used wherever needed. The lib/utils.js file contains functions that are generally useful across many tasks, whereas lib/taskUtils.js contains functions specific to this task.

lib/markup​

markup files should contain primarily templates for HTML that are used throughout the task. Typically this will be a function that takes in some parameters and then returns a string with html.

timelines​

jspsych uses timelines to control what trials are displayed in what order. timelines can contain other timelines, which is why there may be several files in this directory. The main.js file should have the timeline that is called by App.jsx in the <JsPsychExperiment> component.

trials​

jspsych uses trials as its base unit of an experiment. These trials do things such as display some stimulus or request a response.

+ \ No newline at end of file diff --git a/docs/3.0.0/index.html b/docs/3.0.0/index.html index e0c34d2d..17ee5a85 100644 --- a/docs/3.0.0/index.html +++ b/docs/3.0.0/index.html @@ -4,13 +4,13 @@ Introduction | Honeycomb - +
-
Version: 3.0.0

Introduction

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.

Flexible deployment online and in the lab​

Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings.

Easy to install executables​

Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites.

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.

Cite this work​

If you use Honeycomb in your work, please cite

Provenza, N.R., Gelin, L.F.F., Mahaphanit, W., McGrath, M.C., Dastin-van Rijn, E.M., Fan, Y., Dhar, R., Frank, M.J., Restrepo, M.I., Goodman, W.K. and Borton, D.A., 2021. Honeycomb: a template for reproducible psychophysiological tasks for clinic, laboratory, and home use. Brazilian Journal of Psychiatry, 44, pp.147-155.

- +
Version: 3.0.0

Introduction

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.

Flexible deployment online and in the lab​

Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings.

Easy to install executables​

Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites.

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.

Cite this work​

If you use Honeycomb in your work, please cite

Provenza, N.R., Gelin, L.F.F., Mahaphanit, W., McGrath, M.C., Dastin-van Rijn, E.M., Fan, Y., Dhar, R., Frank, M.J., Restrepo, M.I., Goodman, W.K. and Borton, D.A., 2021. Honeycomb: a template for reproducible psychophysiological tasks for clinic, laboratory, and home use. Brazilian Journal of Psychiatry, 44, pp.147-155.

+ \ No newline at end of file diff --git a/docs/3.0.0/npm_scripts/index.html b/docs/3.0.0/npm_scripts/index.html index 73965d02..b875c295 100644 --- a/docs/3.0.0/npm_scripts/index.html +++ b/docs/3.0.0/npm_scripts/index.html @@ -4,13 +4,13 @@ NPM Scripts | Honeycomb - +
-
Version: 3.0.0

NPM Scripts

In the project directory, you can run:

npm run dev​

Runs npm start and npm run electron-dev concurrently. This may not play nicely with windows. If it doesn't, run npm start and npm run electron-dev from different terminal windows.

npm start​

Runs the app in the development mode.

Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.

You will also see any lint errors in the console.

npm test​

Launches the test runner in the interactive watch mode.

See the section about running tests for more information.

npm build​

Creates a production build of the app (renderer). This must be done before running package:platform or the psiturk build instructions.

npm run package:platform​

Uses Electron to build the app and create a standalone installer for the given platform. Supported platforms are:

  • npm run package:windows
  • npm run package:linux
  • npm run package:mac

The output can be found in the ./out subfolder.

Note: Packaging for windows on a non-windows machine requires mono and wine to be installed.

npm run eject​

Note: this is a one-way operation. Once you eject, you can’t go back!

If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.

Run Electron​

npm run electron​

Run the built app.

npm run electron-dev​

Run the current state of the code (un-built).

- +
Version: 3.0.0

NPM Scripts

In the project directory, you can run:

npm run dev​

Runs npm start and npm run electron-dev concurrently. This may not play nicely with windows. If it doesn't, run npm start and npm run electron-dev from different terminal windows.

npm start​

Runs the app in the development mode.

Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.

You will also see any lint errors in the console.

npm test​

Launches the test runner in the interactive watch mode.

See the section about running tests for more information.

npm build​

Creates a production build of the app (renderer). This must be done before running package:platform or the psiturk build instructions.

npm run package:platform​

Uses Electron to build the app and create a standalone installer for the given platform. Supported platforms are:

  • npm run package:windows
  • npm run package:linux
  • npm run package:mac

The output can be found in the ./out subfolder.

Note: Packaging for windows on a non-windows machine requires mono and wine to be installed.

npm run eject​

Note: this is a one-way operation. Once you eject, you can’t go back!

If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.

Run Electron​

npm run electron​

Run the built app.

npm run electron-dev​

Run the current state of the code (un-built).

+ \ No newline at end of file diff --git a/docs/3.0.0/online_integration/index.html b/docs/3.0.0/online_integration/index.html index fc2e1164..87b68702 100644 --- a/docs/3.0.0/online_integration/index.html +++ b/docs/3.0.0/online_integration/index.html @@ -4,7 +4,7 @@ Deploy online | Honeycomb - + @@ -13,8 +13,8 @@ PsiTurk is a Python package used to manage HITs in Mechanical Turk. Before using the provided script, install PsiTurk.

You'll need to follow these steps (the path to the PsiTurk project should be a directory you wish to be created):

  • Build the application: npm run build

  • Move to the psiturkit directory: cd psiturkit

  • If it's the first time you're running the script:
    ./psiturk-it -p <PATH_TO_NEW_PSITURK_PROJECT>

  • To update an existing PsiTurk project (the path to the PsiTurk project should already exist from the previous steps):
    ./psiturk-it -u -p <PATH_TO_NEW_PSITURK_PROJECT>

Running psiturk​

After that, just navigate to your newly created PsiTurk project directory.

shell> psiturk #start psiturk
psiturk> server on #start server
psiturk> debug #debug mode

Running on the Web​

Using Github Pages​

Running npm run build generates static content into the build directory that can be served using any static contents hosting service. The workflow .github/workflows/release-home-all.yml uploads the build directory to the gh-branch to serve the application on GitHub pages as an example. After a creating a tag, the workflow will run and your application will be served at <githubuser>.github.io/<repository>. -For this step to succeed you will need to create a deploy key and enable GitHub Pages for your repository.

  1. Generate a new SSH key.
  2. By default, your public key should have been created in ~/.ssh/id_rsa.pub or use the name you've provided.
  3. Copy key to clipboard with xclip -sel clip < ~/.ssh/id_rsa.pub and paste it as a deploy key in your repository. Copy file content if the command line doesn't work for you. Check the box for Allow write access before saving your deployment key.
  4. You'll need your private key as a GitHub secret to allow the workflow to run the deployment for you.
  5. To create the secret copy your private key e.g. xclip -sel clip < ~/.ssh/id_rsa and paste a GitHub secret with name GH_PAGES_DEPLOY. Copy file content if the command line doesn't work for you. Save your secret.
  6. Make sure the publishing source for your repository is configured for gh-pages branch.

Using Firebase​

We have included methods and configurations for close integration with firebase. Before proceeding with the follwing steps, please make sure that firebase is configured by following the Getting started with firebase section under Set Up Firebase.

  1. Run npm run build:firebase in the terminal to create a production build for firebase.
  2. Run firebase deploy in the terminal to deploy the production build.
  3. The production build is now deployed to the firebase project domain.

To automate firebase deployments, we have included instructions on setting up firebase github actions on our Automated Builds page

- +For this step to succeed you will need to create a deploy key and enable GitHub Pages for your repository.

  1. Generate a new SSH key.
  2. By default, your public key should have been created in ~/.ssh/id_rsa.pub or use the name you've provided.
  3. Copy key to clipboard with xclip -sel clip < ~/.ssh/id_rsa.pub and paste it as a deploy key in your repository. Copy file content if the command line doesn't work for you. Check the box for Allow write access before saving your deployment key.
  4. You'll need your private key as a GitHub secret to allow the workflow to run the deployment for you.
  5. To create the secret copy your private key e.g. xclip -sel clip < ~/.ssh/id_rsa and paste a GitHub secret with name GH_PAGES_DEPLOY. Copy file content if the command line doesn't work for you. Save your secret.
  6. Make sure the publishing source for your repository is configured for gh-pages branch.

Using Firebase​

We have included methods and configurations for close integration with firebase. Before proceeding with the follwing steps, please make sure that firebase is configured by following the Getting started with firebase section under Set Up Firebase.

  1. Run npm run build:firebase in the terminal to create a production build for firebase.
  2. Run firebase deploy in the terminal to deploy the production build.
  3. The production build is now deployed to the firebase project domain.

To automate firebase deployments, we have included instructions on setting up firebase github actions on our Automated Builds page

+ \ No newline at end of file diff --git a/docs/3.0.0/quick_start/index.html b/docs/3.0.0/quick_start/index.html index 9e69d079..5668a046 100644 --- a/docs/3.0.0/quick_start/index.html +++ b/docs/3.0.0/quick_start/index.html @@ -4,13 +4,13 @@ Quick Start | Honeycomb - +
-
Version: 3.0.0

Quick Start

Before we can get started with Honeycomb, we must make sure our machines have the required prerequisites for Honeycomb to run.

1. Install a Package Manager​

There are some prerequisites that are required across all operating systems to run Honeycomb. We will be using a package manager to install these dependencies.

MacOS Package Manager (Homebrew)​

Paste the following in a macOS Terminal and press enter to install Homebrew, then follow the steps in the terminal screen.

/bin/bash -c '$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)'

When this command is run, additional installations may be automatically added by Homebrew based on your machine's configurations. Homebrew will prompt you to Press RETURN to continue or any other key to abort. Please continue with these installations by pressing Return

Set up Homebrew on your PATH​

To make Homebrew available in your shell, we need to add the Homebrew installation location to our PATH. This should be done automatically on macOS 10.14 Mojave or newer. For older versions, or to do it manually run the following command in your terminal.

echo 'PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile

If you're using zsh, also add to your ~/.zshrc file.

Windows Package Manager (Chocolatey)​

Chocolatey is a package manager for Windows - essentially the equivalent of Homebrew for MacOs. It installs software from the command line and makes updates much easier. Run Powershell with administrator privileges and paste the following command:

Run Powershell as an admin form the start menu

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

2. Start your new task from our template repository​

To start a new task locally, in development mode follow these steps:

The simplest way to get started is creating a new repository using Honeycomb as a template. This option will allow you to generate a new repository with the same directory structure and files as an existing repository.

Creating a repository from a template is similar to forking a repository, but there are important differences:

  • A new fork includes the entire commit history of the parent repository, while a repository created from a template starts with a single commit.
  • Commits to a fork don't appear in your contributions graph, while commits to a repository created from a template do appear in your contribution graph.
  • A fork can be a temporary way to contribute code to an existing project, while creating a repository from a template starts a new project quickly.

Go to https://github.com/brown-ccv/honeycomb and click on Use this template on the top right.

Use this template

Then select the organization and the name of your repository and click on create repository from template.

Create repository

Alternatively, you can use GitHub CLI to create a new project based on the Honeycomb template repository. First, install GitHub CLI (https://cli.github.com/), then run on your terminal:

gh repo create your-new-task-name --template brown-ccv/honeycomb

You can now move into the directory that was just created

cd your-new-task-name

3. Install Prerequisites​

Running Brewfile (macOS)​

A Brewfile is a script that developers can use to install multiple software tools that are required to run an application.

brew bundle

This will call the brew command which will install all the listed packages to your project.

Using Chocolatey (Windows)​

Chocolatey will install multiple software packages if given a configuration file. The honeycomb template repository includes one! See Setup Details for more information about using chocolatey.

choco install chocolatey.config
Python on Windows​

In addition to the packages installed by Chocolatey you need to complete your Python installation using pyenv. Please complete the steps in Python on Windows before continuing.

4. Change name and description​

It's best practice to create a new branch whenever we look to make changes and/or add a new feature. Your IDE may have a way to do this or it can always be done on the command line.

git checkout -b <branch-name>

Open package.json and edit it to reflect your app name and description (e.g. name, author, repository). Save your changes and commit them to git:

git commit -m "Commit message goes here!"

Checkout the Version Control page for more information about working with git

5. Install NPM Packages​

npm is a command-line utility for Node.js that makes it easy for you to install packages and maintain them throughout the lifecycle of your application. With Node.js installed in Step 0, we are now able to utilize the npm command in the terminal.

Please run the following command to trigger the installation of all the dependencies relevant to this project:

npm install

Honeycomb, like most applications, contains a template called package.json. This file contains three distinctive parts that we interact with using a series of npm commands.

Metadata​

{
 "name": "honeycomb",
 "description": "all-in-one task starter app with jsPsych + React + Electron + psiturk ",
 "author": {
   "name": "Brown CCV",
   "email": "ccv-bot@brown.edu",
   "url": "ccv.brown.edu"
  }
}

The metadata provides information about the project such as the name, author and description.

Dependencies​

"dependencies": {
  "@brown-ccv/behavioral-task-trials": "^2.0.0",
  "@fortawesome/fontawesome-free": "^5.9.0",
  "bootstrap": "^5.2.0-beta1",
  "electron-log": "^4.4.8",
  "electron-squirrel-startup": "^1.0.0",
  "event-marker": "git+https://github.com/brown-ccv/event-marker.git",
  ...
}

Dependencies are packages that the project rely on for it to function properly.

They are formatted in specific key/value pairs where every key is a name of the package and the value is the version range that’s acceptable.

Note: If any changes are made to the dependencies section of the package.json, you must run npm install again to download the newly updated list of dependencies.

Scripts​

"scripts": {
  "commit": "git-cz",
  "postinstall": "node version.js && npm run rebuild",
  "start": "cross-env BROWSER=\"none\" NODE_PATH=\"./src\" react-scripts start",
  "start:browser": "react-scripts start",
  "test": "react-scripts test",
  "prebuild": "electron-rebuild",
  "build": "react-scripts build",
  ...
}

The scripts section contains a number of commands you can run.

Check out the NPM Scripts page for more information about the different scripts you can run.

6. Run the task in dev mode​

npm run dev

This will launch an electron window with the task and inspector open. It will hot-reload whenever changes are made to the app.

Scripts on Windows​

Windows users must use a Git Bash terminal to execute scripts such as npm run dev. This is because node scripts are designed to execute on a Unix style command line environment but neither Command Prompt nor PowerShell are Unix based.

Check out these instructions to set git bash as your default terminal on VS Code.

7. Learn about configuring your task for different environments​

HoneyComb tasks can be configured to run as a web app in Firebase, as desktop application via electron, to receive port signals from EEG, cameras, foot pedals and more. To learn more about how to configure your task for these different scenarios, see the Configuration Section.

8. Check out the data​

The data is saved throughout the task. When running as a Desktop App, data is saved to the user's app directory. When running as Web App in Firebase, data is stored in the FireStore.

For a Desktop App, the location of the is logged at the beginning of the task wherever you ran npm run dev. Data is also stored in a folder that is generated by the app, which should be found on the desktop.

9. Quit the task​

If you want to quit in the middle of the task, you can use these keyboard shortcuts:

Ctrl+W (for PC/Windows)
Cmd+Q (for Mac)

Partial data will be saved.

10. Run automated tests​

Automated tests can tell a user whether the code is working as expected or if recent changes have broken previous functionality. Running automated tests is a good idea whenever you're getting started, merging updates, or making custom changes.

To run the tests interactively:

npm test

Or non-interactively:

CI=true npm test

Testing on Linux​

When running npm test on Linux, you might get an error that mentions ENOSPC. This is because the test runner creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.

This is a "known issue" with some test runners on Linux, as in discussions here and here.

One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):

  • Command that initially fails with ENOSPC: npm test
  • Check the configured limit on "watchers": cat /proc/sys/fs/inotify/max_user_watches
  • Edit the relevant Linux config file: sudo vim /etc/sysctl.conf
  • Add a line at the end of the config file: fs.inotify.max_user_watches=100000
  • Save, exit, and reload the config file: sudo sysctl -p
  • Check that the limit has changed: cat /proc/sys/fs/inotify/max_user_watches
  • Retry the initial command, which should now succeed: npm test
- +
Version: 3.0.0

Quick Start

Before we can get started with Honeycomb, we must make sure our machines have the required prerequisites for Honeycomb to run.

1. Install a Package Manager​

There are some prerequisites that are required across all operating systems to run Honeycomb. We will be using a package manager to install these dependencies.

MacOS Package Manager (Homebrew)​

Paste the following in a macOS Terminal and press enter to install Homebrew, then follow the steps in the terminal screen.

/bin/bash -c '$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)'

When this command is run, additional installations may be automatically added by Homebrew based on your machine's configurations. Homebrew will prompt you to Press RETURN to continue or any other key to abort. Please continue with these installations by pressing Return

Set up Homebrew on your PATH​

To make Homebrew available in your shell, we need to add the Homebrew installation location to our PATH. This should be done automatically on macOS 10.14 Mojave or newer. For older versions, or to do it manually run the following command in your terminal.

echo 'PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile

If you're using zsh, also add to your ~/.zshrc file.

Windows Package Manager (Chocolatey)​

Chocolatey is a package manager for Windows - essentially the equivalent of Homebrew for MacOs. It installs software from the command line and makes updates much easier. Run Powershell with administrator privileges and paste the following command:

Run Powershell as an admin form the start menu

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

2. Start your new task from our template repository​

To start a new task locally, in development mode follow these steps:

The simplest way to get started is creating a new repository using Honeycomb as a template. This option will allow you to generate a new repository with the same directory structure and files as an existing repository.

Creating a repository from a template is similar to forking a repository, but there are important differences:

  • A new fork includes the entire commit history of the parent repository, while a repository created from a template starts with a single commit.
  • Commits to a fork don't appear in your contributions graph, while commits to a repository created from a template do appear in your contribution graph.
  • A fork can be a temporary way to contribute code to an existing project, while creating a repository from a template starts a new project quickly.

Go to https://github.com/brown-ccv/honeycomb and click on Use this template on the top right.

Use this template

Then select the organization and the name of your repository and click on create repository from template.

Create repository

Alternatively, you can use GitHub CLI to create a new project based on the Honeycomb template repository. First, install GitHub CLI (https://cli.github.com/), then run on your terminal:

gh repo create your-new-task-name --template brown-ccv/honeycomb

You can now move into the directory that was just created

cd your-new-task-name

3. Install Prerequisites​

Running Brewfile (macOS)​

A Brewfile is a script that developers can use to install multiple software tools that are required to run an application.

brew bundle

This will call the brew command which will install all the listed packages to your project.

Using Chocolatey (Windows)​

Chocolatey will install multiple software packages if given a configuration file. The honeycomb template repository includes one! See Setup Details for more information about using chocolatey.

choco install chocolatey.config
Python on Windows​

In addition to the packages installed by Chocolatey you need to complete your Python installation using pyenv. Please complete the steps in Python on Windows before continuing.

4. Change name and description​

It's best practice to create a new branch whenever we look to make changes and/or add a new feature. Your IDE may have a way to do this or it can always be done on the command line.

git checkout -b <branch-name>

Open package.json and edit it to reflect your app name and description (e.g. name, author, repository). Save your changes and commit them to git:

git commit -m "Commit message goes here!"

Checkout the Version Control page for more information about working with git

5. Install NPM Packages​

npm is a command-line utility for Node.js that makes it easy for you to install packages and maintain them throughout the lifecycle of your application. With Node.js installed in Step 0, we are now able to utilize the npm command in the terminal.

Please run the following command to trigger the installation of all the dependencies relevant to this project:

npm install

Honeycomb, like most applications, contains a template called package.json. This file contains three distinctive parts that we interact with using a series of npm commands.

Metadata​

{
 "name": "honeycomb",
 "description": "all-in-one task starter app with jsPsych + React + Electron + psiturk ",
 "author": {
   "name": "Brown CCV",
   "email": "ccv-bot@brown.edu",
   "url": "ccv.brown.edu"
  }
}

The metadata provides information about the project such as the name, author and description.

Dependencies​

"dependencies": {
  "@brown-ccv/behavioral-task-trials": "^2.0.0",
  "@fortawesome/fontawesome-free": "^5.9.0",
  "bootstrap": "^5.2.0-beta1",
  "electron-log": "^4.4.8",
  "electron-squirrel-startup": "^1.0.0",
  "event-marker": "git+https://github.com/brown-ccv/event-marker.git",
  ...
}

Dependencies are packages that the project rely on for it to function properly.

They are formatted in specific key/value pairs where every key is a name of the package and the value is the version range that’s acceptable.

Note: If any changes are made to the dependencies section of the package.json, you must run npm install again to download the newly updated list of dependencies.

Scripts​

"scripts": {
  "commit": "git-cz",
  "postinstall": "node version.js && npm run rebuild",
  "start": "cross-env BROWSER=\"none\" NODE_PATH=\"./src\" react-scripts start",
  "start:browser": "react-scripts start",
  "test": "react-scripts test",
  "prebuild": "electron-rebuild",
  "build": "react-scripts build",
  ...
}

The scripts section contains a number of commands you can run.

Check out the NPM Scripts page for more information about the different scripts you can run.

6. Run the task in dev mode​

npm run dev

This will launch an electron window with the task and inspector open. It will hot-reload whenever changes are made to the app.

Scripts on Windows​

Windows users must use a Git Bash terminal to execute scripts such as npm run dev. This is because node scripts are designed to execute on a Unix style command line environment but neither Command Prompt nor PowerShell are Unix based.

Check out these instructions to set git bash as your default terminal on VS Code.

7. Learn about configuring your task for different environments​

HoneyComb tasks can be configured to run as a web app in Firebase, as desktop application via electron, to receive port signals from EEG, cameras, foot pedals and more. To learn more about how to configure your task for these different scenarios, see the Configuration Section.

8. Check out the data​

The data is saved throughout the task. When running as a Desktop App, data is saved to the user's app directory. When running as Web App in Firebase, data is stored in the FireStore.

For a Desktop App, the location of the is logged at the beginning of the task wherever you ran npm run dev. Data is also stored in a folder that is generated by the app, which should be found on the desktop.

9. Quit the task​

If you want to quit in the middle of the task, you can use these keyboard shortcuts:

Ctrl+W (for PC/Windows)
Cmd+Q (for Mac)

Partial data will be saved.

10. Run automated tests​

Automated tests can tell a user whether the code is working as expected or if recent changes have broken previous functionality. Running automated tests is a good idea whenever you're getting started, merging updates, or making custom changes.

To run the tests interactively:

npm test

Or non-interactively:

CI=true npm test

Testing on Linux​

When running npm test on Linux, you might get an error that mentions ENOSPC. This is because the test runner creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.

This is a "known issue" with some test runners on Linux, as in discussions here and here.

One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):

  • Command that initially fails with ENOSPC: npm test
  • Check the configured limit on "watchers": cat /proc/sys/fs/inotify/max_user_watches
  • Edit the relevant Linux config file: sudo vim /etc/sysctl.conf
  • Add a line at the end of the config file: fs.inotify.max_user_watches=100000
  • Save, exit, and reload the config file: sudo sysctl -p
  • Check that the limit has changed: cat /proc/sys/fs/inotify/max_user_watches
  • Retry the initial command, which should now succeed: npm test
+ \ No newline at end of file diff --git a/docs/3.0.0/setup_details/index.html b/docs/3.0.0/setup_details/index.html index a9a91f03..629ff670 100644 --- a/docs/3.0.0/setup_details/index.html +++ b/docs/3.0.0/setup_details/index.html @@ -4,14 +4,14 @@ Setup Details | Honeycomb - +
Version: 3.0.0

Setup Details

Prerequisites​

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. First we need the following programs

  • git (version control and GitHub integration)
  • nodejs (web development - we recommend the latest long term support version)
  • python (3.7 or later)
  • An Integrated Development Environment (we recommend VS Code)

In addition, Honeycomb relies on Electron to package the cross-platform desktop applications. Some of electron's prerequisites are platform dependant - listed below are the prerequisites for each operating system along with resources for manually installing them.

MacOS​

Brew​

All of the required dependencies for honeycomb on MacOS can be installed via the brewfile. See the quick start for more information.

Manual Installation (MacOS)​

Windows​

Note that Windows occasionally requires a restart after package installations complete. If you are running into issues after installing the packages please restart your terminal and/or your entire computer. This should resolve most issues.

chocolatey​

chocolatey.config​

A Chocolatey configuration file looks something like this:

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="git" />
  <package id="nodejs-lts" />
  <package id="vscode" />
  <package id="pyenv-win" />
  <package id="visualstudio2022community" />
  <package id="visualstudio2022-workload-nativedesktop" />
  <package id="electron" />
</packages>

Running choco install chocolatey.config is the equivalent of calling choco install <id> for every package in the file.

Python on Windows (pyenv)​

Installing and managing Python on Windows is a notoriously difficult task even for advanced developers. It is best practice to have exactly 1 tool for managing python on your system, which is a rule for most things in software development (this is what npm does for node packages). We highly recommend uninstalling Python and using pyenv even if you never anticipate using python again. We promise the extra setup today will pay great dividends in the future!

First and foremost, turn off both Python App Installers in the "App Execution Aliases" settings. Please complete this step even if you already have a Python manager

App execution aliases -Turn off app installer

Now we can set up our python management system1. We recommend pyenv as it is small and intuitive for newer developers. It lets us install python globally AND switch between different versions for individual projects. It does this (and only this) extremely well. Complete the following steps to install pyenv for Windows and set up your global python environment:

  1. Ensure Python is completely uninstalled from your system2

    • Type python on the command line and ensure you get a "Command 'python' not found" error

      python

    • If the command executes, locate the installation (check "Add or Remove programs" in the settings) and remove it. Continue until the error appears

    • If the Microsoft Store launches check again to ensure "Manage App execution aliases" is turned off for python.exe and python3.exe

  2. Install pyenv-win

    • pyenv-win will install with chocolatey.config - enter pyenv on the command line to see if it's already on your system. You should see a list of commands printed to your terminal.

      pyenv

    • If not:

      choco install pyenv-win

  3. Install your python version

    pyenv install <version>

    • If you're using a different Python version for another project that version will work fine so long as it is at least version > 3.0.0

    • Otherwise install the newest version that includes exactly 3 numbers, e.g. 3.10.6

      pyenv install --list

  4. Use that version as your global install

    pyenv global <version>
1_If you are already using [Anaconda](https://www.anaconda.com) for Python and it's various other tools that is okay! You already have python manager installed on your system and can skip this section._2_Any "solo" installations can and will cause major conflicts with `pyenv`. It can cause issues when you try to change your version, when another program checks for python, when you update Windows... so on and so forth. Perhaps you've already run into something unexpected like this! This is why it's essential python is completely uninstalled from your computer before beginning._

Manual Installation (Windows)​

Linux​

We recommend using Ubuntu (18.10 or later) as your distro but any distro new enough to support GLIBC_2.28 should work.

Further Help​

If you are still having issues setting up your computer you can find the full instructions on the electron documentation for your specific OS.

- +Turn off app installer

Now we can set up our python management system1. We recommend pyenv as it is small and intuitive for newer developers. It lets us install python globally AND switch between different versions for individual projects. It does this (and only this) extremely well. Complete the following steps to install pyenv for Windows and set up your global python environment:

  1. Ensure Python is completely uninstalled from your system2

    • Type python on the command line and ensure you get a "Command 'python' not found" error

      python

    • If the command executes, locate the installation (check "Add or Remove programs" in the settings) and remove it. Continue until the error appears

    • If the Microsoft Store launches check again to ensure "Manage App execution aliases" is turned off for python.exe and python3.exe

  2. Install pyenv-win

    • pyenv-win will install with chocolatey.config - enter pyenv on the command line to see if it's already on your system. You should see a list of commands printed to your terminal.

      pyenv

    • If not:

      choco install pyenv-win

  3. Install your python version

    pyenv install <version>

    • If you're using a different Python version for another project that version will work fine so long as it is at least version > 3.0.0

    • Otherwise install the newest version that includes exactly 3 numbers, e.g. 3.10.6

      pyenv install --list

  4. Use that version as your global install

    pyenv global <version>
1_If you are already using [Anaconda](https://www.anaconda.com) for Python and it's various other tools that is okay! You already have python manager installed on your system and can skip this section._2_Any "solo" installations can and will cause major conflicts with `pyenv`. It can cause issues when you try to change your version, when another program checks for python, when you update Windows... so on and so forth. Perhaps you've already run into something unexpected like this! This is why it's essential python is completely uninstalled from your computer before beginning._

Manual Installation (Windows)​

Linux​

We recommend using Ubuntu (18.10 or later) as your distro but any distro new enough to support GLIBC_2.28 should work.

Further Help​

If you are still having issues setting up your computer you can find the full instructions on the electron documentation for your specific OS.

+ \ No newline at end of file diff --git a/docs/3.0.0/troubleshooting/index.html b/docs/3.0.0/troubleshooting/index.html index bf4b6233..34d4d879 100644 --- a/docs/3.0.0/troubleshooting/index.html +++ b/docs/3.0.0/troubleshooting/index.html @@ -4,13 +4,13 @@ Troubleshooting | Honeycomb - +
-
Version: 3.0.0

Troubleshooting

Inspecting Errors​

When developing electron apps there are two processes: main, and renderer. In this case main corresponds to electron-starter.js and its console is wherever you called npm run dev or electron . from. renderer corresponds to the React App - this is everything else. The react app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running npm run dev, it should open by default.

In case you want to find out where the error is coming from when running the app locally:

  • Try reviewing logs in the terminal
  • Inspect element in your browser by openning your developer tools. For instance, in Chrome, this can be done via the menu View -> Developer or right-clicking and pressing inspect.

Try deleting your node_modules folder and the package-lock.json then running npm install then npm run rebuild.

Testing in Linux​

When running npm test on Linux, you might get an error that mentions ENOSPC. This is because the test runer creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.

This is a "known issue" with some test runners on Linux, as in discussions here and here.

One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):

  • Command that initially fails with ENOSPC: npm test
  • Check the configured limit on "watchers": cat /proc/sys/fs/inotify/max_user_watches
  • Edit the relevant Linux config file: sudo vim /etc/sysctl.conf
  • Add a line at the end of the config file: fs.inotify.max_user_watches=100000
  • Save, exit, and reload the config file: sudo sysctl -p
  • Check that the limit has changed: cat /proc/sys/fs/inotify/max_user_watches
  • Retry the initial command, which should now succeed: npm test
- +
Version: 3.0.0

Troubleshooting

Inspecting Errors​

When developing electron apps there are two processes: main, and renderer. In this case main corresponds to electron-starter.js and its console is wherever you called npm run dev or electron . from. renderer corresponds to the React App - this is everything else. The react app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running npm run dev, it should open by default.

In case you want to find out where the error is coming from when running the app locally:

  • Try reviewing logs in the terminal
  • Inspect element in your browser by openning your developer tools. For instance, in Chrome, this can be done via the menu View -> Developer or right-clicking and pressing inspect.

Try deleting your node_modules folder and the package-lock.json then running npm install then npm run rebuild.

Testing in Linux​

When running npm test on Linux, you might get an error that mentions ENOSPC. This is because the test runer creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.

This is a "known issue" with some test runners on Linux, as in discussions here and here.

One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):

  • Command that initially fails with ENOSPC: npm test
  • Check the configured limit on "watchers": cat /proc/sys/fs/inotify/max_user_watches
  • Edit the relevant Linux config file: sudo vim /etc/sysctl.conf
  • Add a line at the end of the config file: fs.inotify.max_user_watches=100000
  • Save, exit, and reload the config file: sudo sysctl -p
  • Check that the limit has changed: cat /proc/sys/fs/inotify/max_user_watches
  • Retry the initial command, which should now succeed: npm test
+ \ No newline at end of file diff --git a/docs/3.0.0/variants/index.html b/docs/3.0.0/variants/index.html index feadd346..c56e0a7a 100644 --- a/docs/3.0.0/variants/index.html +++ b/docs/3.0.0/variants/index.html @@ -4,13 +4,13 @@ Variants | Honeycomb - +
-
Version: 3.0.0

Variants

Variant Specific Executables​

In order to create multiple variants of a task that can be co-installed, it is necessary to add new scripts to the package.json file in addition to creating the necessary environment variables for configuration. Each variant must have a unique, lowercase name. Optionally, a unique icon can be used for each variant by saving multiple icons to the icons directories with the same names as the variants. Example scripts for Windows, Mac, and Linux are shown below.

Windows:

"package:windows:<task_name>": "electron-packager . <task_name> --platform win32 --arch x64 --icon ./assets/icons/win/<task_name> --out dist/ --overwrite --asar"
"postpackage:windows:<task_name>": "electron-installer-windows --src dist/<task_name>-win32-x64/ --dest dist/installers/ --overwrite --homepage https://ccv.brown.edu/ --name <task_name> --exe <task_name>.exe --productName <task_name>"

Mac:

"package:mac:,<task_name>": "electron-packager . <task_name> --platform darwin --arch x64 --out dist/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"
"installer:mac:<task_name>": "electron-installer-dmg ./dist/<task_name>-darwin-x64/<task_name>.app <task_name>-${npm_package_version} --out ./dist/installers/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"

Linux:

"package:linux:<task_name>": "electron-packager . <task_name> --platform linux --arch x64 --icon ./assets/icons/mac/<task_name> --out dist/ --overwrite"
"postpackage:linux:<task_name>": "electron-installer-debian --src dist/<task_name>-linux-x64/ --dest dist/installers/ --arch x64 --overwrite --name <task_name> --productName <task_name> --genericName <task_name> --bin <task_name>"

Variant Specific Workflows​

In order to use Github workflows to build and upload executables for each variant, the build.yaml, package.yaml, and release.yaml files must be modified as well. For all three files, a new row should be added to the matrix variable as follows:

variant: [<comma_separated_list_of_variant_names>]

Add the following before npm build in the steps section of build.yaml, package.yaml, and release.yaml:

- name: Load .env file for variant
  uses: xom9ikk/dotenv@v1.0.2
  with:
    path: ./env
    mode: ${{matrix.variant}}

In package.yaml and release.yaml, replace the # Build electron app package installers section with the following code:

- name: package electron - windows
  if: startsWith(matrix.os, 'windows')
  run: npm run package:windows:${{ matrix.variant }}
- name: package electron - linux
  if: startsWith(matrix.os, 'ubuntu')
  run: npm run package:linux:${{ matrix.variant }}
- name: package electron - mac
  if: startsWith(matrix.os, 'mac')
  run: npm run package:mac:${{ matrix.variant }}
- name: npm rebuild - mac
  if: startsWith(matrix.os, 'mac')
  run: npm rebuild
- name: Mac installer
  if: startsWith(matrix.os, 'mac')
  run: npm run installer:mac:${{ matrix.variant }}

Replace the # Upload installers to github action section in package.yaml with the following code:

- name: upload win-installer
    uses: actions/upload-artifact@master
    if: startsWith(matrix.os, 'windows')
    with:
      name: ${{ format('win-installer-{0}', github.event.inputs.setting) }}
      path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
  - name: upload mac-installer
    uses: actions/upload-artifact@master
    if: startsWith(matrix.os, 'mac')
    with:
      name: ${{ format('mac-installer-{0}', github.event.inputs.setting) }}
      path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
  - name: upload linux-installer
    uses: actions/upload-artifact@master
    if: startsWith(matrix.os, 'ubuntu')
    with:
      name: ${{ format('linux-installer-{0}', github.event.inputs.setting) }}
      path: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb

Replace the # Upload installers to github release section in release.yaml with the following code:

- name: Upload app to release - windows
  if: startsWith(matrix.os, 'windows')
  uses: svenstaro/upload-release-action@v2
  with:
    repo_token: ${{ secrets.GITHUB_TOKEN }}
    file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
    asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}-setup.exe
    tag: ${{ github.ref }}
- name: Upload app to release - linux
  if: startsWith(matrix.os, 'ubuntu')
  uses: svenstaro/upload-release-action@v2
  with:
    repo_token: ${{ secrets.GITHUB_TOKEN }}
    file: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb
    asset_name: ${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_${{ matrix.setting }}_x64.deb
    tag: ${{ github.ref }}
- name: Upload app to release - mac
  if: startsWith(matrix.os, 'mac')
  uses: svenstaro/upload-release-action@v2
  with:
    repo_token: ${{ secrets.GITHUB_TOKEN }}
    file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
    asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}.dmg
    tag: ${{ github.ref }}
- +
Version: 3.0.0

Variants

Variant Specific Executables​

In order to create multiple variants of a task that can be co-installed, it is necessary to add new scripts to the package.json file in addition to creating the necessary environment variables for configuration. Each variant must have a unique, lowercase name. Optionally, a unique icon can be used for each variant by saving multiple icons to the icons directories with the same names as the variants. Example scripts for Windows, Mac, and Linux are shown below.

Windows:

"package:windows:<task_name>": "electron-packager . <task_name> --platform win32 --arch x64 --icon ./assets/icons/win/<task_name> --out dist/ --overwrite --asar"
"postpackage:windows:<task_name>": "electron-installer-windows --src dist/<task_name>-win32-x64/ --dest dist/installers/ --overwrite --homepage https://ccv.brown.edu/ --name <task_name> --exe <task_name>.exe --productName <task_name>"

Mac:

"package:mac:,<task_name>": "electron-packager . <task_name> --platform darwin --arch x64 --out dist/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"
"installer:mac:<task_name>": "electron-installer-dmg ./dist/<task_name>-darwin-x64/<task_name>.app <task_name>-${npm_package_version} --out ./dist/installers/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"

Linux:

"package:linux:<task_name>": "electron-packager . <task_name> --platform linux --arch x64 --icon ./assets/icons/mac/<task_name> --out dist/ --overwrite"
"postpackage:linux:<task_name>": "electron-installer-debian --src dist/<task_name>-linux-x64/ --dest dist/installers/ --arch x64 --overwrite --name <task_name> --productName <task_name> --genericName <task_name> --bin <task_name>"

Variant Specific Workflows​

In order to use Github workflows to build and upload executables for each variant, the build.yaml, package.yaml, and release.yaml files must be modified as well. For all three files, a new row should be added to the matrix variable as follows:

variant: [<comma_separated_list_of_variant_names>]

Add the following before npm build in the steps section of build.yaml, package.yaml, and release.yaml:

- name: Load .env file for variant
  uses: xom9ikk/dotenv@v1.0.2
  with:
    path: ./env
    mode: ${{matrix.variant}}

In package.yaml and release.yaml, replace the # Build electron app package installers section with the following code:

- name: package electron - windows
  if: startsWith(matrix.os, 'windows')
  run: npm run package:windows:${{ matrix.variant }}
- name: package electron - linux
  if: startsWith(matrix.os, 'ubuntu')
  run: npm run package:linux:${{ matrix.variant }}
- name: package electron - mac
  if: startsWith(matrix.os, 'mac')
  run: npm run package:mac:${{ matrix.variant }}
- name: npm rebuild - mac
  if: startsWith(matrix.os, 'mac')
  run: npm rebuild
- name: Mac installer
  if: startsWith(matrix.os, 'mac')
  run: npm run installer:mac:${{ matrix.variant }}

Replace the # Upload installers to github action section in package.yaml with the following code:

- name: upload win-installer
    uses: actions/upload-artifact@master
    if: startsWith(matrix.os, 'windows')
    with:
      name: ${{ format('win-installer-{0}', github.event.inputs.setting) }}
      path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
  - name: upload mac-installer
    uses: actions/upload-artifact@master
    if: startsWith(matrix.os, 'mac')
    with:
      name: ${{ format('mac-installer-{0}', github.event.inputs.setting) }}
      path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
  - name: upload linux-installer
    uses: actions/upload-artifact@master
    if: startsWith(matrix.os, 'ubuntu')
    with:
      name: ${{ format('linux-installer-{0}', github.event.inputs.setting) }}
      path: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb

Replace the # Upload installers to github release section in release.yaml with the following code:

- name: Upload app to release - windows
  if: startsWith(matrix.os, 'windows')
  uses: svenstaro/upload-release-action@v2
  with:
    repo_token: ${{ secrets.GITHUB_TOKEN }}
    file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
    asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}-setup.exe
    tag: ${{ github.ref }}
- name: Upload app to release - linux
  if: startsWith(matrix.os, 'ubuntu')
  uses: svenstaro/upload-release-action@v2
  with:
    repo_token: ${{ secrets.GITHUB_TOKEN }}
    file: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb
    asset_name: ${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_${{ matrix.setting }}_x64.deb
    tag: ${{ github.ref }}
- name: Upload app to release - mac
  if: startsWith(matrix.os, 'mac')
  uses: svenstaro/upload-release-action@v2
  with:
    repo_token: ${{ secrets.GITHUB_TOKEN }}
    file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
    asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}.dmg
    tag: ${{ github.ref }}
+ \ No newline at end of file diff --git a/docs/3.0.0/version_control/index.html b/docs/3.0.0/version_control/index.html index 625bcca9..3ae401a9 100644 --- a/docs/3.0.0/version_control/index.html +++ b/docs/3.0.0/version_control/index.html @@ -4,14 +4,14 @@ Version Control | Honeycomb - +
Version: 3.0.0

Version Control

Git Overview​

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 you 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.

Git basics

If you would like to make any changes to current repository, it is always good to start with creating a feature branch, where you can save all the changes.

Example branch

Comment styles​

We encourage using Commitizen, 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​

CommandBrief
git add <files>add a file to next commit (stage)
git commit -m <message>commit staged files
git pushupload staged commit to repo
git pullget 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
# create branch with your feature
git checkout -b feature_name
# check the status of your repositoey
git status
# commit file contents to the local repository
git commit -am "My feature is ready"
# specific message
# push file contents to the remote (i.e. cloud) repository
git push origin feature_name

Alternative options​

Instead of using commands in the terminal, you can also download GitHub desktop. It is very intuitive to use.

Clone repository​

git clone

Select a branch or create a new branch​

git branch

Commit changes and push​

git commit

Create a Pull Request​

Pull requests are useful before you merge your branch with the main branch. You can request a review from your colleagues and check for any conflicts with the main branch. After you pushed all the changes to your branch, you can go to the original GitHub repository and click on the pull request.

git pr

git pr info

Best Practices​

Git Workflow​

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.

Git Branches​

  • main is the default branch and where releases are made off. 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

This flow is sometimes referred to as Feature Branch Workflow

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, follow the following steps:

Add honeycomb as an additional remote​

By default, your repository is configured to only sync with your remote, which typically is referred to as origin. You can add Honeycomb as an additional remote as follows:

git remote add honeycomb https://github.com/brown-ccv/honeycomb.git

Adding a remote is a one time operation. At that point you can pull content from the honeycomb remote as follows:

git fetch --all
git merge honeycomb/main --allow-unrelated histories

If there are any conflicts, you'll need to resolve those, then commit the merge:

git commit -a -m "merge honeycomb latest"
- +your task, follow the following steps:

Add honeycomb as an additional remote​

By default, your repository is configured to only sync with your remote, which typically is referred to as origin. You can add Honeycomb as an additional remote as follows:

git remote add honeycomb https://github.com/brown-ccv/honeycomb.git

Adding a remote is a one time operation. At that point you can pull content from the honeycomb remote as follows:

git fetch --all
git merge honeycomb/main --allow-unrelated histories

If there are any conflicts, you'll need to resolve those, then commit the merge:

git commit -a -m "merge honeycomb latest"
+ \ No newline at end of file diff --git a/docs/3.1.x/ci/index.html b/docs/3.1.x/ci/index.html index d756a376..a2a1e138 100644 --- a/docs/3.1.x/ci/index.html +++ b/docs/3.1.x/ci/index.html @@ -4,13 +4,13 @@ Continuous Integration | Honeycomb - +
-
Version: 3.1.x

Continuous Integration

Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings on demand or automatically as the code is pushed to the repository. In this section, we provide a short introduction to definitions. We explain the GitHub Actions included with Honeycomb. These workflows should provide a foundation but can easily be modified or extended to meet more needs.

What is CI/CD?​

CI/CD refers to Continuous Integration and either Continuous Delivery or Continuous Deployment. CI/CD enforces the automated building of bundled executables so that tasks can be easily installed without dependencies. In Honeycomb, CI/CD is managed by GitHub Actions.

What are Github Actions​

GitHub Actions automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in GitHub's documentation

GitHub Actions are written as YML files inside a .github/workflows/ folder in your repository.

Building the executables​

Honeycomb includes workflows to build and create installers for Windows, Mac and Linux. These workflows exist for two configurations of the tasks:

  • Home: The app does not expect event code triggers and photodiode spots.
  • Clinic: The app expects event code triggers and photodiode spots.

More specifically, the following workflows are included:

  • build.yaml: Every time an Pull Request (PR) is opened, or a push is made to the main branch, the software is built and tests are run for all platforms and home and clinic settings. This workflow does not build and upload desktop installers
  • package.yaml: Create installers for any/all platforms for the home and clinic setting on demand 1. 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.
  • release.yml: Every time a Tag is released, installers are created and uploaded as packages. This also builds a PsiTurk version, and deploys to GitHub pages a web version of the application.
1 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).

Download your bundled executable to install and run your task​

You can download the executable file from either the tagged release page or the GitHub actions page. To install, unzip the downloaded file, install, and run.

The executable does not require installation of any additional software.

- +
Version: 3.1.x

Continuous Integration

Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings on demand or automatically as the code is pushed to the repository. In this section, we provide a short introduction to definitions. We explain the GitHub Actions included with Honeycomb. These workflows should provide a foundation but can easily be modified or extended to meet more needs.

What is CI/CD?​

CI/CD refers to Continuous Integration and either Continuous Delivery or Continuous Deployment. CI/CD enforces the automated building of bundled executables so that tasks can be easily installed without dependencies. In Honeycomb, CI/CD is managed by GitHub Actions.

What are Github Actions​

GitHub Actions automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in GitHub's documentation

GitHub Actions are written as YML files inside a .github/workflows/ folder in your repository.

Building the executables​

Honeycomb includes workflows to build and create installers for Windows, Mac and Linux. These workflows exist for two configurations of the tasks:

  • Home: The app does not expect event code triggers and photodiode spots.
  • Clinic: The app expects event code triggers and photodiode spots.

More specifically, the following workflows are included:

  • build.yaml: Every time an Pull Request (PR) is opened, or a push is made to the main branch, the software is built and tests are run for all platforms and home and clinic settings. This workflow does not build and upload desktop installers
  • package.yaml: Create installers for any/all platforms for the home and clinic setting on demand 1. 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.
  • release.yml: Every time a Tag is released, installers are created and uploaded as packages. This also builds a PsiTurk version, and deploys to GitHub pages a web version of the application.
1 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).

Download your bundled executable to install and run your task​

You can download the executable file from either the tagged release page or the GitHub actions page. To install, unzip the downloaded file, install, and run.

The executable does not require installation of any additional software.

+ \ No newline at end of file diff --git a/docs/3.1.x/deploy_online/index.html b/docs/3.1.x/deploy_online/index.html index aecd10c0..14f3b870 100644 --- a/docs/3.1.x/deploy_online/index.html +++ b/docs/3.1.x/deploy_online/index.html @@ -4,7 +4,7 @@ Deploy online | Honeycomb - + @@ -13,8 +13,8 @@ PsiTurk is a Python package used to manage HITs in Mechanical Turk. Before using the provided script, install PsiTurk.

You'll need to follow these steps (the path to the PsiTurk project should be a directory you wish to be created):

  • Build the application: npm run build

  • Move to the psiturkit directory: cd psiturkit

  • If it's the first time you're running the script:
    ./psiturk-it -p <PATH_TO_NEW_PSITURK_PROJECT>

  • To update an existing PsiTurk project (the path to the PsiTurk project should already exist from the previous steps):
    ./psiturk-it -u -p <PATH_TO_NEW_PSITURK_PROJECT>

Running PsiTurk​

After that, just navigate to your newly created PsiTurk project directory.

shell> psiturk #start psiturk
psiturk> server on #start server
psiturk> debug #debug mode

Running on the Web​

Using Github Pages​

Running npm run build generates static content into the build directory that can be served using any static contents hosting service. The workflow .github/workflows/release-home-all.yml uploads the build directory to the gh-branch to serve the application on GitHub pages as an example. After a creating a tag, the workflow will run and your application will be served at <github user>.github.io/<repository>. -For this step to succeed you will need to create a deploy key and enable GitHub Pages for your repository.

  1. Generate a new SSH key.

  2. By default, your public key should have been created in ~/.ssh/id_rsa.pub or use the name you've provided.

  3. Copy key to clipboard with xclip -sel clip < ~/.ssh/id_rsa.pub and paste it as a deploy key in your repository. Copy file content if the command line doesn't work for you. Check the box for Allow write access before saving your deployment key.

  4. You'll need your private key as a GitHub secret to allow the workflow to run the deployment for you.

  5. To create the secret, copy your private key (e.g., xclip -sel clip < ~/.ssh/id_rsa) and paste a GitHub secret with name GH_PAGES_DEPLOY. Copy file content if the command line doesn't work for you. Save your secret.

  6. Make sure the publishing source for your repository is configured for gh-pages branch.

- +For this step to succeed you will need to create a deploy key and enable GitHub Pages for your repository.

  1. Generate a new SSH key.

  2. By default, your public key should have been created in ~/.ssh/id_rsa.pub or use the name you've provided.

  3. Copy key to clipboard with xclip -sel clip < ~/.ssh/id_rsa.pub and paste it as a deploy key in your repository. Copy file content if the command line doesn't work for you. Check the box for Allow write access before saving your deployment key.

  4. You'll need your private key as a GitHub secret to allow the workflow to run the deployment for you.

  5. To create the secret, copy your private key (e.g., xclip -sel clip < ~/.ssh/id_rsa) and paste a GitHub secret with name GH_PAGES_DEPLOY. Copy file content if the command line doesn't work for you. Save your secret.

  6. Make sure the publishing source for your repository is configured for gh-pages branch.

+ \ No newline at end of file diff --git a/docs/3.1.x/environment_variables/index.html b/docs/3.1.x/environment_variables/index.html index 25a06ef7..e87ac244 100644 --- a/docs/3.1.x/environment_variables/index.html +++ b/docs/3.1.x/environment_variables/index.html @@ -4,13 +4,13 @@ Environment Variables | Honeycomb - +
-
Version: 3.1.x

Environment Variables

Honeycomb uses environment variables during build and run time to control the different configurations. Below we list the environment variables used by the app and indicate their properties via badges and text. Optional variables are labeled with the optional badge and mandatory variables are labeled with the default <default-value> badge with their default value specified. The buildtime badge indicates the variable is used during the build/compilation phase (npm build) while the runtime badge indicates the variable is used during the executable run (npm run dev).

Dev Mode Only​

  • ELECTRON_START_URL stringoptional: URL (e.g. http://localhost:3000) where the front end of the app is being hosted - also used in electron.js to indicate the app is running in dev mode.

Desktop Only​

  • EVENT_MARKER_PRODUCT_IDstringoptionalruntime: The product ID of the event marker (e.g. 0487). If not set, it will use the productID set in public/config/trigger.js if available, or attempt to connect using the com name.
  • EVENT_MARKER_COM_NAME stringoptionalruntime: The com name of the event marker (e.g. COM3). If not set, it will use the comName set in public/config/trigger.js. If the productID is set (not an empty string), this field will be ignored.
  • REACT_APP_VIDEObooleandefault falsebuildtime: whether the participant is being video recorded. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_EEGbooleandefault falsebuildtime: whether the event marker/EEG is available. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_PHOTODIODEbooleandefault falsebuildtime: whether the photodiode is in use. This can be used when the task is running as a desktop app (electron).

Desktop and Online​

  • REACT_APP_VOLUMEbooleandefault falsebuildtime: whether the participant is being asked to adjust volume. This can be used on both the desktop (electron) and online settings.
  • REACT_APP_PARTICIPANT_ID stringoptionalruntime: The default participant id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.
  • REACT_APP_STUDY_ID stringoptionalruntime: The default study id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.

Understanding Build-Time and Run-Time Variables​

  • runtime: Run-time environment variables allow for quick changes before running the task. They are convenient since they don't require building a whole different executable. For a Desktop Application, these are set at the system level and must be available at the time where the task runs. See this tutorial for OS specific instructions.. For a Firebase Application, these must be stored in the Firestore.

  • build time: Build-time environment variables are configured before the application is built and cannot be changed at run-time. They are configured via .env files before building. Instead of using a single .env file, we prefer to define separate files under the env/ directory, and use a package called dotenv-cli before building`.

The dotenv-cli comes with the dotenv command that can be used to properly load the needed variables. We write our npm scripts with the following format:

package.json
"[build|dev]:<env name>": "dotenv -e env/<env name> npm run [build|dev]:<env name>"

See NPM Scripts for more

- +
Version: 3.1.x

Environment Variables

Honeycomb uses environment variables during build and run time to control the different configurations. Below we list the environment variables used by the app and indicate their properties via badges and text. Optional variables are labeled with the optional badge and mandatory variables are labeled with the default <default-value> badge with their default value specified. The buildtime badge indicates the variable is used during the build/compilation phase (npm build) while the runtime badge indicates the variable is used during the executable run (npm run dev).

Dev Mode Only​

  • ELECTRON_START_URL stringoptional: URL (e.g. http://localhost:3000) where the front end of the app is being hosted - also used in electron.js to indicate the app is running in dev mode.

Desktop Only​

  • EVENT_MARKER_PRODUCT_IDstringoptionalruntime: The product ID of the event marker (e.g. 0487). If not set, it will use the productID set in public/config/trigger.js if available, or attempt to connect using the com name.
  • EVENT_MARKER_COM_NAME stringoptionalruntime: The com name of the event marker (e.g. COM3). If not set, it will use the comName set in public/config/trigger.js. If the productID is set (not an empty string), this field will be ignored.
  • REACT_APP_VIDEObooleandefault falsebuildtime: whether the participant is being video recorded. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_EEGbooleandefault falsebuildtime: whether the event marker/EEG is available. This can be used when the task is running as a desktop app (electron).
  • REACT_APP_USE_PHOTODIODEbooleandefault falsebuildtime: whether the photodiode is in use. This can be used when the task is running as a desktop app (electron).

Desktop and Online​

  • REACT_APP_VOLUMEbooleandefault falsebuildtime: whether the participant is being asked to adjust volume. This can be used on both the desktop (electron) and online settings.
  • REACT_APP_PARTICIPANT_ID stringoptionalruntime: The default participant id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.
  • REACT_APP_STUDY_ID stringoptionalruntime: The default study id to show when authorizing a participant. If not set, user will need to enter the value in the provided input box.

Understanding Build-Time and Run-Time Variables​

  • runtime: Run-time environment variables allow for quick changes before running the task. They are convenient since they don't require building a whole different executable. For a Desktop Application, these are set at the system level and must be available at the time where the task runs. See this tutorial for OS specific instructions.. For a Firebase Application, these must be stored in the Firestore.

  • build time: Build-time environment variables are configured before the application is built and cannot be changed at run-time. They are configured via .env files before building. Instead of using a single .env file, we prefer to define separate files under the env/ directory, and use a package called dotenv-cli before building`.

The dotenv-cli comes with the dotenv command that can be used to properly load the needed variables. We write our npm scripts with the following format:

package.json
"[build|dev]:<env name>": "dotenv -e env/<env name> npm run [build|dev]:<env name>"

See NPM Scripts for more

+ \ No newline at end of file diff --git a/docs/3.1.x/event_triggers/index.html b/docs/3.1.x/event_triggers/index.html index 634be7ba..a5085ae7 100644 --- a/docs/3.1.x/event_triggers/index.html +++ b/docs/3.1.x/event_triggers/index.html @@ -4,13 +4,13 @@ Set up event triggers | Honeycomb - +
-
Version: 3.1.x

Set up event triggers

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:

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.

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 eventCode (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.

- +
Version: 3.1.x

Set up event triggers

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:

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.

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 eventCode (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.

+ \ No newline at end of file diff --git a/docs/3.1.x/firebase/index.html b/docs/3.1.x/firebase/index.html index 45beb274..4487c99f 100644 --- a/docs/3.1.x/firebase/index.html +++ b/docs/3.1.x/firebase/index.html @@ -4,14 +4,14 @@ Firebase | Honeycomb - +
Version: 3.1.x

Firebase

Honeycomb comes with methods and configurations to deploy tasks with Firebase. These tools make it possible to reach a wider audience by hosting your task online.

Setting up Firebase​

info

Please have your PI contact support@ccv.brown.edu to create a Firebase project for your Honeycomb task before beginning.

Adding Products​

First we'll configure Firebase Hosting and Cloud Firestore on your project.

  1. Log in to Firebase with your Google account on the Firebase console.

  2. Navigate to your project from the console

  3. Register a new web app to your project (Register your app)

    note

    We recommend giving your web app the same name as your task's repository

  4. Add Firestore Database to your project (Create a Cloud Firestore database)

    note

    Chose 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.

Installing the Command Line Interface​

The Firebase CLI can be 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!

Install the Firebase CLI
npm install -g firebase-tools
Login to Firebase
firebase login

A "command not found" error usually indicates firebase-tools has not been installed correctly

Connecting Your Firebase Project​

  1. Change the default project name of your task in .firebaserc
.firebaserc
{
  "projects": {
    "default": "<your project name>"
  }
}

  1. 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.

    2. Navigate to your project setting

      Firebase project settings

    3. Scroll down and copy the auto-generated values from the Firebase console to the corresponding variables in the .env.firebase file in the env folder of your Honeycomb task repo

      Firebase web credentials

      env/.env.firebase
      REACT_APP_FIREBASE="true"
      REACT_APP_apiKey=
      REACT_APP_authDomain=
      REACT_APP_projectId=
      REACT_APP_storageBucket=
      REACT_APP_messagingSenderId=
      REACT_APP_appId=

      Additional variables may be present in the console, they do not need to be copied.

  2. Deploy the default Firestore security rules

Deploy Firestore rules
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 for more information.

  1. Navigate to your Firestore Database in the console.
  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
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. Instructions splitting terminals in VSCode can be found here.

Run Honeycomb with Firebase Enabled
npm run dev:firebase
Start the Firebase Emulators
npm run firebase:emulators:start

Honeycomb is now running in the browser and connected to data on an emulated instance of Firestore. -That data can be viewed at 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 practices using GitHub Actions. Here we will connect 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.

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!
  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
  6. Enter y for the prompt "Set up automatic deployment to your site's live channel when a PR is merged?"
  7. Enter main for the prompt "What is the name of the GitHub branch associated with your site's live channel?"
  8. Enter y to overwrite the current workflow file

Firebase will update the files firebase-hosting-pull-request.yml and firebase-hosting-merge.yml inside the .github/workflows/ directory. Ensure the correct run script is present in both files.

Github actions created by firebase

Downloading Data​

Honeycomb ships with a script for downloading data from Firebase onto a computer. A local service account must be created in order to use it.

Setting up a Service Account​

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.

    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!

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.

Using the Download Script​

Honeycomb comes with a download script. It will programmatically access Firestore to download the experiment data you choose

Script Usage
npm run firebase:download -- <studyID> <participantID> [sessionNumber] [outputRoot]
  • studyID: The ID of a given study
  • participantID: The ID of a given participant on the studyID study
  • sessionNumber: Optional number to select which session to download, defaults to the most recent session
  • outputRoot: Optional path to the folder where data should be saved, defaults to the current folder

Running the script without sessionNumber list all of the available sessions. For example:

Found 3 sessions:
  0: 2022-07-26T22:04:55.544Z
  1: 2022-07-27T14:16:36.301Z
  2: 2022-07-27T19:56:26.229Z

sessionNumber​

Adding a sessionNumber will download that sessions data:

Download data for session 2022-07-26T22:04:55.544Z
npm run firebase:download -- <studyID> <participantID> 0 [outputRoot]

outputRoot​

Session data is stored in the current directory by default. The folders and file name are chosen to avoid naming collisions: ./participant_responses/<studyID>/<participantID>/<sessionID>.json

Adding an outputRoot will download that data in a custom location:

Download data for session 2022-07-26T22:04:55.544Z at /path/to/my/data
npm run firebase:download -- <studyID> <participantID> 0 /path/to/my/data

This will result in data saved to /path/to/my/data/participant_responses/<studyID>/<participantID>/<sessionID>.json

Further Reading​

The Firebase Documentation details its Emulator Suite in much greater detail.

Security Rules​

Honeycomb uses security rules to authenticate participants and studies for each task. By default participants must be registered to each study in order to complete the task.

Firestore rules are defined in the firestore.rules file in the home directory. Note the highlighted lines:

firestore.rules
rules_version = '2';
service cloud.firestore {
  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;
        // ...
      }
    }
}

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 manually make these changes from the Firestore console.

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.

- +That data can be viewed at 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 practices using GitHub Actions. Here we will connect 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.

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!
  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
  6. Enter y for the prompt "Set up automatic deployment to your site's live channel when a PR is merged?"
  7. Enter main for the prompt "What is the name of the GitHub branch associated with your site's live channel?"
  8. Enter y to overwrite the current workflow file

Firebase will update the files firebase-hosting-pull-request.yml and firebase-hosting-merge.yml inside the .github/workflows/ directory. Ensure the correct run script is present in both files.

Github actions created by firebase

Downloading Data​

Honeycomb ships with a script for downloading data from Firebase onto a computer. A local service account must be created in order to use it.

Setting up a Service Account​

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.

    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!

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.

Using the Download Script​

Honeycomb comes with a download script. It will programmatically access Firestore to download the experiment data you choose

Script Usage
npm run firebase:download -- <studyID> <participantID> [sessionNumber] [outputRoot]
  • studyID: The ID of a given study
  • participantID: The ID of a given participant on the studyID study
  • sessionNumber: Optional number to select which session to download, defaults to the most recent session
  • outputRoot: Optional path to the folder where data should be saved, defaults to the current folder

Running the script without sessionNumber list all of the available sessions. For example:

Found 3 sessions:
  0: 2022-07-26T22:04:55.544Z
  1: 2022-07-27T14:16:36.301Z
  2: 2022-07-27T19:56:26.229Z

sessionNumber​

Adding a sessionNumber will download that sessions data:

Download data for session 2022-07-26T22:04:55.544Z
npm run firebase:download -- <studyID> <participantID> 0 [outputRoot]

outputRoot​

Session data is stored in the current directory by default. The folders and file name are chosen to avoid naming collisions: ./participant_responses/<studyID>/<participantID>/<sessionID>.json

Adding an outputRoot will download that data in a custom location:

Download data for session 2022-07-26T22:04:55.544Z at /path/to/my/data
npm run firebase:download -- <studyID> <participantID> 0 /path/to/my/data

This will result in data saved to /path/to/my/data/participant_responses/<studyID>/<participantID>/<sessionID>.json

Further Reading​

The Firebase Documentation details its Emulator Suite in much greater detail.

Security Rules​

Honeycomb uses security rules to authenticate participants and studies for each task. By default participants must be registered to each study in order to complete the task.

Firestore rules are defined in the firestore.rules file in the home directory. Note the highlighted lines:

firestore.rules
rules_version = '2';
service cloud.firestore {
  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;
        // ...
      }
    }
}

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 manually make these changes from the Firestore console.

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.

+ \ No newline at end of file diff --git a/docs/3.1.x/index.html b/docs/3.1.x/index.html index 6c2b3acf..e4207cdb 100644 --- a/docs/3.1.x/index.html +++ b/docs/3.1.x/index.html @@ -4,13 +4,13 @@ Introduction | Honeycomb - +
-
Version: 3.1.x

Introduction

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.

Flexible deployment online and in the lab​

Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings.

Easy-to-install executables​

Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites.

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.

Cite this work​

If you use Honeycomb in your work, please cite

Provenza, N.R., Gelin, L.F.F., Mahaphanit, W., McGrath, M.C., Dastin-van Rijn, E.M., Fan, Y., Dhar, R., Frank, M.J., Restrepo, M.I., Goodman, W.K. and Borton, D.A., 2021. Honeycomb: a template for reproducible psychophysiological tasks for clinic, laboratory, and home use. Brazilian Journal of Psychiatry, 44, pp.147-155.

- +
Version: 3.1.x

Introduction

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.

Flexible deployment online and in the lab​

Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings.

Easy-to-install executables​

Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites.

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.

Cite this work​

If you use Honeycomb in your work, please cite

Provenza, N.R., Gelin, L.F.F., Mahaphanit, W., McGrath, M.C., Dastin-van Rijn, E.M., Fan, Y., Dhar, R., Frank, M.J., Restrepo, M.I., Goodman, W.K. and Borton, D.A., 2021. Honeycomb: a template for reproducible psychophysiological tasks for clinic, laboratory, and home use. Brazilian Journal of Psychiatry, 44, pp.147-155.

+ \ No newline at end of file diff --git a/docs/3.1.x/javascript/index.html b/docs/3.1.x/javascript/index.html index e3d907eb..330aae8a 100644 --- a/docs/3.1.x/javascript/index.html +++ b/docs/3.1.x/javascript/index.html @@ -4,13 +4,13 @@ JavaScript | Honeycomb - +
-
Version: 3.1.x

JavaScript

Learning JavaScript​

The Mozilla Developer Network Web Docs is the gold standard for programming on the web. The JavaScript page is an excellent place for further reading about JavaScript.

Interactive Tutorials​

Learn JavaScript is an excellent platform for beginning to learn the JavaScript programming language. It is full of interactive tutorials and small projects.

- +
Version: 3.1.x

JavaScript

Learning JavaScript​

The Mozilla Developer Network Web Docs is the gold standard for programming on the web. The JavaScript page is an excellent place for further reading about JavaScript.

Interactive Tutorials​

Learn JavaScript is an excellent platform for beginning to learn the JavaScript programming language. It is full of interactive tutorials and small projects.

+ \ No newline at end of file diff --git a/docs/3.1.x/npm_scripts/index.html b/docs/3.1.x/npm_scripts/index.html index 856bdd04..1039ad79 100644 --- a/docs/3.1.x/npm_scripts/index.html +++ b/docs/3.1.x/npm_scripts/index.html @@ -4,13 +4,13 @@ NPM Scripts | Honeycomb - +
-
Version: 3.1.x

NPM Scripts

Node package manager (NPM) ships with functionality to combine common shell commands into custom scripts. These scripts are defined in package.json. All of the commands needed to develop, build, and deploy Honeycomb are written out as scripts.

Additional scripts can be created if desired but we generally recommend against changing or deleting the scripts Honeycomb ships with.

Scripts are run using the following terminal command:

npm run <script>

Start​

  • electron starts an electron process with the built application.
  • electron-dev starts an electron process with the current code.
    • Note that the script waits for http://localhost:3000 to be available before launching the electron process.
  • start runs the app in development mode and does NOT open a browser. This makes working with electron easier as it creates its own browser for development.
  • start:browser runs the app in development mode and automatically opens a new browser tab. It uses your system's default browser. The page will reload if you make edits.

Firebase​

  • firebase:emulators:start starts the Firebase emulators with the data found in emulator_data/
  • firebase:emulators:save saves the current state of the Firebase emulators into emulator_data/
    caution

    There's no way to revert to what used to be in `emulator_data/ once it's overwritten!

  • firebase:download runs the firebase-download-script.js script, saving certain data in Firebase to your local machine.

Dev​

npm run dev runs the task in development mode on Electron. It executes npm start and npm run electron-dev concurrently.

Note that this is a base script that other scripts build on top of - you should always run one of the scripts below while developing your task.

  • dev:home executes npm run dev with equipment disabled (env/.env.home)
  • dev:home:video executes npm run dev with equipment disabled (env/.env.home) and video enabled (env/.env.video)
  • dev:clinic executes npm run dev with equipment enabled (env/.env.clinic)
  • dev:clinic:video executes npm run dev with equipment enabled (env/.env.clinic) and video enabled (env/.env.video)
  • dev:firebase executes npm run start:browser with Firebase enabled (env/.env.firebase)
    info

    firebase:emulators:start must be run in its own terminal in order for npm run firebase:dev to work

Build​

npm run build creates a production build of the app in the build/ folder. Note that this is a base script that other scripts build on top of - you should always run one of the scripts below while developing your task.

  • dev:home executes npm run build with equipment disabled (env/.env.home)
  • dev:home:video executes npm run build with equipment disabled (env/.env.home) and video enabled (env/.env.video)
  • dev:clinic executes npm run build with equipment enabled (env/.env.clinic)
  • dev:clinic:video executes npm run build with equipment enabled (env/.env.clinic) and video enabled (env/.env.video)
  • dev:firebase executes npm run build with Firebase enabled (env/.env.firebase)

Package​

npm run package:[platform] creates a standalone installer for the given platform using electron-forge. The installer is created in out/. Note that the scripts build the app before creating the installers

  • npm run package:windows
  • npm run package:linux
  • npm run package:mac
note

Packaging for windows on a non-windows machine requires mono and wine to be installed.

Miscellaneous​

  • commit runs commitizen in the console. It is useful for ensuring your Git commit messages are easy to follow.
  • lint uses Eslint to find problems in the code
  • format uses Eslint to find and fix problems in the code that it can automatically
  • test launches the test runner in the interactive watch mode. See running tests for more information.
- +
Version: 3.1.x

NPM Scripts

Node package manager (NPM) ships with functionality to combine common shell commands into custom scripts. These scripts are defined in package.json. All of the commands needed to develop, build, and deploy Honeycomb are written out as scripts.

Additional scripts can be created if desired but we generally recommend against changing or deleting the scripts Honeycomb ships with.

Scripts are run using the following terminal command:

npm run <script>

Start​

  • electron starts an electron process with the built application.
  • electron-dev starts an electron process with the current code.
    • Note that the script waits for http://localhost:3000 to be available before launching the electron process.
  • start runs the app in development mode and does NOT open a browser. This makes working with electron easier as it creates its own browser for development.
  • start:browser runs the app in development mode and automatically opens a new browser tab. It uses your system's default browser. The page will reload if you make edits.

Firebase​

  • firebase:emulators:start starts the Firebase emulators with the data found in emulator_data/
  • firebase:emulators:save saves the current state of the Firebase emulators into emulator_data/
    caution

    There's no way to revert to what used to be in `emulator_data/ once it's overwritten!

  • firebase:download runs the firebase-download-script.js script, saving certain data in Firebase to your local machine.

Dev​

npm run dev runs the task in development mode on Electron. It executes npm start and npm run electron-dev concurrently.

Note that this is a base script that other scripts build on top of - you should always run one of the scripts below while developing your task.

  • dev:home executes npm run dev with equipment disabled (env/.env.home)
  • dev:home:video executes npm run dev with equipment disabled (env/.env.home) and video enabled (env/.env.video)
  • dev:clinic executes npm run dev with equipment enabled (env/.env.clinic)
  • dev:clinic:video executes npm run dev with equipment enabled (env/.env.clinic) and video enabled (env/.env.video)
  • dev:firebase executes npm run start:browser with Firebase enabled (env/.env.firebase)
    info

    firebase:emulators:start must be run in its own terminal in order for npm run firebase:dev to work

Build​

npm run build creates a production build of the app in the build/ folder. Note that this is a base script that other scripts build on top of - you should always run one of the scripts below while developing your task.

  • dev:home executes npm run build with equipment disabled (env/.env.home)
  • dev:home:video executes npm run build with equipment disabled (env/.env.home) and video enabled (env/.env.video)
  • dev:clinic executes npm run build with equipment enabled (env/.env.clinic)
  • dev:clinic:video executes npm run build with equipment enabled (env/.env.clinic) and video enabled (env/.env.video)
  • dev:firebase executes npm run build with Firebase enabled (env/.env.firebase)

Package​

npm run package:[platform] creates a standalone installer for the given platform using electron-forge. The installer is created in out/. Note that the scripts build the app before creating the installers

  • npm run package:windows
  • npm run package:linux
  • npm run package:mac
note

Packaging for windows on a non-windows machine requires mono and wine to be installed.

Miscellaneous​

  • commit runs commitizen in the console. It is useful for ensuring your Git commit messages are easy to follow.
  • lint uses Eslint to find problems in the code
  • format uses Eslint to find and fix problems in the code that it can automatically
  • test launches the test runner in the interactive watch mode. See running tests for more information.
+ \ No newline at end of file diff --git a/docs/3.1.x/prerequisites/index.html b/docs/3.1.x/prerequisites/index.html index b937c538..82d1a3c4 100644 --- a/docs/3.1.x/prerequisites/index.html +++ b/docs/3.1.x/prerequisites/index.html @@ -4,13 +4,13 @@ Prerequisites | Honeycomb - +
-
Version: 3.1.x

Prerequisites

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 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​

Git​

git is an open-sourced version control system. It is used to track changes, revert mistakes, and enable peer code reviews!

GitHub Desktop is a GUI application used to interact with git and GitHub directly from your computer. It is not strictly needed but many folks find it easier to work with than using git directly from the command line.

Node Version Manager​

NodeJS is a cross-platform runtime environment for JavaScript code. Almost every web application today builds on top of node. Node Version Manager manages running multiple versions of node on the same system. The .nvmrc denotes the version of node that Honeycomb uses.

Python​

Python 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.

Oracle JDk​

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.

note

Honeycomb needs version 11 or later to run - the installers use version 18.

Visual Studio Code​

Visual Studio Code is a well-loved and easy to use integrated development environment (IDE). This is the program you'll use to write your task.

Mac-specific Installs​

X-Code​

XCode is a special IDE for the Apple platform. It comes with everything needed to compile desktop applications from an Apple computer. It must be installed from the terminal:

Installing XCode
  xcode-select --install

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 can be used to make sure it is on your Apple silicon system.

Windows-specific Install​

Visual Studio​

Visual Studio 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.

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)​

The links below will take you to each project installation page should you prefer to manually install the prerequisite software.

Manual Installation (Windows)​

The links below will take you to each project installation page should you prefer to manually install the prerequisite software.

Manual Installation (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 should get you up and running on any Linux distro new enough to support GLIBC_2.28.

Further Help​

If you are still having issues setting up your computer you can find the full instructions on the electron documentation for your specific OS.

- +
Version: 3.1.x

Prerequisites

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 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​

Git​

git is an open-sourced version control system. It is used to track changes, revert mistakes, and enable peer code reviews!

GitHub Desktop is a GUI application used to interact with git and GitHub directly from your computer. It is not strictly needed but many folks find it easier to work with than using git directly from the command line.

Node Version Manager​

NodeJS is a cross-platform runtime environment for JavaScript code. Almost every web application today builds on top of node. Node Version Manager manages running multiple versions of node on the same system. The .nvmrc denotes the version of node that Honeycomb uses.

Python​

Python 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.

Oracle JDk​

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.

note

Honeycomb needs version 11 or later to run - the installers use version 18.

Visual Studio Code​

Visual Studio Code is a well-loved and easy to use integrated development environment (IDE). This is the program you'll use to write your task.

Mac-specific Installs​

X-Code​

XCode is a special IDE for the Apple platform. It comes with everything needed to compile desktop applications from an Apple computer. It must be installed from the terminal:

Installing XCode
  xcode-select --install

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 can be used to make sure it is on your Apple silicon system.

Windows-specific Install​

Visual Studio​

Visual Studio 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.

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)​

The links below will take you to each project installation page should you prefer to manually install the prerequisite software.

Manual Installation (Windows)​

The links below will take you to each project installation page should you prefer to manually install the prerequisite software.

Manual Installation (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 should get you up and running on any Linux distro new enough to support GLIBC_2.28.

Further Help​

If you are still having issues setting up your computer you can find the full instructions on the electron documentation for your specific OS.

+ \ No newline at end of file diff --git a/docs/3.1.x/project_organization/index.html b/docs/3.1.x/project_organization/index.html index 8d5fe078..f12fe921 100644 --- a/docs/3.1.x/project_organization/index.html +++ b/docs/3.1.x/project_organization/index.html @@ -4,13 +4,13 @@ Project Organization | Honeycomb - +
-
Version: 3.1.x

Project Organization

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.

Almost all of the changes needed for custom JsPsych tasks will be done in the src/ folder.

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.

build/​

The build scripts automatically create a build folder at the root of the repository and update it on subsequent builds. build/ should be left alone!

caution

The build folder is in Honeycomb's .gitignore and as such 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 to use the data - emulator_data/ should be left alone!

env/​

This folder contains different .env files used to pass environment variables (secrets and/or settings) into Honeycomb. Honeycomb starts with presets for common use cases and is explained in greater detail in the Environment Variables section.

node_modules/​

danger

node_modules/ is written to when running npm install and should never be manually edited.

psiturkit/​

The file psiturk-it inside psiturkit/ is a bash script used to instal PsiTurk locally - see Deploy Online for more information. psiturkit/ should be left alone!

public/​

The public directory contains files that are used as assets in the built app.

  • favicon.ico is the small icon you can see in the browser tab.
  • index.html is the entry point of the website
    • Changing <title>Honeycomb</title> will update the name you can see in the browser tab.
  • electron.js contains all of the code related to the electron app.

lib/​

The lib/ directory contains the files PsiTurk needs to run. Note that index.html references these files inside the <script> tags

config/​

The config directory contains the config files needed for the electron app. This includes the event-marker details and event codes. version.json keeps track of the current git commit, which Honeycomb uses to keep track of the version of your task used for a given experiment.

src/​

This folder contains the source code for the Honeycomb application.

__tests__/​

Automated test cases should be created in this folder.

assets/​

Any assets used by your task should be stored here, such as images and videos.

note

These assets are not statically generated like the root assets/ folder. Only assets needed by your task should go here.

components/​

The React components that make up Honeycomb are located here.

  • App.jsx initializes and maintains the state of the application. It is also where communication is set up between the electron and psiturk processes.
  • Error.jsx displays a small error message. It is rendered when the App.jsx detects an issue in state.
  • JsPsychExperiment.jsx initializes the JsPsych experiment
  • Login.jsx handles user authentication based on the environment variables passed to Honeycomb

config/​

Each file in the config directory contains settings for a different part of the task.

  • main.js contains the global settings (e.g. whether Honeycomb is running online or in the clinic) passed from env variables and logic for loading the appropriate language file.
  • trigger.js for equipment-related settings (e.g. event markers). It uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.

Other config files can be used to add settings for specific blocks or sub-sections of the experiment.

language/​

Any language that is displayed in the experiment should be stored in this folder. Usage of language json files allows for easy internationalization of the task (e.g. english and spanish) and mturk-specific language. Common phrases can be written once in a language file and re-used throughout the task.

lib/​

The utility functions and markup used in the tasks are located here. This allows for functions and html to be re-used wherever needed.

markup files contain HTML templates used throughout the task. Typically this will be a function that takes in some parameters and then returns a string with html.

tip

Be sure to look through utils.js for functions you might be able to use in your task

timelines/​

A timeline is a collection of trials that JsPsych displays in the given order. Timelines can contain timelines themselves; you may want to break this nesting into multiple files in this folder.

main.js contains the root timeline which App.jsx loads into the <JsPsychExperiment> component.

trials/​

A trial is the base unit of a JsPsych experiment. Each trial should be its own file within this folder - the files in src/timelines/ will combine these trials into the full experiment.

firebase.js​

firebase.js contains all of the logic for creating, reading, and updating data in Firebase. You should not have to update this file.

index.css​

index.css contains all of the styling in the application. Classes can be defined here and referenced in your markup.

index.js​

index.js is the entry point for React in our application. Note that the id 'root' corresponds with a tag in public/index.html:

<div id="root"></div>

Other Files​

  • .github/workflows/ contains .yaml files used to build Honeycomb on a pull request (build.yaml) and create task executables either in a single instance (package.yaml) or for a full release (release.yaml)

  • package.json contains metadata about your project, a list of the dependencies needed for the project, and scripts to run tasks related to your task. The Quick Start lists which metadata should be changed.

  • download-response-data.js is the script used to download data stored in Firestore to your local machine.

  • version.js is the script used to keep track of which version of the task a given experiment is using

danger

package-lock.json is written to when running npm install and should never be manually edited.

Git Files​

  • .gitignore lists the folders and files that should be excluded from Git. Make sure all of your secrets and tokens are listed here!

Eslint Files​

  • .eslintrc.js contains the Eslint settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.
  • .eslintignore lists the folders and files that eslint shouldn't touch, similar to .gitignore.

Prettier Files​

.prettierrc.js contains the Prettier settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.

Firebase Files​

  • .firebaserc contains the name of the project Firebase should connect to. Be sure to update the default project to the one you created!
  • firebase.json contains the Firebase settings for Honeycomb. It should be left alone!
  • firestore.indexes.json contains the Firestore index settings for Honeycomb. It should be left alone!
  • firestore.rules contains the Firestore rules for creating/editing data. It should be left alone!
- +
Version: 3.1.x

Project Organization

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.

Almost all of the changes needed for custom JsPsych tasks will be done in the src/ folder.

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.

build/​

The build scripts automatically create a build folder at the root of the repository and update it on subsequent builds. build/ should be left alone!

caution

The build folder is in Honeycomb's .gitignore and as such 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 to use the data - emulator_data/ should be left alone!

env/​

This folder contains different .env files used to pass environment variables (secrets and/or settings) into Honeycomb. Honeycomb starts with presets for common use cases and is explained in greater detail in the Environment Variables section.

node_modules/​

danger

node_modules/ is written to when running npm install and should never be manually edited.

psiturkit/​

The file psiturk-it inside psiturkit/ is a bash script used to instal PsiTurk locally - see Deploy Online for more information. psiturkit/ should be left alone!

public/​

The public directory contains files that are used as assets in the built app.

  • favicon.ico is the small icon you can see in the browser tab.
  • index.html is the entry point of the website
    • Changing <title>Honeycomb</title> will update the name you can see in the browser tab.
  • electron.js contains all of the code related to the electron app.

lib/​

The lib/ directory contains the files PsiTurk needs to run. Note that index.html references these files inside the <script> tags

config/​

The config directory contains the config files needed for the electron app. This includes the event-marker details and event codes. version.json keeps track of the current git commit, which Honeycomb uses to keep track of the version of your task used for a given experiment.

src/​

This folder contains the source code for the Honeycomb application.

__tests__/​

Automated test cases should be created in this folder.

assets/​

Any assets used by your task should be stored here, such as images and videos.

note

These assets are not statically generated like the root assets/ folder. Only assets needed by your task should go here.

components/​

The React components that make up Honeycomb are located here.

  • App.jsx initializes and maintains the state of the application. It is also where communication is set up between the electron and psiturk processes.
  • Error.jsx displays a small error message. It is rendered when the App.jsx detects an issue in state.
  • JsPsychExperiment.jsx initializes the JsPsych experiment
  • Login.jsx handles user authentication based on the environment variables passed to Honeycomb

config/​

Each file in the config directory contains settings for a different part of the task.

  • main.js contains the global settings (e.g. whether Honeycomb is running online or in the clinic) passed from env variables and logic for loading the appropriate language file.
  • trigger.js for equipment-related settings (e.g. event markers). It uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.

Other config files can be used to add settings for specific blocks or sub-sections of the experiment.

language/​

Any language that is displayed in the experiment should be stored in this folder. Usage of language json files allows for easy internationalization of the task (e.g. english and spanish) and mturk-specific language. Common phrases can be written once in a language file and re-used throughout the task.

lib/​

The utility functions and markup used in the tasks are located here. This allows for functions and html to be re-used wherever needed.

markup files contain HTML templates used throughout the task. Typically this will be a function that takes in some parameters and then returns a string with html.

tip

Be sure to look through utils.js for functions you might be able to use in your task

timelines/​

A timeline is a collection of trials that JsPsych displays in the given order. Timelines can contain timelines themselves; you may want to break this nesting into multiple files in this folder.

main.js contains the root timeline which App.jsx loads into the <JsPsychExperiment> component.

trials/​

A trial is the base unit of a JsPsych experiment. Each trial should be its own file within this folder - the files in src/timelines/ will combine these trials into the full experiment.

firebase.js​

firebase.js contains all of the logic for creating, reading, and updating data in Firebase. You should not have to update this file.

index.css​

index.css contains all of the styling in the application. Classes can be defined here and referenced in your markup.

index.js​

index.js is the entry point for React in our application. Note that the id 'root' corresponds with a tag in public/index.html:

<div id="root"></div>

Other Files​

  • .github/workflows/ contains .yaml files used to build Honeycomb on a pull request (build.yaml) and create task executables either in a single instance (package.yaml) or for a full release (release.yaml)

  • package.json contains metadata about your project, a list of the dependencies needed for the project, and scripts to run tasks related to your task. The Quick Start lists which metadata should be changed.

  • download-response-data.js is the script used to download data stored in Firestore to your local machine.

  • version.js is the script used to keep track of which version of the task a given experiment is using

danger

package-lock.json is written to when running npm install and should never be manually edited.

Git Files​

  • .gitignore lists the folders and files that should be excluded from Git. Make sure all of your secrets and tokens are listed here!

Eslint Files​

  • .eslintrc.js contains the Eslint settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.
  • .eslintignore lists the folders and files that eslint shouldn't touch, similar to .gitignore.

Prettier Files​

.prettierrc.js contains the Prettier settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.

Firebase Files​

  • .firebaserc contains the name of the project Firebase should connect to. Be sure to update the default project to the one you created!
  • firebase.json contains the Firebase settings for Honeycomb. It should be left alone!
  • firestore.indexes.json contains the Firestore index settings for Honeycomb. It should be left alone!
  • firestore.rules contains the Firestore rules for creating/editing data. It should be left alone!
+ \ No newline at end of file diff --git a/docs/3.1.x/quick_start/index.html b/docs/3.1.x/quick_start/index.html index d2431b08..2f500759 100644 --- a/docs/3.1.x/quick_start/index.html +++ b/docs/3.1.x/quick_start/index.html @@ -4,15 +4,15 @@ Quick Start | Honeycomb - +
Version: 3.1.x

Quick Start

Creating Your Task Repository​

The Honeycomb repository is a template and serves as the starting point for all tasks. Creating your repository from the template starts your project with the same directory structure and files as an existing repository.

  1. Go to the Honeycomb repository

  2. Click on Use this template and select Create a new repository. Use this template

  3. Enter the owner, name, and description of your repository and click on Create repository from template. -Create repository

    note

    We recommend creating a public repository and leaving Include all branches unchecked

  4. Ensure the repositories workflow permissions are set to "Read and write permissions"

    Settings -> Actions -> General -> Workflow permissions

    GitHub workflow permissions settings

Additional details about template repositories can be found on the Github Docs.

Cloning the Repository​

With the repository now setup it can be cloned onto your computer.

  1. Navigate to the repository on GitHub.

  2. Click the Code button and copy the URL

    GitHub clone repo button

  3. Open a terminal and navigate to where you want the cloned directory

Terminal.app
cd 'path/to/directory'
  1. Clone the repo with the following command
Paste the URL you copied earlier
 git clone https://github.com/<YOUR-USERNAME>/<YOUR-REPOSITORY>
note

Git can be downloaded here if it is not already on your system.

Additional details and alternative methods for cloning a repository can be found on the Github Docs.

Installing Prerequisites​

All of the needed programs for Honeycomb must be installed before we can develop our task. We will use a package manager to automatically install them.

See Prerequisites for more information about these programs.

Initial Install​

The most commonly used package manager on macOS is Homebrew.

  1. Paste the following command in a macOS Terminal and follow the prompts to install Homebrew.

    /bin/bash -c '$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)'

  2. Paste the following command and follow the prompts to install the listed programs:

    brew bundle

  3. Install Xcode (not available on Homebrew)

    xcode-select --install
note

If you are running into issues after installing the packages please restart your terminal and/or reboot your computer. This should resolve most issues.

Setting Up Node​

NVM (Node Version Manager) is a tool for installing and using multiple versions on node on your computer. It must first be installed:

  1. Install NVM

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.4/install.sh | bash

  2. Copy the version number listed in .nvmrc. The version may be different than the screenshot below.

    .nvmrc file

  3. Install that version.

    nvm install [version]

  4. Use the needed version. This will automatically check the version listed in the .nvmrc file.

    nvm use

  5. Set the current version as your default

    nvm alias default node
note

You can skip step 4 if you've already set a default node version in a different project.

Install Dependencies​

There are many node packages used by Honeycomb that also need to be installed. Node (installed in the previous step) comes with its own package manager to install, update, and maintain these dependencies throughout the development lifecycle.

Install Honeycomb's dependencies
npm install

Certain dependencies are best installed globally within node. These tools will be available from the command line anywhere on your system.

Install Honeycomb's global dependencies
npm install -g electron firebase-tools dotenv-cli

Run the Task in Development Mode​

Running the task in development mode causes it to hot-reload whenever changes are made to the app. This is how you'll run the project while building your task.

Run the task in dev mode
npm run dev

This script launches an electron window with the task and inspector open.

You can quit the task in the middle of development if needed:

⌘ + Q

Saving data​

Data is saved throughout the task, even when running in development mode. The location of the task is logged at the beginning of the task wherever you ran npm run dev.

Note how the data is organized by study and participant. Every run through of the task will save the data somewhere within this folder!

Edit the Task​

Now that the task is up and running we can make our first changes to the code! We'll edit the package.json file to reflect your information.

  1. Create a new branch

    git checkout -b <branch-name>

  2. Open package.json and edit it to reflect your app:

    1. name is your task's name, generally this is the name of our repository
    2. description should be rewritten to better match your task
    3. author is your lab (or PIs) name, email, and website
    4. version should be reset to 1.0.0
    5. repository is the link the GitHub repository you created earlier.

  3. Save your changes and commit them to git:

    git commit -m "Commit message goes here!"

  4. Create a pull request to bring your changes into the main branch

Next Steps​

Honeycomb tasks can be configured to run as a web app in Firebase, or as desktop application via electron. The desktop application can receive port signals from EEG, cameras, foot pedals, and more.

The Firebase page explains how to set up your task with Firebase.

To learn more about how to configure your task for these different scenarios, see Environment Variables.

The NPM Scripts page lists every script you can run and which environment they use.

- +Create repository

note

We recommend creating a public repository and leaving Include all branches unchecked

  • Ensure the repositories workflow permissions are set to "Read and write permissions"

    Settings -> Actions -> General -> Workflow permissions

    GitHub workflow permissions settings

    • Additional details about template repositories can be found on the Github Docs.

    Cloning the Repository​

    With the repository now setup it can be cloned onto your computer.

    1. Navigate to the repository on GitHub.

    2. Click the Code button and copy the URL

      GitHub clone repo button

    3. Open a terminal and navigate to where you want the cloned directory

    Terminal.app
    cd 'path/to/directory'
    1. Clone the repo with the following command
    Paste the URL you copied earlier
     git clone https://github.com/<YOUR-USERNAME>/<YOUR-REPOSITORY>
    note

    Git can be downloaded here if it is not already on your system.

    Additional details and alternative methods for cloning a repository can be found on the Github Docs.

    Installing Prerequisites​

    All of the needed programs for Honeycomb must be installed before we can develop our task. We will use a package manager to automatically install them.

    See Prerequisites for more information about these programs.

    Initial Install​

    The most commonly used package manager on macOS is Homebrew.

    1. Paste the following command in a macOS Terminal and follow the prompts to install Homebrew.

      /bin/bash -c '$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)'

    2. Paste the following command and follow the prompts to install the listed programs:

      brew bundle

    3. Install Xcode (not available on Homebrew)

      xcode-select --install
    note

    If you are running into issues after installing the packages please restart your terminal and/or reboot your computer. This should resolve most issues.

    Setting Up Node​

    NVM (Node Version Manager) is a tool for installing and using multiple versions on node on your computer. It must first be installed:

    1. Install NVM

      curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.4/install.sh | bash

    2. Copy the version number listed in .nvmrc. The version may be different than the screenshot below.

      .nvmrc file

    3. Install that version.

      nvm install [version]

    4. Use the needed version. This will automatically check the version listed in the .nvmrc file.

      nvm use

    5. Set the current version as your default

      nvm alias default node
    note

    You can skip step 4 if you've already set a default node version in a different project.

    Install Dependencies​

    There are many node packages used by Honeycomb that also need to be installed. Node (installed in the previous step) comes with its own package manager to install, update, and maintain these dependencies throughout the development lifecycle.

    Install Honeycomb's dependencies
    npm install

    Certain dependencies are best installed globally within node. These tools will be available from the command line anywhere on your system.

    Install Honeycomb's global dependencies
    npm install -g electron firebase-tools dotenv-cli

    Run the Task in Development Mode​

    Running the task in development mode causes it to hot-reload whenever changes are made to the app. This is how you'll run the project while building your task.

    Run the task in dev mode
    npm run dev

    This script launches an electron window with the task and inspector open.

    You can quit the task in the middle of development if needed:

    ⌘ + Q

    Saving data​

    Data is saved throughout the task, even when running in development mode. The location of the task is logged at the beginning of the task wherever you ran npm run dev.

    Note how the data is organized by study and participant. Every run through of the task will save the data somewhere within this folder!

    Edit the Task​

    Now that the task is up and running we can make our first changes to the code! We'll edit the package.json file to reflect your information.

    1. Create a new branch

      git checkout -b <branch-name>

    2. Open package.json and edit it to reflect your app:

      1. name is your task's name, generally this is the name of our repository
      2. description should be rewritten to better match your task
      3. author is your lab (or PIs) name, email, and website
      4. version should be reset to 1.0.0
      5. repository is the link the GitHub repository you created earlier.

    3. Save your changes and commit them to git:

      git commit -m "Commit message goes here!"

    4. Create a pull request to bring your changes into the main branch

    Next Steps​

    Honeycomb tasks can be configured to run as a web app in Firebase, or as desktop application via electron. The desktop application can receive port signals from EEG, cameras, foot pedals, and more.

    The Firebase page explains how to set up your task with Firebase.

    To learn more about how to configure your task for these different scenarios, see Environment Variables.

    The NPM Scripts page lists every script you can run and which environment they use.

    + \ No newline at end of file diff --git a/docs/3.1.x/troubleshooting/index.html b/docs/3.1.x/troubleshooting/index.html index 85b05df3..ae964c33 100644 --- a/docs/3.1.x/troubleshooting/index.html +++ b/docs/3.1.x/troubleshooting/index.html @@ -4,13 +4,13 @@ Troubleshooting | Honeycomb - +
    -
    Version: 3.1.x

    Troubleshooting

    Inspecting Errors​

    When developing Electron apps there are two processes: main, and renderer. In this case main corresponds to electron-starter.js and its console is wherever you called npm run dev or electron . from. renderer corresponds to the React App - this is everything else. The React app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running npm run dev, it should open by default.

    In case you want to find out where the error is coming from when running the app locally:

    • Try reviewing logs in the terminal
    • Inspect element in your browser by opening your developer tools. For instance, in Chrome, this can be done via the menu View -> Developer or right-clicking and pressing inspect.

    Testing in Linux​

    When running npm test on Linux, you might get an error that mentions ENOSPC. This is because the test runner creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.

    This is a "known issue" with some test runners on Linux, as in discussions here and here.

    One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):

    • Command that initially fails with ENOSPC: npm test
    • Check the configured limit on "watchers": cat /proc/sys/fs/inotify/max_user_watches
    • Edit the relevant Linux config file: sudo vim /etc/sysctl.conf
    • Add a line at the end of the config file: fs.inotify.max_user_watches=100000
    • Save, exit, and reload the config file: sudo sysctl -p
    • Check that the limit has changed: cat /proc/sys/fs/inotify/max_user_watches
    • Retry the initial command, which should now succeed: npm test

    Common issues​

    Installing Dependencies​

    Brew Not Available​

    If you run into issues installing Homebrew in step 1 of Installing Prerequisites it may be because Homebrew is not available on your shell. Older versions of macOS (under 10.14) do not do this automatically.

    Run the following command to manually add the Homebrew installation location to your PATH so it is available in your shell.

    echo 'PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile
    note

    If you're using zsh, also add to your ~/.zshrc file.

    NPM Errors​

    Try deleting your node_modules folder and the package-lock.json then running npm install then npm run rebuild. This should fix most issues.

    - +
    Version: 3.1.x

    Troubleshooting

    Inspecting Errors​

    When developing Electron apps there are two processes: main, and renderer. In this case main corresponds to electron-starter.js and its console is wherever you called npm run dev or electron . from. renderer corresponds to the React App - this is everything else. The React app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running npm run dev, it should open by default.

    In case you want to find out where the error is coming from when running the app locally:

    • Try reviewing logs in the terminal
    • Inspect element in your browser by opening your developer tools. For instance, in Chrome, this can be done via the menu View -> Developer or right-clicking and pressing inspect.

    Testing in Linux​

    When running npm test on Linux, you might get an error that mentions ENOSPC. This is because the test runner creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.

    This is a "known issue" with some test runners on Linux, as in discussions here and here.

    One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):

    • Command that initially fails with ENOSPC: npm test
    • Check the configured limit on "watchers": cat /proc/sys/fs/inotify/max_user_watches
    • Edit the relevant Linux config file: sudo vim /etc/sysctl.conf
    • Add a line at the end of the config file: fs.inotify.max_user_watches=100000
    • Save, exit, and reload the config file: sudo sysctl -p
    • Check that the limit has changed: cat /proc/sys/fs/inotify/max_user_watches
    • Retry the initial command, which should now succeed: npm test

    Common issues​

    Installing Dependencies​

    Brew Not Available​

    If you run into issues installing Homebrew in step 1 of Installing Prerequisites it may be because Homebrew is not available on your shell. Older versions of macOS (under 10.14) do not do this automatically.

    Run the following command to manually add the Homebrew installation location to your PATH so it is available in your shell.

    echo 'PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile
    note

    If you're using zsh, also add to your ~/.zshrc file.

    NPM Errors​

    Try deleting your node_modules folder and the package-lock.json then running npm install then npm run rebuild. This should fix most issues.

    + \ No newline at end of file diff --git a/docs/3.1.x/variants/index.html b/docs/3.1.x/variants/index.html index 529ffc54..e5c8f16a 100644 --- a/docs/3.1.x/variants/index.html +++ b/docs/3.1.x/variants/index.html @@ -4,13 +4,13 @@ Variants | Honeycomb - +
    -
    Version: 3.1.x

    Variants

    Variant-specific Executables​

    In order to create multiple variants of a task that can be co-installed, it is necessary to add new scripts to the package.json file in addition to creating the necessary environment variables for configuration. Each variant must have a unique, lowercase name. Optionally, a unique icon can be used for each variant by saving multiple icons to the icons directories with the same names as the variants. Example scripts for Windows, Mac, and Linux are shown below.

    Windows:

    "package:windows:<task_name>": "electron-packager . <task_name> --platform win32 --arch x64 --icon ./assets/icons/win/<task_name> --out dist/ --overwrite --asar"
    "postpackage:windows:<task_name>": "electron-installer-windows --src dist/<task_name>-win32-x64/ --dest dist/installers/ --overwrite --homepage https://ccv.brown.edu/ --name <task_name> --exe <task_name>.exe --productName <task_name>"

    Mac:

    "package:mac:,<task_name>": "electron-packager . <task_name> --platform darwin --arch x64 --out dist/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"
    "installer:mac:<task_name>": "electron-installer-dmg ./dist/<task_name>-darwin-x64/<task_name>.app <task_name>-${npm_package_version} --out ./dist/installers/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"

    Linux:

    "package:linux:<task_name>": "electron-packager . <task_name> --platform linux --arch x64 --icon ./assets/icons/mac/<task_name> --out dist/ --overwrite"
    "postpackage:linux:<task_name>": "electron-installer-debian --src dist/<task_name>-linux-x64/ --dest dist/installers/ --arch x64 --overwrite --name <task_name> --productName <task_name> --genericName <task_name> --bin <task_name>"

    Variant-specific Workflows​

    In order to use Github workflows to build and upload executables for each variant, the build.yaml, package.yaml, and release.yaml files must be modified as well. For all three files, a new row should be added to the matrix variable as follows:

    variant: [<comma_separated_list_of_variant_names>]

    Add the following before npm build in the steps section of build.yaml, package.yaml, and release.yaml:

    - name: Load .env file for variant
      uses: xom9ikk/dotenv@v1.0.2
      with:
        path: ./env
        mode: ${{matrix.variant}}

    In package.yaml and release.yaml, replace the # Build electron app package installers section with the following code:

    - name: package electron - windows
      if: startsWith(matrix.os, 'windows')
      run: npm run package:windows:${{ matrix.variant }}
    - name: package electron - linux
      if: startsWith(matrix.os, 'ubuntu')
      run: npm run package:linux:${{ matrix.variant }}
    - name: package electron - mac
      if: startsWith(matrix.os, 'mac')
      run: npm run package:mac:${{ matrix.variant }}
    - name: npm rebuild - mac
      if: startsWith(matrix.os, 'mac')
      run: npm rebuild
    - name: Mac installer
      if: startsWith(matrix.os, 'mac')
      run: npm run installer:mac:${{ matrix.variant }}

    Replace the # Upload installers to github action section in package.yaml with the following code:

    - name: upload win-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'windows')
        with:
          name: ${{ format('win-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
      - name: upload mac-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'mac')
        with:
          name: ${{ format('mac-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
      - name: upload linux-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'ubuntu')
        with:
          name: ${{ format('linux-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb

    Replace the # Upload installers to github release section in release.yaml with the following code:

    - name: Upload app to release - windows
      if: startsWith(matrix.os, 'windows')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
        asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}-setup.exe
        tag: ${{ github.ref }}
    - name: Upload app to release - linux
      if: startsWith(matrix.os, 'ubuntu')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb
        asset_name: ${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_${{ matrix.setting }}_x64.deb
        tag: ${{ github.ref }}
    - name: Upload app to release - mac
      if: startsWith(matrix.os, 'mac')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
        asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}.dmg
        tag: ${{ github.ref }}
    - +
    Version: 3.1.x

    Variants

    Variant-specific Executables​

    In order to create multiple variants of a task that can be co-installed, it is necessary to add new scripts to the package.json file in addition to creating the necessary environment variables for configuration. Each variant must have a unique, lowercase name. Optionally, a unique icon can be used for each variant by saving multiple icons to the icons directories with the same names as the variants. Example scripts for Windows, Mac, and Linux are shown below.

    Windows:

    "package:windows:<task_name>": "electron-packager . <task_name> --platform win32 --arch x64 --icon ./assets/icons/win/<task_name> --out dist/ --overwrite --asar"
    "postpackage:windows:<task_name>": "electron-installer-windows --src dist/<task_name>-win32-x64/ --dest dist/installers/ --overwrite --homepage https://ccv.brown.edu/ --name <task_name> --exe <task_name>.exe --productName <task_name>"

    Mac:

    "package:mac:,<task_name>": "electron-packager . <task_name> --platform darwin --arch x64 --out dist/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"
    "installer:mac:<task_name>": "electron-installer-dmg ./dist/<task_name>-darwin-x64/<task_name>.app <task_name>-${npm_package_version} --out ./dist/installers/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"

    Linux:

    "package:linux:<task_name>": "electron-packager . <task_name> --platform linux --arch x64 --icon ./assets/icons/mac/<task_name> --out dist/ --overwrite"
    "postpackage:linux:<task_name>": "electron-installer-debian --src dist/<task_name>-linux-x64/ --dest dist/installers/ --arch x64 --overwrite --name <task_name> --productName <task_name> --genericName <task_name> --bin <task_name>"

    Variant-specific Workflows​

    In order to use Github workflows to build and upload executables for each variant, the build.yaml, package.yaml, and release.yaml files must be modified as well. For all three files, a new row should be added to the matrix variable as follows:

    variant: [<comma_separated_list_of_variant_names>]

    Add the following before npm build in the steps section of build.yaml, package.yaml, and release.yaml:

    - name: Load .env file for variant
      uses: xom9ikk/dotenv@v1.0.2
      with:
        path: ./env
        mode: ${{matrix.variant}}

    In package.yaml and release.yaml, replace the # Build electron app package installers section with the following code:

    - name: package electron - windows
      if: startsWith(matrix.os, 'windows')
      run: npm run package:windows:${{ matrix.variant }}
    - name: package electron - linux
      if: startsWith(matrix.os, 'ubuntu')
      run: npm run package:linux:${{ matrix.variant }}
    - name: package electron - mac
      if: startsWith(matrix.os, 'mac')
      run: npm run package:mac:${{ matrix.variant }}
    - name: npm rebuild - mac
      if: startsWith(matrix.os, 'mac')
      run: npm rebuild
    - name: Mac installer
      if: startsWith(matrix.os, 'mac')
      run: npm run installer:mac:${{ matrix.variant }}

    Replace the # Upload installers to github action section in package.yaml with the following code:

    - name: upload win-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'windows')
        with:
          name: ${{ format('win-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
      - name: upload mac-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'mac')
        with:
          name: ${{ format('mac-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
      - name: upload linux-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'ubuntu')
        with:
          name: ${{ format('linux-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb

    Replace the # Upload installers to github release section in release.yaml with the following code:

    - name: Upload app to release - windows
      if: startsWith(matrix.os, 'windows')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
        asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}-setup.exe
        tag: ${{ github.ref }}
    - name: Upload app to release - linux
      if: startsWith(matrix.os, 'ubuntu')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb
        asset_name: ${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_${{ matrix.setting }}_x64.deb
        tag: ${{ github.ref }}
    - name: Upload app to release - mac
      if: startsWith(matrix.os, 'mac')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
        asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}.dmg
        tag: ${{ github.ref }}
    + \ No newline at end of file diff --git a/docs/3.1.x/version_control/index.html b/docs/3.1.x/version_control/index.html index feb79dd9..5e145adc 100644 --- a/docs/3.1.x/version_control/index.html +++ b/docs/3.1.x/version_control/index.html @@ -4,13 +4,13 @@ Version Control | Honeycomb - +
    -
    Version: 3.1.x

    Version Control

    Git Overview​

    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.

    Git basics

    If you would like to make any changes to current repository, it is always good to start with creating a feature branch, where you can save all the changes.

    Example branch

    Create a Pull Request​

    Pull requests are useful before you merge your branch with the main branch. You can request a review from your colleagues and check for any conflicts with the main branch. After you pushed all the changes to your branch, you can go to the original GitHub repository and click on the pull request.

    git pr

    git pr info

    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:

      git remote add honeycomb https://github.com/brown-ccv/honeycomb.git

    2. Fetch the changes made to Honeycomb

      git fetch --all

    3. Merge the current Honeycomb repo

      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

    This flow is sometimes referred to as Feature Branch Workflow

    Basic Workflow​

    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.

    Comment styles​

    We encourage using Commitizen, 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​

    CommandBrief
    git add <files>add a file to next commit (stage)
    git commit -m <message>commit staged files
    git pushupload staged commit to repo
    git pullget 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
    # create branch with your feature
    git checkout -b feature_name
    # check the status of your repositoey
    git status
    # commit file contents to the local repository
    git commit -m "My feature is ready"

    # specific message
    # push file contents to the remote (i.e. cloud) repository
    git push origin feature_name

    Alternative options​

    VS Code​

    Most IDEs have some built in tools for working with Git and VS Code is no exception. Check out this overview of source control in VS Code!

    GitHub Desktop​

    GitHub Desktop is a GUI application for working with git. It is one of the programs installed as a prerequisite of Honeycomb. Check out this overview of source control in GitHub Desktop!

    - +
    Version: 3.1.x

    Version Control

    Git Overview​

    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.

    Git basics

    If you would like to make any changes to current repository, it is always good to start with creating a feature branch, where you can save all the changes.

    Example branch

    Create a Pull Request​

    Pull requests are useful before you merge your branch with the main branch. You can request a review from your colleagues and check for any conflicts with the main branch. After you pushed all the changes to your branch, you can go to the original GitHub repository and click on the pull request.

    git pr

    git pr info

    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:

      git remote add honeycomb https://github.com/brown-ccv/honeycomb.git

    2. Fetch the changes made to Honeycomb

      git fetch --all

    3. Merge the current Honeycomb repo

      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

    This flow is sometimes referred to as Feature Branch Workflow

    Basic Workflow​

    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.

    Comment styles​

    We encourage using Commitizen, 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​

    CommandBrief
    git add <files>add a file to next commit (stage)
    git commit -m <message>commit staged files
    git pushupload staged commit to repo
    git pullget 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
    # create branch with your feature
    git checkout -b feature_name
    # check the status of your repositoey
    git status
    # commit file contents to the local repository
    git commit -m "My feature is ready"

    # specific message
    # push file contents to the remote (i.e. cloud) repository
    git push origin feature_name

    Alternative options​

    VS Code​

    Most IDEs have some built in tools for working with Git and VS Code is no exception. Check out this overview of source control in VS Code!

    GitHub Desktop​

    GitHub Desktop is a GUI application for working with git. It is one of the programs installed as a prerequisite of Honeycomb. Check out this overview of source control in GitHub Desktop!

    + \ No newline at end of file diff --git a/docs/ci_cd/index.html b/docs/ci_cd/index.html index a92d6b73..42e87dc7 100644 --- a/docs/ci_cd/index.html +++ b/docs/ci_cd/index.html @@ -4,13 +4,13 @@ Continuous Integration / Deployment | Honeycomb - +
    -
    Version: 3.2.x

    Continuous Integration / Deployment

    Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings, both on demand and automatically as code is pushed to the repository. Honeycomb's CI/CD is managed by GitHub Actions. These workflows provide Honeycomb's foundation and can easily be modified or extended to meet more needs.

    What are Github Actions​

    GitHub Actions automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in GitHub's documentation

    GitHub Actions are written as YML files inside the .github/workflows/ folder of your repository.

    Honeycomb's CI/CD Workflows​

    Honeycomb includes workflows to build and create installers for Windows, Mac and Linux, as well as for deploying to Firebase. These workflows exist for two configurations of the tasks:

    • Home: The app does not expect event code triggers and photodiode spots.
    • Clinic: The app expects event code triggers and photodiode spots.
    tip

    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.

    • 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.

      note

      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.

    • 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​

    • firebase-hosting-merge.yaml: Deploys the web version of the application to Firebase when a PR is merged into the main branch.
    • firebase-hosting-pull-request.yaml: Creates a preview version of the application with Firebase when a PR is opened.
      danger

      While this workflow uses a preview link it does use the production database. Ensure you use a test study to not conflict with your participant data.

    note

    If you are not planning on ever using Firebase these workflows may be safely deleted.

    - +
    Version: 3.2.x

    Continuous Integration / Deployment

    Honeycomb leverages Continuous Integration/Deployment (CI/CD) to build the code and installers for different operating systems and settings, both on demand and automatically as code is pushed to the repository. Honeycomb's CI/CD is managed by GitHub Actions. These workflows provide Honeycomb's foundation and can easily be modified or extended to meet more needs.

    What are Github Actions​

    GitHub Actions automate tasks within the development life cycle of your software. GitHub Actions consist of a series of commands that run after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command to build and test your software. You can learn more about the events that trigger workflows in GitHub's documentation

    GitHub Actions are written as YML files inside the .github/workflows/ folder of your repository.

    Honeycomb's CI/CD Workflows​

    Honeycomb includes workflows to build and create installers for Windows, Mac and Linux, as well as for deploying to Firebase. These workflows exist for two configurations of the tasks:

    • Home: The app does not expect event code triggers and photodiode spots.
    • Clinic: The app expects event code triggers and photodiode spots.
    tip

    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.

    • 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.

      note

      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.

    • 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​

    • firebase-hosting-merge.yaml: Deploys the web version of the application to Firebase when a PR is merged into the main branch.
    • firebase-hosting-pull-request.yaml: Creates a preview version of the application with Firebase when a PR is opened.
      danger

      While this workflow uses a preview link it does use the production database. Ensure you use a test study to not conflict with your participant data.

    note

    If you are not planning on ever using Firebase these workflows may be safely deleted.

    + \ No newline at end of file diff --git a/docs/directory_structure/index.html b/docs/directory_structure/index.html index 594a7343..86f167f8 100644 --- a/docs/directory_structure/index.html +++ b/docs/directory_structure/index.html @@ -4,13 +4,13 @@ Directory Structure | Honeycomb - +
    -
    Version: 3.2.x

    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.

    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.

    caution

    Assets that pertain to your specific task should be added to the public/assets/ folder, not here!

    build/​

    The build scripts automatically create a build folder at the root of the repository and update it on subsequent builds. build/ should be left alone!

    danger

    The build folder 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 to use the data.

    danger

    emulator_data/ is written to when running npm run firebase:emulators:save and should never be manually edited.

    env/​

    This folder contains different files used to pass environment variables (settings) into Honeycomb. Honeycomb starts with presets for common use cases and is explained in greater detail in the Environment Variables section.

    node_modules/​

    danger

    node_modules/ is written to when running npm install and should never be manually edited.

    psiturkit/​

    The file psiturk-it inside psiturkit/ is a bash script used to instal PsiTurk locally - see PsiTurk for more information.

    caution

    Nothing in this folder should ever need to be manually edited.

    public/​

    The public directory contains files that are used as assets in the built app.

    • index.html is the entry point of the website
      • Changing <title>Honeycomb</title> 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.

    assets/​

    The public/assets/ directory contains all of the images and videos needed to run your task.

    lib/​

    The public/lib/ directory contains the files PsiTurk needs to run. Note that index.html references these files inside the <script> tags.

    danger

    These files are minified versions of dependencies and should never be manually edited.

    config/​

    The public/config/ directory contains the config files needed for the electron app. This includes the event-marker details and event codes. version.json keeps track of the current git commit, which Honeycomb uses to keep track of the version of your task used for a given experiment.

    src/​

    This folder contains the source code for the Honeycomb application.

    App/​

    Files relating to the React application. This is the code that runs your JsPsych task and shouldn't need to be changed.

    components/​

    The React components that make up Honeycomb are located here.

    • App.jsx initializes and maintains the state of the application. It is also where communication is set up between the electron and psiturk processes.
    • Error.jsx displays a small error message. It is rendered when the App.jsx detects an issue in state.
    • JsPsychExperiment.jsx initializes the JsPsych experiment
    • Login.jsx handles user authentication based on the environment variables passed to Honeycomb

    deployments/​

    Custom code used by the various deployments such as Firebase.

    caution

    Changes to these files will change how Honeycomb handles data and should be done with great caution.

    config/​

    Each file in the config directory contains settings for a different part of the task.

    • main.js contains the global settings (e.g. whether Honeycomb is running online or in the clinic) passed from env variables and logic for loading the appropriate language file.
    • trigger.js for equipment-related settings (e.g. event markers). It uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.
    • config.json contains the settings for your task. Usage of the config file allows for easy updating of task settings. Common settings can be written once in the config file and re-used throughout the task.
    • language.json contains the language used in your task. Usage of language json files allows for easy internationalization of the task (e.g. english and spanish) and mturk-specific language. Common phrases can be written once in a language file and re-used throughout the task.

    lib/​

    A library of utility and markup are located here. This allows for functions and html to be re-used wherever needed.

    markup/​

    src/lib/markup/ files contain HTML templates used throughout the task.

    • stimuli.js contains a baseStimulus function that wraps some markup in a container that takes up 100% of the height and width of the viewport
    • photodiode.js contains the markup for the photodiode box and spot. It is displayed in the bottom right corner of the scree.
    • tags.js contains functions for wrapping language in common html tags.
      • p('Hello World') will return <p>Hello World</p>. You should always wrap your language in a tag to ensure it is displayed correctly.
    tip

    The tag function inside tags.js can be used to wrap language in any html tag you need.

    utils.js​

    utils.js contains utility functions that can be used across a variety of trials. Be sure to look for functions you might be able to use in your task!

    timelines/​

    A timeline is a collection of trials that JsPsych displays in the given order. Timelines can contain timelines themselves; you may want to break this nesting into multiple files in this folder.

    • main.js contains the JsPsych options and root timeline which App.jsx uses to run the experiment.
    • honeycombBlock.js contains the timeline for the Honeycomb block - the "meat" the example reaction-time task. It uses the task settings from config.json.
    • honeycombTimeline.js contains the timeline for the entire Honeycomb task. This includes the block timeline from honeycombBlock.js, as well as individual trials such as the welcome screen, full screen trial, and instructions.
    • preamble.js contains a base timeline for showing the name and welcome screen of an experiment, as well as automatically entering fullscreen mode. It adds the photodiode instructions to the timeline if Honeycomb is using the photodiode.

    trials/​

    A trial is the base unit of a JsPsych experiment. Each trial should be its own file within this folder - the files in src/timelines/ will combine these trials into the full experiment.

    • honeycombTrials.js contains the individual trials used in the Honeycomb task. These trials are imported into honeycombBlock.js and honeycombTimeline.js.
    • adjustVolume.js prompts the user to adjust the volume on their computer.
    • camera.js contains trials for beginning and ending a camera recording.
    • fullscreen.js contains trials for entering and exiting fullscreen mode.
    • holdUpMarker.js prompts the user to connect their event marker and hold it up to the camera.
    • quizTrial.js contains trials for a quiz/survey.
    • startCode.js emits a start code to a photodiode spot and audible beep

    index.js​

    index.js is the entry point for React in our application. Note that the id 'root' corresponds with a tag in public/index.html:

    <div id="root"></div>

    Other Folders/Files​

    • .github/workflows/ contains .yaml files used to build Honeycomb on a pull request (build.yaml) and create task executables either in a single instance (package.yaml) or for a full release (release.yaml)
    • package.json contains metadata about your project, a list of the dependencies needed for the project, and scripts to run tasks related to your task. The Quick Start lists which metadata should be changed.
    • cli.mjs is the script used to download and delete data stored in Firestore.
    • version.js is the script used to keep track of which version of the task a given experiment is using
    danger

    package-lock.json is written to when running npm install and should never be manually edited.

    Firebase Files​

    • .firebaserc contains the name of the project Firebase should connect to. Be sure to update the default project to the one you created!
    • firebase.json contains the Firebase settings for Honeycomb.
    • firestore.indexes.json contains the Firestore index settings for Honeycomb.
    • firestore.rules contains the Firestore rules for creating/editing data.
    caution

    firebase.json, firestore.indexes.json, and firestore.rules shouldn't need to be manually edited.

    Git Files​

    • .gitignore lists the folders and files that should be excluded from Git.
    danger

    Any secrets and/or tokens must be added to .gitignore or they will be visible to anyone with access to the repository!

    Eslint Files​

    • .eslintrc.js contains the Eslint settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.
    • .eslintignore lists the folders and files that eslint shouldn't touch, similar to .gitignore.

    Prettier Files​

    .prettierrc.js contains the Prettier settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.

    - +
    Version: 3.2.x

    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.

    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.

    caution

    Assets that pertain to your specific task should be added to the public/assets/ folder, not here!

    build/​

    The build scripts automatically create a build folder at the root of the repository and update it on subsequent builds. build/ should be left alone!

    danger

    The build folder 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 to use the data.

    danger

    emulator_data/ is written to when running npm run firebase:emulators:save and should never be manually edited.

    env/​

    This folder contains different files used to pass environment variables (settings) into Honeycomb. Honeycomb starts with presets for common use cases and is explained in greater detail in the Environment Variables section.

    node_modules/​

    danger

    node_modules/ is written to when running npm install and should never be manually edited.

    psiturkit/​

    The file psiturk-it inside psiturkit/ is a bash script used to instal PsiTurk locally - see PsiTurk for more information.

    caution

    Nothing in this folder should ever need to be manually edited.

    public/​

    The public directory contains files that are used as assets in the built app.

    • index.html is the entry point of the website
      • Changing <title>Honeycomb</title> 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.

    assets/​

    The public/assets/ directory contains all of the images and videos needed to run your task.

    lib/​

    The public/lib/ directory contains the files PsiTurk needs to run. Note that index.html references these files inside the <script> tags.

    danger

    These files are minified versions of dependencies and should never be manually edited.

    config/​

    The public/config/ directory contains the config files needed for the electron app. This includes the event-marker details and event codes. version.json keeps track of the current git commit, which Honeycomb uses to keep track of the version of your task used for a given experiment.

    src/​

    This folder contains the source code for the Honeycomb application.

    App/​

    Files relating to the React application. This is the code that runs your JsPsych task and shouldn't need to be changed.

    components/​

    The React components that make up Honeycomb are located here.

    • App.jsx initializes and maintains the state of the application. It is also where communication is set up between the electron and psiturk processes.
    • Error.jsx displays a small error message. It is rendered when the App.jsx detects an issue in state.
    • JsPsychExperiment.jsx initializes the JsPsych experiment
    • Login.jsx handles user authentication based on the environment variables passed to Honeycomb

    deployments/​

    Custom code used by the various deployments such as Firebase.

    caution

    Changes to these files will change how Honeycomb handles data and should be done with great caution.

    config/​

    Each file in the config directory contains settings for a different part of the task.

    • main.js contains the global settings (e.g. whether Honeycomb is running online or in the clinic) passed from env variables and logic for loading the appropriate language file.
    • trigger.js for equipment-related settings (e.g. event markers). It uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.
    • config.json contains the settings for your task. Usage of the config file allows for easy updating of task settings. Common settings can be written once in the config file and re-used throughout the task.
    • language.json contains the language used in your task. Usage of language json files allows for easy internationalization of the task (e.g. english and spanish) and mturk-specific language. Common phrases can be written once in a language file and re-used throughout the task.

    lib/​

    A library of utility and markup are located here. This allows for functions and html to be re-used wherever needed.

    markup/​

    src/lib/markup/ files contain HTML templates used throughout the task.

    • stimuli.js contains a baseStimulus function that wraps some markup in a container that takes up 100% of the height and width of the viewport
    • photodiode.js contains the markup for the photodiode box and spot. It is displayed in the bottom right corner of the scree.
    • tags.js contains functions for wrapping language in common html tags.
      • p('Hello World') will return <p>Hello World</p>. You should always wrap your language in a tag to ensure it is displayed correctly.
    tip

    The tag function inside tags.js can be used to wrap language in any html tag you need.

    utils.js​

    utils.js contains utility functions that can be used across a variety of trials. Be sure to look for functions you might be able to use in your task!

    timelines/​

    A timeline is a collection of trials that JsPsych displays in the given order. Timelines can contain timelines themselves; you may want to break this nesting into multiple files in this folder.

    • main.js contains the JsPsych options and root timeline which App.jsx uses to run the experiment.
    • honeycombBlock.js contains the timeline for the Honeycomb block - the "meat" the example reaction-time task. It uses the task settings from config.json.
    • honeycombTimeline.js contains the timeline for the entire Honeycomb task. This includes the block timeline from honeycombBlock.js, as well as individual trials such as the welcome screen, full screen trial, and instructions.
    • preamble.js contains a base timeline for showing the name and welcome screen of an experiment, as well as automatically entering fullscreen mode. It adds the photodiode instructions to the timeline if Honeycomb is using the photodiode.

    trials/​

    A trial is the base unit of a JsPsych experiment. Each trial should be its own file within this folder - the files in src/timelines/ will combine these trials into the full experiment.

    • honeycombTrials.js contains the individual trials used in the Honeycomb task. These trials are imported into honeycombBlock.js and honeycombTimeline.js.
    • adjustVolume.js prompts the user to adjust the volume on their computer.
    • camera.js contains trials for beginning and ending a camera recording.
    • fullscreen.js contains trials for entering and exiting fullscreen mode.
    • holdUpMarker.js prompts the user to connect their event marker and hold it up to the camera.
    • quizTrial.js contains trials for a quiz/survey.
    • startCode.js emits a start code to a photodiode spot and audible beep

    index.js​

    index.js is the entry point for React in our application. Note that the id 'root' corresponds with a tag in public/index.html:

    <div id="root"></div>

    Other Folders/Files​

    • .nvmrc determines which version of node that Honeycomb is designed to be run on
    • .github/workflows/ contains .yaml files used to build Honeycomb on a pull request (build.yaml) and create task executables either in a single instance (package.yaml) or for a full release (release.yaml)
    • package.json contains metadata about your project, a list of the dependencies needed for the project, and scripts to run tasks related to your task. The Quick Start lists which metadata should be changed.
    • cli.mjs is the script used to download and delete data stored in Firestore.
    • version.js is the script used to keep track of which version of the task a given experiment is using
    danger

    package-lock.json is written to when running npm install and should never be manually edited.

    Firebase Files​

    • .firebaserc contains the name of the project Firebase should connect to. Be sure to update the default project to the one you created!
    • firebase.json contains the Firebase settings for Honeycomb.
    • firestore.indexes.json contains the Firestore index settings for Honeycomb.
    • firestore.rules contains the Firestore rules for creating/editing data.
    caution

    firebase.json, firestore.indexes.json, and firestore.rules shouldn't need to be manually edited.

    Git Files​

    • .gitignore lists the folders and files that should be excluded from Git.
    danger

    Any secrets and/or tokens must be added to .gitignore or they will be visible to anyone with access to the repository!

    Eslint Files​

    • .eslintrc.js contains the Eslint settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.
    • .eslintignore lists the folders and files that eslint shouldn't touch, similar to .gitignore.

    Prettier Files​

    .prettierrc.js contains the Prettier settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.

    + \ No newline at end of file diff --git a/docs/environment_variables/index.html b/docs/environment_variables/index.html index 3b22f4b5..a77cd87b 100644 --- a/docs/environment_variables/index.html +++ b/docs/environment_variables/index.html @@ -4,13 +4,13 @@ Environment Variables | Honeycomb - +
    -
    Version: 3.2.x

    Environment Variables

    Honeycomb uses environment variables to control the different configurations. Below we list the environment variables used by the app and indicate their properties via badges and text.

    NameDesktop vs OnlineBuild vs Run-timeDefault ValueTypeDescription
    REACT_APP_FIREBASEonlinebuildFalsebooleanIf the task is saving its data on Firebase.
    REACT_APP_VIDEOdesktopbuildFalsebooleanIf the participant is being video recorded.
    REACT_APP_USE_EEGdesktopbuildFalsebooleanIf the EEG (Event Marker) is available and recording.
    REACT_APP_USE_PHOTODIODEdesktopbuildFalsebooleanIf the photodiode spot is in use.
    REACT_APP_USE_VOLUMEdesktop onlinebuildFalsebooleanIf the participant should be asked to adjust their volume. (e.g. the task is using sound)
    REACT_APP_STUDY_IDdesktop onlinerun""stringThe id of a study. User will enter this value in the login screen if not set.
    REACT_APP_PARTICIPANT_IDdesktop onlinerun""stringThe id of a participant. User will enter this value in the login screen if not set.
    EVENT_MARKER_PRODUCT_IDdesktoprun""stringThe product ID of the event marker. If not set, it will default to the productID set in public/config/trigger.js. If neither are set it will attempt to connect using the COM name.
    EVENT_MARKER_COM_NAMEdesktoprun"COM3"stringThe COM name of the event marker. If not set, it will use the comName set in public/config/trigger.js. Field is ignored if EVENT_MARKER_PRODUCT_ID is set.
    note

    Note that Honeycomb does use other environment variables (e.g. ELECTRON_START_URL) but they do not effect the task itself. They can be safely ignored.

    Understanding the Environment Variables​

    Run-time​

    The run badge indicates the variable is set/determined each time the executable is run. Run-time environment variables allow for quick changes when running the task. They are convenient since they don't require building a whole different executable.

    • Desktop deployments must set these environment variables at the system level.
    • Online deployments must use Firebase, and store the runtime environment variables in Firestore.

    Build-time​

    The build badge indicates the variable is set during the build phase (npm run build) and cannot be changed at run-time. These variables are configured via .env files in the env folder.

    The dotenv-cli comes with the dotenv command that can be used to properly load the needed variables. We write our npm scripts with the following format:

    package.json
    "[build|dev]:<env name>": "dotenv -e env/<env name> npm run [build|dev]"

    See NPM Scripts for more

    - +
    Version: 3.2.x

    Environment Variables

    Honeycomb uses environment variables to control the different configurations. Below we list the environment variables used by the app and indicate their properties via badges and text.

    NameDesktop vs OnlineBuild vs Run-timeDefault ValueTypeDescription
    REACT_APP_FIREBASEonlinebuildFalsebooleanIf the task is saving its data on Firebase.
    REACT_APP_VIDEOdesktopbuildFalsebooleanIf the participant is being video recorded.
    REACT_APP_USE_EEGdesktopbuildFalsebooleanIf the EEG (Event Marker) is available and recording.
    REACT_APP_USE_PHOTODIODEdesktopbuildFalsebooleanIf the photodiode spot is in use.
    REACT_APP_USE_VOLUMEdesktop onlinebuildFalsebooleanIf the participant should be asked to adjust their volume. (e.g. the task is using sound)
    REACT_APP_STUDY_IDdesktop onlinerun""stringThe id of a study. User will enter this value in the login screen if not set.
    REACT_APP_PARTICIPANT_IDdesktop onlinerun""stringThe id of a participant. User will enter this value in the login screen if not set.
    EVENT_MARKER_PRODUCT_IDdesktoprun""stringThe product ID of the event marker. If not set, it will default to the productID set in public/config/trigger.js. If neither are set it will attempt to connect using the COM name.
    EVENT_MARKER_COM_NAMEdesktoprun"COM3"stringThe COM name of the event marker. If not set, it will use the comName set in public/config/trigger.js. Field is ignored if EVENT_MARKER_PRODUCT_ID is set.
    note

    Note that Honeycomb does use other environment variables (e.g. ELECTRON_START_URL) but they do not effect the task itself. They can be safely ignored.

    Understanding the Environment Variables​

    Run-time​

    The run badge indicates the variable is set/determined each time the executable is run. Run-time environment variables allow for quick changes when running the task. They are convenient since they don't require building a whole different executable.

    • Desktop deployments must set these environment variables at the system level.
    • Online deployments must use Firebase, and store the runtime environment variables in Firestore.

    Build-time​

    The build badge indicates the variable is set during the build phase (npm run build) and cannot be changed at run-time. These variables are configured via .env files in the env folder.

    The dotenv-cli comes with the dotenv command that can be used to properly load the needed variables. We write our npm scripts with the following format:

    package.json
    "[build|dev]:<env name>": "dotenv -e env/<env name> npm run [build|dev]"

    See NPM Scripts for more

    + \ No newline at end of file diff --git a/docs/event_triggers/index.html b/docs/event_triggers/index.html index efb631d0..6c989a75 100644 --- a/docs/event_triggers/index.html +++ b/docs/event_triggers/index.html @@ -4,13 +4,13 @@ Event Triggers | Honeycomb - +
    -
    Version: 3.2.x

    Event Triggers

    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:

    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.

    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 eventCode (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.

    - +
    Version: 3.2.x

    Event Triggers

    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:

    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.

    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 eventCode (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.

    + \ No newline at end of file diff --git a/docs/firebase/index.html b/docs/firebase/index.html index b6bc3420..7e7c828e 100644 --- a/docs/firebase/index.html +++ b/docs/firebase/index.html @@ -4,13 +4,13 @@ Firebase | Honeycomb - +
    -
    Version: 3.2.x

    Firebase

    Honeycomb comes with methods and configurations to deploy tasks with Firebase. These tools make it possible to reach a wider audience by hosting your task online.

    Setting up Firebase​

    info

    Please have your PI contact support@ccv.brown.edu to create a Firebase project for your Honeycomb task before beginning.

    Adding Products​

    First we'll configure Firebase Hosting and Cloud Firestore on your project.

    1. Log in to Firebase with your Google account on the Firebase console.

    2. Navigate to your project from the console

    3. Register a new web app to your project (Register your app)

      note

      We recommend giving your web app the same name as your task's repository

    4. Add Firestore Database to your project (Create a Cloud Firestore database)

      note

      Chose 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.

    Installing the Command Line Interface​

    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!

    Install the Firebase CLI
    npm install -g firebase-tools
    Login to Firebase
    firebase login

    A "command not found" error usually indicates firebase-tools has not been installed correctly

    Connecting Your Firebase Project​

    1. Change the default project name of your task in .firebaserc
    .firebaserc
    {
      "projects": {
        "default": "<your project name>"
      }
    }

    1. 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.

      2. Navigate to your project setting

        Firebase project settings

      3. Scroll down and copy the auto-generated values from the Firebase console to the corresponding variables in the .env.firebase file in the env folder of your Honeycomb task repo

        Firebase web credentials

        env/.env.firebase
        REACT_APP_FIREBASE="true"
        REACT_APP_apiKey=
        REACT_APP_authDomain=
        REACT_APP_projectId=
        REACT_APP_storageBucket=
        REACT_APP_messagingSenderId=
        REACT_APP_appId=

        Additional variables may be present in the console, they do not need to be copied.

    2. Deploy the default Firestore security rules

    Deploy Firestore rules
    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 for more information.

    1. Navigate to your Firestore Database in the console.
    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
    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 for instructions on splitting terminals in VSCode.

    Run Honeycomb with Firebase Enabled
    npm run dev:firebase
    Start the Firebase Emulators
    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.

    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) practices using GitHub Actions. Here we will connect 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.

    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!
    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
    6. Enter y for the prompt "Set up automatic deployment to your site's live channel when a PR is merged?"
    7. Enter main for the prompt "What is the name of the GitHub branch associated with your site's live channel?"
    8. Enter y to overwrite the current workflow file

    Firebase will update the files firebase-hosting-pull-request.yml and firebase-hosting-merge.yml inside the .github/workflows/ directory. Ensure the correct run script is present in both files.

    Github actions created by firebase

    Managing Data​

    Honeycomb ships with a CLI script for managing data in Firebase. A local service account must be created in order to use it.

    Setting up a Service Account​

    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.

      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!

    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.

    Using the CLI Script​

    Script Usage
    npm run cli

    The CLI script will guide you through the steps needed to manage your data appropriately:

    1. Whether you wish to download or delete data

    2. Entering the ID of a given study

    3. Entering the ID of a given participant on that study

    4. Selecting the sessions to download/delete

      info
      SPACE selects a single session and A toggles every session
    note

    The download script will prompt you for where the data should be saved. It defaults to ., which is your current folder. The folder must exist before running the script.

    Further Reading​

    The Firebase Documentation details its Emulator Suite in much greater detail.

    Security Rules​

    Honeycomb uses security rules to authenticate participants and studies for each task. By default participants must be registered to each study in order to complete the task.

    Firestore rules are defined in the firestore.rules file in the home directory. Note the highlighted lines:

    firestore.rules
    rules_version = '2';
    service cloud.firestore {
      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;
            // ...
          }
        }
    }

    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 manually make these changes from the Firestore console.

    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.

    - +
    Version: 3.2.x

    Firebase

    Honeycomb comes with methods and configurations to deploy tasks with Firebase. These tools make it possible to reach a wider audience by hosting your task online.

    Setting up Firebase​

    info

    Please have your PI contact support@ccv.brown.edu to create a Firebase project for your Honeycomb task before beginning.

    Adding Products​

    First we'll configure Firebase Hosting and Cloud Firestore on your project.

    1. Log in to Firebase with your Google account on the Firebase console.

    2. Navigate to your project from the console

    3. Register a new web app to your project (Register your app)

      note

      We recommend giving your web app the same name as your task's repository

    4. Add Firestore Database to your project (Create a Cloud Firestore database)

      note

      Chose 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.

    Installing the Command Line Interface​

    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!

    Install the Firebase CLI
    npm install -g firebase-tools
    Login to Firebase
    firebase login

    A "command not found" error usually indicates firebase-tools has not been installed correctly

    Connecting Your Firebase Project​

    1. Change the default project name of your task in .firebaserc
    .firebaserc
    {
      "projects": {
        "default": "<your project name>"
      }
    }

    1. 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.

      2. Navigate to your project setting

        Firebase project settings

      3. Scroll down and copy the auto-generated values from the Firebase console to the corresponding variables in the .env.firebase file in the env folder of your Honeycomb task repo

        Firebase web credentials

        env/.env.firebase
        REACT_APP_FIREBASE="true"
        REACT_APP_apiKey=
        REACT_APP_authDomain=
        REACT_APP_projectId=
        REACT_APP_storageBucket=
        REACT_APP_messagingSenderId=
        REACT_APP_appId=

        Additional variables may be present in the console, they do not need to be copied.

    2. Deploy the default Firestore security rules

    Deploy Firestore rules
    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 for more information.

    1. Navigate to your Firestore Database in the console.
    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
    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 for instructions on splitting terminals in VSCode.

    Run Honeycomb with Firebase Enabled
    npm run dev:firebase
    Start the Firebase Emulators
    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.

    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) practices using GitHub Actions. Here we will connect 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.

    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!
    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
    6. Enter y for the prompt "Set up automatic deployment to your site's live channel when a PR is merged?"
    7. Enter main for the prompt "What is the name of the GitHub branch associated with your site's live channel?"
    8. Enter y to overwrite the current workflow file

    Firebase will update the files firebase-hosting-pull-request.yml and firebase-hosting-merge.yml inside the .github/workflows/ directory. Ensure the correct run script is present in both files.

    Github actions created by firebase

    Managing Data​

    Honeycomb ships with a CLI script for managing data in Firebase. A local service account must be created in order to use it.

    Setting up a Service Account​

    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.

      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!

    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.

    Using the CLI Script​

    Script Usage
    npm run cli

    The CLI script will guide you through the steps needed to manage your data appropriately:

    1. Whether you wish to download or delete data

    2. Entering the ID of a given study

    3. Entering the ID of a given participant on that study

    4. Selecting the sessions to download/delete

      info
      SPACE selects a single session and A toggles every session
    note

    The download script will prompt you for where the data should be saved. It defaults to ., which is your current folder. The folder must exist before running the script.

    Further Reading​

    The Firebase Documentation details its Emulator Suite in much greater detail.

    Security Rules​

    Honeycomb uses security rules to authenticate participants and studies for each task. By default participants must be registered to each study in order to complete the task.

    Firestore rules are defined in the firestore.rules file in the home directory. Note the highlighted lines:

    firestore.rules
    rules_version = '2';
    service cloud.firestore {
      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;
            // ...
          }
        }
    }

    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 manually make these changes from the Firestore console.

    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.

    + \ No newline at end of file diff --git a/docs/gh_pages/index.html b/docs/gh_pages/index.html index c607fd8f..41cd1f9b 100644 --- a/docs/gh_pages/index.html +++ b/docs/gh_pages/index.html @@ -4,13 +4,13 @@ GitHub Pages | Honeycomb - +
    -
    Version: 3.2.x

    GitHub Pages

    The .github/workflows/release.yml workflow will automatically deploy your task to GitHub pages if you have it enabled for your repository. It uploads the built website to the gh-pages branch. You can then access your task at <github user>.github.io/<repository>.

    danger

    Session data is downloaded to the user's local machine upon completion of the experiment when using GH Pages. Because of this, GH Pages is not suitable for fully online experiments.

    Setup​

    Please follow the GitHub documentation for setting up GH Pages on your repository and make sure the publishing source for your repository is configured for gh-pages branch.

    - +
    Version: 3.2.x

    GitHub Pages

    The .github/workflows/release.yml workflow will automatically deploy your task to GitHub pages if you have it enabled for your repository. It uploads the built website to the gh-pages branch. You can then access your task at <github user>.github.io/<repository>.

    danger

    Session data is downloaded to the user's local machine upon completion of the experiment when using GH Pages. Because of this, GH Pages is not suitable for fully online experiments.

    Setup​

    Please follow the GitHub documentation for setting up GH Pages on your repository and make sure the publishing source for your repository is configured for gh-pages branch.

    + \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 40d06c2c..b6480b87 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,13 +4,13 @@ Introduction | Honeycomb - +
    -
    Version: 3.2.x

    Introduction

    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.

    Flexible deployment online and in the lab​

    Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings.

    Easy-to-install executables​

    Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites.

    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.

    Cite this work​

    If you use Honeycomb in your work, please cite

    Provenza, N.R., Gelin, L.F.F., Mahaphanit, W., McGrath, M.C., Dastin-van Rijn, E.M., Fan, Y., Dhar, R., Frank, M.J., Restrepo, M.I., Goodman, W.K. and Borton, D.A., 2021. Honeycomb: a template for reproducible psychophysiological tasks for clinic, laboratory, and home use. Brazilian Journal of Psychiatry, 44, pp.147-155.

    - +
    Version: 3.2.x

    Introduction

    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.

    Flexible deployment online and in the lab​

    Honeycomb provides the ability to write one codebase and use it flexibly across settings (with guaranteed consistency in instructions, timing, etc.). The same code-base is used to maintain and deploy the identical task on Mechanical Turk, Prolific, and in research settings during concurrent electrophysiological recordings.

    Easy-to-install executables​

    Deployment specifications are abstracted as parameters that are easy to configure, and application building is automated via GitHub actions providing continuous delivery of easy-to-download executables, easing setup burden across research sites.

    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.

    Cite this work​

    If you use Honeycomb in your work, please cite

    Provenza, N.R., Gelin, L.F.F., Mahaphanit, W., McGrath, M.C., Dastin-van Rijn, E.M., Fan, Y., Dhar, R., Frank, M.J., Restrepo, M.I., Goodman, W.K. and Borton, D.A., 2021. Honeycomb: a template for reproducible psychophysiological tasks for clinic, laboratory, and home use. Brazilian Journal of Psychiatry, 44, pp.147-155.

    + \ No newline at end of file diff --git a/docs/javascript/index.html b/docs/javascript/index.html index 7d528ca9..867bae07 100644 --- a/docs/javascript/index.html +++ b/docs/javascript/index.html @@ -4,13 +4,13 @@ JavaScript | Honeycomb - +
    -
    Version: 3.2.x

    JavaScript

    Learning JavaScript​

    The Mozilla Developer Network Web Docs is the gold standard for programming on the web. The JavaScript page is an excellent place for further reading about JavaScript.

    Interactive Tutorials​

    Learn JavaScript is an excellent platform for beginning to learn the JavaScript programming language. It is full of interactive tutorials and small projects.

    - +
    Version: 3.2.x

    JavaScript

    Learning JavaScript​

    The Mozilla Developer Network Web Docs is the gold standard for programming on the web. The JavaScript page is an excellent place for further reading about JavaScript.

    Interactive Tutorials​

    Learn JavaScript is an excellent platform for beginning to learn the JavaScript programming language. It is full of interactive tutorials and small projects.

    + \ No newline at end of file diff --git a/docs/local_application/index.html b/docs/local_application/index.html index e9abc5e2..88cb50dd 100644 --- a/docs/local_application/index.html +++ b/docs/local_application/index.html @@ -4,13 +4,13 @@ Local Application | Honeycomb - +
    -
    Version: 3.2.x

    Local Application

    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.

    Creating a Release​

    Follow the GitHub documentation for creating a release.

    The tag should be in the format vX.X.X where X.X.X is the version number of the release. For example, if the release is version 1.0.0, the tag should be v1.0.0.

    danger

    Your release must included a new tag for the CI/CD workflow to work.

    Running 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.
    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!

    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.

    - +
    Version: 3.2.x

    Local Application

    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.

    Creating a Release​

    Follow the GitHub documentation for creating a release.

    The tag should be in the format vX.X.X where X.X.X is the version number of the release. For example, if the release is version 1.0.0, the tag should be v1.0.0.

    danger

    Your release must included a new tag for the CI/CD workflow to work.

    Running 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.
    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!

    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.

    + \ No newline at end of file diff --git a/docs/npm_scripts/index.html b/docs/npm_scripts/index.html index 684fceee..ef70d6cc 100644 --- a/docs/npm_scripts/index.html +++ b/docs/npm_scripts/index.html @@ -4,13 +4,13 @@ NPM Scripts | Honeycomb - +
    -
    Version: 3.2.x

    NPM Scripts

    Custom scripts for common shell commands can be written in package.json and run the node package manager (NPM). All of the commands needed to develop, build, and deploy Honeycomb are written as scripts.

    Additional scripts can be created if desired but we generally recommend against changing or deleting the scripts Honeycomb ships with.

    Executing an NPM Script
    npm run <script>

    Start​

    • start runs the app in development mode and does NOT open a browser. This makes working with electron easier as it creates its own browser for development.
    • start:browser runs the app in development mode and automatically opens a new browser tab. It uses your system's default browser. The page will reload if you make edits.
    • start:electron: Waits for the app to be running (from start) and then starts an electron process.

    Firebase​

    • firebase:emulators:start starts the Firebase emulators with the data found in emulator_data/
    • firebase:emulators:save saves the current state of the Firebase emulators into emulator_data/
    • firebase:download runs the firebase-download-script.js script, saving certain data in Firebase to your local machine.

    Dev​

    npm run dev runs the app in development mode on Electron. It executes start and start:electron concurrently.

    Note that this is a base script that other scripts build on top of - you should always run one of the scripts below while developing your app. The additional scripts execute npm run dev with different environment variables.

    • dev:home runs the app with equipment disabled
    • dev:home:video runs the app with equipment disabled and video enabled
    • dev:clinic runs the app with equipment enabled
    • dev:clinic:video runs the app with equipment enabled and video enabled
    • dev:turk-prolific runs the app with prolific and PsiTurk enabled

    Firebase​

    Working with Firebase is slightly different as it is meant to be run on the browser. npm run dev:firebase executes start:browser with Firebase enabled, which will automatically launch the running app in your default browser. It can be found on other browsers by navigating to localhost:3000.

    dev:firebase must be run in conjunction with firebase:emulators:start to work properly. This runs the Firebase Emulators locally with some dummy data. The emulator data can be viewed at localhost:4000.

    caution

    npm run firebase:emulators:start must be run in a separate terminal window that stays during development.

    tip

    The dummy study is s1 and the dummy participant is p1.

    Build​

    npm run build creates a production build of the app in the build/ folder.

    Note that this is a base script that other scripts build on top of - you should always run one of the scripts below while developing your app. The additional scripts execute npm run build with different environment variables.

    • build:home builds the app with equipment disabled
    • build:home:video builds the app with equipment disabled and video enabled
    • build:clinic builds the app with equipment enabled
    • build:clinic:video builds the app with equipment enabled and video enabled
    • build:firebase builds the app with Firebase enabled
    • build:turk-prolific builds the app with prolific and PsiTurk enabled

    Package​

    npm run package:[platform] creates a standalone installer for the given platform using electron-forge. The installer is created in out/. Note that the scripts build the app before creating the installers

    • npm run package:windows
    • npm run package:linux
    • npm run package:mac
    info

    Packaging for windows on a non-windows machine requires mono and wine to be installed.

    Miscellaneous​

    • commit runs commitizen in the console. It is useful for ensuring your Git commit messages are easy to follow.
    • lint uses Eslint to find problems in the code
    • format uses Eslint to find and fix problems in the code that it can automatically
    • test launches the test runner in the interactive watch mode. See running tests for more information.
    - +
    Version: 3.2.x

    NPM Scripts

    Custom scripts for common shell commands can be written in package.json and run the node package manager (NPM). All of the commands needed to develop, build, and deploy Honeycomb are written as scripts.

    Additional scripts can be created if desired but we generally recommend against changing or deleting the scripts Honeycomb ships with.

    Executing an NPM Script
    npm run <script>

    Start​

    • start runs the app in development mode and does NOT open a browser. This makes working with electron easier as it creates its own browser for development.
    • start:browser runs the app in development mode and automatically opens a new browser tab. It uses your system's default browser. The page will reload if you make edits.
    • start:electron: Waits for the app to be running (from start) and then starts an electron process.

    Firebase​

    • firebase:emulators:start starts the Firebase emulators with the data found in emulator_data/
    • firebase:emulators:save saves the current state of the Firebase emulators into emulator_data/
    • firebase:download runs the firebase-download-script.js script, saving certain data in Firebase to your local machine.

    Dev​

    npm run dev runs the app in development mode on Electron. It executes start and start:electron concurrently.

    Note that this is a base script that other scripts build on top of - you should always run one of the scripts below while developing your app. The additional scripts execute npm run dev with different environment variables.

    • dev:home runs the app with equipment disabled
    • dev:home:video runs the app with equipment disabled and video enabled
    • dev:clinic runs the app with equipment enabled
    • dev:clinic:video runs the app with equipment enabled and video enabled
    • dev:turk-prolific runs the app with prolific and PsiTurk enabled

    Firebase​

    Working with Firebase is slightly different as it is meant to be run on the browser. npm run dev:firebase executes start:browser with Firebase enabled, which will automatically launch the running app in your default browser. It can be found on other browsers by navigating to localhost:3000.

    dev:firebase must be run in conjunction with firebase:emulators:start to work properly. This runs the Firebase Emulators locally with some dummy data. The emulator data can be viewed at localhost:4000.

    caution

    npm run firebase:emulators:start must be run in a separate terminal window that stays during development.

    tip

    The dummy study is s1 and the dummy participant is p1.

    Build​

    npm run build creates a production build of the app in the build/ folder.

    Note that this is a base script that other scripts build on top of - you should always run one of the scripts below while developing your app. The additional scripts execute npm run build with different environment variables.

    • build:home builds the app with equipment disabled
    • build:home:video builds the app with equipment disabled and video enabled
    • build:clinic builds the app with equipment enabled
    • build:clinic:video builds the app with equipment enabled and video enabled
    • build:firebase builds the app with Firebase enabled
    • build:turk-prolific builds the app with prolific and PsiTurk enabled

    Package​

    npm run package:[platform] creates a standalone installer for the given platform using electron-forge. The installer is created in out/. Note that the scripts build the app before creating the installers

    • npm run package:windows
    • npm run package:linux
    • npm run package:mac
    info

    Packaging for windows on a non-windows machine requires mono and wine to be installed.

    Miscellaneous​

    • commit runs commitizen in the console. It is useful for ensuring your Git commit messages are easy to follow.
    • lint uses Eslint to find problems in the code
    • format uses Eslint to find and fix problems in the code that it can automatically
    • test launches the test runner in the interactive watch mode. See running tests for more information.
    + \ No newline at end of file diff --git a/docs/prerequisites/index.html b/docs/prerequisites/index.html index a86c27b6..6c97e7fe 100644 --- a/docs/prerequisites/index.html +++ b/docs/prerequisites/index.html @@ -4,13 +4,13 @@ Prerequisites | Honeycomb - +
    -
    Version: 3.2.x

    Prerequisites

    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 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​

    Git​

    git is an open-sourced version control system. It is used to track changes, revert mistakes, and enable peer code reviews!

    GitHub Desktop is a GUI application used to interact with git and GitHub directly from your computer. It is not strictly needed but many folks find it easier to work with than using git directly from the command line.

    Node Version Manager​

    NodeJS is a cross-platform runtime environment for JavaScript code. Almost every web application today builds on top of node. Node Version Manager manages running multiple versions of node on the same system. The .nvmrc denotes the version of node that Honeycomb uses.

    Python​

    Python 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.

    Oracle JDk​

    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.

    note

    Honeycomb needs version 11 or later to run - the installers use version 18.

    Visual Studio Code​

    Visual Studio Code is a well-loved and easy to use integrated development environment (IDE). This is the program you'll use to write your task.

    Mac-specific Installs​

    X-Code​

    XCode is a special IDE for the Apple platform. It comes with everything needed to compile desktop applications from an Apple computer. It must be installed from the terminal:

    Installing XCode
      xcode-select --install

    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 can be used to make sure it is on your Apple silicon system.

    Windows-specific Install​

    Visual Studio​

    Visual Studio 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.

    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)​

    The links below will take you to each project installation page should you prefer to manually install the prerequisite software.

    Manual Installation (Windows)​

    The links below will take you to each project installation page should you prefer to manually install the prerequisite software.

    Manual Installation (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 should get you up and running on any Linux distro new enough to support GLIBC_2.28.

    Further Help​

    If you are still having issues setting up your computer you can find the full instructions on the electron documentation for your specific OS.

    - +
    Version: 3.2.x

    Prerequisites

    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 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​

    Git​

    git is an open-sourced version control system. It is used to track changes, revert mistakes, and enable peer code reviews!

    GitHub Desktop is a GUI application used to interact with git and GitHub directly from your computer. It is not strictly needed but many folks find it easier to work with than using git directly from the command line.

    Node Version Manager​

    NodeJS is a cross-platform runtime environment for JavaScript code. Almost every web application today builds on top of node. Node Version Manager manages running multiple versions of node on the same system. The .nvmrc denotes the version of node that Honeycomb uses.

    Python​

    Python 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.

    Oracle JDk​

    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.

    note

    Honeycomb needs version 11 or later to run - the installers use version 18.

    Visual Studio Code​

    Visual Studio Code is a well-loved and easy to use integrated development environment (IDE). This is the program you'll use to write your task.

    Mac-specific Installs​

    X-Code​

    XCode is a special IDE for the Apple platform. It comes with everything needed to compile desktop applications from an Apple computer. It must be installed from the terminal:

    Installing XCode
      xcode-select --install

    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 can be used to make sure it is on your Apple silicon system.

    Windows-specific Install​

    Visual Studio​

    Visual Studio 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.

    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)​

    The links below will take you to each project installation page should you prefer to manually install the prerequisite software.

    Manual Installation (Windows)​

    The links below will take you to each project installation page should you prefer to manually install the prerequisite software.

    Manual Installation (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 should get you up and running on any Linux distro new enough to support GLIBC_2.28.

    Further Help​

    If you are still having issues setting up your computer you can find the full instructions on the electron documentation for your specific OS.

    + \ No newline at end of file diff --git a/docs/psiturk/index.html b/docs/psiturk/index.html index 0fbe99a7..6529307a 100644 --- a/docs/psiturk/index.html +++ b/docs/psiturk/index.html @@ -4,14 +4,14 @@ PsiTurk | Honeycomb - +
    Version: 3.2.x

    PsiTurk

    While honeycomb is optimized for use on a local application, we added functionality for usage with PsiTurk. 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.

    If this is all you need, the build instructions below can be skipped!

    Build instructions​

    To set up your PsiTurk project, we provide a script that does the conversion. -PsiTurk is a Python package used to manage HITs in Mechanical Turk. Before using the provided script, install PsiTurk.

    You'll need to follow these steps (the path to the PsiTurk project should be a directory you wish to be created):

    • Build the application: npm run build

    • Move to the psiturkit directory: cd psiturkit

    • If it's the first time you're running the script:

      ./psiturk-it -p <PATH_TO_NEW_PSITURK_PROJECT>

    • To update an existing PsiTurk project (the path to the PsiTurk project should already exist from the previous steps):

      ./psiturk-it -U -p <PATH_TO_NEW_PSITURK_PROJECT>

    Running PsiTurk​

    After that, just navigate to your newly created PsiTurk project directory.

    shell> psiturk # start psiturk
    psiturk> server on # start server
    psiturk> debug # enter debug mode
    - +PsiTurk is a Python package used to manage HITs in Mechanical Turk. Before using the provided script, install PsiTurk.

    You'll need to follow these steps (the path to the PsiTurk project should be a directory you wish to be created):

    • Build the application: npm run build

    • Move to the psiturkit directory: cd psiturkit

    • If it's the first time you're running the script:

      ./psiturk-it -p <PATH_TO_NEW_PSITURK_PROJECT>

    • To update an existing PsiTurk project (the path to the PsiTurk project should already exist from the previous steps):

      ./psiturk-it -U -p <PATH_TO_NEW_PSITURK_PROJECT>

    Running PsiTurk​

    After that, just navigate to your newly created PsiTurk project directory.

    shell> psiturk # start psiturk
    psiturk> server on # start server
    psiturk> debug # enter debug mode
    + \ No newline at end of file diff --git a/docs/quick_start/index.html b/docs/quick_start/index.html index a02baec4..29dd7e85 100644 --- a/docs/quick_start/index.html +++ b/docs/quick_start/index.html @@ -4,15 +4,15 @@ Quick Start | Honeycomb - +
    Version: 3.2.x

    Quick Start

    Creating Your Task Repository​

    The Honeycomb repository is a template and serves as the starting point for all tasks. Creating your repository from the template starts your project with the same directory structure and files as an existing repository.

    1. Go to the Honeycomb repository

    2. Click on Use this template and select Create a new repository. Use this template

    3. Enter the owner, name, and description of your repository and click on Create repository from template. -Create repository

      note

      We recommend creating a public repository and leaving Include all branches unchecked

    4. Ensure the repositories workflow permissions are set to "Read and write permissions"

      Settings -> Actions -> General -> Workflow permissions

      GitHub workflow permissions settings

    Additional details about template repositories can be found on the Github Docs.

    Cloning the Repository​

    With the repository now setup it can be cloned onto your computer.

    1. Navigate to the repository on GitHub.

    2. Click the Code button and copy the URL

      GitHub clone repo button

    3. Open a terminal and navigate to where you want the cloned directory

    Terminal.app
    cd 'path/to/directory'
    1. Clone the repo with the following command
    Paste the URL you copied earlier
     git clone https://github.com/<YOUR-USERNAME>/<YOUR-REPOSITORY>
    note

    Git can be downloaded here if it is not already on your system.

    Additional details and alternative methods for cloning a repository can be found on the Github Docs.

    Installing Prerequisites​

    All of the needed programs for Honeycomb must be installed before we can develop our task. We will use a package manager to automatically install them.

    See Prerequisites for more information about these programs.

    Initial Install​

    The most commonly used package manager on macOS is Homebrew.

    1. Paste the following command in a macOS Terminal and follow the prompts to install Homebrew.

      /bin/bash -c '$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)'

    2. Paste the following command and follow the prompts to install the listed programs:

      brew bundle

    3. Install Xcode (not available on Homebrew)

      xcode-select --install
    note

    If you are running into issues after installing the packages please restart your terminal and/or reboot your computer. This should resolve most issues.

    Setting Up Node​

    NVM (Node Version Manager) is a tool for installing and using multiple versions on node on your computer. It must first be installed:

    1. Install NVM

      curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.4/install.sh | bash

    2. Copy the version number listed in .nvmrc. The version may be different than the screenshot below.

      .nvmrc file

    3. Install that version.

      nvm install [version]

    4. Use the needed version. This will automatically check the version listed in the .nvmrc file.

      nvm use

    5. Set the current version as your default

      nvm alias default node
    note

    You can skip step 4 if you've already set a default node version in a different project.

    Install Dependencies​

    There are many node packages used by Honeycomb that also need to be installed. Node (installed in the previous step) comes with its own package manager to install, update, and maintain these dependencies throughout the development lifecycle.

    Install Honeycomb's dependencies
    npm install

    Certain dependencies are best installed globally within node. These tools will be available from the command line anywhere on your system.

    Install Honeycomb's global dependencies
    npm install -g electron firebase-tools dotenv-cli

    Run the Task in Development Mode​

    Running the task in development mode causes it to hot-reload whenever changes are made to the app. This is how you'll run the project while building your task.

    Run the task in dev mode
    npm run dev

    This script launches an electron window with the task and inspector open.

    You can quit the task in the middle of development if needed:

    ⌘ + Q

    Saving data​

    Data is saved throughout the task, even when running in development mode. The location of the task is logged at the beginning of the task wherever you ran npm run dev.

    Note how the data is organized by study and participant. Every run through of the task will save the data somewhere within this folder!

    Edit the Task​

    Now that the task is up and running we can make our first changes to the code! We'll edit the package.json file to reflect your information.

    1. Create a new branch

      git checkout -b <branch-name>

    2. Open package.json and edit it to reflect your app:

      1. name is your task's name, generally this is the name of our repository
      2. description should be rewritten to better match your task
      3. author is your lab (or PIs) name, email, and website
      4. version should be reset to 1.0.0
      5. repository is the link the GitHub repository you created earlier.

    3. Save your changes and commit them to git:

      git commit -m "Commit message goes here!"

    4. Create a pull request to bring your changes into the main branch

    Next Steps​

    Honeycomb tasks can be configured to run as a web app in Firebase, or as desktop application via electron. The desktop application can receive port signals from EEG, cameras, foot pedals, and more.

    The Firebase page explains how to set up your task with Firebase.

    To learn more about how to configure your task for these different scenarios, see Environment Variables.

    The NPM Scripts page lists every script you can run and which environment they use.

    - +Create repository

    note

    We recommend creating a public repository and leaving Include all branches unchecked

  • Ensure the repositories workflow permissions are set to "Read and write permissions"

    Settings -> Actions -> General -> Workflow permissions

    GitHub workflow permissions settings

    • Additional details about template repositories can be found on the Github Docs.

    Cloning the Repository​

    With the repository now setup it can be cloned onto your computer.

    1. Navigate to the repository on GitHub.

    2. Click the Code button and copy the URL

      GitHub clone repo button

    3. Open a terminal and navigate to where you want the cloned directory

    Terminal.app
    cd 'path/to/directory'
    1. Clone the repo with the following command
    Paste the URL you copied earlier
     git clone https://github.com/<YOUR-USERNAME>/<YOUR-REPOSITORY>
    note

    Git can be downloaded here if it is not already on your system.

    Additional details and alternative methods for cloning a repository can be found on the Github Docs.

    Installing Prerequisites​

    All of the needed programs for Honeycomb must be installed before we can develop our task. We will use a package manager to automatically install them.

    See Prerequisites for more information about these programs.

    Initial Install​

    The most commonly used package manager on macOS is Homebrew.

    1. Paste the following command in a macOS Terminal and follow the prompts to install Homebrew.

      /bin/bash -c '$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)'

    2. Paste the following command and follow the prompts to install the listed programs:

      brew bundle

    3. Install Xcode (not available on Homebrew)

      xcode-select --install
    note

    If you are running into issues after installing the packages please restart your terminal and/or reboot your computer. This should resolve most issues.

    Setting Up Node​

    NVM (Node Version Manager) is a tool for installing and using multiple versions on node on your computer. It must first be installed:

    1. Install NVM

      curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.4/install.sh | bash

    2. Copy the version number listed in .nvmrc. The version may be different than the screenshot below.

      .nvmrc file

    3. Install that version.

      nvm install [version]

    4. Use the needed version. This will automatically check the version listed in the .nvmrc file.

      nvm use

    5. Set the current version as your default

      nvm alias default node
    note

    You can skip step 4 if you've already set a default node version in a different project.

    Install Dependencies​

    There are many node packages used by Honeycomb that also need to be installed. Node (installed in the previous step) comes with its own package manager to install, update, and maintain these dependencies throughout the development lifecycle.

    Install Honeycomb's dependencies
    npm install

    Certain dependencies are best installed globally within node. These tools will be available from the command line anywhere on your system.

    Install Honeycomb's global dependencies
    npm install -g electron firebase-tools dotenv-cli

    Run the Task in Development Mode​

    Running the task in development mode causes it to hot-reload whenever changes are made to the app. This is how you'll run the project while building your task.

    Run the task in dev mode
    npm run dev

    This script launches an electron window with the task and inspector open.

    You can quit the task in the middle of development if needed:

    ⌘ + Q

    Saving data​

    Data is saved throughout the task, even when running in development mode. The location of the task is logged at the beginning of the task wherever you ran npm run dev.

    Note how the data is organized by study and participant. Every run through of the task will save the data somewhere within this folder!

    Edit the Task​

    Now that the task is up and running we can make our first changes to the code! We'll edit the package.json file to reflect your information.

    1. Create a new branch

      git checkout -b <branch-name>

    2. Open package.json and edit it to reflect your app:

      1. name is your task's name, generally this is the name of our repository
      2. description should be rewritten to better match your task
      3. author is your lab (or PIs) name, email, and website
      4. version should be reset to 1.0.0
      5. repository is the link the GitHub repository you created earlier.

    3. Save your changes and commit them to git:

      git commit -m "Commit message goes here!"

    4. Create a pull request to bring your changes into the main branch

    Next Steps​

    Honeycomb tasks can be configured to run as a web app in Firebase, or as desktop application via electron. The desktop application can receive port signals from EEG, cameras, foot pedals, and more.

    The Firebase page explains how to set up your task with Firebase.

    To learn more about how to configure your task for these different scenarios, see Environment Variables.

    The NPM Scripts page lists every script you can run and which environment they use.

    + \ No newline at end of file diff --git a/docs/troubleshooting/index.html b/docs/troubleshooting/index.html index f8aca9a9..f17d4154 100644 --- a/docs/troubleshooting/index.html +++ b/docs/troubleshooting/index.html @@ -4,13 +4,13 @@ Troubleshooting | Honeycomb - +
    -
    Version: 3.2.x

    Troubleshooting

    Inspecting Errors​

    When developing Electron apps there are two processes: main, and renderer. In this case main corresponds to electron-starter.js and its console is wherever you called npm run dev or electron . from. renderer corresponds to the React App - this is everything else. The React app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running npm run dev, it should open by default.

    In case you want to find out where the error is coming from when running the app locally:

    • Try reviewing logs in the terminal
    • Inspect element in your browser by opening your developer tools. For instance, in Chrome, this can be done via the menu View -> Developer or right-clicking and pressing inspect.

    Testing in Linux​

    When running npm test on Linux, you might get an error that mentions ENOSPC. This is because the test runner creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.

    This is a "known issue" with some test runners on Linux, as in discussions here and here.

    One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):

    • Command that initially fails with ENOSPC: npm test
    • Check the configured limit on "watchers": cat /proc/sys/fs/inotify/max_user_watches
    • Edit the relevant Linux config file: sudo vim /etc/sysctl.conf
    • Add a line at the end of the config file: fs.inotify.max_user_watches=100000
    • Save, exit, and reload the config file: sudo sysctl -p
    • Check that the limit has changed: cat /proc/sys/fs/inotify/max_user_watches
    • Retry the initial command, which should now succeed: npm test

    Common issues​

    Installing Dependencies​

    Brew Not Available​

    If you run into issues installing Homebrew in step 1 of Installing Prerequisites it may be because Homebrew is not available on your shell. Older versions of macOS (under 10.14) do not do this automatically.

    Run the following command to manually add the Homebrew installation location to your PATH so it is available in your shell.

    echo 'PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile
    note

    If you're using zsh, also add to your ~/.zshrc file.

    NPM Errors​

    Try deleting your node_modules folder and the package-lock.json then running npm install then npm run rebuild. This should fix most issues.

    - +
    Version: 3.2.x

    Troubleshooting

    Inspecting Errors​

    When developing Electron apps there are two processes: main, and renderer. In this case main corresponds to electron-starter.js and its console is wherever you called npm run dev or electron . from. renderer corresponds to the React App - this is everything else. The React app's console is in the electron/browser window and can be seen by using dev tools to inspect the window. When running npm run dev, it should open by default.

    In case you want to find out where the error is coming from when running the app locally:

    • Try reviewing logs in the terminal
    • Inspect element in your browser by opening your developer tools. For instance, in Chrome, this can be done via the menu View -> Developer or right-clicking and pressing inspect.

    Testing in Linux​

    When running npm test on Linux, you might get an error that mentions ENOSPC. This is because the test runner creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.

    This is a "known issue" with some test runners on Linux, as in discussions here and here.

    One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):

    • Command that initially fails with ENOSPC: npm test
    • Check the configured limit on "watchers": cat /proc/sys/fs/inotify/max_user_watches
    • Edit the relevant Linux config file: sudo vim /etc/sysctl.conf
    • Add a line at the end of the config file: fs.inotify.max_user_watches=100000
    • Save, exit, and reload the config file: sudo sysctl -p
    • Check that the limit has changed: cat /proc/sys/fs/inotify/max_user_watches
    • Retry the initial command, which should now succeed: npm test

    Common issues​

    Installing Dependencies​

    Brew Not Available​

    If you run into issues installing Homebrew in step 1 of Installing Prerequisites it may be because Homebrew is not available on your shell. Older versions of macOS (under 10.14) do not do this automatically.

    Run the following command to manually add the Homebrew installation location to your PATH so it is available in your shell.

    echo 'PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile
    note

    If you're using zsh, also add to your ~/.zshrc file.

    NPM Errors​

    Try deleting your node_modules folder and the package-lock.json then running npm install then npm run rebuild. This should fix most issues.

    + \ No newline at end of file diff --git a/docs/variants/index.html b/docs/variants/index.html index 71cd25fb..85bcc949 100644 --- a/docs/variants/index.html +++ b/docs/variants/index.html @@ -4,13 +4,13 @@ Variants | Honeycomb - +
    -
    Version: 3.2.x

    Variants

    Variant-specific Executables​

    In order to create multiple variants of a task that can be co-installed, it is necessary to add new scripts to the package.json file in addition to creating the necessary environment variables for configuration. Each variant must have a unique, lowercase name. Optionally, a unique icon can be used for each variant by saving multiple icons to the icons directories with the same names as the variants. Example scripts for Windows, Mac, and Linux are shown below.

    Windows:

    "package:windows:<task_name>": "electron-packager . <task_name> --platform win32 --arch x64 --icon ./assets/icons/win/<task_name> --out dist/ --overwrite --asar"
    "postpackage:windows:<task_name>": "electron-installer-windows --src dist/<task_name>-win32-x64/ --dest dist/installers/ --overwrite --homepage https://ccv.brown.edu/ --name <task_name> --exe <task_name>.exe --productName <task_name>"

    Mac:

    "package:mac:,<task_name>": "electron-packager . <task_name> --platform darwin --arch x64 --out dist/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"
    "installer:mac:<task_name>": "electron-installer-dmg ./dist/<task_name>-darwin-x64/<task_name>.app <task_name>-${npm_package_version} --out ./dist/installers/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"

    Linux:

    "package:linux:<task_name>": "electron-packager . <task_name> --platform linux --arch x64 --icon ./assets/icons/mac/<task_name> --out dist/ --overwrite"
    "postpackage:linux:<task_name>": "electron-installer-debian --src dist/<task_name>-linux-x64/ --dest dist/installers/ --arch x64 --overwrite --name <task_name> --productName <task_name> --genericName <task_name> --bin <task_name>"

    Variant-specific Workflows​

    In order to use Github workflows to build and upload executables for each variant, the build.yaml, package.yaml, and release.yaml files must be modified as well. For all three files, a new row should be added to the matrix variable as follows:

    variant: [<comma_separated_list_of_variant_names>]

    Add the following before npm build in the steps section of build.yaml, package.yaml, and release.yaml:

    - name: Load .env file for variant
      uses: xom9ikk/dotenv@v1.0.2
      with:
        path: ./env
        mode: ${{matrix.variant}}

    In package.yaml and release.yaml, replace the # Build electron app package installers section with the following code:

    - name: package electron - windows
      if: startsWith(matrix.os, 'windows')
      run: npm run package:windows:${{ matrix.variant }}
    - name: package electron - linux
      if: startsWith(matrix.os, 'ubuntu')
      run: npm run package:linux:${{ matrix.variant }}
    - name: package electron - mac
      if: startsWith(matrix.os, 'mac')
      run: npm run package:mac:${{ matrix.variant }}
    - name: npm rebuild - mac
      if: startsWith(matrix.os, 'mac')
      run: npm rebuild
    - name: Mac installer
      if: startsWith(matrix.os, 'mac')
      run: npm run installer:mac:${{ matrix.variant }}

    Replace the # Upload installers to github action section in package.yaml with the following code:

    - name: upload win-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'windows')
        with:
          name: ${{ format('win-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
      - name: upload mac-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'mac')
        with:
          name: ${{ format('mac-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
      - name: upload linux-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'ubuntu')
        with:
          name: ${{ format('linux-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb

    Replace the # Upload installers to github release section in release.yaml with the following code:

    - name: Upload app to release - windows
      if: startsWith(matrix.os, 'windows')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
        asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}-setup.exe
        tag: ${{ github.ref }}
    - name: Upload app to release - linux
      if: startsWith(matrix.os, 'ubuntu')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb
        asset_name: ${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_${{ matrix.setting }}_x64.deb
        tag: ${{ github.ref }}
    - name: Upload app to release - mac
      if: startsWith(matrix.os, 'mac')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
        asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}.dmg
        tag: ${{ github.ref }}
    - +
    Version: 3.2.x

    Variants

    Variant-specific Executables​

    In order to create multiple variants of a task that can be co-installed, it is necessary to add new scripts to the package.json file in addition to creating the necessary environment variables for configuration. Each variant must have a unique, lowercase name. Optionally, a unique icon can be used for each variant by saving multiple icons to the icons directories with the same names as the variants. Example scripts for Windows, Mac, and Linux are shown below.

    Windows:

    "package:windows:<task_name>": "electron-packager . <task_name> --platform win32 --arch x64 --icon ./assets/icons/win/<task_name> --out dist/ --overwrite --asar"
    "postpackage:windows:<task_name>": "electron-installer-windows --src dist/<task_name>-win32-x64/ --dest dist/installers/ --overwrite --homepage https://ccv.brown.edu/ --name <task_name> --exe <task_name>.exe --productName <task_name>"

    Mac:

    "package:mac:,<task_name>": "electron-packager . <task_name> --platform darwin --arch x64 --out dist/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"
    "installer:mac:<task_name>": "electron-installer-dmg ./dist/<task_name>-darwin-x64/<task_name>.app <task_name>-${npm_package_version} --out ./dist/installers/ --icon ./assets/icons/mac/<task_name>.icns --overwrite"

    Linux:

    "package:linux:<task_name>": "electron-packager . <task_name> --platform linux --arch x64 --icon ./assets/icons/mac/<task_name> --out dist/ --overwrite"
    "postpackage:linux:<task_name>": "electron-installer-debian --src dist/<task_name>-linux-x64/ --dest dist/installers/ --arch x64 --overwrite --name <task_name> --productName <task_name> --genericName <task_name> --bin <task_name>"

    Variant-specific Workflows​

    In order to use Github workflows to build and upload executables for each variant, the build.yaml, package.yaml, and release.yaml files must be modified as well. For all three files, a new row should be added to the matrix variable as follows:

    variant: [<comma_separated_list_of_variant_names>]

    Add the following before npm build in the steps section of build.yaml, package.yaml, and release.yaml:

    - name: Load .env file for variant
      uses: xom9ikk/dotenv@v1.0.2
      with:
        path: ./env
        mode: ${{matrix.variant}}

    In package.yaml and release.yaml, replace the # Build electron app package installers section with the following code:

    - name: package electron - windows
      if: startsWith(matrix.os, 'windows')
      run: npm run package:windows:${{ matrix.variant }}
    - name: package electron - linux
      if: startsWith(matrix.os, 'ubuntu')
      run: npm run package:linux:${{ matrix.variant }}
    - name: package electron - mac
      if: startsWith(matrix.os, 'mac')
      run: npm run package:mac:${{ matrix.variant }}
    - name: npm rebuild - mac
      if: startsWith(matrix.os, 'mac')
      run: npm rebuild
    - name: Mac installer
      if: startsWith(matrix.os, 'mac')
      run: npm run installer:mac:${{ matrix.variant }}

    Replace the # Upload installers to github action section in package.yaml with the following code:

    - name: upload win-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'windows')
        with:
          name: ${{ format('win-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
      - name: upload mac-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'mac')
        with:
          name: ${{ format('mac-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
      - name: upload linux-installer
        uses: actions/upload-artifact@master
        if: startsWith(matrix.os, 'ubuntu')
        with:
          name: ${{ format('linux-installer-{0}', github.event.inputs.setting) }}
          path: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb

    Replace the # Upload installers to github release section in release.yaml with the following code:

    - name: Upload app to release - windows
      if: startsWith(matrix.os, 'windows')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-setup.exe
        asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}-setup.exe
        tag: ${{ github.ref }}
    - name: Upload app to release - linux
      if: startsWith(matrix.os, 'ubuntu')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_x64.deb
        asset_name: ${{ matrix.variant }}_${{ steps.package_info.outputs.package_version }}_${{ matrix.setting }}_x64.deb
        tag: ${{ github.ref }}
    - name: Upload app to release - mac
      if: startsWith(matrix.os, 'mac')
      uses: svenstaro/upload-release-action@v2
      with:
        repo_token: ${{ secrets.GITHUB_TOKEN }}
        file: dist/installers/${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}.dmg
        asset_name: ${{ matrix.variant }}-${{ steps.package_info.outputs.package_version }}-${{ matrix.setting }}.dmg
        tag: ${{ github.ref }}
    + \ No newline at end of file diff --git a/docs/version_control/index.html b/docs/version_control/index.html index cc90d692..977a30b9 100644 --- a/docs/version_control/index.html +++ b/docs/version_control/index.html @@ -4,13 +4,13 @@ Version Control | Honeycomb - +
    -
    Version: 3.2.x

    Version Control

    Git Overview​

    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.

    Git basics

    If you would like to make any changes to current repository, it is always good to start with creating a feature branch, where you can save all the changes.

    Example branch

    Create a Pull Request​

    Pull requests are useful before you merge your branch with the main branch. You can request a review from your colleagues and check for any conflicts with the main branch. After you pushed all the changes to your branch, you can go to the original GitHub repository and click on the pull request.

    git pr

    git pr info

    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:

      git remote add honeycomb https://github.com/brown-ccv/honeycomb.git

    2. Fetch the changes made to Honeycomb

      git fetch --all

    3. Merge the current Honeycomb repo

      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

    This flow is sometimes referred to as Feature Branch Workflow

    Basic Workflow​

    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.

    Comment styles​

    We encourage using Commitizen, 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​

    CommandBrief
    git add <files>add a file to next commit (stage)
    git commit -m <message>commit staged files
    git pushupload staged commit to repo
    git pullget 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
    # create branch with your feature
    git checkout -b feature_name
    # check the status of your repositoey
    git status
    # commit file contents to the local repository
    git commit -m "My feature is ready"

    # specific message
    # push file contents to the remote (i.e. cloud) repository
    git push origin feature_name

    Alternative options​

    VS Code​

    Most IDEs have some built in tools for working with Git and VS Code is no exception. Check out this overview of source control in VS Code!

    GitHub Desktop​

    GitHub Desktop is a GUI application for working with git. It is one of the programs installed as a prerequisite of Honeycomb. Check out this overview of source control in GitHub Desktop!

    - +
    Version: 3.2.x

    Version Control

    Git Overview​

    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.

    Git basics

    If you would like to make any changes to current repository, it is always good to start with creating a feature branch, where you can save all the changes.

    Example branch

    Create a Pull Request​

    Pull requests are useful before you merge your branch with the main branch. You can request a review from your colleagues and check for any conflicts with the main branch. After you pushed all the changes to your branch, you can go to the original GitHub repository and click on the pull request.

    git pr

    git pr info

    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:

      git remote add honeycomb https://github.com/brown-ccv/honeycomb.git

    2. Fetch the changes made to Honeycomb

      git fetch --all

    3. Merge the current Honeycomb repo

      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

    This flow is sometimes referred to as Feature Branch Workflow

    Basic Workflow​

    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.

    Comment styles​

    We encourage using Commitizen, 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​

    CommandBrief
    git add <files>add a file to next commit (stage)
    git commit -m <message>commit staged files
    git pushupload staged commit to repo
    git pullget 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
    # create branch with your feature
    git checkout -b feature_name
    # check the status of your repositoey
    git status
    # commit file contents to the local repository
    git commit -m "My feature is ready"

    # specific message
    # push file contents to the remote (i.e. cloud) repository
    git push origin feature_name

    Alternative options​

    VS Code​

    Most IDEs have some built in tools for working with Git and VS Code is no exception. Check out this overview of source control in VS Code!

    GitHub Desktop​

    GitHub Desktop is a GUI application for working with git. It is one of the programs installed as a prerequisite of Honeycomb. Check out this overview of source control in GitHub Desktop!

    + \ No newline at end of file diff --git a/index.html b/index.html index 814f27d2..45762d23 100644 --- a/index.html +++ b/index.html @@ -4,13 +4,13 @@ Honeycomb | Honeycomb - +

    Honeycomb

    A template for reproducible psychophysiological tasks for clinic, laboratory, and home use.

    Read the Docs
    Modular and Configurable

    Modular and Configurable

    Honeycomb was designed to be modular, composable, easily configured to deploy to Linux, Mac, Windows, Browsers, PsiTurk, and more

    Packed with automation

    Packed with automation

    Honeycomb includes GitHub Actions that build the executables/deployments for you.

    Based on trusted and mature libraries

    Based on trusted and mature libraries

    Honeycomb relies on mature libraries such as JSPsych, React and Electron

    - + \ No newline at end of file