86 lines
2.8 KiB
Plaintext
86 lines
2.8 KiB
Plaintext
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
|
|
|
|
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.
|