These instructions are for developers and designers who would like to contribute code to Oppia. If you'd prefer to help out with other things, please see our general contribution guidelines.
Thanks for your interest in contributing code or design help to the Oppia project! This page explains how to get set up, how to find something to work on, and how to make a code change. If you run into any problems along the way, please file an issue on our issue tracker, or get help by posting to the developers' mailing list. You might also want to look at the resources on the developer wiki.
- Please sign the CLA so that we can accept your contributions. If you're contributing as an individual, use the individual CLA. If your company owns the copyright to your contributions, a company representative should sign the corporate CLA.
- Fill in the Oppia contributor survey to let us know what your interests are. (You can always change your responses later.)
- Join the oppia-dev@ mailing list, and say hi on the gitter chat channel!
- While you're waiting for a reply, create a new, empty folder called
opensource/in your computer's home folder. Navigate to it (cd opensource), then fork and clone the Oppia repo so that it gets downloaded intoopensource/oppia. Then follow the appropriate installation instructions (Linux, Mac OS, Windows). - Update your GitHub notification settings: * Go to your settings page (click the Settings option under the profile menu in the top right), then go to 'Notification center' and ensure that everything's as you want it. * Go to the Oppia repo, and click 'Watch' at the top right. Ensure that you're not 'ignoring' the repo, so that you'll be notified when someone replies to a conversation you're part of.
- (Optional) You may also want to set up automatic auth so you don't have to type in a username and password each time you commit a change.
The primary chat channel that the team uses is Gitter. Feel free to hang out there! (You might also consider 'pinning' the tab in your browser, so that it's easily accessible.)
We have also recently started offering office hours for new contributors on Gitter, where you can get your questions answered! You can find the schedule on the wiki homepage. We also maintain a list of Frequently Asked Questions.
If you have an idea for something to do, first check if it's already on the issue tracker. If so, add a comment to the issue saying you'd like to work on it, and we'll help you get started! Otherwise, please file a new issue, and say you'd like to work on it.
If you don't have an idea for something to do, try searching the issue tracker for something that looks interesting! High-priority issues are tracked by milestones, so we recommend starting there, but feel free to take on any of the others as well. Each issue is tagged based on which part of the site it affects, and also categorized based on the type of help needed. If this is your first contribution, we recommend picking one of the following types of issues:
- TODO: code means that the issue is suitable for new developers: the overall solution is known and is described in the issue, and the only thing left to do is code it.
- TODO: design (UI/Interaction) means that the issue is suitable for new UI designers, interaction designers, artists and writers. In general, it means that UI design help is needed, and the deliverable would usually be a mockup, drawing, prototype or text that conveys what the feature should look like.
- TODO: design (usability) means that the issue is suitable for new usability testers. In general, it means that we have one (or more) ideas or designs for a project, and usability testing/research is needed to find out which one to go with.
These issues, also tagged as 'starter projects', are usually local to a small part of the codebase. They tend to be easier, so they give you a chance to get your feet wet without having to understand the entire codebase. If you'd like some help finding an issue to work on, please don't hesitate to reach out to us at the developers' mailing list or the Gitter chat room! Also, if the issue you're working on has a grey label of the form "team-name (@team-lead)", please feel free to reach out to that team lead for help or advice on that issue -- they should be able to answer questions about that area of the codebase.
For reference, here are descriptions of what the other 'TODO' tags mean:
- TODO: tech (instructions) means that the overall solution is generally known, but newcomers to the codebase may need additional instructions to be able to implement them. Adding instructions, such as where to make the necessary changes, will help move these issues to the
TODO: codestage. - TODO: tech (breakdown) means that the approach is known, but needs to be broken down into single-person projects.
- TODO: tech (design doc) means that the problem is known, but the solution needs fleshing out. In that case, the best thing to do is to prepare a short doc outlining the solution approach and implementation plan, add a link to it on the issue thread, then discuss it before starting implementation.
- TODO: design (breakdown) means the UX design is completed, but the issue needs to be broken down into single-person projects.
- TODO: design (UX) means the way that the user interacts with this feature needs to be planned. The best way to approach this is to outline the core user journeys (probably using slides), and discuss them on the issue thread, so that the feature can move forward.
- TODO: triage means we aren't sure whether to work on this issue or not. It would be helpful to give comments on this issue in support of or against implementing that feature, or mention if you encountered something similar.
Working on your first Pull Request? You can learn how from this free series: How to Contribute to an Open Source Project on GitHub.
If your change isn't trivial, please talk to us before you start working on it -- this helps avoid duplication of effort, and allows us to offer advice and suggestions. For larger changes, it may be better to first create a short doc outlining a suggested implementation plan, and send it to the dev team for feedback.
Our central development branch is develop, which should be clean and ready for release at any time. In general, all changes should be done as feature branches based off of develop. (In case you're interested, we mainly use the Gitflow workflow, which also incorporates master, hotfix- and release- branches -- but you don't need to worry about these.)
Here's how to make a one-off code change. (If you're working on a larger feature, see the instructions at the end.)
- Choose a descriptive branch name. It should be lowercase, hyphen-separated, and a noun describing the change (so,
fuzzy-rules, but notimplement-fuzzy-rules). Also, it shouldn't start withhotfixorrelease. - Create a new branch with this name, starting from 'develop'. In other words, run:
git fetch upstream
git checkout develop
git merge upstream/develop
git checkout -b your-branch-name
- Make a commit to your feature branch. Each commit should be self-contained and have a descriptive commit message that helps other developers understand why the changes were made.
-
You can refer to relevant issues in the commit message by writing, e.g., "Fixes #105".
-
In general, code should be formatted consistently with other code around it; we use Google's Python and JavaScript style guides as a reference. If you use Sublime Text, consider installing the SublimeLinter, SublimeLinter-jscs and SublimeLinter-pylint plugins, following the instructions on their respective pages. Please also ensure that your code follows these additional style rules.
-
Please ensure that the code you write is well-tested.
-
Before making the commit, start up a local instance of Oppia and do some manual testing in order to check that you haven't broken anything! After that, ensure that the added code has no lint errors and passes all automated tests by running the presubmit script:
bash scripts/run_presubmit_checks.sh -
To actually make the commit and push it to your GitHub fork, run:
git commit -a -m "{{YOUR COMMIT MESSAGE HERE}}" git push origin {{YOUR BRANCH NAME}}Before your code gets uploaded to GitHub, a script is automatically executed that checks the styling of all changed JavaScript and Python files and runs the front-end tests. Run the push command in command line, and not GitHub's Desktop client, as the script needs access to other tools like pip.
If any of the tests fail, the push will be interrupted. If this happens, fix the issues that the tests tell you about and repeat the instructions above ('commit' and then 'push').
If you need some help with your code and therefore want to put non functioning code into your GitHub fork to show it to other developers, you can force a push with
git push origin {{YOUR BRANCH NAME}} --no-verify.
- When your feature is ready to merge, create a pull request.
- Go to your fork on GitHub, select your branch from the dropdown menu, and click "pull request". Ensure that the 'base' repository is the main oppia repo and that the 'base' branch is 'develop'.
- Add a descriptive title explaining the purpose of the PR (e.g. "Fix #bugnum: add a warning when the user leaves a page in the middle of an exploration."). The "Fix #bugnum: " prefix must be included if this PR resolves an issue on the issue tracker.
- Click "Create pull request". An admin will assign a reviewer to your commit.
- Address review comments until all reviewers give LGTM ('looks good to me').
- When your reviewer has reviewed the code, you'll get an email. You'll need to respond in two ways:
- Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".
- In addition, please reply to each comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. All comments must be resolved before LGTM can be given.
- Resolve any merge conflicts that arise. To resolve conflicts between 'new-branch-name' (in your fork) and 'develop' (in the oppia repository), run:
git checkout new-branch-name
git fetch upstream
git merge upstream/develop
...[fix the conflicts]...
...[make sure the tests pass before committing]...
git commit -a
git push origin new-branch-name
- Once you've finished addressing everything, and would like the reviewer to take another look, please write a top-level comment explicitly asking them to do so.
- At the end, the reviewer will merge the pull request.
- Tidy up! Delete the feature branch from your both your local clone and the GitHub repository:
git branch -D new-branch-name
git push origin --delete new-branch-name
- Celebrate. Congratulations, you have contributed to Oppia!
The pre-push hook should take care of most of the style issues (for Python and JavaScript code). However, we follow a few additional rules that aren't baked into the linter. Please adhere to these as well, in order to minimize back-and-forth during review.
General
- The last character in each file should be a newline. (If you're using Sublime, you can enforce this locally by adding
"ensure_newline_at_eof_on_save": trueto your user preferences file.)
Python
-
There should be two empty lines before any top-level class or function definition.
-
Prefer string interpolation over concatenation -- e.g. prefer:
'My string %s' % varname
over
'My string ' + varname
-
When indenting from an open parenthesis ('('), prefer indenting by 4 rather than indenting from the position of the parenthesis. For example, prefer:
my_function_with_a_really_long_name( 'abc', 'def', None)
over
my_function_with_a_really_long_name('abc',
'def',
None)
-
Docstrings should start with """ and end with """. The content of each docstring should be left-aligned. For example:
"""Check whether an email message with the same recipient_id, email_subject and (cleaned) email_html_body has been sent in the last DUPLICATE_EMAIL_INTERVAL_MINS. """ -
Never use backslashes to end a line. It's hard to tell whether they're escaping newlines, spaces, or something else. Use parentheses instead to break the line up, e.g.:
my_variable = (
my_very_long_module_name.my_really_long_function_name())
JavaScript
- We are moving away from using underscores as prefixes for variable names, so, in the future, use
var localVariableand notvar _localVariable. Instead, we are adopting the convention that anything declared usingvaris private to the controller/service/etc. If you want a variable to be accessible to the controller, declare it on $scope instead.
CSS
- Within each CSS rule, attributes should be alphabetized (e.g. 'height' before 'margin' before 'top'). This makes it easy to find the value of an attribute if there are lots of them.
- If the CSS class is oppia-specific, prefix it with
oppia-. This helps distinguish it from CSS classes used by other third-party libraries. - For directives, include the CSS in the directive template file, similar to what we do in
core/templates/dev/head/components/exploration_summary_tile_directive.html. (Note that, in this case, all CSS rules should start with the top-level CSS class of the directive, so that they don't affect other elements outside it.) All other CSS should go incore/templates/dev/head/css/oppia.css.
We do not use author tags in files, since they tend to be inaccurate or become stale when the author is no longer a regular contributor. However, you can still find the author of a particular change in a file by running the command:
git blame file-name
The output will show the latest commit SHA, author, date, and time of commit for each line.
To confine the search of an author between particular lines in a file, you can use:
git blame -L 40,60 file-name
The output will then show lines 40 to 60 of the particular file.
For more git blame options, you can visit the git blame documentation.
We have several mailing lists in the form of Google Groups that you can join:
- oppia-announce is for announcements of new releases or blog posts.
- oppia-dev is the main mailing list for communication between developers, and for technical questions.
We also have a developer chat room here. Feel free to drop in and say hi!
GitHub teams allow contributors working on similar areas of the Oppia codebase to to find and contact each other easily. These teams will be accessible via the GitHub alias @oppia/{{team-name}}. Mentioning a team in a issue or comment will notify all members in the team. During the issue triage process, issues will be assigned to a team, and members of the team are encouraged to comment on or take up the issue. If a contributor who is not part of the team is working on an issue, they will also be able to ask the team for guidance.
You can indicate which team(s) you want to join by filling in the form here, or requesting to join/leave teams on the teams page. You can join or leave a team at any time.
Design documents and meeting minutes are in our Google Drive folder.