Skip to content

Contributing code to Oppia

Sandeep Dubey edited this page Oct 31, 2019 · 152 revisions

These instructions are for developers and designers who'd like to contribute code or design help to improve the Oppia platform. If you'd prefer to help out with other things, please see our general contribution guidelines.

Thanks for your interest in improving the Oppia platform! 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. There are also lots of helpful resources in the sidebar, check that out too!

Also, if you'd like to get familiar with Oppia from a user's point of view, you can take a look at the user documentation.

Setting things up

  1. 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.
  2. Fill in the Oppia contributor survey to let us know what your interests are. (You can always change your responses later.)
  3. Create a new, empty folder called opensource/ in your computer's home folder. Navigate to it (cd opensource), then fork and clone (why?) the Oppia repo so that it gets downloaded into opensource/oppia. Then, go to opensource/oppia (cd oppia) and do git remote add upstream https://github.com/oppia/oppia.git (use git@github.com:oppia/oppia.git if using SSH) to add a remote called upstream and link it to Oppia's main repository (this will be used to merge with the latest version on develop, mentioned later on and also to prevent running lint checks on merge commits when you later update your local branch with upstream/develop). Then follow the appropriate installation instructions -- Linux, Mac OS, Windows.
    • Please do not use sudo at any point of the installation. Oppia's setup does not require it. If you face any permissions issues, please make sure that the directory where you're trying to setup Oppia does not require additional permissions. If you run into any other problems during installation, please read these notes.
    • If your upstream is not set correctly, the lint checks will run on merge commits as well. The way to fix this will be to update the upstream url by running the following command: git remote set-url upstream https://github.com/oppia/oppia.git (use git@github.com:oppia/oppia.git if using SSH)
  4. Update your GitHub settings:
    • Set up 2FA on your GitHub account. This is important to prevent people from impersonating you.
    • Go to your Notifications page, and configure it according to your preferences.
    • (Optional) Consider setting up automatic auth so you don't have to type in a username and password each time you commit a change.
    • (Optional) 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.
  5. Familiarize yourself with the resources linked to from the sidebar of this page, especially the overview of the codebase, the coding style guide, and our Frequently Asked Questions. You don't have to read all the other stuff right now, but it's a good idea to be aware of what's available, so that you can refer to it later if needed.
  6. Join the oppia-dev@ mailing list, and say hi on the gitter chat channel!
  7. On your browser, consider pinning both this wiki page (for easy reference later) and the Gitter tab (so that you can keep abreast of new activity). To pin a tab, just right-click the tab you want to pin, and select "Pin Tab".
  8. If you use Sublime Text, consider installing the SublimeLinter, SublimeLinter-jscs and SublimeLinter-pylint plugins, following the instructions on their respective pages.
  9. Take up your first starter project! You can find more details in the next section.

Developing your skills

In general, it's easier to contribute to the Oppia codebase if you have some knowledge of git, as well as at least one of Python or AngularJS. You don't need to know all of this before you start, though! Many of our contributors have picked these skills up concurrently while tackling their first issues.

That said, we strongly recommend that you be open to learning new things. If you need to brush up on some of the technologies used in Oppia, here are some resources that may help:

  • Git and Github are used to make changes to the repository. So, it's good to know how to use them to do basic stuff like branching, merging, pull/push etc. Here is a page we've compiled that contains some links to useful learning materials.
  • AngularJS (v1) is used for Oppia's frontend. A nice youtube video tutorial can be found here and you can check the official tutorial/guide, also for an outline of AngularJS you can take a look into this short overview with pointers to other resources. Most of our open issues are in the frontend and require at least some knowledge of HTML, AngularJS and CSS, so knowledge of frontend coding will serve you well if you'd like to contribute to Oppia over the longer term.
  • If you are new to HTML, some tutorials include Mozilla's guide (which includes some practice assessments), as well as this tutorial for beginners.
  • We also have some backend (python) and devops (bash) projects available, but not as many, so we'd strongly recommend learning AngularJS if you have the opportunity and inclination -- otherwise, the range of projects you can take up will be more limited. That said, let us know at welcome@oppia.org if you'd like suggestions for non-frontend projects, and we'll do our best to help.

