2.4. Code Considerations#

This is a checklist of all of the things that we expect developers to consider as they are building new, or modifying existing, functionality.

2.4.1. Basic Code Quality#

As described in Process for Contributing Code, your code should meet basic Open edX project standards: it should be accessible, internationalized, and meet the concerns of analytics.

2.4.2. Feature Documentation#

Documentation can occur in multiple places - in code, in decision records, or in formal feature documentation.

OEP-19 Developer Documentation describes the various ways to provide documentation of your code and features to a developer audience. This includes API documentation, decision records (ADRs and OEPs), and README files. Of course, you should always provide detailed, informative comments within your code and excellent docstrings for your functions and classes!

If you have developed a new feature, created an XBlock, or otherwise see that a topic is missing in this documentation, you can create one or more new pages in this document and submit a pull request to have the content added. Follow the guidelines in Getting Started.

Additionally, please see the section on Open edX Named Releases - consider documenting your change for the upcoming Named Release.

2.4.3. Feature Rollout Concerns#

When writing your feature, consider the ways in which your code might be rolled out on various Open edX instances. OEP-17 Feature Toggles describes the many reasons why you might use a feature toggle, including releasing incrementally, beta testing, and providing one Open edX release where the feature is optional before making it the default. Utilizing various Waffle flags, you can gate your feature using an on/off switch. Within edx-platform, you can also utilize CourseWaffleFlag, a toggle that allows you to gate a feature per-course.

Waffle flags should be well-documented when they are used. Some of the Waffle flags used in edx-platform, as well as how they are documented, can be seen in the lms/djangoapps/courseware/toggles.py file. (As a note, you can view all Waffle flags in edx-platform here: Feature Toggles, and please be sure to document any Django settings you define as well - those are documented here: Settings.)

2.4.4. Operational Impact on edx.org#

The edx.org website continuously deploys the latest version of the Open edX code directly onto its site. This means that, for most repos, once your code is merged to master/main it will be deployed live on edx.org within a few hours. This is very cool - your changes are live, immediately! - and it also means that edx.org does the community a large service of testing our code in advanced of the next named release.

However, this also means that if your code causes a problem on edx.org, your pull request may get reverted. Please pay attention to PRs that are especially prone to problems (for example, database migrations) and be prepared to answer questions posted to your PR for the day or so after it merges.

2.4.5. Open edX Named Releases#

Open edX Named Releases come out every six months. They are cut in early April and early October, tested for two months, and released in June and December. If you are introducing breaking changes, complicated migrations, deprecations, or anything else of note, please note your changes on the appropriate release page of the Open edX Release Planning wiki page. Especially important is information that system installers or operators will need to know. Please include your name when you add an item, so that the release coordinators can get back to you with questions.