Update readme and tox.ini for recent tooling changes by EliahKagan · Pull Request #1868 · gitpython-developers/GitPython (original) (raw)

There are some changes that I should have proposed and/or made in README.md and tox.ini related to #1862, which are made slightly more needed by #1865. This brings the readme and tox configuration up to date for both #1862, which was merged, and #1865, which I think will be merged soon pending one small change. Further related changes should be eventually be made in both, but they will depend on future decisions, and nothing bad will happen if changes end up not being made for an extended time after merging both #1865 and this PR.

The changes here seem significantly more cumbersome to recommend be included in #1865 than to do separately, and because they also apply to the situation brought about since #1862, I don't think they need to be done there or done before that is merged. I suggest #1865 be merged before this; the changes here will not be all correct until #1865 comes in anyway. #1865 could be merged and then this immediately merged, but I think it is also fine to merge #1865 and request changes here; that is, I think #1865 is reasonable to merge even if this is delayed. Merging them in the other order would also be okay, I think.

The core issue is that some actions that were presented as not changing file contents now change them. Currently on the main branch:

  1. I believe running tox with no arguments is always in practice assumed not to change source code in the working tree. But its lint environment changes source code due to running ruff with --fix through pre-commit. With #1865, this will happen in more cases, but the issue already exists. As noted below and in commit messages, I believe --fix is nonetheless good and should be kept. (When I reviewed #1862 I did not mention this, because I agreed with the change, which is what users of pre-commit will expect. In hindsight, I could've simplified things by proposing these changes at that time.)
  2. The readme documents make lint as linting and running a formatting check without modifying any files. This is likewise not fully accurate since #1862. The issue is not that make lint needs to behave differently, because (a) in hindsight I shouldn't have added that target, (b) I'm not sure anyone uses it, and (c) it was added to address a situation where checking for code style and formatting problems involved multiple commands and tool and plugin packages, instead of just ruff. So it's sufficient for the readme to stop recommending it as a way to avoid linting without automatic code changes.

This PR fixes (1) by making the tox lint environment not run unless explicitly listed on the command line, for now, and fixes (2) by changing the readme. This also fixes some related outdated material in the readme, improves how tools are described, and makes some some other small improvements when it seemed like I could do them without significantly complicating this PR or its review.

Most information about these changes is in the two most important commits, c66257e and 91f967a. This includes some information about why I believe --fix should be kept.