Contributor Guidelines¶
Interested in helping write the code behind the Lookit platform? Thanks for supporting open source science! This page describes the process any would-be contributor should plan to use. We have included some beginner-friendly details in case you are new to open source projects.
The content of this page applies to all three Lookit repos: lookit-api
(Lookit site), ember-lookit-frameplayer
(system for displaying experiments & components to use), and lookit-docs
(the documentation you’re reading now).
Where’s the code I need?
If you only want to change something about the Lookit site, without touching experiment functionality (for instance, to add a question to the demographic survey or change how studies are sorted), you will only need to run lookit-api and can follow the Django project installation steps. If you want to develop experiment frames or change how the experiment player works, you will need to follow the steps for local frame development, installing both lookit-api and ember-lookit-frameplayer and telling them how to talk to each other. Your changes, however, will likely be limited to ember-lookit-frameplayer.
Prerequisites¶
To contribute to the lookit-api codebase, it will be very helpful to have a (a) a strong grasp of Python and (b) some familiarity with the Django framework. Learning Python is outside the scope of these docs, but if you want someplace to start, we highly recommend Think Python. If you’re already familiar with Python but haven’t used the web framework Django, we highly recommend taking the time to complete the official Django tutorial.
To contribute to the ember-lookit-frameplayer codebase - e.g., when creating your own experiment frames - it will be helpful to have (a) a strong grasp of Javascript and (b) some familiarity with Ember.js. However, we’re really not using that much of the functionality of Ember, and if you’re just making some new frames, we would recommend getting started by trying out modifications of an existing frame to get your feet wet, rather than trying to learn Ember from scratch.
Getting started¶
At a high level, we are roughly following a Forking Workflow version of Gitflow as described here.
You should plan to make feature-specific branches off of the develop
branch (for lookit-api, lookit-docs) or master
branch (for ember-lookit-frameplayer) of a local copy of the code running on your own machine. This will keep the codebase as clean as possible.
First create your own fork of lookit-api, ember-lookit-frameplayer, and/or lookit-docs. Follow the directions for installation of lookit-api or ember-lookit-frameplayer if needed.
Ignoring some files¶
You may want to configure a global .gitignore on your machine and include your virtualenv(s) along with any files specific to your system. A sample global .gitignore is available here – you can tell git to globally ignore files specified in a .gitignore file via:
git config --global core.excludesfile ~/path/to/your/.gitignore_global
Add your own feature and submit a Pull Request¶
Keep your commit history clean and merge process simple by following these steps before starting on any new feature.
One time only, add the original repo as a remote to your fork, e.g., if you are contributing to lookit-api you would run a command like this:
SSH:
git remote add upstream git@github.com:lookit/lookit-api.git
HTTPS:
git remote add upstream https://github.com/lookit/lookit-api.git
Anytime a PR is merged or changes are pushed (or you’re starting this process for the first time), you should run:
git checkout develop
git pull upstream develop
in order to make sure you are working with an up-to-date copy of the develop branch.
Once you have the most recent develop code, pick an issue (or create a new one) which your new feature will address and create a new branch off of develop. Note: our project convention is to prepend feature/ or hotfix/ to the feature or issue name for a richer annotation of the commit history.
If you want to create a new validation feature, for example, you might name it like this:
git checkout -b feature/my-validation-feature
Now you can run git branch and should see an output like this:
$ git branch
develop
master
* feature/my-validation-feature
Proceed with writing code. Commit frequently! Focus on writing very clear, concise commit statements and plentiful comments. If you have poor comments or zero tests, your PR will not be merged.
If you are aware of changes in the branch you forked from, rebase your branch from that changing branch (in our case that is develop) by running:
git rebase develop
and then resolving all merge conflicts.
On lookit-api
, you should then update dependencies like this:
pip install -r requirements/defaults.txt
python manage.py migrate
python manage.py test
On ember-lookit-frameplayer
, you should update dependencies using the package manager yarn.
Next, push all your local changes to your own fork. You should push your code (making sure to replace feature/my-validation-feature
with whatever your branch is actually called):
git push --set-upstream origin feature/my-validation-feature
Prior to finalizing your commit, make sure to clean up your code to comply with PEP8. Since both black and isort are included in our development dependencies, you should just be able to run isort -rc . --skip venv
to fix your imports, and similarly black . --exclude=venv
to “blacken” your changes. With both commands, replace venv
with the actual name of your virtual env directory so that you don’t blacken/isort your dependencies.
When your branch is ready (you’ve tested your changes out, and your code has comments and tests), submit a Pull Request! To do this, go to GitHub, navigate to your fork (in this case the github extension should be /your-username/lookit-api), then click new pull request
. Change the base to develop
and the compare to feature/my-validation-feature
. Finally, click Create pull request and describe the changes you have made. Your pull request will be reviewed by Lookit staff; changes may be requested before changes are merged into the develop branch. To allow Lookit staff to add changes directly to your feature branch, follow the directions here.
IMPORTANT: WHEN YOUR PR IS ACCEPTED, stop using your branch right away (or delete it altogether). New features (or enhanced versions of your existing feature) should be created on brand new branches (after pulling in all the fresh changes from develop
).
Writing your tests¶
In lookit-api
, you should generally add to or edit the tests.py
file in the appropriate app (e.g., exp/tests.py
). You can run tests like this:
python manage.py test
For more information see https://docs.djangoproject.com/en/2.1/topics/testing/.
In ember-lookit-frameplayer
you should generally edit the tests under tests/
, but as
you will see there is currently very little coverage. Just try to leave it better than you found it.
In ember-lookit-frameplayer
, you should generally add a test file under tests/unit/components/
if you have created a new frame. As you can see, we do not have a strong convention for this yet except for randomizer frames.
To learn more about how testing is supposed to work for ember-lookit-frameplayer
, see https://guides.emberjs.com/v2.11.0/testing/.
Creating a release (ember-lookit-frameplayer)¶
The ember-lookit-frameplayer repo is semantically versioned.
The release process is relatively manual for now because the expected workflow isn’t finalized (it’s currently almost entirely a one-person project).
Work should be completed and tested on a feature branch, then merged into develop.
To create a new major or minor release:¶
- When a set of features is ready to release, create a release branch off of develop named
release/vX.Y.Z
- Change version number in package.json in the release branch.
- Turn on readthedocs builds for the release branch.
- Make PRs from the release branch to master and develop, and merge commit.
- Create a new release on GitHub, exactly matching the version name used above. Include release notes explaining what has been added/changed. For major versions (backwards-incompatible changes), include step-by-step instructions for updating study protocols (e.g., “1. If your study contains a frame with
kind: "exp-lookit-oldsurvey"
, replace “exp-lookit-oldsurvey” with “exp-lookit-survey”. It will work the same way, the name has just changed.”)
To create a new bugfix release for the latest version:¶
Follow the steps above except don’t turn on readthedocs builds.
To create a new bugfix release for an older version:¶
- Create a new release branch off of the target release branch (e.g.,
release/v3.1.5
). Increment the version in the new branch name (e.g.,release/v3.1.6
). - Apply appropriate patch and increment version on new bugfix branch.
- Create a new release on GitHub, exactly matching new version name. Include release notes explaining what has been fixed.