diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000000..ce9c182edf --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,22 @@ +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.1.0 + hooks: + - id: check-yaml + - id: end-of-file-fixer + - id: trailing-whitespace + - id: check-case-conflict + - id: check-merge-conflict +- repo: https://github.com/psf/black + rev: 22.3.0 + hooks: + - id: black +- repo: https://gitlab.com/pycqa/flake8 + rev: 4.0.1 + hooks: + - id: flake8 + types: [file, python] +- repo: https://github.com/PyCQA/isort + rev: 5.10.1 + hooks: + - id: isort diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 18f1bd3e63..eb5339ba74 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,7 +72,7 @@ file explaining how you may test your code. ## Documentation -The content in the `docs` folder is the official [Hugging Face Hub documentation]. It is not limited to the +The content in the `docs` folder is the official [Hugging Face Hub documentation]. It is not limited to the Python package `huggingface_hub`, as it includes guides on using the frontend, ho to build Spaces, how to search efficiently, and others. @@ -100,7 +100,7 @@ Did not find it? :( So we can act quickly on it, please follow these steps: **Tensorflow** when applicable; * A short, self-contained, code snippet that allows us to reproduce the bug in less than 30s; -* Provide the *full* traceback if an exception is raised by copying the text from your terminal +* Provide the *full* traceback if an exception is raised by copying the text from your terminal in the issue description. ### Do you want a new feature? @@ -167,7 +167,7 @@ Follow these steps to start contributing: **Do not** work on the `master` branch. -4. Set up a development environment by running the following command in a virtual environment a conda or a +4. Set up a development environment by running the following command in a virtual environment a conda or a virtual environment you've created for working on this library: ```bash @@ -181,13 +181,13 @@ Follow these steps to start contributing: 5. Develop the features on your branch. As you work on the features, you should make sure that the test suite - passes. You should run the tests impacted by your changes like this (see + passes. You should run the tests impacted by your changes like this (see below an explanation regarding the environment variable): ```bash $ HUGGINGFACE_CO_STAGING=1 pytest tests/.py ``` - + > For the following commands leveraging the `make` utility, we recommend using the WSL system when running on > Windows. More information [here](https://docs.microsoft.com/en-us/windows/wsl/about). @@ -198,8 +198,26 @@ Follow these steps to start contributing: ``` `hugginface_hub` relies on `black` and `isort` to format its source code - consistently. After you make changes, apply automatic style corrections and code verifications - that can't be automated: + consistently. You can install pre-commit hooks so that these styles are + applied and checked on files that you have touched in each commit: + + ```bash + pip install pre-commit + pre-commit install + ``` + + You only need to do the above once in your repository's environment. If for + any reason you would like to disable pre-commit hooks on a commit, you can + pass `-n` to your `git commit` command to temporarily disable pre-commit + hooks. + + To permanently disable hooks, you can run the following command: + ```bash + pre-commit uninstall + ``` + + Alternatively, you can apply automatic style corrections and code + verifications manually with the following command: ```bash $ make style @@ -225,7 +243,7 @@ Follow these steps to start contributing: It is a good idea to sync your copy of the code with the original repository regularly. The following document covers it in length: [github documentation]( https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) - + And here's how you can do it quickly from your `git` commandline: ```bash @@ -255,8 +273,8 @@ Follow these steps to start contributing: 2. If your pull request addresses an issue, please mention the issue number in the pull request description to make sure they are linked (and people consulting the issue know you are working on it); -3. To indicate a work in progress please prefix the title with `[WIP]`, or mark - the PR as a draft PR. These are useful to avoid duplicated work, and to differentiate +3. To indicate a work in progress please prefix the title with `[WIP]`, or mark + the PR as a draft PR. These are useful to avoid duplicated work, and to differentiate it from PRs ready to be merged; 4. Make sure existing tests pass; 5. Add high-coverage tests. No quality testing = no merge. @@ -272,7 +290,7 @@ An extensive test suite is included to test the library behavior and several exa the [tests folder](https://github.com/huggingface/huggingface_hub/tree/main/tests). The `huggingface_hub` library's normal behavior is to work with the production Hugging Face Hub. However, -for tests, we prefer to run on a staging version. In order to do this, it's important to set the +for tests, we prefer to run on a staging version. In order to do this, it's important to set the `HUGGINGFACE_CO_STAGING` environment variable to `1` when running tests. It is preferred to pass this in when running the tests, than setting a permanent environmental variable, as shown below. We use `pytest` in order to run the tests for the library . From the root of the