docs: Update Dev Guide > Code Considerations file

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://open-edx-proposals.readthedocs.io/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/
 

source/developers/references/developer_guide/process/code-considerations.rst

@@ -9,15 +9,91 @@ 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`.
+
+**TODO** How do I add a note about my new feature for the next named release release notes?
+
+========================
+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.
+
+.. _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.
 
-Hedging Against Failure
+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.
+
+=======================
+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

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