How to Start Contributing Code

Owned by Bill DeRusha (Deactivated)
Last updated: May 24, 2024 by Sara Burns
6 min read

This article is for people who are interested in contributing code to the Open edX open-source project space but don't know what contributions would be most valuable. 



Start Here!

Before we can merge your contribution you'll need to sign a Contributor Agreement.  We suggest starting that process sooner rather than later.

  1. If you are contributing as an individual go ahead and sign the Individual Contributor Agreement.

  2. If your work will be contributed as part of a company or institution email mailto:legal@axim.org 

How do I know if I should sign the individual contributor agreement or contribute as part of a larger organization?

If you will be working on your contribution during school or work time or are using a GitHub or email account administered by that organization you likely fall under our larger organization agreements.  You may also be under contractual obligation from your employer that all code you write is their property or maybe their property if written on a machine that they purchased.  If you have any questions about whether you should sign the individual contributor agreement or contribute as part of an organization email your situation to legal@tcril.org and they will help find the right agreement for you.

Process Overview

Finding Something To Work On

Right now, we're in the process of retooling how we capture and advertise "good first tasks". One source of candidates is this list of issues labeled “help wanted”. We also encourage you to check out our Working groups! There are a few working groups that may have some work they can help guide you through as a new contributor to the project. Particularly:

  • The Build-Test-Release WG (or BTR): they manage our named releases, which come out each June and December. They particularly need help starting mid-Feb through June and mid-August through December. See the Working groups page to get in touch with them and view their project board.

  • The frontend working group: they manage the state of our frontend, including both new features and upgrades. They'd love more people to join them!

  • The DEPR WG: they work on deprecating various aspects of the Open edX platform. Some deprecations are pretty approachable, others are rather complex. Reach out to them to see if they've got anything you might be able to work on.

  • The Educators WG is developing, migrating, and improving documentation for the Open edX Platform. This is a first task that is non-technical, and open to anyone who builds on the platform. To learn more about helping with this, reach out in the #wg-educators Slack channel or the discussion board and let the group know you are interested.

The other working groups are very interesting (and worth attending!) but don't have a backlog of work.

Do you have an idea of what to work on? That's awesome! We encourage you to post your ideas on the Open edX discussion forums to get feedback on your idea and get connected to others that can help you out. Please clearly state your idea, and what you plan to do, link to any relevant code/screenshots, and ask specifically for what type of feedback or help you are looking for.

Dev Env!

Tutor is the official Docker-based Open edX distribution, both for production and local development. There's a Tutor Topic to get help specifically on Tutor or you can post in the Development category on the Open edX forum if you have questions about set-up or development. 

Getting Support

Join the #dev Open edX Slack channel to ask questions and get support.  There may be also more channels to get technical support, for example, #ops is better suited if you are running your own instance and have questions. Also, consider using the Open edX forums - please search for your answer first.  Why?  The Slack history is deleted after 6 months but the forums never delete history, so your questions there will be displayed to people searching for similar questions in the future.

Making Your First Pull Request

Are you used to making branches within an Open edX repo, but can’t for a certain one? See Working with Personal Forks.

When you are ready to submit changes, create a Pull Request.  (Don't forget to sign the Contributor Agreement)

  1. Be sure to reference which ticket your code is resolving.

  2. If you did work for a working group, post your pull request in the appropriate WG Slack channel

  3. Communicate with the reviewer about the code and respond to feedback.

  4. Once your PR is approved it will be merged by the reviewer.

  5. Celebrate 🎉

How To Streamline Getting Your Contribution Merged

When pull requests come in they need to be reviewed by team that maintains the repository. Depending upon that teams priorities, it may take some time to get your review schedule. We aim at having predicable lead times and transparency about what is happening and when. There are things that you can do as a contributor to help.

  1. If your change in still in progress or experimental, please open the pull request as a draft. We won’t focus on reviews until the code is ready and will reduce wasted attention on both sides.

  2. Make sure that you describe the purpose of the change that you are proposing clearly in the description of the pull request and why the change is valuable.

  3. Read the bot messages on your PR carefully.

  4. Use conventional commits following the Open edX project standard.

  5. Allow admins to push commits onto your branch. GitHub has settings that allow reviewers to push commits onto your branch. This feature is valuable when the branch is out of date with the base. Reviewers can update your branch from the base with a merge commit that will isolate those changes, but decrease the back-and-forth, which can add days to review times.

  6. Mention related pull requests so reviewers can review them as a single body of work and avoid context shifts.

  7. Check the checks. GitHub required that the Open edX team run checks manually for new contributors. When there are failures, please review them and address them quickly to ensure a timely completion of your review. Failures you may see include linting errors, test failures, failures related to decreased test coverage, etc. On occasion failures may not be related to your change, but can be fixed by merging in updates on the base branch. If you believe this is the case, please update your branch.

Working with GitHub Issues

Work on Open edX is often tracked on GitHub issues, which are organized on GitHub project boards.

Anyone with a GitHub account can interact with our GitHub issues in some basic ways using issue commands. For example, if you would like to work on an issue, let everyone know by simply commenting assign me !

Once you have established yourself as involved in a working group or some other project, feel free to request “Triage” access to our repositories. Open an Axim Request using the “Onboarding” template, and specify that you would like Triage access in order to be more involved in the project. Provide a link to what you’re working on, and @-mention another GitHub user who you have been working with who can vouch for you. If Axim grants the request, then you will find that you’re now able to manage assignees, labels, and handful of other aspects of Open edX GitHub issues.

Once you have Triage access, you can also ask project leaders to give you access to individual project boards that you want to help manage, which will let you change status and other metadata on project issues.

Giving Feedback

We are always looking to improve this process and make it easier for people to contribute to the platform.  Your feedback is a very important part of that process.

Please fill out the survey posted on your pull request once it is closed. If you have specific praise, or constructive criticism you think the community could benefit from, please post on the forums.

 

More Details

If you’re looking for more help or more details about the contribution process, check out our more detailed documentation on read the docs!