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