]> git.madduck.net Git - etc/vim.git/blobdiff - docs/the_black_code_style/index.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Improve caching by comparing file hashes as fallback for mtime and size (#3821)
[etc/vim.git] / docs / the_black_code_style / index.md
index d1508552fee8311be2fc77776dd96fda71cfdaa3..1719347eec81ae97a10f181e149a6fb2194acbcc 100644 (file)
@@ -17,20 +17,25 @@ Python language and, occasionally, in response to user feedback. Large-scale sty
 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](https://github.com/psf/black/labels/T%3A%20design) issue label.
+[style](https://github.com/psf/black/labels/T%3A%20style) issue label.
+
+(labels/stability-policy)=
 
 ## 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.
+- If code has been formatted with _Black_, it will remain unchanged when formatted with
+  the same options using any other release in the same calendar year.
+
+  This means projects can safely use `black ~= 22.0` without worrying about 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.
 
-  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.
+  In rare cases, we may make changes affecting code that has not been previously
+  formatted with _Black_. For example, we have had bugs where we accidentally removed
+  some comments. Such bugs can be fixed without breaking the stability policy.
 
 - 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