Create experiment protocol

Protocol for creating an experiment

We use the Github Flow workflow when working with lab code to create new experiments or editing existing ones.

Github Flow at-a-glance

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.

Create a branch

Clone the pennchildlanglab/experiments repository and create a branch for your experiment. Name your branch after your experiment so we know what it is.

Create a branch in the Github Desktop

Make sure you publish your branch back to the experiments repo.

Copy templates folder

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

Write your code

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.

Test your changes locally

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


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:

Start a php server to test code locally

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

Run a local test from the lab's dashboard

Commit your changes

Make sure you commit changes to your branch as you work.

And push your changes to your branch.

Open a pull request

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.

Click Create Pull Request button to do that
You'll be taken to the github repo to complete the request


  • Make sure you've tested your experiment and it works locally

Discuss and review

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.

Merge and deploy

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 But you aren't ready to run participants, yet. Read Deploy experiments for next steps.

Update a study

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.