Create experiment protocol
We use the Github Flow workflow when working with lab code to create new experiments or editing existing ones.
If you are new to git and Github, I recommend starting with GitHub Desktop. It's a great way to get your feet wet with git and learn how the process works. If you'd rather use the command line git, go ahead. If you are comfortable with git, you should know how to create a branch, commit your changes, and open a pull request without detailed instruction here.
Clone the pennchildlanglab/experiments repository and create a branch for your experiment. Name your branch after your experiment so we know what it is.
Make sure you publish your branch back to the experiments repo.
Open the repo in your text editor (I like Atom) and copy the template folder. Name the copy expX, where X is your experiment's ExperimentID. This will set you up with a skeleton experiment containing lab-specific code (like writing your data to the lab's database).
Build on the template files to code your experiment. We program experiments with javascript, using the jsPsych library. There is a great tutorial available here. If you need some help, you can read our tips in the How To section.
As you create your experiment, you usually want to test it to see how it is looking. To do that, you'll need to start a php server on your computer in the terminal. First, navigate to the directory in which your code is stored (mine is saved in a folder called github/experiments , but yours will be different).
cd github/experiments
You can use ls to make sure you are in the right place
ls
Once you are inside your local copy of the experiments folder, you'll start a php server
php -S localhost:8000
This starts your php server at the address http://localhost:8000. You should see a notification that the document root is wherever your local copy of the experiments folder is. Here is a gif of the whole thing in action:
Hint: a very common mistake is to start the server inside the subfolder for your experiment (e.g. exp23). The code requires libraries that are inside the experiments folder, so you need to launch your server from there so it has access to those.
You can run a test on your local machine by visiting https://experiments.childlanglab.com/ and selecting test locally on the Run Experiment tab. If you entered a port other than 8000, you can edit the listening on box to reflect that.
Make sure you commit changes to your branch as you work.
And push your changes to your branch.
When you've finished your experiment (and tested locally), the next major step is to open a pull request so we can check your code.
Make sure you've tested your experiment and it works locally
When you create the pull request, you'll see a screen like this:
Everyone will be able to see a summary of everything you've changed, and Github will let us know if there are any conflicts with the master branch (e.g. you changed something you shouldn't). There is also a place for us to discuss the changes.
Katie does this part!
If everything looks good, Katie will merge your branch with the master. We use a push-to-deploy approach, which means that the files in the master branch are the ones that go live on the website. When Katie merges your changes with the master branch, your experiment is deployed!
git push deploy
Your experiment will be live on experiments.childlanglab.com. But you aren't ready to run participants, yet. Read Deploy experiments for next steps.
It is possible that you will need to update your study. Before making any changes, make sure that the branch you are working on is up to date with the master, otherwise it may be in conflict with the current master and therefore cannot be merged. You can do this in command: Starting from your branch, use git merge master to merge all the changes in the master with your branch. Then you can make changes to your code, and follow the procedures of "commit your changes" etc. as above.
