Scope

This document describes code quality standards for the i4x
system. 

1. Coding Standards

Code falls into four categories:

* Deployed. Running on a live server. 
* Production. Intended for deployment. 
* Scaffolding. Intended to define interfaces for future work, and
  minimal implementations to support further development. 
* Prototype. Experimental new features. 

1.1 Deployed

The standards for deployed code are identical to production. In
general, we tend to do either:

1) Perform a final verification QA cycle on changed parts of code
before deploying.
2) Use code on a staging or internal server for a week before
deploying.

1.2 Production

All production code must be peer-reviewed. The code must meet the
following standards:

1) Test Suite. Code must have reasonable, although not complete, test
   coverage.
2) Consistent. Code must follow PEP8
3) Clean Abstractions. 
4) Future-Compatible. Code must not be incompatible with the
   long-term vision of either the codebase or of edX. 
5) Properly Documented
6) Maintainable and deployable
7) Robust. 

All code paths must be manually or automatically verified. 

1.3 Scaffolding

All scaffolding code should be peer-reviewed. The code must meet the
following standards:

1) Testable. We do not require test coverage, but we do require the
   code to be structured such that it is possible to build tests.
2) Consistent. Code must follow PEP8
3) Clean abstractions or obvious throw-away code. One of the goals 
   of scaffolding is to define proper abstractions. 
4) Future-Compatible. Code must not be incompatible with the
   long-term vision of either the codebase or of edX. 
5) Somewhat documented
6) Unpluggable. There should be a setting to disable scaffolding code. 
   By default, and by policy, it should never be enabled on production 
   servers.
7) Purpose. The scaffolding must provide a clean reason for existence
   (e.g. define a specific interface, etc.)

1.4 Prototype

Prototype code should live in a separate branch. It should strive
to follow PEP8, be readable, testable, and future-proof, but we have
no hard standards. 

2. Process Standards

* Code should be integrated in small pull requests. Large commits
  should be broken down into small commits for integration.
* Every piece of production and deployed code must be reviewed prior
  to integration.
* Anyone on the edX team competent to review a piece of code may
  review it (this may change as the team grows). 
* Each contributor is responsible for finding a person to review their
  code. If it is not clear to the contributor who is appropriate, each
  project has an owner who is the default go-to. 

2.1 Rapid pull

Unmerged code can lead to merge conflicts, and slow down
development. We have an experimental procedure for handling rapid
pulls and merges. To qualify:

* A piece of code must only have minor issues remaining (nothing which
  we would be uncomfortable placing on a server).  
* Either the requester or the puller takes ownership for guaranteeing
  that those issues are resolved within a short timeframe.
* Both the requester and the puller must be comfortable with it. 
* Both the requester and the owner must have a history of/ability to 
  resolve remaining issues quickly. 

If code qualifies: 
* It can be merged, and repaired in master. 
* The pull message should specify '## pending fixes/OWNER' where ## is
  the pull request number, and OWNER is the owner. 
* All required fixes are documented in github in the (now closed) pull
  request, and should be marked off there when applied (potentially,
  directly to master).
* Once all fixes are applied, the final commit should specify 
  '## closed'. 

3. Documentation Standards

* Whenever possible, documentation should live in code. 
* When impossible, it should live in the github repo. 
* Discussion should live on github, Basecamp or Pivotal, depending on
  context.
* Notes for later fixes should in general be put into Pivotal as stories.
  If they are left in the code, they should be prefixed by
  # TODO (<name>)