X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/62bfbd6a63dcac2f6f31eb014f69397c9eb967d2..71e71e5f52e5f6bdeae63cc8c11b1bee44d11c30:/docs/the_black_code_style/index.rst?ds=sidebyside diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst index 4693437..511a6ec 100644 --- a/docs/the_black_code_style/index.rst +++ b/docs/the_black_code_style/index.rst @@ -9,9 +9,37 @@ The Black Code Style *Black* is a PEP 8 compliant opinionated formatter with its own style. -It should be noted that while keeping the style unchanged throughout releases is a -goal, the *Black* code style isn't set in stone. Sometimes it's modified in response to -user feedback or even changes to the Python language! +While keeping the style unchanged throughout releases has always been a goal, +the *Black* code style isn't set in stone. It evolves to accommodate for new features +in the Python language and, occasionally, in response to user feedback. +Large-scale style preferences presented in :doc:`current_style` are very unlikely to +change, but minor style aspects and details might change according to the stability +policy presented below. Ongoing style considerations are tracked on GitHub with the +`design `_ issue label. + +Stability Policy +---------------- + +The following policy applies for the *Black* code style, in non pre-release +versions of *Black*: + +- The same code, formatted with the same options, will produce the same + output for all releases in a given calendar year. + + This means projects can safely use `black ~= 22.0` without worrying about + major formatting changes disrupting their project in 2022. We may still + fix bugs where *Black* crashes on some code, and make other improvements + that do not affect formatting. + +- The first release in a new calendar year *may* contain formatting changes, + although these will be minimised as much as possible. This is to allow for + improved formatting enabled by newer Python language syntax as well as due + to improvements in the formatting logic. + +- The ``--preview`` flag is exempt from this policy. There are no guarantees + around the stability of the output with that flag passed into *Black*. This + flag is intended for allowing experimentation with the proposed changes to + the *Black* code style. Documentation for both the current and future styles can be found: