*******************
Code Considerations
*******************

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

Operational Impact
==================

* Are there new points in the system that require operational monitoring?

    * External system that you now depend on (Mathworks, SoftwareSecure,
      CyberSource, etc...)
    * New reliance on disk space?
    * New stand process (workers? elastic search?) that need to always be available?
    * A new queue that needs to be monitored for dequeueing
    * Bulk Email --> Amazon SES, Inbound queues, etc...
    * Are important feature metrics sent to datadog and is there a
      dashboard to monitor them?

* Am I building a feature that will have impact to the performance of the system?
  Keep in mind that Open edX needs to support hundreds of thousands if not
  millions of students, so be careful that you code will work well when the
  numbers get large.

    * Deep Search
    * Grade Downloads

* Are reasonable log messages being written out for debugging purposes?
* Will this new feature easily start up in the Vagrant image?
* Do we have documentation for how to start up this feature if it has any
  new startup requirements?
* Are there any special directories/file system permissions that need to be set?
* Will this have any impact to the CDN related technologies?
* Are we pushing any extra manual burden on the Operations team to have to
  provision anything new when new courses launch? when new schools start? etc....
* Has the feature been tested using a production configuration with vagrant?

See also: :doc:`deploy-new-service`

Documentation/Training/Support
==============================

* Is there appropriate documentation in the context of the product for
  this feature? If not, how can we get it to folks?

  * For Studio much of the documentation is in the product.

* Is this feature big enough that we need to have a session with stakeholders
  to introduce this feature BEFORE we release it? (PMs, Support, etc...)

  * Paid Certificates

* Do I have to give some more information to the Escalation Team
  so that this can be supported?
* Did you add an entry to CHANGELOG?
* Did you write/edit docstrings for all of your modules, classes, and functions?

Development
===========

* Did you consider a reasonable upgrade path?
* Is this a feature that we need to slowly roll out to different audiences?

  * Bulk Email

* Have you considered exposing an appropriate amount of configuration options
  in case something happens?
* Have you considered a simple way to "disable" this feature if something is broken?

  * Centralized Logging

* Will this feature require any security provisioning?

  * Which roles use this feature? Does it make sense to ensure that only those
    roles can see this feature?
  * Assets in the Studio Library

* Did you ensure that any new libraries are added to appropriate provisioning
  scripts and have been checked by OSCM for license appropriateness?
* Is there an open source alternative?
* Are we locked down to any proprietary technologies? (AWS, ...)
* Did you consider making APIs so that others can change the implementation if applicable?
* Did you consider Internationalization (I18N) and Localization (L10N)?
* Did you consider Accessibility (A11y)?
* Will your code work properly in workers?
* Have you considered the large-scale modularity of the code? For example,
  xmodule and xblock should not use Django features directly.

Testing
=======

* Did you make sure that you tried boundary conditions?
* Did you try unicode input/data?

  * The name of the person in paid certifactes
  * The name of the person in bulk email
  * The body of the text in bulk email
  * etc

* Did you try funny characters in the input/data? (~!@#$%^&*()';/.,<>, etc...)
* Have you done performance testing on this feature? Do you know how much
  performance is good enough?
* Did you ensure that your functionality works across all supported browsers?
* Do you have the right hooks in your HTML to ensure that the views are automatable?
* Are you ready if this feature has 10x the expected usage?
* What happens if an external service does not respond or responds with
  a significant delay?
* What are possible failure modes?  Do your unit tests exercise these code paths?
* Does this change affect templates and/or JavaScript?  If so, are there
  Selenium tests for the affected page(s)?  Have you tested the affected
  page(s) in a sandbox?

Analytics
=========

* Are learning analytics events being recorded in an appropriate way?

  * Do your events use a descriptive and uniquely enough event type and
    namespace?
  * Did you ensure that you capture enough information for the researchers
    to benefit from this event information?
  * Is it possible to reconstruct the state of your module from the history
    of its events?
  * Has this new event been documented  so that folks downstream know how
    to interpret it?
  * Are you increasing the amount of logging in any major way?

* Are you sending appropriate/enough information to MixPanel,
  Google Analytics, Segment IO?

Collaboration
=============
* Are there are other teams that would benefit from knowing about this feature?

  * Forums/LMS - email

* Does this feature require a special broadcast to external teams as well?

Open Source
===========
* Can we get help from the community on this feature?
* Does the community know enough about this?

UX/Design/Front End Development
===============================
* Did you make sure that the feature is going to pass
  Accessibility requirements (still TBD)?
* Did you make sure any system/instructional text is I18N ready?
* Did you ensure that basic functionality works across all supported browsers?
* Did you plan for the feature's UI to degrade gracefully (or be
  progressively enhanced) based on browser capability?
* Did you review the page/view under all browser/agent conditions -
  viewport sizes, images off, css off?
* Did you write any HTML with ideal page/view semantics in mind?
* When writing HTML, did you adhere to standards/conventions around class/id names?
* When writing Sass, did you follow OOCSS/SMACSS philosophy ([1]_, [2]_, [3]_),
  variable/extend organization and naming conventions, and UI abstraction conventions?
* When writing Sass, did you document any new variables,
  extend-based classes, or mixins?
* When writing/adding JavaScript, did you consider the asset pipeline
  and page load timeline?
* When writing JavaScript, did you note what code is for prototyping vs. production?
* When adding new templates, views, assets (Sass, images, plugins/libraries),
  did you follow existing naming and file architecture conventions?
* When adding new templates, views, assets (Sass, images, plugins/libraries),
  did you add any needed documentation?
* Did you use templates and good Sass architecture to keep DRY?
* Did we document any aspects about the feature (flow, purpose, intent)
  that we or other teams will need to know going forward?

.. [1] http://smacss.com/
.. [2] http://thesassway.com/intermediate/avoid-nested-selectors-for-more-modular-css
.. [3] http://ianstormtaylor.com/oocss-plus-sass-is-the-best-way-to-css/

edX.org Specific
================

* Ensure that you have not broken import/export?
* Ensure that you have not broken video player? (Lyla video)
