Skip to content

Latest commit

 

History

History
210 lines (121 loc) · 21.7 KB

Contributing-code-to-Oppia.md

File metadata and controls

210 lines (121 loc) · 21.7 KB
Raw

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

Thanks for your interest in improving the Oppia platform! This page explains how you can get involved.

If you run into any problems along the way, we're here to help! Check out our [[Getting Help Page|Get-help]] for the communication channels you can use. If you find any bugs, you can also file an issue on our issue tracker. 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.

Important! Please read this page in its entirety before making any code changes. It contains lots of really important information. You should also read through our [[guide to making pull requests|Rules-for-making-PRs]].

Table of Contents

How to find information in the repo and the wiki

  1. In the top-right corner of the repository page, you'll find a search bar. Click on it to expand the search options.
  2. Enter the search query you want to use. You can search for specific keywords, file names, code snippets, or any other relevant information you're looking for.
  3. GitHub provides some advanced search filters that you can use to refine your search further. You can filter results by the file type, code language, author, or specific locations within the repository. To use these filters, click on the "Filters" button next to the search bar and select the desired options.
  4. Press Enter or click on the search button to initiate the search.
  5. GitHub will display the search results based on your query. The results will show matching files, code snippets, issues, pull requests, commits, discussions, wikis and other relevant information which you can see in left side after search.
  6. You can click on any search result to view more details or explore the code/files associated with it.

Additionally, GitHub also provides an advanced search syntax that allows you to construct more complex queries. You can find more information about this syntax in the GitHub documentation.