Finding something to do...

... as a new contributor

Welcome! Please make sure to follow the setup instructions above if you haven't already. After that, we'd strongly recommend tackling some part of one of the following starter issues:

  • #4057 (frontend; Karma tests)
  • #7450 (backend; Refactoring unit tests)
  • #6240 (writing end to end tests)

so that you can become familiar with the codebase and the development workflow. If you decide to do so, please go ahead and leave a comment saying which part of the issue you're taking, and submit a follow-up PR by following the instructions below. You don't need to wait for approval to get started!

Important Note: Please make sure to read and follow the PR instructions carefully, otherwise your PR review may be delayed.

... after completing two starter projects

After you've completed parts of at least two different starter projects and successfully submitted PRs for them into develop, we'll add you as a collaborator on the Oppia repository. Please visit this link to accept the invitation to collaborate. We'll also get in touch to suggest suitable longer-term projects based on your interests, but please feel free to email us at admin@oppia.org if you don't receive the email!

... as an existing contributor

There are lots of options!

If an issue hasn't got someone assigned to it, and there's no existing PR for the issue (you can check this by scanning the list of existing PRs), feel free to take it up by assigning yourself to it. You don't need to ask permission to do so. Also, if you need help or advice on an issue, you can contact the corresponding team lead, whose GitHub username you can find in the issue's grey label.

Instructions for making a code change

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.

