Draft OEP-31: Code Autoformatting

oeps/oep-0031-bp-code-autoformatting.rst

@@ -0,0 +1,80 @@
+===========================
+OEP-31: Code Autoformatting
+===========================
+
++-----------------+--------------------------------------------------------+
+| OEP             | :doc:`OEP-31 </oeps/oep-0031-bp-code-autoformatting>`  |
++-----------------+--------------------------------------------------------+
+| Title           | Code Autoformatting                                    |
++-----------------+--------------------------------------------------------+
+| Last Modified   | 2019-03-04                                             |
++-----------------+--------------------------------------------------------+
+| Authors         | Calen Pennington <cale@edx.org>                        |
++-----------------+--------------------------------------------------------+
+| Arbiter         | Ned Batchelder <ned@edx.org> (Tentatively)             |
++-----------------+--------------------------------------------------------+
+| Status          | Draft                                                  |
++-----------------+--------------------------------------------------------+
+| Type            | Best Practice                                          |
++-----------------+--------------------------------------------------------+
+| Created         | 2019-03-04                                             |
++-----------------+--------------------------------------------------------+
+| `Review Period` | 2019-03-04 - 2019-04-01                                |
++-----------------+--------------------------------------------------------+
+
+Context
+-------
+
+In a large software project or ecosystem like the OpenEdX codebase, consistency
+of code formatting makes it easier to read the code. In an ecosystem with many
+contributors, maintaining that consistency requires automated tools (such as
+linters), consistent code review, or both. In general, minimizing the number
+of review comments that a reviewer has to make on an incoming change makes
+review easier, and lessens the number of back-and-forths required to merge
+the code. As such, linters that can be run locally should be preferred.
+Similarly, ambiguity in style guidelines should be minimized, so that there
+are fewer places for commentary around what amounts to personal preference
+(which might then instigate unnecessary debate).
+
+In short, more consistent, less ambiguous standards for code formatting
+make for more production code reviews and waste less time on inconsequential
+details.
+
+Decision
+--------
+
+We will select automatic code formatters for all of our major languages. These
+formatters will have both a lint-mode (that will be run in continuous
+integration to ensure consistent formatting) and an autoformat mode (which
+can be integrated with editors to free developers from having to think about
+code formatting). These formatting standards will be applied across all
+OpenEdX-authored repositories.
+
+The current recommended formatters are:
+
+    - Python: `black`_
+    - Javascript: `prettier`_
+    - CSS/SASS: `prettier`_
+    - HTML: `prettier`_
+
+.. _black: https://github.com/ambv/black
+.. _prettier: https://prettier.io/
+
+Consequences
+------------
+
+There will be commits to all OpenEdX repositories that cause large-scale
+reformatting without functional changes. This will muddy the blame-file
+history. Users with auto-formatters configured in their editors working
+in a repo that is not yet OEP-31 compliant will need to disable their
+autoformatter, or risk large-scale changes that are unrelated to their
+current tasks. All OpenEdX code will be formatted consistently and
+unambiguously. Developers will not have will not have arguments about
+code layout.
+
+References
+----------
+
+`gofmt`_ was the first code-autoformatter to gain wide-scale acceptance.
+
+.. _gofmt: https://blog.golang.org/go-fmt-your-code