Contributor-dashboard.md

Overview

The contributor dashboard page on the Oppia site allows users to submit content suggestions (currently translations and practice questions) directly to lessons. These suggestions are then reviewed, and either accepted, or sent back for revision. See the user docs for step-by-step instructions how to contribute content suggestions.

How items for contribution are populated

Translate text tab

Every list item on the "Translate Text" tab corresponds to a particular lesson and all of its pieces of text content. In the codebase, we refer to each of these list items as opportunities. The contributor dashboard automatically shows a translation opportunity for a lesson when the following are true:

1. The lesson (also called an exploration) corresponds to a chapter in a story of a published classroom subject, e.g. "Decimals" (also called a topic). See the user docs for an overview of these terms.
2. There is at least one piece of text content in the lesson that does not yet have an accepted translation.

Submit question tab

Every list item on the "Submit Question" tab corresponds to a particular skill, e.g. "Adding Decimals", in a topic. The contributor dashboard automatically shows a question opportunity for a skill when the following are true:

1. The skill is part of a published classroom topic.
2. The skill does not yet have 10 accepted practice questions.

Additional feature behavior

• Unlike with submitting translation suggestions, users need to be allowlisted by an admin before being able to submit question suggestions. Until then, the user will not see the "Submit Question" tab on the contributor dashboard page:

  

• Users cannot review their own suggestions.

• Users must be allowlisted by an admin to be able to review translation suggestions in a particular language or to review question suggestions.

• Reviewers can edit a suggestion and accept the edited version.

• Only subjects/topics associated with a classroom, e.g. Math, are surfaced in the topic/subject selector of the "Translate Text" tab.

Admin page

There exists a separate admin page for the contributor dashboard at /contributor-admin-dashboard. There, an admin user can:

1. allowlist a user to submit question suggestions
2. allowlist a user to review translation suggestions in a particular language
3. allowlist a user to review question suggestions
4. remove rights from a user for any of the above

See this doc for step-by-step admin instructions. This may be useful for developing locally as a coder as well.

Local development

Some setup is usually required when developing locally for the contributor dashboard since before a user can submit a content suggestion to a lesson, a lesson needs to exist. Additionally, the requirements outlined in How items for contribution are populated must be satisfied.

To populate contributor dashboard data, first start your local server using:

python -m scripts.start

And then navigate to Admin page and go to the "Roles" tab. Assign yourself the "Curriculum Admin" role.

Now go back to the "Activities" tab on the Admin page and click on "Load Data" as shown in the below screenshot.

This will generate three translatable opportunities, for which suggestions can be made through the "Translate Text" tab of Contributor Dashboard page (http://localhost:8181/contributor-dashboard).

If you need to generate more sample data, follow the step-by-step instructions on how to generate sample data manually. See this doc.

Accepted translation suggestions

Upon accepting a translation suggestion, the translation becomes a part of the target exploration. To view these translations as the exploration creator, turn on the feature flag named "exploration_editor_can_modify_translations". See this page for instructions to turn on feature flags.

Then, go to the exploration editor page corresponding to the target exploration ID of the accepted suggestion. Go to the translations tab. Switch to translate mode and select the target language of the suggestion. On the graph, click on the content card corresponding to the suggestion. The translation should appear in the edit translation text area.

Code pointers

See the Oppia codebase overview for a general overview of Oppia's code structure.

Frontend

• core/templates/pages/contributor-dashboard-page/: Main directory of Angular components, frontend services, HTML, CSS.
• core/templates/domain/opportunity/: Frontend opportunity models.
• core/templates/domain/suggestion/: Frontend suggestion models.

Highlights:

• core/templates/pages/contributions-and-review/: Component for the "My Contributions" tab. Handles viewing and reviewing suggestions.
• core/templates/pages/modal-templates/: Templates for pop-up modals, e.g. for submitting/reviewing a question/translation suggestion.
• core/templates/pages/question-opportunities/: Component for showing question opportunity list items on the "Submit Question" tab.
• core/templates/pages/translation-opportunities/: Component for showing translation opportunity list items on the "Translate Text" tab.

Backend

Controllers

• core/controllers/contributor_dashboard.py: Handles fetching opportunities and contributor dashboard metadata such as eligible translatable text content.
• core/controllers/suggestion.py: Handles everything suggestion related, e.g. submitting and reviewing suggestions.
• core/controllers/contributor_dashboard_admin.py: Handles admin actions.

Domain services

• core/domain/opportunity_services.py: Backend services for operating over opportunities.
• core/domain/suggestion_services.py: Backend services for operating over suggestions.
• core/domain/email_manager.py: Contains services for sending contributor dashboard related emails, e.g. for notifying users when they have been added as a reviewer.

Domain models

• core/domain/opportunity_domain.py: Domain models for opportunities.
• core/domain/suggestion_registry.py: Domain models for suggestions.

Storage

• core/storage/opportunity/gae_models.py: Storage models for opportunities.
• core/storage/suggestion/gae_models.py: Storage models for suggestions.

E2E Tests

• core/tests/webdriverio_desktop/contributorDashboard.js: E2E tests for contributor dashboard CUJs.
• core/tests/webdriverio_utils/ContributorDashboardAdminPage.js: Utilities for navigating/asserting on the admin page.
• core/tests/webdriverio_utils/ContributorDashboardPage.js: Utilities for navigating/asserting on the contributor dashboard page.
• core/tests/webdriverio_utils/ContributorDashboardTranslateTextTab.js: Utilities for navigating/asserting on the "Translate Text" tab.

Sample coding exercise

To familiarize ourselves with the codebase, let's go through an exercise to show custom description text for the translation opportunity subheading:

This text will be populated in the backend and propagated to the frontend.

1. First, start a local server and follow the steps outlined in the doc linked in Local development to populate translation opportunities. Then, navigate to /contributor-dashboard and click on the "Translate Text" tab. You should see something like the following:

Notice the subheadings are formatted [TOPIC NAME - CHAPTER TITLE]. Now let's make our code changes.

2. Add a new field description of type str to the PartialExplorationOpportunitySummaryDict backend model in core/domain/opportunity_domain.py. This will allow us to pass a description from the backend to the frontend.

3. Populate the backend description field with some custom text in the returned translation opportunities in core/controllers/contributor_dashboard.py like so:

4. Add a description field to the ExplorationOpportunitySummaryBackendDict and ExplorationOpportunitySummary classes in core/templates/domain/opportunity/exploration-opportunity-summary.model.ts. Make sure to update the constructor definitions as well.

5. Populate the description field in the _getExplorationOpportunityFromDict() method of the frontend API service: core/templates/pages/contributor-dashboard-page/services/contribution-opportunities-backend-api.service.ts. This step adds the description field from the backend dict to the frontend model.

6. Finally, go back to core/templates/domain/opportunity/exploration-opportunity-summary.model.ts and modify getOpportunitySubheading() to return the description instead of the topic and chapter title. Make sure all your changes are saved, refresh the page, and you should see your custom description in all the opportunity subheadings!

Note

For this example, our description field was not fetched from persisted storage and was instead manually set in the backend controller.

Appendix

1. Contributor dashboard overview: More in-depth developer focused overview of the system design of the contributor dashboard.