Getting Ready for Open Source Day
Table Of Contents
How To Get Started
Welcome to Oppia! This wiki page aims to provide a quick-start guide to Oppia and guide you in making your first changes to Oppia’s codebase. For a longer, more comprehensive guide to getting started, please see our full “Getting Started” page.
Some background info about the project:
The Oppia codebase sits in Github at https://github.com/oppia. Some knowledge of Github would be useful to make changes to the repository. Take a look at the Github guides for a brief introduction to Github along with some common methods!
AngularJS (v1) is used for Oppia’s frontend. A nice youtube video tutorial can be found here. For an outline of AngularJS, please see this short overview with pointers to other resources.
If you are new to HTML, some useful tutorials are Mozilla’s guide (which includes some practice assessments), as well as this tutorial for beginners.
Some new features will require backend work. Oppia’s backend is written in Python 2.7.
Setting Up Before Open Source Day
Sign the CLA
Oppia is licensed under Apache v2. Please sign the CLA so that we can accept your contributions and redistribute the code you contribute under this license.
Once you’ve done this, you’ll receive a confirmation email which includes some suggestions for next steps! These are completely optional, but if time permits, it might not be a bad idea to try a starter project to get familiar with the codebase and development workflow.
Create a GitHub account
To make code changes, you will require a Github account with 2 factor authentication set up.
Set up 2FA on your GitHub account. This is important to prevent people from impersonating you.
You might need to create a personal access token so you can log in from the command line.
Go to your settings page (click the Settings option under the profile menu in the top right), then go to ‘Notifications’ and ensure that everything’s as you want it.
(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.
Install Oppia on your machine
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. (If you run into any problems during installation, please read these notes.)
Some useful links
Gitter GHC chatroom | General chatroom
Oppia Wiki Page | Documentation | Full “Getting Started” page
Github Cheat Sheet | Guide
Python 2.7 Introduction | Tutorial | Documentation
Bash Introduction
Making A Code Change
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. For a more detailed explanation on how to make a code change, please take a look at this wiki page. In order to make a change in the repository, you can follow the steps below:
Sync with the develop branch and create a new branch, starting from develop (e.g. your-branch-name). The branch name should be descriptive, lowercase, and hyphen-separated. It shouldn’t start with the words hotfix or release.
git fetch upstream
git checkout develop
git merge upstream/develop
git checkout -b your-branch-name
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.
Before your code gets uploaded to GitHub, a script is automatically executed that checks the styling of all changed files and runs some front-end tests. Run the ‘push’ command in command line 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’).
When your feature is ready to merge, create a pull request on Github. When you create a pull request, you will be assigned a reviewer who will take a look at your code.
Address review comments until all reviewers give LGTM (‘looks good to me’).
Resolve any merge conflicts that arise.
Run
python -m scripts.startand play with the dev server in order to make sure that everything still works, and also to install any new dependencies that have been added since you last synced the repo.WARNING: Do not 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. Always make commits locally, and then push to GitHub.
Tidy up! After the PR status has changed to “Merged”, delete the feature branch from both your local clone and the GitHub repository
Celebrate. Congratulations, you have contributed to Oppia!
What to do when you are stuck
Oppia has a Gitter chat room where everyone can post their questions and help each other out! The organizers and mentors will also be walking around to help with any questions.
List of Projects
Easy
Project 3: Limit questions to a specific amount in the question player
Project 5: Lint checks for the yield keyword and inline styling
Project 8: Fix the UI in the card view of the creator dashboard
Project 9: Convert the QuestionSummary dictionary into a frontend domain object
Project 13: Link check to ensure require statements are alphabetized
Intermediate
Hard
For this open source day, we tried to shortlist projects that are fairly self contained, and can be completed within 3-4 hours by a group of 2-3 people. We also tried to pick those projects from our issue tracker itself so that you get an idea of what it’s like to contribute to Oppia on a regular basis.
Each project has a brief explanation, a link to the issue tracker, the skills required, and some deliverables. We encourage you to look at the issue tracker link for the project that interests you. You can comment expressing interest in that project (and mention you will be working on it for OSD). You can also gain more context and ask questions to help get a kickstart for the day. Please work in groups of 2-3 people.
This list is not an exhaustive list of projects. If none of these projects appeal to you, you can take a look at our issue tracker and comment on the issue that interests you. (also mention that you will be working on it during the OSD event so that we are aware). Please tag us (@dchen97 and @vinitamurthi) in any comment expressing interest in a project so that we get notified about this!
If you would like to understand the vocabulary and general structure of content in Oppia, you can take a look at this document.
Project 1: Change the Style of Playthrough Buttons in Improvements Tab
Context
The “View Playthrough” button in our Improvements tab currently is shaped like a hexagon, which doesn’t fit the overall style of the page anymore. We need a new design and implementation for this button that better suits the broader styling of the Lesson Improvements tab.
Deliverables
Create design for new “View Playthrough” button style
Change the styling for the “View Playthrough” button to match the new style
Required Skills
AngularJS, Web Development, UX Design, JavaScript
Difficulty
Easy
Project 2: Render Suggested Changes in Suggestion Improvement Cards
Context
Suggestion Improvement cards only render the latest message of the associated thread:
To view the actual suggestion, creators must click the “Review Thread” button and then the “Review Suggestion” button from the thread modal:
We’d like to render the suggestion (and possibly the current version) directly on the card to minimize the indirections that creators need to step through when trying to understand what the suggested improvement requires from them.
Deliverables
Modify the Suggestion Improvement card to display the suggestion directly on the card
(optional) Modify the Suggestion Improvement card to display the current version of the message directly on the card
Required Skills
AngularJS, Web Development, UX Design, JavaScript
Difficulty
Intermediate
Project 3: Limit questions requested to a specific amount in the question player
Context The question player is a reusable element that is used anywhere we would like to show tests to the user (currently in practice sessions, and in review tests). Fetching questions from the database can be expensive so we would like to set a limit on the number of questions we request in any test. Currently users of the question player can ask for an infinite number of questions. However, we would like to limit that down to 20 questions. For that we need to add checks to the frontend controller and backend controller to limit the number of questions we can request in the question player. Both the frontend controller and the backend controller should return an error message to callers of the question player if they ask for > 20 questions.
Deliverables
Throw an error in the backend controller of the question player if the number of questions requested is greater than 20. Throw an error in the frontend API of the question player if the number of questions is > 20.
Required Skills
Python
Difficulty
Easy
Project 4: “Card is too long” warning is not prominent enough, and isn’t shown when the RTE is closed
Context
Whenever a card in a lesson is too long, a warning should display prominently enough that the lesson editors know to adjust this content (i.e. split up between multiple cards, shorten text, etc.). However, right now, this warning is only displayed when you open up the Rich Text Editor (RTE) for the card and this warning is buried at the bottom of the editor in a way that users do not immediately see or notice the warning. Additionally, when you close the RTE, this warning disappears altogether.
Steps to reproduce the behavior:
Log in and create an exploration.
Type lots of text in the content card
View the blue text at the bottom of the Rich Text Editor (RTE):
This warning disappears when the RTE is closed:
We need this warning to be redesigned such that it is more prominently displayed when users view the card outside of the RTE and inside of the RTE.
Deliverables
Design the new way in which users will see the “Card too long” warning both inside and outside of the RTE.
Change the “Card too long” warning to match this new style
Required Skills
AngularJS, Web Development, UX Design, JavaScript
Difficulty
Intermediate
Project 5: Lint check to ensure a single space after yield keyword in python and to avoid inline styling
Context
For a project as large as Oppia, code health is extremely important. We have a style guide that we expect new developers to read and follow, however it is equally important to have tests that enforce this style guide. That’s where our lint checks come in. Currently we have several lint checks, we would like to improve them by adding two more checks: Ensuring a single space is present after the ‘yield’ keyword in python files (#6276), and ensure that we do not have any inline styles in HTML pages. Instead we would like to have CSS classes wherever there are inline files(#6212). This project needs to add the lint check, as well as fix any parts of the code base that violate these new checks.
Deliverables
Remove all cases where there is more than 1 space after the yield keyword in python files
Add a lint check to enforce this
Replace all cases of inline styles with CSS classes
Add a lint check to stop allowing inline styles.
Required Skills
Python
Difficulty
Easy
Project 6: Convert frontend dicts to domain objects
Context
We want to represent objects in the frontend using frontend domain objects rather than raw, opaque JS dicts. For example, here are some frontend domain objects for Explorations (see the *ObjectFactory.js files): https://github.com/oppia/oppia/tree/develop/core/templates/dev/head/domain/exploration.
The aim of this issue is to convert remaining frontend objects that are still represented as dicts to actual domain objects. Ideally, for each object, a single PR should be created that updates the entire frontend to replace references to the old JS dict with the new domain object instead.
Deliverables
Change “Change” (the objects in core/templates/dev/head/pages/exploration_editor/ChangeListService.js) to domain objects
Change “Link” (cf., e.g., core/templates/dev/head/components/VersionDiffVisualizationDirective.js and other graph visualizations: look for objects that have a “source” and a “target” field) to domain objects
Required Skills
JavaScript
Difficulty
Easy
Project 7: Capture screenshot in Travis e2e tests
Context
Considering the size of the codebase, maintaining end to end tests is important to ensure that new changes don’t break our old functionality. We use protractor end to end tests to ensure all our critical flows aren’t broken. It tests every flow and performs all the tasks that a normal user would perform in order to interact with oppia. The e2e tests take time to run and usually run on Travis (or continuous build system) anytime we create/update a PR. Whenever a test fails, a user has to manually rerun the test in their system in order to see what point in the flow the test fails. Instead we would like to capture a screenshot anytime the test fails and then report that in Travis. This is so that the PR author can quickly identify the error and work on fixing it. (Useful Link)
Deliverables
Capture a screenshot when the test fails and report it
Required Skills
Javascript, Protractor JS
Difficulty
Intermediate
Project 8: Resolve styling for card view on creator-dashboard
Context
Currently, card views on our creator dashboard look like the following:
We need to adjust the styling for the cards to look like the following:
Deliverables
Change the card views on the Creator Dashboard to follow the desired styling
Required Skills
AngularJS, Web Development, JavaScript
Difficulty
Easy
Project 9: Convert questionSummary dict to a frontend domain object
Context
Currently in questions-list.directive.ts, the elements in ctrl.questionSummaries are still backend dicts, which are never converted to a frontend domain object. We should convert the backend dict to a domain object and pass the domain object around instead.
Deliverables
Convert the questionSummary dictionary into a frontend domain object
Required Skills
Angular JS
Difficulty
Easy
Project 10: Remove underscores in routes to improve SEO
Context
If possible underscores should be avoided within a URL. These URLs should be replaced with Hyphens if possible. The underscores make it harder for the search engine to determine site relevance to the searched.
For example, ‘oppia.org/get_started’ should be ‘oppia.org/get-started.’
In order to maintain consistency, not only should URLs be changed to this standard, but all routes in the codebase should follow this standard (e.g. ‘’’r’/preferenceshandler/profile_picture’, profile.ProfilePictureHandler’’’ in main.py).
Additionally, we should ensure that all old URLs redirect to the new pages to minimize any broken links.
Deliverables
Change all routes in the codebase to use hyphens (‘-’) rather than underscores (‘_’)
Required Skills
Python, JavaScript
Difficulty
Easy
Project 11: E2E Tests
Multiple people can work on this
Context
This project is aimed to complete writing all e2e tests for functional capabilities. The general procedure to write such tests is as follows:
Try manually doing the action you are trying to test.
Get a list of smaller actions needed by the user to complete the action (like, click button X to navigate to page Y, then input “text” in component Z)
At each stage, there should be some way to assert that the smaller action has completed. (This includes waiting for a page to load, waiting for a button to become clickable, etc).
The e2e test written must perform the exact same set of smaller actions, and verify that the action is completed.
More details and guidelines for writing an e2e test can be seen in the Github issue.
Deliverables
Pick up and complete any of the pending e2e tests mentioned in #6240
Required Skills
JavaScript
Difficulty
Varying difficulty
Project 12: Refactor dicts in the frontend to use camel case key
Context
At present many dicts in frontend have underscore_cased keys which prevent explicit typing of the object as it raises tslint errors regarding the casing. All of these dicts should camel case (Example: camelCase) instead.
For the full list of files that need to be refactored, take a look at the issue.
Deliverables
Change files listed above so that all dicts use camel case
Required Skills
JavaScript, Python
Difficulty
Intermediate
Project 13: Add a lint check to ensure require(…) statements are alphabetized
Context
At Oppia, we have a style guide that we expect new developers to read and follow, however it is equally important to have tests that enforce this style guide. We use lint checks to ensure that the oppia codebase follows the style guide. In this project, we would like to add another lint check to ensure that all require(…) statements are in alphabetical order.
Deliverables
Remove all cases where the require statements are not alphabetized in the code base
Add a lint check to enforce this
Required Skills
Python
Difficulty
Easy
Project 14: Enable animated GIFs in the lessons
Context
Animated GIFs provide a powerful way of conveying information in the lessons. However, currently animated GIFs do not play in any of the lessons. In this project, we would like to enable animated GIFs in lessons. In order to test out this behavior you can:
Create an exploration
Add an animated GIF with several frames to the content section of the exploration
Play the exploration
When the exploration is played you will notice that the GIF will not animate.
Deliverables
Investigate the root cause of why the animated GIFs are not animating
Enable animated GIFs in explorations
Required Skills
HTML, CSS, Angular JS
Difficulty
Intermediate
Project 15: Disable the ‘Save and Publish’ button in the question editor when the question doesn’t have an interaction
Context
When creating a question for a skill, the creator can try to go ahead and create the question without filling any details by clicking on the ‘Save and Publish’ button. Clicking on the button causes an error, but the fact that the button is green indicates that the question can be created without any interaction being filled. This is at odds with other publish/save buttons in Oppia editors which only turn green once all errors are resolved.
Deliverables
Ensure the ‘Save and Publish’ button is enabled only after the question has an interaction in the question editor
Required Skills
Angular JS
Difficulty
Easy
Project 16: Add a tutorial for the topic editor on first visit
Context
Currently, the topic editor, accessible through the topics and skills dashboard, does not have a tutorial for first time visitors. So, this issue aims at adding that, similar to the one in exploration editor, to the topic editor.
Deliverables
Create simple design doc to outline what the tutorial should look like and how users would walk through it
Implement tutorial based on this design doc
Required Skills
Python, AngularJS, Web Development, UX Design, JavaScript
Difficulty
Hard
Project 17: Make Answers Anonymous in the Statistics Tab
Context
Currently in our statistics tab, we show all answers to explorations so that creators have information on how their exploration performs. In this project, we would like to protect our learners from being identified. We’ll accomplish this using k-anonymity. From Wikipedia: “A release of data is said to have the k-anonymity property if the information for each person contained in the release cannot be distinguished from at least k - 1 individuals whose information also appear in the release.”
We’d like the statistics tab to have this property to protect learners from being identified. Anonymity can give our learners confidence in playing our explorations, and would improve the overall privacy of Oppia.
As far as implementation goes, we should only show a particular answer in the stats tab when k unique learners have input that same answer. Additionally, we should only show such answers if there are at least j of them in total. The Github issue has more guidelines on how to go about the implementation.
Deliverables
Write a design doc on the approach that will be taken to enforce this
Complete the implementation to enable k-anonymity
Required Skills
Angular JS, Python
Difficulty
Hard