From 395b70ae2fdf01590f157e94d96e7ddac7893ba9 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Tue, 12 Mar 2024 12:12:27 -0400 Subject: [PATCH 1/4] Very slightly improve readme presentation - Add a missing period. - Indicate sh rather than bash as as the language for syntax highlighting of shell commands that don't need bash. I had held off on making that second change in previous revisions because it would have involved either introducing an inconsistency or editing the section giving the deprecated signature-checking instructions. That section was removed in 2671167 (#1823). (This also wraps a paragraph where the immediately surrounding text was wrapped, but that should not affect rendered text, and broader consistency improvements to Markdown wrapping style are not done.) --- README.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 33e093945..458162212 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ probably the skills to scratch that itch of mine: implement `git` in a way that If you like the idea and want to learn more, please head over to [gitoxide](https://github.com/Byron/gitoxide), an implementation of 'git' in [Rust](https://www.rust-lang.org). -*(Please note that `gitoxide` is not currently available for use in Python, and that Rust is required)* +*(Please note that `gitoxide` is not currently available for use in Python, and that Rust is required.)* ## GitPython @@ -39,9 +39,9 @@ The project is open to contributions of all kinds, as well as new maintainers. ### REQUIREMENTS -GitPython needs the `git` executable to be installed on the system and available in your `PATH` for most operations. -If it is not in your `PATH`, you can help GitPython find it by setting -the `GIT_PYTHON_GIT_EXECUTABLE=` environment variable. +GitPython needs the `git` executable to be installed on the system and available in your +`PATH` for most operations. If it is not in your `PATH`, you can help GitPython find it +by setting the `GIT_PYTHON_GIT_EXECUTABLE=` environment variable. - Git (1.7.x or newer) - Python >= 3.7 @@ -57,7 +57,7 @@ GitPython and its required package dependencies can be installed in any of the f To obtain and install a copy [from PyPI](https://pypi.org/project/GitPython/), run: -```bash +```sh pip install GitPython ``` @@ -67,7 +67,7 @@ pip install GitPython If you have downloaded the source code, run this from inside the unpacked `GitPython` directory: -```bash +```sh pip install . ``` @@ -75,7 +75,7 @@ pip install . To clone the [the GitHub repository](https://github.com/gitpython-developers/GitPython) from source to work on the code, you can do it like so: -```bash +```sh git clone https://github.com/gitpython-developers/GitPython cd GitPython ./init-tests-after-clone.sh @@ -85,7 +85,7 @@ On Windows, `./init-tests-after-clone.sh` can be run in a Git Bash shell. If you are cloning [your own fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks), then replace the above `git clone` command with one that gives the URL of your fork. Or use this [`gh`](https://cli.github.com/) command (assuming you have `gh` and your fork is called `GitPython`): -```bash +```sh gh repo clone GitPython ``` @@ -93,7 +93,7 @@ Having cloned the repo, create and activate your [virtual environment](https://d Then make an [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs): -```bash +```sh pip install -e ".[test]" ``` @@ -105,7 +105,7 @@ In rare cases, you may want to work on GitPython and one or both of its [gitdb]( If you want to do that *and* you want the versions in GitPython's git submodules to be used, then pass `-e git/ext/gitdb` and/or `-e git/ext/gitdb/gitdb/ext/smmap` to `pip install`. This can be done in any order, and in separate `pip install` commands or the same one, so long as `-e` appears before *each* path. For example, you can install GitPython, gitdb, and smmap editably in the currently active virtual environment this way: -```bash +```sh pip install -e ".[test]" -e git/ext/gitdb -e git/ext/gitdb/gitdb/ext/smmap ``` @@ -141,13 +141,13 @@ you will encounter test failures. Ensure testing libraries are installed. This is taken care of already if you installed with: -```bash +```sh pip install -e ".[test]" ``` Otherwise, you can run: -```bash +```sh pip install -r test-requirements.txt ``` @@ -155,19 +155,19 @@ pip install -r test-requirements.txt To test, run: -```bash +```sh pytest ``` To lint, and apply automatic code formatting, run: -```bash +```sh pre-commit run --all-files ``` To typecheck, run: -```bash +```sh mypy -p git ``` From 3a6ee9e0e478eea5f6defe2b851a7ca6c74976ca Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Tue, 12 Mar 2024 12:31:06 -0400 Subject: [PATCH 2/4] Make installation instructions more consistent If people who want to run the tests didn't install the test extra, they can still install that extra. This simplifies the instructions accordingly. test-requirements.txt is still mentioned near the beginning in case people want to look at it to see dependencies. But the changed code is the only place where the instructions had still said to do anything with those files. A possible disadvantage of this change is that in the rare case that someone following those instructions to run the tests locally didn't do an editable installation, then installing with the extra shouldn't be done editably either. But this doesn't seem like a likely problem, and the new text has an example command with -e to clarify the kind of command whose effect is augmented here. Because of that subtlety, it is not obvious that this change is really justified for purposes of clarity. However, this also helps prepare for a time when test-requirements.txt won't exist anymore, as may happen when the project definition is made fully declarative (see discussion in comments in #1716). --- README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 458162212..ead8093f8 100644 --- a/README.md +++ b/README.md @@ -145,11 +145,8 @@ Ensure testing libraries are installed. This is taken care of already if you ins pip install -e ".[test]" ``` -Otherwise, you can run: - -```sh -pip install -r test-requirements.txt -``` +If you had installed with a command like `pip install -e .` instead, you can still run +the above command to add the testing dependencies. #### Test commands From 826234384d38126130388102355a274a353bfade Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Tue, 12 Mar 2024 12:50:41 -0400 Subject: [PATCH 3/4] Update readme for recent tooling changes This also reorganizes the "Specific tools" list, since they are all configured in pyproject.toml now (only flake8 was not before, and it was removed in favor of ruff in #1862). In doing so, I've also added brief parenthesized phrases to characterize what each of these four tools is for, so readers don't have to look around as much to understand most of the tooling GitPython has set up. --- README.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ead8093f8..30af532db 100644 --- a/README.md +++ b/README.md @@ -156,12 +156,14 @@ To test, run: pytest ``` -To lint, and apply automatic code formatting, run: +To lint, and apply some linting fixes as well as automatic code formatting, run: ```sh pre-commit run --all-files ``` +This includes the linting and autoformatting done by Ruff, as well as some other checks. + To typecheck, run: ```sh @@ -170,7 +172,7 @@ mypy -p git #### CI (and tox) -The same linting, and running tests on all the different supported Python versions, will be performed: +Style and formatting checks, and running tests on all the different supported Python versions, will be performed: - Upon submitting a pull request. - On each push, *if* you have a fork with GitHub Actions enabled. @@ -178,10 +180,12 @@ The same linting, and running tests on all the different supported Python versio #### Configuration files -Specific tools: +Specific tools are all configured in the `./pyproject.toml` file: -- Configurations for `mypy`, `pytest`, `coverage.py`, and `black` are in `./pyproject.toml`. -- Configuration for `ruff` is in the `pyproject.toml` file. +- `pytest` (test runner) +- `coverage.py` (code coverage) +- `ruff` (linter and formatter) +- `mypy` (type checker) Orchestration tools: From b059cd580b71b44488bf3cc77000a6dea3cb1898 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Tue, 12 Mar 2024 13:27:34 -0400 Subject: [PATCH 4/4] Have tox skip linting unless requested, for now This is to make it so simple `tox` usage has the expected property of leaving all source code files in the working tree unchanged. Linting how sometimes performs auto-fixes since #1862, and the pre-commit command in tox.ini, which had also run `black --check`, will do even more file editing due to the changes in #1865. The bifurcation for black into separate mutating and non-mutating hooks, introduced in 5d8ddd9 (#1693), was not carried over into Ruff autoformatting in #1865. But also it: - Was not necessarily a good approach, and likely should not be preserved in any form. It was an unusual and unintuitive use of pre-commit. (It can be brought back if no better approach is found, though.) - Was done to avoid a situation where it was nontrivial to set up necessary dependencies for linting in the GitPython virtual environment itself, because flake8 and its various plugins would have to be installed. They were not listed in any existing or newly introduced extra (for example, they were not added to test-requirements.txt) in part in the hope that they would all be replaced by Ruff, which happened in #1862. - Already did not achieve its goal as of #1862, since it was (probably rightly) not extended to Ruff linting to use/omit --fix. Now that Ruff is being used, people can run `pip install ruff` in a virtual environment, then run the `ruff` command however they like. This takes the place of multiple tools and plugins. The situation with the tox "lint" environment is thus now similar to that of the tox "html" environment when it was added in e6ec6c8 (#1667), until it was improved in f094909 (#1693) to run with proper isolation. --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 28b7b147f..6e02e5aee 100644 --- a/tox.ini +++ b/tox.ini @@ -1,6 +1,6 @@ [tox] requires = tox>=4 -env_list = py{37,38,39,310,311,312}, lint, mypy, html +env_list = py{37,38,39,310,311,312}, mypy, html [testenv] description = Run unit tests