diff --git a/source/developers/references/developer_guide/links.rst b/source/developers/references/developer_guide/links.rst index af644edbd..58f63c816 100644 --- a/source/developers/references/developer_guide/links.rst +++ b/source/developers/references/developer_guide/links.rst @@ -264,6 +264,8 @@ .. _jscs: https://www.npmjs.org/package/jscs .. _Waffle: http://waffle.readthedocs.io/en/latest .. _Waffle documentation: http://waffle.readthedocs.io/en/latest +.. _OEP-17 Feature Toggles: https://docs.openedx.org/projects/openedx-proposals/en/latest/best-practices/oep-0017-bp-feature-toggles.html +.. _OEP-19 Developer Documentation: https://docs.openedx.org/projects/openedx-proposals/en/latest/best-practices/oep-0019-bp-developer-documentation.html .. _Segment: https://segment.com .. _CourseTalk: https://www.coursetalk.com/ .. _Google Play: https://play.google.com/store/apps/details?id=org.edx.mobile @@ -279,6 +281,11 @@ .. _Google Calendar website: https://www.google.com/calendar .. _Adobe Flash Player: https://get.adobe.com/flashplayer/ .. _Oppia XBlock: https://github.com/oppia/xblock +.. _Internationalization Coding Guidelines: https://openedx.atlassian.net/wiki/edx.readthedocs.io/projects/edx-developer-guide/en/latest/internationalization/i18n.html +.. _RTL UI Best Practices: https://github.com/openedx/edx-platform/wiki/RTL-UI-Best-Practices +.. _Accessibility Guidelines: http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/accessibility.html +.. _Analytics Guidelines: http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/analytics.html +.. _Eventing Design and Review Process: https://openedx.atlassian.net/wiki/display/AN/Eventing+Design+and+Review+Process .. _Durham University Alt Text Checker: https://www.dur.ac.uk/cis/web/accessibility/tools/alttext/ diff --git a/source/developers/references/developer_guide/process/code-considerations.rst b/source/developers/references/developer_guide/process/code-considerations.rst index 22d717d1f..723d316ee 100644 --- a/source/developers/references/developer_guide/process/code-considerations.rst +++ b/source/developers/references/developer_guide/process/code-considerations.rst @@ -9,15 +9,97 @@ as they are building new, or modifying existing, functionality. :local: :depth: 1 +================== +Basic Code Quality +================== + +As described in :doc:`overview`, your code should meet basic Open edX project +standards: it should be accessible, internationalized, and meet the concerns of +analytics. + +* `Internationalization Coding Guidelines`_ +* `RTL UI Best Practices`_ +* `Accessibility Guidelines`_ +* `Analytics Guidelines`_ +* `Eventing Design and Review Process`_ + +.. _Contributing to the Documentation for your Open Source Feature: + +===================== +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 :doc:`../../../../documentors/references/doc_guidelines`. + +Additionally, please see the section on :ref:`Named Release documentation` - +consider documenting your change for the upcoming Named Release. + +======================== +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: :doc:`edx-platform:references/featuretoggles`, +and please be sure to document any Django settings you define as well - those +are documented here: :doc:`edx-platform:references/settings`.) + +.. _lms/djangoapps/courseware/toggles.py: https://github.com/openedx/edx-platform/blob/master/lms/djangoapps/courseware/toggles.py + +============================= Operational Impact on edx.org ============================= -TODO: Write a section explaining how edx.org uses CD and how that may impact your -PR if it has certain types of operational impacts (eg database stuff, etc) +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. -Hedging Against Failure +.. _Named Release documentation: + +======================= +Open edX Named Releases ======================= -TODO: Link concept doc on waffle flags etc +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. -.. _Contributing to the Documentation for your Open Source Feature: +.. _Open edX Release Planning: https://openedx.atlassian.net/wiki/spaces/COMM/pages/13205845/Open+edX+Release+Planning + + +.. include:: ../links.rst diff --git a/source/developers/references/developer_guide/process/overview.rst b/source/developers/references/developer_guide/process/overview.rst index ceac0de9f..9ebe19fc3 100644 --- a/source/developers/references/developer_guide/process/overview.rst +++ b/source/developers/references/developer_guide/process/overview.rst @@ -33,14 +33,10 @@ questions or concerns. * `Analytics Guidelines`_ * `Eventing Design and Review Process`_ -.. _Internationalization Coding Guidelines: https://openedx.atlassian.net/wiki/edx.readthedocs.io/projects/edx-developer-guide/en/latest/internationalization/i18n.html -.. _RTL UI Best Practices: https://github.com/openedx/edx-platform/wiki/RTL-UI-Best-Practices -.. _Accessibility Guidelines: http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/accessibility.html -.. _Analytics Guidelines: http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/analytics.html -.. _Eventing Design and Review Process: https://openedx.atlassian.net/wiki/display/AN/Eventing+Design+and+Review+Process - Roles ----- TODO + +.. include:: ../links.rst