Create experiments

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. If you need some help, you can read our tips in the How To section.

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.

Requirements

  • Make sure you've tested your experiment locally

  • Include a link to your final data screen (e.g. this)

  • Include a link to your preregistration draft google doc

  • Include a copy of your database table design

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 experiments.childlanglab.com. 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.