How.to.find.information.in.the.repo.and.the.wiki.mov

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. If you do not sign the CLA, any PRs you open will be closed.

  2. Fill in the Oppia contributor survey to let us know what your interests are. (You can always change your responses later.)

  3. Say hi and introduce yourself on GitHub Discussions!

  4. Install Oppia following the [[installation instructions|Installing-Oppia]]. If you run into any issues, please check out the [[troubleshooting instructions|Troubleshooting]]. If you want help setting up a code editor, also check out our [[guide to common IDEs|Tips-for-common-IDEs]]. If the above resources don't help and you're still stuck, please check GitHub Discussions to see if any existing threads address the issue. If not, feel free to start a new thread explaining what you've tried and what you're seeing, so that we can try and help you!

  5. Update your GitHub settings:

    • Set up 2FA on your GitHub account. This is important to prevent people from impersonating you.

      When using 2FA, you might need to create a personal access token so that you can log in from the command line. Alternatively, you can log in using SSH.

    • Set your GitHub notification preferences here. The important thing is to make sure you notice when someone replies to a conversation you're part of -- many people choose "Not watching" so that they do not get overwhelmed. Selecting "Watching" will notify you about everything that happens on the Oppia repository (which is a lot!), and notifications specifically addressed to you might end up getting lost in the noise.

    • (Optional) Consider setting up automatic auth so you don't have to type in a username and password each time you push a change. Note that this isn't an issue if you use SSH.

  6. Familiarize yourself with the resources linked to from the sidebar of this page, especially the [[overview of the codebase|Overview-of-the-Oppia-codebase]], the [[coding style guide|Coding-style-guide]], and the [[Frequently Asked Questions|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.

  7. Take up your first Oppia starter issue! (See below on how to do this.) Make sure to read and follow the [[PR instructions|Rules-for-making-PRs]] closely so that your PR review proceeds smoothly.

    • In your browser, consider bookmarking the [[guide to making pull requests|Rules-for-making-PRs]] for easy reference, as well as the "my issues" page (so that you can keep track of the issues assigned to you).

    • Facing any problems (including non-coding ones)? Please feel free to create a GitHub Discussion and get help from the Oppia community. You can use this avenue for asking anything -- questions about any issue, who to contact for specific things, etc.

  8. When you have merged PRs that correspond to two different pre-existing GitHub issues, please fill in this form to become an Oppia collaborator! This will grant you access to the repository, and allow you to join a team. (But please don't create your own issues and then make PRs for them -- that won't count.)

Developing your skills

See our [[page of learning resources|Learning-Resources]] for suggestions on how you can improve your development skills. When you take up an issue that requires programming languages or tools you are unfamiliar with, check out that page for resources that other developers have found useful when learning.

Our wiki has lots of useful documentation, including tutorials which are denoted in the sidebar by 👣 icons. Use them to learn key skills that are needed for solving issues.

We also strongly recommend looking through the resources under "Developing Oppia" in the wiki sidebar. Good places to start include the [[Overview of the Oppia codebase|Overview-of-the-Oppia-codebase]] and the [[tips on how to find the right code to change|Find-the-right-code-to-change]].

Finding something to do

Good first issues for new contributors

Welcome! Please make sure to follow the instructions above if you haven't already.

After that, you can choose a good first issue from the list of good first issues. These issues are hand-picked to ensure that you don't run into unexpected roadblocks while working on them, and each of them should have clear instructions for new contributors. If you see one that doesn't, please let us know via GitHub Discussions and we'll fix it. For other issues, you might need to be more independent because we might not know how to solve them either.

Please only work on issues that are labelled "Impact: High" or "Impact: Medium".

Caution

  • Do not work on "Impact: Low" or "Backlog" issues. If you submit a fix for those, you will probably be asked to pick a different issue. Those issues often haven't been looked at closely yet, and might not be priorities for implementation.
  • Do not work on issues with the "triage needed" label, including issues that you recently filed. These issues haven't been vetted yet and might get closed or modified during the weekly triage process.

As a new contributor, if you run into any problems along the way, we're here to help! Check out our [[Getting Help Page|Get-help]] for the communication channels you can use.

You can also browse good first issues for each of the core Oppia Web teams to find something you'd enjoy working on! Please only choose issues that have not yet been assigned, unless the issue is a "checkbox issue" with multiple claimable parts. Here are the project boards for the different teams:

How to tackle good first issues

When you've found a good first issue you'd like to tackle, please investigate it first to understand why the issue is happening. Here are some things you should do:

  • Read the entire discussion thread to understand what has been tried so far.
  • Try to reproduce the issue on your local dev server. (For Contributor Dashboard issues, the [[Contributor Dashboard onboarding guide|Contributor-dashboard]] has some useful setup information. For Learner and Creator Experience related issues, you can refer to the [[LaCE onboarding guide|LaCE-onboarding-guide]].)
  • Figure out why the problem is happening, and [find the relevant code in the Oppia repository to change|Find-the-right-code-to-change]. If you have trouble with this, feel free to ask on GitHub Discussion and explain what you've tried doing so far.
  • Try and get a fix working on your local dev server. You will need to do this in order to claim the issue (see below).

Once you have a good understanding of the issue, you can ask for it to be assigned to you by leaving a comment as follows:

  • Show a video of the fix working correctly on your local machine. (For user-facing changes, your video should show a URL that starts with localhost:8181.)
  • Explain clearly what you did to tackle the issue (at a minimum, point to which file(s) you modified and describe the changes you made). You can include code snippets if you like.
  • @-mention the leads of the corresponding project (you can find their details here), letting them know you'd like to work on it and when you can submit a PR by.

If your proof looks good and your explanation makes sense, we'll assign the issue to you. Once assigned, feel free to submit a PR by following the [[instructions for making a PR|Rules-for-making-PRs]]. We recommend actively working to get your PR merged once you are assigned, because we will de-assign contributors if the PR is closed for being stale or there is no activity after the initial assignment.

Important

Please follow the [[PR instructions|Rules-for-making-PRs]] carefully, otherwise your PR review may be delayed or your PR may be closed.

Getting help

Generally, we aim to review PRs within 48 hours. If you have not heard from a reviewer within 48 hours, feel free to leave a comment on the review thread, and also add a message to the "Contacting Folks" section of GitHub Discussions. Don't wait longer than 2 days to do this.

If you run into a general problem, please create a GitHub Discussion thread to get help from the Oppia community.

Note: It is important to pick a starter issue that you are able to do! If you find that the issue you are tackling is too difficult, it is fine to choose another one instead and come back to it later.

Contributor Roles

If you want to play a more integral role in sustaining Oppia, you can look forward to being able to take on more responsibilities as you continue to make quality contributions to the project. Here is a rough outline of the roles developers play at Oppia:

graph TD;
    Everyone("Everyone (read access)") --> Contributors("New Contributors (read access)") --Get 2 PRs Merged--> Collaborators("Collaborators (triage access)") --Make Sustained Quality Contributions--> Members("Members (write access)") --> Lead(Project Leads<br /> and<br /> Core Maintainers);
Loading

As a new contributor, you won't have any permissions on the repository except to read the code, so you'll need to ask other developers (or Oppiabot) to assign reviewers to your PR or add labels to your issue.

After you've completed parts of at least two different issues and successfully submitted PRs for them into develop, you can fill in this form to become an Oppia collaborator! This will grant you access to the repository, and allow you to join a team of your choice. Once you fill out the form, we'll mail you a collaborator invite link for the Oppia repository -- this is a manual process, and may take up to 48 hours. Please visit this link to accept the invitation to collaborate. Feel free to email us at [email protected] if you don't receive the email!

Then you'll be a collaborator with triage access, which lets you assign reviewers and labels. No more asking for reviewers to be assigned! If you continue to make quality contributions, you may be added as a member of the Oppia organization, which grants you write access. Then you'll be able to restart tests, serve as a code owner, and review pull requests.

Finally, after you've been contributing to the project for a while, you may become a project lead and/or core maintainer. In those roles, you'll help plan and lead Oppia's development.

If you ever wonder why you don't have permission to perform some action on the Oppia repository, it might be because of your role. GitHub details each role's privileges in more detail in their documentation.

Tasks for Existing Contributors

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, and let the corresponding team lead know. Also, if you need help or advice on an issue, you can contact the corresponding team lead. See the Projects page for details of who the team leads are.

Tips for Success

  1. Make dependent (“stacked”) PRs to ensure smaller time between reviews and subsequent PRs. A large PR results in difficulty to review for the reviewer as well as difficulty in making changes according to a review for an author. So, it is better to create smaller PRs which deliver a single small goal. If you have code changes dependent on a PR, it is better to create a separate PR for those changes.

  2. Try and follow test-driven development. This is the easiest way to make sure the code you wrote is working fine. The basic idea is to first write tests for the expected behaviour and then write code that will pass those tests. Refer to our [[guides for writing good tests|Tests]].

  3. If you're stuck on something, ask for help instead of letting it block all your work. It can be difficult to know when to ask for help, so one rule of thumb is to ask whenever you've been unable to make progress for an hour.

  4. When asking questions, follow our guide to [[getting help|Get-help]] to make sure your question gets to the right people and has the information they need to help you.

  5. Remember that you're working with volunteers, nearly all of whom spend most of their time at school or a job. Don't be surprised if it takes a few hours for someone to get back to you (they might be in a different time zone!).

  6. Do a self-review to find your own mistakes. Reviews by other developers take time, so any mistakes you can catch by yourself will speed things up.

  7. Take the time to understand what the code you are changing is doing. Sometimes we see PRs for changes that don't do anything useful or that don't make sense given the context of the code. These won't get merged.

  8. If you are making a contribution which involves changing some user interface or introducing a new feature, it is good to start with a design doc to avoid wasting efforts later. Follow our [[guide for writing design docs|Writing-design-docs]].

  9. You will almost certainly run into bugs where you aren't sure what the cause is. This is normal! Our [[debugging guides|Debugging]] will help you investigate the problem.

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.

  • Sometimes, GitHub comments in the main conversation thread don't have a reply box. This seems to be a quirk with GitHub: apparently the reply box doesn't show up on outdated threads if you're currently in the middle of a review (or a reply to someone else's review) that you haven't submitted. After you submit the review, the reply field should show up again.

  • If you want to do a codebase change that is large and somewhat repetitive, do a small trial PR first for a limited subset of the change, and check with reviewers whether the approach makes sense. Only after getting that trial PR merged (or at least approved by all reviewers) should you do the full change.

    This helps because, if you just did the full PR at the outset instead, then if a reviewer requests changes to the approach, you'd need to go back and modify all the files. On the other hand, with a trial PR, addressing an initial round of changes is less work, and by the time you get to the full PR, you'd already know what you need to do!

  • 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. You can also view this information on GitHub. Just navigate to the file you are interested and click the "Blame" button:

    Screenshot showing the blame button on GitHub

  • Important PRs marked with the “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.