The following instructions describe how to make a one-off code change using a feature branch. (In case you're interested, we mainly use the Gitflow workflow.) Please follow them carefully, otherwise your code review may be delayed.

  1. Choose a descriptive branch name. It should be lowercase and hyphen-separated, such as fuzzy-rules. Also, it shouldn't start with hotfix or release.

  2. Before coding anything, create a new branch with this name, starting from 'develop'. I.e., run:

      git fetch upstream
      git checkout develop
      git merge upstream/develop
      git checkout -b your-branch-name
    
  3. Make commit(s) 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. However, do not write "Fix #ISSUE_NUMBER" (e.g. Fix #99999) in your commit messages, as this will cause Github to close the original issue automatically. You can rename your commit messages using git commit --amend.

    • Before making the commit, do some sanity-checks:

      • Start up a local instance of Oppia and do some manual testing in order to check that you haven't broken anything!

      • Ensure that your code follows the style rules and that it is well-tested.

      • Ensure that the code has no lint errors and passes all automated tests by running the presubmit script:

          bash scripts/run_presubmit_checks.sh
        
      • Use a tool like git diff or meld to check that the changes you've made are exactly what you want them to be, and that you haven't left in anything spurious. Make sure to do this before you push.

    • 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}}
      

      Make sure to do this from the command line (and not GitHub's Desktop client), since this also runs some important presubmit checks before your code gets uploaded to GitHub. If any of these checks 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').

  4. 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 issue #bugnum: add a warning when the user leaves a page in the middle of an exploration.").
      • If the PR resolves an issue on the issue tracker, the title must start with "Fix #bugnum: ". This will be the case for most PRs.
      • However, if your PR fixes part of a bigger issue (e.g. the first-contributor-issues listed above), please use "Fix part of #bugnum: " instead. Otherwise, GitHub will close the entire issue automatically when your PR is merged.
    • Fill out the PR checklist, ensuring that your PR description includes the issue number (e.g. "This PR fixes issue #bugnum" or "This PR fixes part of issue #bugnum").
    • If users can now do any actions as a result of your PR that they couldn't do before (e.g. rating an exploration, adding a hint to a state, or replying to a feedback thread), cc the QA team (using @oppia/qa-team) so that they can ensure that there is sufficient automated test coverage and/or add it to the list of critical user journeys. (This is important to prevent the new functionality you added from breaking in the future!)
    • Click "Create pull request", then immediately check the "Files changed" tab on your PR on GitHub and read it carefully to make sure that the changes are correct (e.g., that you haven't left out important files that should be part of the PR. (If not, please fix this by making additional commits, or by closing this PR and submitting a new one, before requesting a review.) This is a good way to catch obvious errors that would otherwise lead to delays in the review process.
    • Request a review from the issue's "owner" (which can be found in a label on the issue) and also set them as the PR assignee.
    • Leave a top-level comment on your PR saying "@{{reviewer}} PTAL", where {{reviewer}} is the GitHub username of your reviewer. ("PTAL" means "Please take a look".)
    • After a while, check your PR to see whether the Travis checks have passed. If not, follow the instructions at "If your build fails...".
    • Then, wait for your code to get reviewed! While you're doing so, it's totally fine to start work on a new PR if you like. Just make sure to checkout the develop branch and sync to HEAD before you check out a new branch, so that each of your feature branches is based off the main trunk.
  5. 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. (Continue to use descriptive commit messages. If your commit addresses lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".)
        • Always make commits locally, and then push to GitHub. Don't make changes using the online GitHub editor -- this bypasses lint/presubmit checks, and will cause the code on GitHub to diverge from the code on your machine.
        • Never force-push changes to GitHub once reviews have started. This will delay your review, because it overwrites history on GitHub and makes the incremental changes harder to review.
      • In addition, reply to each comment via the Files Changed tab, choosing the "Start a review" option for the first comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. Once you have replied "Done" (or similar), you can also click "Resolve conversation" to close the comment thread. When you've responded to all comments, submit the review to add all your messages to the main thread. All comments must be responded to and 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 -- see https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line]...
        ...[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:

      • Run bash scripts/start.sh and play with the dev server in order to make sure that everything still works.
      • Check that the changes in the "Files Changed" tab are what you intend them to be.
      • Write a top-level comment explicitly asking the reviewer to take another look (e.g. "@XXX PTAL"), and set them as the assignee for the PR.
    • At the end, the reviewer will merge the pull request.

  6. Tidy up! After the PR status has changed to "Merged", delete the feature branch from both your local clone and the GitHub repository:

      git branch -D new-branch-name
      git push origin --delete new-branch-name
    
  7. Celebrate. Congratulations, you have contributed to Oppia!

Notes

  • Our central development branch is develop, which should be clean and ready for release at any time. All changes should be done in feature branches based off of develop.

  • If you face any issues while setting things up, or your PR build fails unexpectedly (please go through the logs of the PR build and try debugging the problem on your own first!), feel free to ping @oppia/dev-workflow-team for help.

  • To find the author of a particular change in a file, run this 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.

  • If your PR includes changing the location of the file, if you simply move the file by cut and paste method, then the git will track it as a new file. So to prevent this, use:

    git mv old_file_path new_file_path
    

    By using this command git will detect the file as a renamed file.

  • Important PRs marked with “critical” label need to be tested in the backup server before being merged. For this, one of the release coordinators (with access to deploy) should checkout a new branch from develop, merge the branch from the PR into the new branch, and initiate deployment to the backup server from this branch. The PR author should give specific testing instructions for the changes (like which job to run, what the expected output is, etc) and the coordinator should verify the same. Once successfully tested, the PR should be merged into develop. This is to prevent cases like exploration migrations which can result in data corruption (as it will auto-migrate) if the migration isn’t safe. The "critical" label needs to be applied on PRs that change data validation checks, and other possibly critical changes which could affect production data.

Communication channels

Mailing lists

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.
  • oppia-dev-workflow is the mailing list for communication between Dev Workflow Team, and for workflow issues faced by the contributor.

We also have a developer chat room here. Feel free to drop in and say hi!

Clone this wiki locally
You can’t perform that action at this time.