From 5020577788eeab758a2c33d1d563e4ea82617ed4 Mon Sep 17 00:00:00 2001 From: Cooper Lees Date: Sun, 9 May 2021 00:08:03 -0700 Subject: [PATCH 01/16] Remove docker CI from look at 'master' branch (#2209) --- .github/workflows/docker.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 7eaf233..788c505 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -3,7 +3,7 @@ name: docker on: push: branches: - - "master" + - "main" release: types: created -- 2.39.5 From 06ccb88bf2bd35a4dc5d591bb296b5b299d07323 Mon Sep 17 00:00:00 2001 From: Panagiotis Vasilopoulos Date: Sun, 9 May 2021 21:50:17 +0000 Subject: [PATCH 02/16] Replace references to master branch (#2210) Commit history before merge: * Replace references to master branch * Update .flake8 to reference docs on RTD We're moving away from GitHub as a documentation host to only RTD because it's makes our lives easier creating good docs. I know this link is dead right now, but it won't be once we release a new version with the documentation reorganization changes (which should be soon!). Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com> --- .flake8 | 2 +- .github/ISSUE_TEMPLATE/bug_report.md | 8 ++++---- CHANGES.md | 4 ++++ README.md | 6 +++--- docs/contributing/the_basics.md | 2 +- docs/guides/using_black_with_other_tools.md | 2 +- docs/integrations/editors.md | 2 +- gallery/gallery.py | 8 ++++---- setup.py | 2 +- 9 files changed, 20 insertions(+), 16 deletions(-) diff --git a/.flake8 b/.flake8 index 656c0df..68d1501 100644 --- a/.flake8 +++ b/.flake8 @@ -1,7 +1,7 @@ [flake8] extend-ignore = E203, E266, E501 # line length is intentionally set to 80 here because black uses Bugbear -# See https://github.com/psf/black/blob/master/docs/the_black_code_style.md#line-length for more details +# See https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length for more details max-line-length = 80 max-complexity = 18 select = B,C,E,F,W,T4,B9 diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 3b59906..c6c80be 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -18,13 +18,13 @@ assignees: "" **Environment (please complete the following information):** -- Version: \[e.g. master\] +- Version: \[e.g. main\] - OS and Python version: \[e.g. Linux/Python 3.7.4rc1\] -**Does this bug also happen on master?** To answer this, you have two options: +**Does this bug also happen on main?** To answer this, you have two options: -1. Use the online formatter at , which will - use the latest master branch. +1. Use the online formatter at , which will use + the latest main branch. 1. Or run _Black_ on your machine: - create a new virtualenv (make sure it's the same Python version); - clone this repository; diff --git a/CHANGES.md b/CHANGES.md index 9b15592..32c2d8d 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -8,6 +8,10 @@ ### Documentation +- Replaced all remaining references to the + [`master`](https://github.com/psf/black/tree/main) branch with the + [`main`](https://github.com/psf/black/tree/main) branch. Some additional changes in + the source code were also made. (#2210) - Sigificantly reorganized the documentation to make much more sense. Check them out by heading over to [the stable docs on RTD](https://black.readthedocs.io/en/stable/). (#2174) diff --git a/README.md b/README.md index ceccbb7..beb8069 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Black Logo](https://raw.githubusercontent.com/psf/black/master/docs/_static/logo2-readme.png) +![Black Logo](https://raw.githubusercontent.com/psf/black/main/docs/_static/logo2-readme.png)

The Uncompromising Code Formatter

@@ -6,8 +6,8 @@ Actions Status Actions Status Documentation Status -Coverage Status -License: MIT +Coverage Status +License: MIT PyPI Downloads conda-forge diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md index 461bff9..d36b17e 100644 --- a/docs/contributing/the_basics.md +++ b/docs/contributing/the_basics.md @@ -81,7 +81,7 @@ $ sphinx-build -a -b html -W docs/ docs/_build/ if we get source code changes. It will error on formatting changes or errors. Please run before pushing your PR to see if you get the actions you would expect from _Black_ with your PR. You may need to change -[primer.json](https://github.com/psf/black/blob/master/src/black_primer/primer.json) +[primer.json](https://github.com/psf/black/blob/main/src/black_primer/primer.json) configuration for it to pass. For more `black-primer` information visit the diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md index 4b22f67..2b3855f 100644 --- a/docs/guides/using_black_with_other_tools.md +++ b/docs/guides/using_black_with_other_tools.md @@ -13,7 +13,7 @@ tools out there. tools, using **their** supported file formats. Compatible configuration files can be -[found here](https://github.com/psf/black/blob/master/docs/compatible_configs/). +[found here](https://github.com/psf/black/blob/main/docs/compatible_configs/). ### isort diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md index 6a69e9e..88176e1 100644 --- a/docs/integrations/editors.md +++ b/docs/integrations/editors.md @@ -166,7 +166,7 @@ automatically installs _Black_. You can upgrade it later by calling `:BlackUpgra restarting Vim. If you need to do anything special to make your virtualenv work and install _Black_ (for -example you want to run a version from master), create a virtualenv manually and point +example you want to run a version from main), create a virtualenv manually and point `g:black_virtualenv` to it. The plugin will use it. To run _Black_ on save, add the following line to `.vimrc` or `init.vim`: diff --git a/gallery/gallery.py b/gallery/gallery.py index 6b42ec3..3df05c1 100755 --- a/gallery/gallery.py +++ b/gallery/gallery.py @@ -74,7 +74,7 @@ def get_top_packages(days: Days) -> List[str]: def get_package_source(package: str, version: Optional[str]) -> str: if package == "cpython": if version is None: - version = "master" + version = "main" return f"https://github.com/python/cpython/archive/{version}.zip" elif package == "pypy": if version is None: @@ -248,9 +248,9 @@ def format_repos(repos: Tuple[Path, ...], options: Namespace) -> None: black_version=black_version, input_directory=options.input, ) - git_switch_branch("master", repo=repo) + git_switch_branch("main", repo=repo) - git_switch_branch("master", repo=options.black_repo) + git_switch_branch("main", repo=options.black_repo) def main() -> None: @@ -296,7 +296,7 @@ def main() -> None: type=Path, help="Output directory to download and put result artifacts.", ) - parser.add_argument("versions", nargs="*", default=("master",), help="") + parser.add_argument("versions", nargs="*", default=("main",), help="") options = parser.parse_args() repos = init_repos(options) diff --git a/setup.py b/setup.py index af93d0f..3dc52b2 100644 --- a/setup.py +++ b/setup.py @@ -58,7 +58,7 @@ setup( author="Łukasz Langa", author_email="lukasz@langa.pl", url="https://github.com/psf/black", - project_urls={"Changelog": "https://github.com/psf/black/blob/master/CHANGES.md"}, + project_urls={"Changelog": "https://github.com/psf/black/blob/main/CHANGES.md"}, license="MIT", py_modules=["_black_version"], ext_modules=ext_modules, -- 2.39.5 From 3d96b7f10a56fcf826693e98f08b673dad8ac256 Mon Sep 17 00:00:00 2001 From: Richard Si <63936253+ichard26@users.noreply.github.com> Date: Sun, 9 May 2021 22:35:56 -0400 Subject: [PATCH 03/16] Autogenerate black(d|-primer)? help in usage docs (#2212) So these won't go out of date. This does mean the environment has be setup a bit more carefully so the right version of the tool is used, but thankfully the build environment is rebuilt on change on RTD anyway. Also since the HTML docs are known to build fine, let's provide downloadable HTMLzips of our docs. This change needs RTD and GH to install Black with the [d] extra so blackd's help can generated. While editing RTD's config file, let's migrate the file to a non-deprecated filename. Also I missed adding AUTHORS.md to the files key in the doc GHA config. --- .github/workflows/doc.yml | 6 +- readthedocs.yml => .readthedocs.yaml | 9 +- Pipfile | 1 + Pipfile.lock | 90 ++++++++++--------- docs/conf.py | 1 + docs/contributing/gauging_changes.md | 21 +---- docs/requirements.txt | 3 +- .../black_as_a_server.md | 10 +-- docs/usage_and_configuration/the_basics.md | 88 +----------------- 9 files changed, 70 insertions(+), 159 deletions(-) rename readthedocs.yml => .readthedocs.yaml (55%) diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 930b6d4..74ec316 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -7,12 +7,14 @@ on: - "README.md" - "CHANGES.md" - "CONTRIBUTING.md" + - "AUTHORS.md" pull_request: paths: - "docs/**" - "README.md" - "CHANGES.md" - "CONTRIBUTING.md" + - "AUTHORS.md" jobs: build: @@ -35,8 +37,8 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip setuptools wheel - python -m pip install -e "." + python -m pip install -e ".[d]" python -m pip install -r "docs/requirements.txt" - name: Build documentation - run: sphinx-build -a -b html -W docs/ docs/_build/ + run: sphinx-build -a -b html -W --keep-going docs/ docs/_build diff --git a/readthedocs.yml b/.readthedocs.yaml similarity index 55% rename from readthedocs.yml rename to .readthedocs.yaml index 1506503..24eb3ea 100644 --- a/readthedocs.yml +++ b/.readthedocs.yaml @@ -1,7 +1,14 @@ version: 2 + +formats: + - htmlzip + python: version: 3.8 install: - requirements: docs/requirements.txt - - method: setuptools + + - method: pip path: . + extra_requirements: + - d diff --git a/Pipfile b/Pipfile index d1842ff..b385957 100644 --- a/Pipfile +++ b/Pipfile @@ -13,6 +13,7 @@ mypy = ">=0.812" pre-commit = "*" readme_renderer = "*" MyST-Parser = ">=0.13.7" +sphinxcontrib-programoutput = ">=0.17" setuptools = ">=39.2.0" setuptools-scm = "*" twine = ">=1.11.0" diff --git a/Pipfile.lock b/Pipfile.lock index f973c84..0b9e529 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "62bc4bdb0117234d1f374b2dc0685369f6df7c7192d16409cc9c42a429770166" + "sha256": "fdfbacb362e4514e588736a7e8783837cb5e3aa2fbab98ea17894fdb50d51a8e" }, "pipfile-spec": 6, "requires": {}, @@ -83,11 +83,11 @@ }, "attrs": { "hashes": [ - "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6", - "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700" + "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1", + "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb" ], - "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", - "version": "==20.3.0" + "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'", + "version": "==21.2.0" }, "black": { "editable": true, @@ -290,13 +290,13 @@ }, "typing-extensions": { "hashes": [ - "sha256:7cb407020f00f7bfc3cb3e7881628838e69d8f3fcab2f64742a5e76b2f841918", - "sha256:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c", - "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f" + "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497", + "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342", + "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84" ], "index": "pypi", "python_version <": "3.8", - "version": "==3.7.4.3", + "version": "==3.10.0.0", "version >=": "3.7.4" }, "yarl": { @@ -420,11 +420,11 @@ }, "attrs": { "hashes": [ - "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6", - "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700" + "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1", + "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb" ], - "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", - "version": "==20.3.0" + "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'", + "version": "==21.2.0" }, "babel": { "hashes": [ @@ -631,11 +631,11 @@ }, "flake8": { "hashes": [ - "sha256:1aa8990be1e689d96c745c5682b687ea49f2e05a443aff1f8251092b0014e378", - "sha256:3b9f848952dddccf635be78098ca75010f073bfe14d2c6bda867154bea728d2a" + "sha256:07528381786f2a6237b061f6e96610a4167b226cb926e2aa2b6b1d78057c576b", + "sha256:bf8fd333346d844f616e8d47905ef3a3384edae6b4e9beb0c5101e25e3110907" ], "index": "pypi", - "version": "==3.9.1" + "version": "==3.9.2" }, "flake8-bugbear": { "hashes": [ @@ -703,11 +703,11 @@ }, "markdown-it-py": { "hashes": [ - "sha256:30b3e9f8198dc82a5df0dcb73fd31d56cd9a43bf8a747feb10b2ba74f962bcb1", - "sha256:c3b9f995be0792cbbc8ab2f53d74072eb7ff8a8b622be8d61d38ab879709eca3" + "sha256:36be6bb3ad987bfdb839f5ba78ddf094552ca38ccbd784ae4f74a4e1419fc6e3", + "sha256:98080fc0bc34c4f2bcf0846a096a9429acbd9d5d8e67ed34026c03c61c464389" ], "markers": "python_version ~= '3.6'", - "version": "==0.6.2" + "version": "==1.1.0" }, "markupsafe": { "hashes": [ @@ -776,11 +776,11 @@ }, "mdit-py-plugins": { "hashes": [ - "sha256:1e467ca2ea056e8065cbd5d6c61e5052bb50826bde84c40f6a5ed77e82125710", - "sha256:77fd75dad81109ee91f30eb49146196f79afbbae041f298ae4886c8c2b5e23d7" + "sha256:1833bf738e038e35d89cb3a07eb0d227ed647ce7dd357579b65343740c6d249c", + "sha256:5991cef645502e80a5388ec4fc20885d2313d4871e8b8e320ca2de14ac0c015f" ], "markers": "python_version ~= '3.6'", - "version": "==0.2.6" + "version": "==0.2.8" }, "multidict": { "hashes": [ @@ -863,11 +863,11 @@ }, "myst-parser": { "hashes": [ - "sha256:260355b4da8e8865fe080b0638d7f1ab1791dc4bed02a7a48630b6bad4249219", - "sha256:e4bc99e43e19f70d22e528de8e7cce59f7e8e7c4c34dcba203de92de7a7c7c85" + "sha256:8d7db76e2f33cd1dc1fe0c76af9f09e5cf19ce2c2e85074bc82f272c0f7c08ce", + "sha256:fc262959a74cdc799d7fa9b30c320c17187485b9a1e8c39e988fc12f3adff63c" ], "index": "pypi", - "version": "==0.13.7" + "version": "==0.14.0" }, "nodeenv": { "hashes": [ @@ -933,11 +933,11 @@ }, "pygments": { "hashes": [ - "sha256:2656e1a6edcdabf4275f9a3640db59fd5de107d88e8663c5d4e9a0fa62f77f94", - "sha256:534ef71d539ae97d4c3a4cf7d6f110f214b0e687e92f9cb9d2a3b0d3101289c8" + "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f", + "sha256:d66e804411278594d764fc69ec36ec13d9ae9147193a1740cd34d272ca383b8e" ], "markers": "python_version >= '3.5'", - "version": "==2.8.1" + "version": "==2.9.0" }, "pyparsing": { "hashes": [ @@ -1061,10 +1061,10 @@ }, "rfc3986": { "hashes": [ - "sha256:112398da31a3344dc25dbf477d8df6cb34f9278a94fee2625d89e4514be8bb9d", - "sha256:af9147e9aceda37c91a05f4deb128d4b4b49d6b199775fd2d2927768abdc8f50" + "sha256:270aaf10d87d0d4e095063c65bf3ddbc6ee3d0b226328ce21e036f946e421835", + "sha256:a86d6e1f5b1dc238b218b012df0aa79409667bb209e58da56d0b94704e712a97" ], - "version": "==1.4.0" + "version": "==1.5.0" }, "secretstorage": { "hashes": [ @@ -1084,11 +1084,11 @@ }, "six": { "hashes": [ - "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259", - "sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced" + "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926", + "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254" ], "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", - "version": "==1.15.0" + "version": "==1.16.0" }, "snowballstemmer": { "hashes": [ @@ -1137,6 +1137,14 @@ "markers": "python_version >= '3.5'", "version": "==1.0.1" }, + "sphinxcontrib-programoutput": { + "hashes": [ + "sha256:0ef1c1d9159dbe7103077748214305eb4e0138e861feb71c0c346afc5fe97f84", + "sha256:300ee9b8caee8355d25cc74b4d1c7efd12e608d2ad165e3141d31e6fbc152b7f" + ], + "index": "pypi", + "version": "==0.17" + }, "sphinxcontrib-qthelp": { "hashes": [ "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72", @@ -1215,13 +1223,13 @@ }, "typing-extensions": { "hashes": [ - "sha256:7cb407020f00f7bfc3cb3e7881628838e69d8f3fcab2f64742a5e76b2f841918", - "sha256:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c", - "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f" + "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497", + "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342", + "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84" ], "index": "pypi", "python_version <": "3.8", - "version": "==3.7.4.3", + "version": "==3.10.0.0", "version >=": "3.7.4" }, "urllib3": { @@ -1234,11 +1242,11 @@ }, "virtualenv": { "hashes": [ - "sha256:09c61377ef072f43568207dc8e46ddeac6bcdcaf288d49011bda0e7f4d38c4a2", - "sha256:a935126db63128861987a7d5d30e23e8ec045a73840eeccb467c148514e29535" + "sha256:307a555cf21e1550885c82120eccaf5acedf42978fd362d32ba8410f9593f543", + "sha256:72cf267afc04bf9c86ec932329b7e94db6a0331ae9847576daaa7ca3c86b29a4" ], "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", - "version": "==20.4.4" + "version": "==20.4.6" }, "webencodings": { "hashes": [ diff --git a/docs/conf.py b/docs/conf.py index d567373..7162f13 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,6 +59,7 @@ extensions = [ "sphinx.ext.intersphinx", "sphinx.ext.napoleon", "myst_parser", + "sphinxcontrib.programoutput", ] # If you need extensions of a certain version or higher, list them here. diff --git a/docs/contributing/gauging_changes.md b/docs/contributing/gauging_changes.md index 6b70e0b..b41c7a3 100644 --- a/docs/contributing/gauging_changes.md +++ b/docs/contributing/gauging_changes.md @@ -37,25 +37,6 @@ If you're running locally yourself to test black on lots of code try: ### CLI arguments -```text -Usage: black-primer [OPTIONS] +```{program-output} black-primer --help - primer - prime projects for blackening... 🏴 - -Options: - -c, --config PATH JSON config file path [default: /Users/cooper/repos/ - black/src/black_primer/primer.json] - - --debug Turn on debug logging [default: False] - -k, --keep Keep workdir + repos post run [default: False] - -L, --long-checkouts Pull big projects to test [default: False] - -R, --rebase Rebase project if already checked out [default: - False] - - -w, --workdir PATH Directory path for repo checkouts [default: /var/fol - ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200 - 517125229] - - -W, --workers INTEGER Number of parallel worker coroutines [default: 2] - -h, --help Show this message and exit. ``` diff --git a/docs/requirements.txt b/docs/requirements.txt index 6c34e1f..c65cbe3 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ -MyST-Parser==0.13.7 +MyST-Parser==0.14.0 Sphinx==3.5.4 +sphinxcontrib-programoutput==0.17 diff --git a/docs/usage_and_configuration/black_as_a_server.md b/docs/usage_and_configuration/black_as_a_server.md index 0c0382b..75a4d92 100644 --- a/docs/usage_and_configuration/black_as_a_server.md +++ b/docs/usage_and_configuration/black_as_a_server.md @@ -18,14 +18,8 @@ formatting requests. `blackd` provides even less options than _Black_. You can see them by running `blackd --help`: -```text -Usage: blackd [OPTIONS] - -Options: - --bind-host TEXT Address to bind the server to. - --bind-port INTEGER Port to listen on - --version Show the version and exit. - -h, --help Show this message and exit. +```{program-output} blackd --help + ``` There is no official `blackd` client tool (yet!). You can test that blackd is working diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md index 6fd8769..4ac1693 100644 --- a/docs/usage_and_configuration/the_basics.md +++ b/docs/usage_and_configuration/the_basics.md @@ -34,92 +34,8 @@ running `black --help`. Help output -``` - Usage: black [OPTIONS] [SRC]... - - The uncompromising code formatter. - - Options: - -c, --code TEXT Format the code passed in as a string. - -l, --line-length INTEGER How many characters per line to allow. - [default: 88] - - -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39] - Python versions that should be supported by - Black's output. [default: per-file auto- - detection] - - --pyi Format all input files like typing stubs - regardless of file extension (useful when - piping source on standard input). - - -S, --skip-string-normalization - Don't normalize string quotes or prefixes. - -C, --skip-magic-trailing-comma - Don't use trailing commas as a reason to - split lines. - - --check Don't write the files back, just return the - status. Return code 0 means nothing would - change. Return code 1 means some files - would be reformatted. Return code 123 means - there was an internal error. - - --diff Don't write the files back, just output a - diff for each file on stdout. - - --color / --no-color Show colored diff. Only applies when - `--diff` is given. - - --fast / --safe If --fast given, skip temporary sanity - checks. [default: --safe] - - --include TEXT A regular expression that matches files and - directories that should be included on - recursive searches. An empty value means - all files are included regardless of the - name. Use forward slashes for directories - on all platforms (Windows, too). Exclusions - are calculated first, inclusions later. - [default: \.pyi?$] - - --exclude TEXT A regular expression that matches files and - directories that should be excluded on - recursive searches. An empty value means no - paths are excluded. Use forward slashes for - directories on all platforms (Windows, too). - Exclusions are calculated first, inclusions - later. [default: /(\.direnv|\.eggs|\.git|\. - hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_bu - ild|buck-out|build|dist)/] - - --extend-exclude TEXT Like --exclude, but adds additional files - and directories on top of the excluded - ones (useful if you simply want to add to - the default). - - --force-exclude TEXT Like --exclude, but files and directories - matching this regex will be excluded even - when they are passed explicitly as - arguments. - - - --stdin-filename TEXT The name of the file when passing it through - stdin. Useful to make sure Black will - respect --force-exclude option on some - editors that rely on using stdin. - - -q, --quiet Don't emit non-error messages to stderr. - Errors are still emitted; silence those with - 2>/dev/null. - - -v, --verbose Also emit messages to stderr about files - that were not changed or were ignored due to - exclusion patterns. - - --version Show the version and exit. - --config FILE Read configuration from FILE path. - -h, --help Show this message and exit. +```{program-output} black --help + ``` -- 2.39.5 From 7c851dfa2c2a8f0bf4c529d7f6faa43798d04325 Mon Sep 17 00:00:00 2001 From: Richard Si <63936253+ichard26@users.noreply.github.com> Date: Mon, 10 May 2021 10:57:22 -0400 Subject: [PATCH 04/16] Cover more in the usage docs (#2208) Commit history before merge: * Cover more in the usage docs * Minor fixes * Even more corrections by Jelle * Update docs/usage_and_configuration/the_basics.md Co-authored-by: Jelle Zijlstra --- docs/usage_and_configuration/the_basics.md | 143 +++++++++++++++++++++ 1 file changed, 143 insertions(+) diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md index 4ac1693..0b2cd3b 100644 --- a/docs/usage_and_configuration/the_basics.md +++ b/docs/usage_and_configuration/the_basics.md @@ -40,6 +40,149 @@ running `black --help`. +### Code input alternatives + +#### Standard Input + +_Black_ supports formatting code via stdin, with the result being printed to stdout. +Just let _Black_ know with `-` as the path. + +```console +$ echo "print ( 'hello, world' )" | black - +print("hello, world") +reformatted - +All done! ✨ 🍰 ✨ +1 file reformatted. +``` + +**Tip:** if you need _Black_ to treat stdin input as a file passed directly via the CLI, +use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude` +option on some editors that rely on using stdin. + +#### As a string + +You can also pass code as a string using the `-c` / `--code` option. + +```console +$ black --code "print ( 'hello, world' )" +print("hello, world") +``` + +```{warning} +--check, --diff, and --safe / --fast have no effect when using -c / --code. Safety +checks normally turned on by default that verify _Black_'s output are disabled as well. +This is a bug which we intend to fix eventually. More details can be found in this [bug +report](https://github.com/psf/black/issues/2104). +``` + +### Writeback and reporting + +By default _Black_ reformats the files given and/or found in place. Sometimes you need +_Black_ to just tell you what it _would_ do without actually rewriting the Python files. + +There's two variations to this mode that are independently enabled by their respective +flags. Both variations can be enabled at once. + +#### Exit code + +Passing `--check` will make _Black_ exit with: + +- code 0 if nothing would change; +- code 1 if some files would be reformatted; or +- code 123 if there was an internal error + +```console +$ black test.py --check +All done! ✨ 🍰 ✨ +1 file would be left unchanged. +$ echo $? +0 + +$ black test.py --check +would reformat test.py +Oh no! 💥 💔 💥 +1 file would be reformatted. +$ echo $? +1 + +$ black test.py --check +error: cannot format test.py: INTERNAL ERROR: Black produced code that is not equivalent to the source. Please report a bug on https://github.com/psf/black/issues. This diff might be helpful: /tmp/blk_kjdr1oog.log +Oh no! 💥 💔 💥 +1 file would fail to reformat. +$ echo $? +123 +``` + +#### Diffs + +Passing `--diff` will make _Black_ print out diffs that indicate what changes _Black_ +would've made. They are printed to stdout so capturing them is simple. + +If you'd like colored diffs, you can enable them with the `--color`. + +```console +$ black test.py --diff +--- test.py 2021-03-08 22:23:40.848954 +0000 ++++ test.py 2021-03-08 22:23:47.126319 +0000 +@@ -1 +1 @@ +-print ( 'hello, world' ) ++print("hello, world") +would reformat test.py +All done! ✨ 🍰 ✨ +1 file would be reformatted. +``` + +### Output verbosity + +_Black_ in general tries to produce the right amount of output, balancing between +usefulness and conciseness. By default, _Black_ emits files modified and error messages, +plus a short summary. + +```console +$ black src/ +error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio +reformatted src/black_primer/lib.py +reformatted src/blackd/__init__.py +reformatted src/black/__init__.py +Oh no! 💥 💔 💥 +3 files reformatted, 2 files left unchanged, 1 file failed to reformat. +``` + +Passing `-v` / `--verbose` will cause _Black_ to also emit messages about files that +were not changed or were ignored due to exclusion patterns. If _Black_ is using a +configuration file, a blue message detailing which one it is using will be emitted. + +```console +$ black src/ -v +Using configuration from /tmp/pyproject.toml. +src/blib2to3 ignored: matches the --extend-exclude regular expression +src/_black_version.py wasn't modified on disk since last run. +src/black/__main__.py wasn't modified on disk since last run. +error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio +reformatted src/black_primer/lib.py +reformatted src/blackd/__init__.py +reformatted src/black/__init__.py +Oh no! 💥 💔 💥 +3 files reformatted, 2 files left unchanged, 1 file failed to reformat +``` + +Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critial output. +Error messages will still be emitted (which can silenced by `2>/dev/null`). + +```console +$ black src/ -q +error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio +``` + +### Getting the version + +You can check the version of _Black_ you have installed using the `--version` flag. + +```console +$ black --version +black, version 21.5b0 +``` + ## Configuration via a file _Black_ is able to read project-specific default values for its command line options -- 2.39.5 From f1ce47bd2b0150d2b7c78beaafd3b60c469345d0 Mon Sep 17 00:00:00 2001 From: Cooper Lees Date: Mon, 10 May 2021 07:58:36 -0700 Subject: [PATCH 05/16] Release process docs (#2214) * Setup groundwork for release process docs I'm using MyST for the index page since I like it more and it's easier to work with. * Fill in Release Process for black * Apply suggestions from code review Apply Jelle's grammar + typo fixes. I am a terrible only English speaker. Co-authored-by: Jelle Zijlstra * Update release_process.md Make lint happy via web UI. * Move to contribution section and fix prettier Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com> Co-authored-by: Jelle Zijlstra --- docs/contributing/index.rst | 2 + docs/contributing/release_process.md | 72 ++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 docs/contributing/release_process.md diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index 68dfcd6..e7a7f9f 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -6,6 +6,7 @@ Contributing the_basics gauging_changes + release_process reference/reference_summary Welcome! Happy to see you willing to make the project better. Have you read the entire @@ -31,6 +32,7 @@ This section covers the following topics: - :doc:`the_basics` - :doc:`gauging_changes` +- :doc:`release_process` - :doc:`reference/reference_summary` For an overview on contributing to the *Black*, please checkout :doc:`the_basics`. diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md new file mode 100644 index 0000000..fadef4b --- /dev/null +++ b/docs/contributing/release_process.md @@ -0,0 +1,72 @@ +# Release process + +_Black_ has had a lot of work automating its release process. This document sets out to +explain what everything does and how to release _Black_ using said automation. + +## Cutting a Relase + +To cut a realease, you must be a _Black_ maintainer with `GitHub Release` creation +access. Using this access, the release process is: + +1. Cut a new PR editing `CHANGES.md` to version the latest changes + 1. Example PR: https://github.com/psf/black/pull/2192 + 2. Example title: `Update CHANGES.md for XX.X release` +2. Once the release PR is merged ensure all CI passes + 1. If not, ensure there is an Issue open for the cause of failing CI (generally we'd + want this fixed before cutting a release) +3. Open `CHANGES.md` and copy the _raw markdown_ of the latest changes to use in the + description of the GitHub Release. +4. Go and [cut a release](https://github.com/psf/black/releases) using the GitHub UI so + that all workflows noted below are triggered. + 1. The release version and tag should be the [CalVer](https://calver.org) version + _Black_ used for the current release e.g. `21.6` / `21.5b1` + 2. _Black_ uses [setuptools scm](https://pypi.org/project/setuptools-scm/) to pull + the current version for the package builds and release. +5. Once the release is cut, you're basically done. It's a good practice to go and watch + to make sure all the [GitHub Actions](https://github.com/psf/black/actions) pass, + although you should receive an email to your registered GitHub email address should + one fail. + 1. You should see all the release workflows and lint/unittests workflows running on + the new tag in the Actions UI + +If anything fails, please go read the respective action's log output and configuration +file to reverse engineer your way to a fix/soluton. + +## Release workflows + +All _Blacks_'s automation workflows use GitHub Actions. All workflows are therefore +configured using `.yml` files in the `.github/workflows` directory of the _Black_ +repository. + +Below are descriptions of our release workflows. + +### Docker + +This workflow uses the QEMU powered `buildx` feature of docker to upload a `arm64` and +`amd64`/`x86_64` build of the official _Black_ docker image™. + +- Currently this workflow uses an API Token associated with @cooperlees account + +### pypi_upload + +This workflow builds a Python +[sdist](https://docs.python.org/3/distutils/sourcedist.html) and +[wheel](https://pythonwheels.com) using the latest +[setuptools](https://pypi.org/project/setuptools/) and +[wheel](https://pypi.org/project/wheel/) modules. + +It will then use [twine](https://pypi.org/project/twine/) to upload both release formats +to PyPI for general downloading of the _Black_ Python package. This is where +[pip](https://pypi.org/project/pip/) looks by default. + +- Currently this workflow uses an API token associated with @ambv's PyPI account + +### Upload self-contained binaries + +This workflow builds self-contained binaries for multiple platforms. This allows people +to download the executable for their platform and run _Black_ without a +[Python Runtime](https://wiki.python.org/moin/PythonImplementations) installed. + +The created binaries are attached/stored on the associated +[GitHub Release](https://github.com/psf/black/releases) for download over _IPv4 only_ +(GitHub still does not have IPv6 access 😢). -- 2.39.5 From f933e8a8382e6945bf950356f6ecc4ded5617617 Mon Sep 17 00:00:00 2001 From: Cooper Lees Date: Mon, 10 May 2021 07:59:32 -0700 Subject: [PATCH 06/16] Update CHANGES.md for 21.5b1 release (#2215) --- CHANGES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGES.md b/CHANGES.md index 32c2d8d..38eef52 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,6 @@ # Change Log -## Unreleased +## 21.5b1 ### _Black_ -- 2.39.5 From 2f52e4b4929370ec503ee272bcc10d3176db8e89 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Mon, 10 May 2021 08:01:53 -0700 Subject: [PATCH 07/16] fix typo (#2217) --- docs/contributing/release_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md index fadef4b..ae95cd7 100644 --- a/docs/contributing/release_process.md +++ b/docs/contributing/release_process.md @@ -5,7 +5,7 @@ explain what everything does and how to release _Black_ using said automation. ## Cutting a Relase -To cut a realease, you must be a _Black_ maintainer with `GitHub Release` creation +To cut a release, you must be a _Black_ maintainer with `GitHub Release` creation access. Using this access, the release process is: 1. Cut a new PR editing `CHANGES.md` to version the latest changes -- 2.39.5 From 53d9bace12b3aa230820c869a079020b4608c945 Mon Sep 17 00:00:00 2001 From: Cooper Lees Date: Tue, 11 May 2021 10:01:03 -0700 Subject: [PATCH 08/16] Add stable tag process to release process documentation (#2224) * Add stable tag process to release process documentation - Add reasoning + step commands * Bah - I ran the linter but forgot to commit * Update docs/contributing/release_process.md Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com> Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com> --- docs/contributing/release_process.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md index ae95cd7..718ea3d 100644 --- a/docs/contributing/release_process.md +++ b/docs/contributing/release_process.md @@ -3,7 +3,7 @@ _Black_ has had a lot of work automating its release process. This document sets out to explain what everything does and how to release _Black_ using said automation. -## Cutting a Relase +## Cutting a Release To cut a release, you must be a _Black_ maintainer with `GitHub Release` creation access. Using this access, the release process is: @@ -70,3 +70,20 @@ to download the executable for their platform and run _Black_ without a The created binaries are attached/stored on the associated [GitHub Release](https://github.com/psf/black/releases) for download over _IPv4 only_ (GitHub still does not have IPv6 access 😢). + +## Moving the `stable` tag + +_Black_ provides a stable tag for people who want to move along as _Black_ developers +deem the newest version reliable. Here the _Black_ developers will move once the release +has been problem free for at least ~24 hours from release. Given the large _Black_ +userbase we hear about bad bugs quickly. We do strive to continually improve our CI too. + +### Tag moving process + +#### stable + +From a rebased `main` checkout: + +1. `git tag -f stable VERSION_TAG` + 1. e.g. `git tag -f stable 21.5b1` +1. `git push --tags -f` -- 2.39.5 From 94a0b07dbebabe344991dc27f9eb0b11597bb3b5 Mon Sep 17 00:00:00 2001 From: Richard Si <63936253+ichard26@users.noreply.github.com> Date: Tue, 11 May 2021 14:09:33 -0400 Subject: [PATCH 09/16] Remove useless flake8 config + test support code (#2221) We've depended on Click 7.x ever since we broke CI systems across the world (oops lol) and flake8-mypy was purged a fair bit back: #1867 Also remove the primer tests import in tests/test_black.py because it's annoying when just trying to actually target tests/test_black.py tests. `pytest -k test_black.py` doesn't do what you expect due to that import. --- .flake8 | 4 ---- tests/test_black.py | 35 +++++++---------------------------- 2 files changed, 7 insertions(+), 32 deletions(-) diff --git a/.flake8 b/.flake8 index 68d1501..4866133 100644 --- a/.flake8 +++ b/.flake8 @@ -5,7 +5,3 @@ extend-ignore = E203, E266, E501 max-line-length = 80 max-complexity = 18 select = B,C,E,F,W,T4,B9 -# We need to configure the mypy.ini because the flake8-mypy's default -# options don't properly override it, so if we don't specify it we get -# half of the config from mypy.ini and half from flake8-mypy. -mypy_config = mypy.ini diff --git a/tests/test_black.py b/tests/test_black.py index 347eaf6..4cbb022 100644 --- a/tests/test_black.py +++ b/tests/test_black.py @@ -6,7 +6,7 @@ from concurrent.futures import ThreadPoolExecutor from contextlib import contextmanager from dataclasses import replace import inspect -from io import BytesIO, TextIOWrapper +from io import BytesIO import os from pathlib import Path from platform import system @@ -16,10 +16,8 @@ from tempfile import TemporaryDirectory import types from typing import ( Any, - BinaryIO, Callable, Dict, - Generator, List, Iterator, TypeVar, @@ -52,7 +50,6 @@ from tests.util import ( ff, dump_to_stderr, ) -from .test_primer import PrimerCLITests # noqa: F401 THIS_FILE = Path(__file__) @@ -104,28 +101,10 @@ class FakeParameter(click.Parameter): class BlackRunner(CliRunner): - """Modify CliRunner so that stderr is not merged with stdout. - - This is a hack that can be removed once we depend on Click 7.x""" + """Make sure STDOUT and STDERR are kept seperate when testing Black via its CLI.""" def __init__(self) -> None: - self.stderrbuf = BytesIO() - self.stdoutbuf = BytesIO() - self.stdout_bytes = b"" - self.stderr_bytes = b"" - super().__init__() - - @contextmanager - def isolation(self, *args: Any, **kwargs: Any) -> Generator[BinaryIO, None, None]: - with super().isolation(*args, **kwargs) as output: - try: - hold_stderr = sys.stderr - sys.stderr = TextIOWrapper(self.stderrbuf, encoding=self.charset) - yield output - finally: - self.stdout_bytes = sys.stdout.buffer.getvalue() # type: ignore - self.stderr_bytes = sys.stderr.buffer.getvalue() # type: ignore - sys.stderr = hold_stderr + super().__init__(mix_stderr=False) class BlackTestCase(BlackBaseTestCase): @@ -141,8 +120,8 @@ class BlackTestCase(BlackBaseTestCase): exit_code, msg=( f"Failed with args: {args}\n" - f"stdout: {runner.stdout_bytes.decode()!r}\n" - f"stderr: {runner.stderr_bytes.decode()!r}\n" + f"stdout: {result.stdout_bytes.decode()!r}\n" + f"stderr: {result.stderr_bytes.decode()!r}\n" f"exception: {result.exception}" ), ) @@ -483,7 +462,7 @@ class BlackTestCase(BlackBaseTestCase): finally: os.unlink(tmp_file) actual = ( - runner.stderr_bytes.decode() + result.stderr_bytes.decode() .replace("\n", "") .replace("\\n", "") .replace("\\r", "") @@ -1806,7 +1785,7 @@ class BlackTestCase(BlackBaseTestCase): black.main, ["-", "--fast"], input=BytesIO(contents.encode("utf8")) ) self.assertEqual(result.exit_code, 0) - output = runner.stdout_bytes + output = result.stdout_bytes self.assertIn(nl.encode("utf8"), output) if nl == "\n": self.assertNotIn(b"\r\n", output) -- 2.39.5 From b2ee211b5ad84b62738ac0997b73bf6ee9a74d06 Mon Sep 17 00:00:00 2001 From: =?utf8?q?=C5=81ukasz=20Langa?= Date: Wed, 12 May 2021 21:47:32 +0200 Subject: [PATCH 10/16] Click 8.0 renamed its "die on LANG=C" function so we need to look for that one too (#2227) --- CHANGES.md | 6 ++++++ mypy.ini | 6 ++++-- src/black/__init__.py | 6 ++++-- 3 files changed, 14 insertions(+), 4 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 38eef52..becd621 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,5 +1,11 @@ # Change Log +## Unreleased + +### _Black_ + +- Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227) + ## 21.5b1 ### _Black_ diff --git a/mypy.ini b/mypy.ini index 589fbf6..ae7be5e 100644 --- a/mypy.ini +++ b/mypy.ini @@ -33,5 +33,7 @@ cache_dir=/dev/null [mypy-aiohttp.*] follow_imports=skip -[mypy-_version] -follow_imports=skip +[mypy-black] +# The following is because of `patch_click()`. Remove when +# we drop Python 3.6 support. +warn_unused_ignores=False diff --git a/src/black/__init__.py b/src/black/__init__.py index c61bc8c..f46b866 100644 --- a/src/black/__init__.py +++ b/src/black/__init__.py @@ -1029,7 +1029,7 @@ def nullcontext() -> Iterator[None]: def patch_click() -> None: - """Make Click not crash. + """Make Click not crash on Python 3.6 with LANG=C. On certain misconfigured environments, Python 3 selects the ASCII encoding as the default which restricts paths that it can access during the lifetime of the @@ -1047,7 +1047,9 @@ def patch_click() -> None: for module in (core, _unicodefun): if hasattr(module, "_verify_python3_env"): - module._verify_python3_env = lambda: None + module._verify_python3_env = lambda: None # type: ignore + if hasattr(module, "_verify_python_env"): + module._verify_python_env = lambda: None # type: ignore def patched_main() -> None: -- 2.39.5 From 3ef339b2e75468a09d617e6aa74bc920c317bce6 Mon Sep 17 00:00:00 2001 From: Richard Si <63936253+ichard26@users.noreply.github.com> Date: Wed, 12 May 2021 21:28:41 -0400 Subject: [PATCH 11/16] Modify when Test, Primer, and Documentation Build run (#2226) - Test and Primer don't run for documentation only changes since it's unnecessary, eating unnecessary cycles and slowing down CI since these workflows eat up the 20 max workers limit quite easily! - Documentation Build runs all of the time now since quite a bit of the content depends on Black's code so even a simple 1-file change in src/black/__init__.py may break the docs build. It's not like this is a costly workflow anyway. Fuzz is still running on all changes because with fuzzing, the more the better in general. 6 or 7 jobs on a documentation only commit is much better than 27/28 jobs anyway :p I also found an error in our bug report issue template :) --- .github/ISSUE_TEMPLATE/bug_report.md | 2 +- .github/workflows/doc.yml | 16 +--------------- .github/workflows/primer.yml | 11 ++++++++++- .github/workflows/test.yml | 11 ++++++++++- 4 files changed, 22 insertions(+), 18 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index c6c80be..069795f 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -30,7 +30,7 @@ assignees: "" - clone this repository; - run `pip install -e .[d,python2]`; - run `pip install -r test_requirements.txt` - - make sure it's sane by running `python -m unittest`; and + - make sure it's sane by running `python -m pytest`; and - run `black` like you did last time. **Additional context** Add any other context about the problem here. diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 74ec316..04b25cf 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -1,20 +1,6 @@ name: Documentation Build -on: - push: - paths: - - "docs/**" - - "README.md" - - "CHANGES.md" - - "CONTRIBUTING.md" - - "AUTHORS.md" - pull_request: - paths: - - "docs/**" - - "README.md" - - "CHANGES.md" - - "CONTRIBUTING.md" - - "AUTHORS.md" +on: [push, pull_request] jobs: build: diff --git a/.github/workflows/primer.yml b/.github/workflows/primer.yml index 4c5751a..5f41c30 100644 --- a/.github/workflows/primer.yml +++ b/.github/workflows/primer.yml @@ -1,6 +1,15 @@ name: Primer -on: [push, pull_request] +on: + push: + paths-ignore: + - "docs/**" + - "*.md" + + pull_request: + paths-ignore: + - "docs/**" + - "*.md" jobs: build: diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 2cfbab6..ef8debb 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,6 +1,15 @@ name: Test -on: [push, pull_request] +on: + push: + paths-ignore: + - "docs/**" + - "*.md" + + pull_request: + paths-ignore: + - "docs/**" + - "*.md" jobs: build: -- 2.39.5 From 445f094f1fa2d998bf0cc0007ea48d62953fa876 Mon Sep 17 00:00:00 2001 From: Christian Clauss Date: Thu, 13 May 2021 19:28:41 +0200 Subject: [PATCH 12/16] Use codespell to find typos (#2228) --- CHANGES.md | 1 + docs/index.rst | 2 +- src/black/trans.py | 2 +- src/black_primer/lib.py | 2 +- tests/test_black.py | 4 ++-- 5 files changed, 6 insertions(+), 5 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index becd621..3639d8e 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -4,6 +4,7 @@ ### _Black_ +- Fix typos discovered by codespell (#2228) - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227) ## 21.5b1 diff --git a/docs/index.rst b/docs/index.rst index a7a7160..2b85cdd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,7 +22,7 @@ Try it out now using the `Black Playground `_. many projects, small and big. *Black* has a comprehensive test suite, with efficient parallel tests, our own auto formatting and parallel Continuous Integration runner. However, *Black* is still beta. Things will probably be wonky for a while. This is - made explicit by the "Beta" trove classifier, as well as by the "b" in the versio + made explicit by the "Beta" trove classifier, as well as by the "b" in the version number. What this means for you is that **until the formatter becomes stable, you should expect some formatting to change in the future**. That being said, no drastic stylistic changes are planned, mostly responses to bug reports. diff --git a/src/black/trans.py b/src/black/trans.py index 055f33c..7ecc31d 100644 --- a/src/black/trans.py +++ b/src/black/trans.py @@ -576,7 +576,7 @@ class StringParenStripper(StringTransformer): - The target string is NOT the only argument to a function call. - The target string is NOT a "pointless" string. - If the target string contains a PERCENT, the brackets are not - preceeded or followed by an operator with higher precedence than + preceded or followed by an operator with higher precedence than PERCENT. Transformations: diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py index 3ce383f..384c0ad 100644 --- a/src/black_primer/lib.py +++ b/src/black_primer/lib.py @@ -128,7 +128,7 @@ async def black_run( cmd.extend(["--diff", "."]) with TemporaryDirectory() as tmp_path: - # Prevent reading top-level user configs by manipulating envionment variables + # Prevent reading top-level user configs by manipulating environment variables env = { **os.environ, "XDG_CONFIG_HOME": tmp_path, # Unix-like diff --git a/tests/test_black.py b/tests/test_black.py index 4cbb022..5ab25cd 100644 --- a/tests/test_black.py +++ b/tests/test_black.py @@ -101,7 +101,7 @@ class FakeParameter(click.Parameter): class BlackRunner(CliRunner): - """Make sure STDOUT and STDERR are kept seperate when testing Black via its CLI.""" + """Make sure STDOUT and STDERR are kept separate when testing Black via its CLI.""" def __init__(self) -> None: super().__init__(mix_stderr=False) @@ -1508,7 +1508,7 @@ class BlackTestCase(BlackBaseTestCase): @patch("black.find_project_root", lambda *args: THIS_DIR.resolve()) def test_get_sources_with_stdin_filename_and_exclude(self) -> None: - # Exclude shouldn't exclude stdin_filename since it is mimicing the + # Exclude shouldn't exclude stdin_filename since it is mimicking the # file being passed directly. This is the same as # test_exclude_for_issue_1572 path = THIS_DIR / "data" / "include_exclude_tests" -- 2.39.5 From 904fe94ceba29f3f0c5b8772c4faf699de57338f Mon Sep 17 00:00:00 2001 From: Richard Si <63936253+ichard26@users.noreply.github.com> Date: Thu, 13 May 2021 15:30:34 -0400 Subject: [PATCH 13/16] Add lower bound for aiohttp-cors + fix primer (#2231) It appears sqlalchemy has recently reformatted their project with Black 21.5b1. Most of our dependencies have a lower bound and creating a test environment with the oldest acceptable dependencies runs the full Black test suite just fine. The only exception to this is aiohttp-cors. It's unbounded and the oldest version 0.1.0 until 0.4.0 breaks the test suite in such an old environment. Failure with 0.1.0: ``` tests/test_blackd.py:10: in import blackd testenv/lib/python3.8/site-packages/blackd/__init__.py:12: in import aiohttp_cors testenv/lib/python3.8/site-packages/aiohttp_cors/__init__.py:29: in from .urldispatcher_router_adapter import UrlDistatcherRouterAdapter testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:27: in class UrlDistatcherRouterAdapter(RouterAdapter): testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:32: in UrlDistatcherRouterAdapter def route_methods(self, route: web.Route): E AttributeError: module 'aiohttp.web' has no attribute 'Route' ``` For 0.2.0: ``` tests/test_blackd.py:10: in import blackd testenv/lib/python3.8/site-packages/blackd/__init__.py:12: in import aiohttp_cors testenv/lib/python3.8/site-packages/aiohttp_cors/__init__.py:27: in from .cors_config import CorsConfig testenv/lib/python3.8/site-packages/aiohttp_cors/cors_config.py:24: in from .urldispatcher_router_adapter import UrlDistatcherRouterAdapter testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:27: in class UrlDistatcherRouterAdapter(AbstractRouterAdapter): testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:32: in UrlDistatcherRouterAdapter def route_methods(self, route: web.Route): E AttributeError: module 'aiohttp.web' has no attribute 'Route' ``` For 0.3.0: ``` ERROR: Cannot install aiohttp-cors==0.3.0 and aiohttp==3.6.0 because these package versions have conflicting dependencies. The conflict is caused by: The user requested aiohttp==3.6.0 aiohttp-cors 0.3.0 depends on aiohttp<=0.20.2 and >=0.18.0 To fix this you could try to: 1. loosen the range of package versions you've specified 2. remove package versions to allow pip attempt to solve the dependency conflict ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/user_guide/#fixing-conflicting-dependencies ``` --- CHANGES.md | 5 +++++ setup.py | 2 +- src/black_primer/primer.json | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 3639d8e..85936e8 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -7,6 +7,11 @@ - Fix typos discovered by codespell (#2228) - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227) +### _Blackd_ + +- Add a lower bound for the `aiohttp-cors` dependency. Only 0.4.0 or higher is + supported. (#2231) + ## 21.5b1 ### _Black_ diff --git a/setup.py b/setup.py index 3dc52b2..2b5f71f 100644 --- a/setup.py +++ b/setup.py @@ -83,7 +83,7 @@ setup( "mypy_extensions>=0.4.3", ], extras_require={ - "d": ["aiohttp>=3.6.0", "aiohttp-cors"], + "d": ["aiohttp>=3.6.0", "aiohttp-cors>=0.4.0"], "colorama": ["colorama>=0.4.3"], "python2": ["typed-ast>=1.4.2"], }, diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json index 76ed482..0bbac85 100644 --- a/src/black_primer/primer.json +++ b/src/black_primer/primer.json @@ -106,7 +106,7 @@ "sqlalchemy": { "no_cli_args_reason": "breaks black with new string parsing - #2188", "cli_arguments": [], - "expect_formatting_changes": true, + "expect_formatting_changes": false, "git_clone_url": "https://github.com/sqlalchemy/sqlalchemy.git", "long_checkout": false, "py_versions": ["all"] -- 2.39.5 From 403ce1a18a8a1600ab8249d828e7eaaca442cad7 Mon Sep 17 00:00:00 2001 From: Richard Si <63936253+ichard26@users.noreply.github.com> Date: Sun, 16 May 2021 12:07:27 -0400 Subject: [PATCH 14/16] Add issue triage documentation (#2236) MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit * Add issue triage documentation Co-authored-by: Łukasz Langa Co-authored-by: Jelle Zijlstra --- Pipfile | 3 +- Pipfile.lock | 120 ++++++++++----------- docs/conf.py | 1 + docs/contributing/index.rst | 1 + docs/contributing/issue_triage.md | 167 ++++++++++++++++++++++++++++++ docs/requirements.txt | 3 + 6 files changed, 229 insertions(+), 66 deletions(-) create mode 100644 docs/contributing/issue_triage.md diff --git a/Pipfile b/Pipfile index b385957..789d97c 100644 --- a/Pipfile +++ b/Pipfile @@ -14,6 +14,7 @@ pre-commit = "*" readme_renderer = "*" MyST-Parser = ">=0.13.7" sphinxcontrib-programoutput = ">=0.17" +sphinx-copybutton = ">=0.3.0" setuptools = ">=39.2.0" setuptools-scm = "*" twine = ">=1.11.0" @@ -22,7 +23,7 @@ black = {editable = true, extras = ["d"], path = "."} [packages] aiohttp = ">=3.6.0" -aiohttp-cors = "*" +aiohttp-cors = ">=0.4.0" appdirs = "*" click = ">=7.1.2" mypy_extensions = ">=0.4.3" diff --git a/Pipfile.lock b/Pipfile.lock index 0b9e529..b6dfe43 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "fdfbacb362e4514e588736a7e8783837cb5e3aa2fbab98ea17894fdb50d51a8e" + "sha256": "b450e698cfe4d856397cb9d0695dcd74eb97b1d234de273179d78c0d0efccd0f" }, "pipfile-spec": 6, "requires": {}, @@ -106,11 +106,11 @@ }, "click": { "hashes": [ - "sha256:d2b5255c7c6349bc1bd1e59e08cd12acbbd63ce649f2588755783aa94dfb6b1a", - "sha256:dacca89f4bfadd5de3d7489b7c8a566eee0d3676333fbb50030263894c38c0dc" + "sha256:7d8c289ee437bcb0316820ccee14aefcb056e58d31830ecab8e47eda6540e136", + "sha256:e90e62ced43dc8105fb9a26d62f0d9340b5c8db053a814e25d95c19873ae87db" ], "index": "pypi", - "version": "==7.1.2" + "version": "==8.0.0" }, "dataclasses": { "hashes": [ @@ -516,11 +516,11 @@ }, "click": { "hashes": [ - "sha256:d2b5255c7c6349bc1bd1e59e08cd12acbbd63ce649f2588755783aa94dfb6b1a", - "sha256:dacca89f4bfadd5de3d7489b7c8a566eee0d3676333fbb50030263894c38c0dc" + "sha256:7d8c289ee437bcb0316820ccee14aefcb056e58d31830ecab8e47eda6540e136", + "sha256:e90e62ced43dc8105fb9a26d62f0d9340b5c8db053a814e25d95c19873ae87db" ], "index": "pypi", - "version": "==7.1.2" + "version": "==8.0.0" }, "colorama": { "hashes": [ @@ -687,11 +687,11 @@ }, "jinja2": { "hashes": [ - "sha256:03e47ad063331dd6a3f04a43eddca8a966a26ba0c5b7207a9a9e4e08f1b29419", - "sha256:a6d58433de0ae800347cab1fa3043cebbabe8baa9d29e668f1c768cb87a333c6" + "sha256:2f2de5285cf37f33d33ecd4a9080b75c87cd0c1994d5a9c6df17131ea1f049c6", + "sha256:ea8d7dd814ce9df6de6a761ec7f1cac98afe305b8cdc4aaae4e114b8d8ce24c5" ], - "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'", - "version": "==2.11.3" + "markers": "python_version >= '3.6'", + "version": "==3.0.0" }, "keyring": { "hashes": [ @@ -711,61 +711,43 @@ }, "markupsafe": { "hashes": [ - "sha256:00bc623926325b26bb9605ae9eae8a215691f33cae5df11ca5424f06f2d1f473", - "sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161", - "sha256:09c4b7f37d6c648cb13f9230d847adf22f8171b1ccc4d5682398e77f40309235", - "sha256:1027c282dad077d0bae18be6794e6b6b8c91d58ed8a8d89a89d59693b9131db5", - "sha256:13d3144e1e340870b25e7b10b98d779608c02016d5184cfb9927a9f10c689f42", - "sha256:195d7d2c4fbb0ee8139a6cf67194f3973a6b3042d742ebe0a9ed36d8b6f0c07f", - "sha256:22c178a091fc6630d0d045bdb5992d2dfe14e3259760e713c490da5323866c39", - "sha256:24982cc2533820871eba85ba648cd53d8623687ff11cbb805be4ff7b4c971aff", - "sha256:29872e92839765e546828bb7754a68c418d927cd064fd4708fab9fe9c8bb116b", - "sha256:2beec1e0de6924ea551859edb9e7679da6e4870d32cb766240ce17e0a0ba2014", - "sha256:3b8a6499709d29c2e2399569d96719a1b21dcd94410a586a18526b143ec8470f", - "sha256:43a55c2930bbc139570ac2452adf3d70cdbb3cfe5912c71cdce1c2c6bbd9c5d1", - "sha256:46c99d2de99945ec5cb54f23c8cd5689f6d7177305ebff350a58ce5f8de1669e", - "sha256:500d4957e52ddc3351cabf489e79c91c17f6e0899158447047588650b5e69183", - "sha256:535f6fc4d397c1563d08b88e485c3496cf5784e927af890fb3c3aac7f933ec66", - "sha256:596510de112c685489095da617b5bcbbac7dd6384aeebeda4df6025d0256a81b", - "sha256:62fe6c95e3ec8a7fad637b7f3d372c15ec1caa01ab47926cfdf7a75b40e0eac1", - "sha256:6788b695d50a51edb699cb55e35487e430fa21f1ed838122d722e0ff0ac5ba15", - "sha256:6dd73240d2af64df90aa7c4e7481e23825ea70af4b4922f8ede5b9e35f78a3b1", - "sha256:6f1e273a344928347c1290119b493a1f0303c52f5a5eae5f16d74f48c15d4a85", - "sha256:6fffc775d90dcc9aed1b89219549b329a9250d918fd0b8fa8d93d154918422e1", - "sha256:717ba8fe3ae9cc0006d7c451f0bb265ee07739daf76355d06366154ee68d221e", - "sha256:79855e1c5b8da654cf486b830bd42c06e8780cea587384cf6545b7d9ac013a0b", - "sha256:7c1699dfe0cf8ff607dbdcc1e9b9af1755371f92a68f706051cc8c37d447c905", - "sha256:7fed13866cf14bba33e7176717346713881f56d9d2bcebab207f7a036f41b850", - "sha256:84dee80c15f1b560d55bcfe6d47b27d070b4681c699c572af2e3c7cc90a3b8e0", - "sha256:88e5fcfb52ee7b911e8bb6d6aa2fd21fbecc674eadd44118a9cc3863f938e735", - "sha256:8defac2f2ccd6805ebf65f5eeb132adcf2ab57aa11fdf4c0dd5169a004710e7d", - "sha256:98bae9582248d6cf62321dcb52aaf5d9adf0bad3b40582925ef7c7f0ed85fceb", - "sha256:98c7086708b163d425c67c7a91bad6e466bb99d797aa64f965e9d25c12111a5e", - "sha256:9add70b36c5666a2ed02b43b335fe19002ee5235efd4b8a89bfcf9005bebac0d", - "sha256:9bf40443012702a1d2070043cb6291650a0841ece432556f784f004937f0f32c", - "sha256:a6a744282b7718a2a62d2ed9d993cad6f5f585605ad352c11de459f4108df0a1", - "sha256:acf08ac40292838b3cbbb06cfe9b2cb9ec78fce8baca31ddb87aaac2e2dc3bc2", - "sha256:ade5e387d2ad0d7ebf59146cc00c8044acbd863725f887353a10df825fc8ae21", - "sha256:b00c1de48212e4cc9603895652c5c410df699856a2853135b3967591e4beebc2", - "sha256:b1282f8c00509d99fef04d8ba936b156d419be841854fe901d8ae224c59f0be5", - "sha256:b1dba4527182c95a0db8b6060cc98ac49b9e2f5e64320e2b56e47cb2831978c7", - "sha256:b2051432115498d3562c084a49bba65d97cf251f5a331c64a12ee7e04dacc51b", - "sha256:b7d644ddb4dbd407d31ffb699f1d140bc35478da613b441c582aeb7c43838dd8", - "sha256:ba59edeaa2fc6114428f1637ffff42da1e311e29382d81b339c1817d37ec93c6", - "sha256:bf5aa3cbcfdf57fa2ee9cd1822c862ef23037f5c832ad09cfea57fa846dec193", - "sha256:c8716a48d94b06bb3b2524c2b77e055fb313aeb4ea620c8dd03a105574ba704f", - "sha256:caabedc8323f1e93231b52fc32bdcde6db817623d33e100708d9a68e1f53b26b", - "sha256:cd5df75523866410809ca100dc9681e301e3c27567cf498077e8551b6d20e42f", - "sha256:cdb132fc825c38e1aeec2c8aa9338310d29d337bebbd7baa06889d09a60a1fa2", - "sha256:d53bc011414228441014aa71dbec320c66468c1030aae3a6e29778a3382d96e5", - "sha256:d73a845f227b0bfe8a7455ee623525ee656a9e2e749e4742706d80a6065d5e2c", - "sha256:d9be0ba6c527163cbed5e0857c451fcd092ce83947944d6c14bc95441203f032", - "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7", - "sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be", - "sha256:feb7b34d6325451ef96bc0e36e1a6c0c1c64bc1fbec4b854f4529e51887b1621" + "sha256:007dc055dbce5b1104876acee177dbfd18757e19d562cd440182e1f492e96b95", + "sha256:031bf79a27d1c42f69c276d6221172417b47cb4b31cdc73d362a9bf5a1889b9f", + "sha256:161d575fa49395860b75da5135162481768b11208490d5a2143ae6785123e77d", + "sha256:24bbc3507fb6dfff663af7900a631f2aca90d5a445f272db5fc84999fa5718bc", + "sha256:2efaeb1baff547063bad2b2893a8f5e9c459c4624e1a96644bbba08910ae34e0", + "sha256:32200f562daaab472921a11cbb63780f1654552ae49518196fc361ed8e12e901", + "sha256:3261fae28155e5c8634dd7710635fe540a05b58f160cef7713c7700cb9980e66", + "sha256:3b54a9c68995ef4164567e2cd1a5e16db5dac30b2a50c39c82db8d4afaf14f63", + "sha256:3c352ff634e289061711608f5e474ec38dbaa21e3e168820d53d5f4015e5b91b", + "sha256:3fb47f97f1d338b943126e90b79cad50d4fcfa0b80637b5a9f468941dbbd9ce5", + "sha256:441ce2a8c17683d97e06447fcbccbdb057cbf587c78eb75ae43ea7858042fe2c", + "sha256:45535241baa0fc0ba2a43961a1ac7562ca3257f46c4c3e9c0de38b722be41bd1", + "sha256:4aca81a687975b35e3e80bcf9aa93fe10cd57fac37bf18b2314c186095f57e05", + "sha256:4cc563836f13c57f1473bc02d1e01fc37bab70ad4ee6be297d58c1d66bc819bf", + "sha256:4fae0677f712ee090721d8b17f412f1cbceefbf0dc180fe91bab3232f38b4527", + "sha256:58bc9fce3e1557d463ef5cee05391a05745fd95ed660f23c1742c711712c0abb", + "sha256:664832fb88b8162268928df233f4b12a144a0c78b01d38b81bdcf0fc96668ecb", + "sha256:70820a1c96311e02449591cbdf5cd1c6a34d5194d5b55094ab725364375c9eb2", + "sha256:79b2ae94fa991be023832e6bcc00f41dbc8e5fe9d997a02db965831402551730", + "sha256:83cf0228b2f694dcdba1374d5312f2277269d798e65f40344964f642935feac1", + "sha256:87de598edfa2230ff274c4de7fcf24c73ffd96208c8e1912d5d0fee459767d75", + "sha256:8f806bfd0f218477d7c46a11d3e52dc7f5fdfaa981b18202b7dc84bbc287463b", + "sha256:90053234a6479738fd40d155268af631c7fca33365f964f2208867da1349294b", + "sha256:a00dce2d96587651ef4fa192c17e039e8cfab63087c67e7d263a5533c7dad715", + "sha256:a08cd07d3c3c17cd33d9e66ea9dee8f8fc1c48e2d11bd88fd2dc515a602c709b", + "sha256:a19d39b02a24d3082856a5b06490b714a9d4179321225bbf22809ff1e1887cc8", + "sha256:d00a669e4a5bec3ee6dbeeeedd82a405ced19f8aeefb109a012ea88a45afff96", + "sha256:dab0c685f21f4a6c95bfc2afd1e7eae0033b403dd3d8c1b6d13a652ada75b348", + "sha256:df561f65049ed3556e5b52541669310e88713fdae2934845ec3606f283337958", + "sha256:e4570d16f88c7f3032ed909dc9e905a17da14a1c4cfd92608e3fda4cb1208bbd", + "sha256:e77e4b983e2441aff0c0d07ee711110c106b625f440292dfe02a2f60c8218bd6", + "sha256:e79212d09fc0e224d20b43ad44bb0a0a3416d1e04cf6b45fed265114a5d43d20", + "sha256:f58b5ba13a5689ca8317b98439fccfbcc673acaaf8241c1869ceea40f5d585bf", + "sha256:fef86115fdad7ae774720d7103aa776144cf9b66673b4afa9bcaa7af990ed07b" ], - "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", - "version": "==1.1.1" + "markers": "python_version >= '3.6'", + "version": "==2.0.0" }, "mccabe": { "hashes": [ @@ -1105,6 +1087,14 @@ "index": "pypi", "version": "==3.5.4" }, + "sphinx-copybutton": { + "hashes": [ + "sha256:0e0461df394515284e3907e3f418a0c60ef6ab6c9a27a800c8552772d0a402a2", + "sha256:5125c718e763596e6e52d92e15ee0d6f4800ad3817939be6dee51218870b3e3d" + ], + "index": "pypi", + "version": "==0.3.1" + }, "sphinxcontrib-applehelp": { "hashes": [ "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a", diff --git a/docs/conf.py b/docs/conf.py index 7162f13..15adb5d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -60,6 +60,7 @@ extensions = [ "sphinx.ext.napoleon", "myst_parser", "sphinxcontrib.programoutput", + "sphinx_copybutton", ] # If you need extensions of a certain version or higher, list them here. diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index e7a7f9f..7e3a909 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -6,6 +6,7 @@ Contributing the_basics gauging_changes + issue_triage release_process reference/reference_summary diff --git a/docs/contributing/issue_triage.md b/docs/contributing/issue_triage.md new file mode 100644 index 0000000..780b2b5 --- /dev/null +++ b/docs/contributing/issue_triage.md @@ -0,0 +1,167 @@ +# Issue triage + +Currently, _Black_ uses the issue tracker for bugs, feature requests, proposed design +modifications, and general user support. Each of these issues have to be triaged so they +can be eventually be resolved somehow. This document outlines the triaging process and +also the current guidelines and recommendations. + +```{tip} +If you're looking for a way to contribute without submitting patches, this might be +the area for you. Since _Black_ is a popular project, its issue tracker is quite busy +and always needs more attention than is available. While triage isn't the most +glamorous or technically challenging form of contribution, it's still important. +For example, we would love to know whether that old bug report is still reproducible! + +You can get easily started by reading over this document and then responding to issues. + +If you contribute enough and have stayed for a long enough time, you may even be +given Triage permissions! +``` + +## The basics + +_Black_ gets a whole bunch of different issues, they range from bug reports to user +support issues. To triage is to identify, organize, and kickstart the issue's journey +through its lifecycle to resolution. + +More specifically, to triage an issue means to: + +- identify what type and categories the issue falls under +- confirm bugs +- ask questions / for further information if necessary +- link related issues +- provide the first initial feedback / support + +Note that triage is typically the first response to an issue, so don't fret if the issue +doesn't make much progress after initial triage. The main goal of triaging to prepare +the issue for future more specific development or discussion, so _eventually_ it will be +resolved. + +The lifecycle of a bug report or user support issue typically goes something like this: + +1. _the issue is waiting for triage_ +2. **identified** - has been marked with a type label and other relevant labels, more + details or a functional reproduction may be still needed (and therefore should be + marked with `S: needs repro` or `S: awaiting reponse`) +3. **confirmed** - the issue can reproduced and necessary details have been provided +4. **discussion** - initial triage has been done and now the general details on how the + issue should be best resolved are being hashed out +5. **awaiting fix** - no further discussion on the issue is necessary and a resolving PR + is the next step +6. **closed** - the issue has been resolved, reasons include: + - the issue couldn't be reproduced + - the issue has been fixed + - duplicate of another pre-existing issue or is invalid + +For enhancement, documentation, and design issues, the lifecycle looks very similar but +the details are different: + +1. _the issue is waiting for triage_ +2. **identified** - has been marked with a type label and other relevant labels +3. **discussion** - the merits of the suggested changes are currently being discussed, a + PR would be acceptable but would be at sigificant risk of being rejected +4. **accepted & awaiting PR** - it's been determined the suggested changes are OK and a + PR would be welcomed (`S: accepted`) +5. **closed**: - the issue has been resolved, reasons include: + - the suggested changes were implemented + - it was rejected (due to technical concerns, ethos conflicts, etc.) + - duplicate of a pre-existing issue or is invalid + +**Note**: documentation issues don't use the `S: accepted` label currently since they're +less likely to be rejected. + +## Labelling + +We use labels to organize, track progress, and help effectively divvy up work. + +Our labels are divided up into several groups identified by their prefix: + +- **T - Type**: the general flavor of issue / PR +- **C - Category**: areas of concerns, ranges from bug types to project maintenance +- **F - Formatting Area**: like C but for formatting specifically +- **S - Status**: what stage of resolution is this issue currently in? +- **R - Resolution**: how / why was the issue / PR resolved? + +We also have a few standalone labels: + +- **`good first issue`**: issues that are beginner-friendly (and will show up in GitHub + banners for first-time visitors to the repository) +- **`help wanted`**: complex issues that need and are looking for a fair bit of work as + to progress (will also show up in various GitHub pages) +- **`skip news`**: for PRs that are trivial and don't need a CHANGELOG entry (and skips + the CHANGELOG entry check) + +```{note} +We do use labels for PRs, in particular the `skip news` label, but we aren't that +rigorous about it. Just follow your judgement on what labels make sense for the +specific PR (if any even make sense). +``` + +## Projects + +For more general and broad goals we use projects to track work. Some may be longterm +projects with no true end (e.g. the "Amazing documentation" project) while others may be +more focused and have a definite end (like the "Getting to beta" project). + +```{note} +To modify GitHub Projects you need the [Write repository permission level or higher](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#repository-access-for-each-permission-level). +``` + +## Closing issues + +Closing an issue signifies the issue has reached the end of its life, so closing issues +should be taken with care. The following is the general recommendation for each type of +issue. Note that these are only guidelines and if your judgement says something else +it's totally cool to go with it instead. + +For most issues, closing the issue manually or automatically after a resolving PR is +ideal. For bug reports specifically, if the bug has already been fixed, try to check in +with the issue opener that their specific case has been resolved before closing. + +Design and enhancement issues should be also closed when it's clear the proposed change +won't be implemented, whether that has been determined after a lot of discussion or just +simply goes against _Black_'s ethos. If such an issue turns heated, closing and locking +is acceptable if it's severe enough (although checking in with the core team is probably +a good idea). + +User support issues are best closed by the author or when it's clear the issue has been +resolved in some sort of manner. + +Duplicates and invalid issues should always be closed since they serve no purpose and +add noise to an already busy issue tracker. Although be careful to make sure it's truly +a duplicate and not just very similar before labelling and closing an issue as +duplicate. + +## Common reports + +Some issues are frequently opened, like issues about _Black_ formatted code causing E203 +messages. Even though these issues are probably heavily duplicated, they still require +triage sucking up valuable time from other things (although they usually skip most of +their lifecycle since they're closed on triage). + +Here's some of the most common issues and also pre-made responses you can use: + +### "The trailing comma isn't being removed by Black!" + +```text +Black used to remove the trailing comma if the expression fits in a single line, but this was changed by #826 and #1288. Now a trailing comma tells Black to always explode the expression. This change was made mostly for the cases where you _know_ a collection or whatever will grow in the future. Having it always exploded as one element per line reduces diff noise when adding elements. Before the "magic trailing comma" feature, you couldn't anticipate a collection's growth reliably since collections that fitted in one line were ruthlessly collapsed regardless of your intentions. One of Black's goals is reducing diff noise, so this was a good pragmatic change. + +So no, this is not a bug, but an intended feature. Anyway, [here's the documentation](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#the-magic-trailing-comma) on the "magic trailing comma". Hopefully that helps and sorry for the possible confusion. +``` + +### "Black formatted code is violating Flake8's E203!" + +```text +Hi, + +This is expected behaviour, please see the documentation regarding this case (emphasis +mine): + +> PEP 8 recommends to treat : in slices as a binary operator with the lowest priority, and to leave an equal amount of space on either side, **except if a parameter is omitted (e.g. ham[1 + 1 :])**. It recommends no spaces around : operators for “simple expressions” (ham[lower:upper]), and **extra space for “complex expressions” (ham[lower : upper + offset])**. **Black treats anything more than variable names as “complex” (ham[lower : upper + 1]).** It also states that for extended slices, both : operators have to have the same amount of spacing, except if a parameter is omitted (ham[1 + 1 ::]). Black enforces these rules consistently. + +> This behaviour may raise E203 whitespace before ':' warnings in style guide enforcement tools like Flake8. **Since E203 is not PEP 8 compliant, you should tell Flake8 to ignore these warnings**. + +https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#slices + +Have a good day! +``` diff --git a/docs/requirements.txt b/docs/requirements.txt index c65cbe3..56dbf3f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,6 @@ +# Used by ReadTheDocs; pinned requirements for stability. + MyST-Parser==0.14.0 Sphinx==3.5.4 sphinxcontrib-programoutput==0.17 +sphinx_copybutton==0.3.1 -- 2.39.5 From 9704922cf92c8f4b26a5efc6ddfdbd42064eae5f Mon Sep 17 00:00:00 2001 From: Matthew Clapp Date: Sun, 16 May 2021 09:10:59 -0700 Subject: [PATCH 15/16] Update vim plugin manual installation instructions. (#2235) --- CHANGES.md | 1 + docs/integrations/editors.md | 7 +++++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 85936e8..1a38bf6 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -6,6 +6,7 @@ - Fix typos discovered by codespell (#2228) - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227) +- Fix vim plugin installation instructions. (#2235) ### _Blackd_ diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md index 88176e1..dd09b4d 100644 --- a/docs/integrations/editors.md +++ b/docs/integrations/editors.md @@ -146,12 +146,15 @@ $ cd ~/.vim/bundle/black $ git checkout origin/stable -b stable ``` -or you can copy the plugin from -[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim). +or you can copy the plugin files from +[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim) and +[autoload/black.vim](https://github.com/psf/black/blob/stable/autoload/black.vim). ``` mkdir -p ~/.vim/pack/python/start/black/plugin +mkdir -p ~/.vim/pack/python/start/black/autoload curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim +curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/.vim/pack/python/start/black/autoload/black.vim ``` Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or -- 2.39.5 From 60f8bd2c89fbb370e6816fd6d6e5eca64d5b9f13 Mon Sep 17 00:00:00 2001 From: =?utf8?q?=C5=81ukasz=20Langa?= Date: Sun, 16 May 2021 18:24:28 +0200 Subject: [PATCH 16/16] Include Jelle's review suggestions --- CHANGES.md | 7 +++++-- docs/contributing/issue_triage.md | 6 ++++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 1a38bf6..f2c7954 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -4,15 +4,18 @@ ### _Black_ -- Fix typos discovered by codespell (#2228) - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227) -- Fix vim plugin installation instructions. (#2235) ### _Blackd_ - Add a lower bound for the `aiohttp-cors` dependency. Only 0.4.0 or higher is supported. (#2231) +### Documentation + +- Fix typos discovered by codespell (#2228) +- Fix Vim plugin installation instructions. (#2235) + ## 21.5b1 ### _Black_ diff --git a/docs/contributing/issue_triage.md b/docs/contributing/issue_triage.md index 780b2b5..9b987fb 100644 --- a/docs/contributing/issue_triage.md +++ b/docs/contributing/issue_triage.md @@ -116,7 +116,9 @@ it's totally cool to go with it instead. For most issues, closing the issue manually or automatically after a resolving PR is ideal. For bug reports specifically, if the bug has already been fixed, try to check in -with the issue opener that their specific case has been resolved before closing. +with the issue opener that their specific case has been resolved before closing. Note +that we close issues as soon as they're fixed in the `main` branch. This doesn't +necessarily mean they've been released yet. Design and enhancement issues should be also closed when it's clear the proposed change won't be implemented, whether that has been determined after a lot of discussion or just @@ -146,7 +148,7 @@ Here's some of the most common issues and also pre-made responses you can use: ```text Black used to remove the trailing comma if the expression fits in a single line, but this was changed by #826 and #1288. Now a trailing comma tells Black to always explode the expression. This change was made mostly for the cases where you _know_ a collection or whatever will grow in the future. Having it always exploded as one element per line reduces diff noise when adding elements. Before the "magic trailing comma" feature, you couldn't anticipate a collection's growth reliably since collections that fitted in one line were ruthlessly collapsed regardless of your intentions. One of Black's goals is reducing diff noise, so this was a good pragmatic change. -So no, this is not a bug, but an intended feature. Anyway, [here's the documentation](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#the-magic-trailing-comma) on the "magic trailing comma". Hopefully that helps and sorry for the possible confusion. +So no, this is not a bug, but an intended feature. Anyway, [here's the documentation](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#the-magic-trailing-comma) on the "magic trailing comma", including the ability to skip this functionality with the `--skip-magic-trailing-comma` option. Hopefully that helps solve the possible confusion. ``` ### "Black formatted code is violating Flake8's E203!" -- 2.39.5