chendl/compositional_test

1<!---2Copyright 2020 The HuggingFace Team. All rights reserved.3 4Licensed under the Apache License, Version 2.0 (the "License");5you may not use this file except in compliance with the License.6You may obtain a copy of the License at7 8    http://www.apache.org/licenses/LICENSE-2.09 10Unless required by applicable law or agreed to in writing, software11distributed under the License is distributed on an "AS IS" BASIS,12WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.13See the License for the specific language governing permissions and14limitations under the License.15-->16 17# Contribute to 🤗 Transformers18 19Everyone is welcome to contribute, and we value everybody's contribution. Code20contributions are not the only way to help the community. Answering questions, helping21others, and improving the documentation are also immensely valuable.22 23It also helps us if you spread the word! Reference the library in blog posts24about the awesome projects it made possible, shout out on Twitter every time it has25helped you, or simply ⭐️ the repository to say thank you.26 27However you choose to contribute, please be mindful and respect our28[code of conduct](https://github.com/huggingface/transformers/blob/main/CODE_OF_CONDUCT.md).29 30**This guide was heavily inspired by the awesome [scikit-learn guide to contributing](https://github.com/scikit-learn/scikit-learn/blob/main/CONTRIBUTING.md).**31 32## Ways to contribute33 34There are several ways you can contribute to 🤗 Transformers:35 36* Fix outstanding issues with the existing code.37* Submit issues related to bugs or desired new features.38* Implement new models.39* Contribute to the examples or to the documentation.40 41If you don't know where to start, there is a special [Good First42Issue](https://github.com/huggingface/transformers/contribute) listing. It will give you a list of43open issues that are beginner-friendly and help you start contributing to open-source. Just comment in the issue that you'd like to work44on it. 45 46For something slightly more challenging, you can also take a look at the [Good Second Issue](https://github.com/huggingface/transformers/labels/Good%20Second%20Issue) list. In general though, if you feel like you know what you're doing, go for it and we'll help you get there! 🚀47 48> All contributions are equally valuable to the community. 🥰49 50## Fixing outstanding issues51 52If you notice an issue with the existing code and have a fix in mind, feel free to [start contributing](https://github.com/huggingface/transformers/blob/main/CONTRIBUTING.md/#create-a-pull-request) and open a Pull Request!53 54## Submitting a bug-related issue or feature request55 56Do your best to follow these guidelines when submitting a bug-related issue or a feature57request. It will make it easier for us to come back to you quickly and with good58feedback.59 60### Did you find a bug?61 62The 🤗 Transformers library is robust and reliable thanks to users who report the problems they encounter.63 64Before you report an issue, we would really appreciate it if you could **make sure the bug was not65already reported** (use the search bar on GitHub under Issues). Your issue should also be related to bugs in the library itself, and not your code. If you're unsure whether the bug is in your code or the library, please ask on the [forum](https://discuss.huggingface.co/) first. This helps us respond quicker to fixing issues related to the library versus general questions.66 67Once you've confirmed the bug hasn't already been reported, please include the following information in your issue so we can quickly resolve it:68 69* Your **OS type and version** and **Python**, **PyTorch** and70  **TensorFlow** versions when applicable.71* A short, self-contained, code snippet that allows us to reproduce the bug in72  less than 30s.73* The *full* traceback if an exception is raised.74* Attach any other additional information, like screenshots, you think may help.75 76To get the OS and software versions automatically, run the following command:77 78```bash79transformers-cli env80```81 82You can also run the same command from the root of the repository:83 84```bash85python src/transformers/commands/transformers_cli.py env86```87 88### Do you want a new feature?89 90If there is a new feature you'd like to see in 🤗 Transformers, please open an issue and describe:91 921. What is the *motivation* behind this feature? Is it related to a problem or frustration with the library? Is it a feature related to something you need for a project? Is it something you worked on and think it could benefit the community?93 94   Whatever it is, we'd love to hear about it!95 962. Describe your requested feature in as much detail as possible. The more you can tell us about it, the better we'll be able to help you.973. Provide a *code snippet* that demonstrates the features usage.984. If the feature is related to a paper, please include a link.99 100If your issue is well written we're already 80% of the way there by the time you create it.101 102We have added [templates](https://github.com/huggingface/transformers/tree/main/templates) to help you get started with your issue.103 104## Do you want to implement a new model?105 106New models are constantly released and if you want to implement a new model, please provide the following information107 108* A short description of the model and link to the paper.109* Link to the implementation if it is open-sourced.110* Link to the model weights if they are available.111 112If you are willing to contribute the model yourself, let us know so we can help you add it to 🤗 Transformers!113 114We have added a [detailed guide and templates](https://github.com/huggingface/transformers/tree/main/templates) to help you get started with adding a new model, and we also have a more technical guide for [how to add a model to 🤗 Transformers](https://huggingface.co/docs/transformers/add_new_model).115 116## Do you want to add documentation?117 118We're always looking for improvements to the documentation that make it more clear and accurate. Please let us know how the documentation can be improved such as typos and any content that is missing, unclear or inaccurate. We'll be happy to make the changes or help you make a contribution if you're interested!119 120For more details about how to generate, build, and write the documentation, take a look at the documentation [README](https://github.com/huggingface/transformers/tree/main/docs).121 122## Create a Pull Request123 124Before writing any code, we strongly advise you to search through the existing PRs or125issues to make sure nobody is already working on the same thing. If you are126unsure, it is always a good idea to open an issue to get some feedback.127 128You will need basic `git` proficiency to contribute to129🤗 Transformers. While `git` is not the easiest tool to use, it has the greatest130manual. Type `git --help` in a shell and enjoy! If you prefer books, [Pro131Git](https://git-scm.com/book/en/v2) is a very good reference.132 133You'll need **[Python 3.7]((https://github.com/huggingface/transformers/blob/main/setup.py#L426))** or above to contribute to 🤗 Transformers. Follow the steps below to start contributing:134 1351. Fork the [repository](https://github.com/huggingface/transformers) by136   clicking on the **[Fork](https://github.com/huggingface/transformers/fork)** button on the repository's page. This creates a copy of the code137   under your GitHub user account.138 1392. Clone your fork to your local disk, and add the base repository as a remote:140 141   ```bash142   git clone git@github.com:<your Github handle>/transformers.git143   cd transformers144   git remote add upstream https://github.com/huggingface/transformers.git145   ```146 1473. Create a new branch to hold your development changes:148 149   ```bash150   git checkout -b a-descriptive-name-for-my-changes151   ```152 153   🚨 **Do not** work on the `main` branch!154 1554. Set up a development environment by running the following command in a virtual environment:156 157   ```bash158   pip install -e ".[dev]"159   ```160 161   If 🤗 Transformers was already installed in the virtual environment, remove162   it with `pip uninstall transformers` before reinstalling it in editable163   mode with the `-e` flag.164   165   Depending on your OS, and since the number of optional dependencies of Transformers is growing, you might get a166   failure with this command. If that's the case make sure to install the Deep Learning framework you are working with167   (PyTorch, TensorFlow and/or Flax) then do:168 169   ```bash170   pip install -e ".[quality]"171   ```172 173   which should be enough for most use cases.174 1755. Develop the features on your branch.176 177   As you work on your code, you should make sure the test suite178   passes. Run the tests impacted by your changes like this:179 180   ```bash181   pytest tests/<TEST_TO_RUN>.py182   ```183 184   For more information about tests, check out the185   [Testing](https://huggingface.co/docs/transformers/testing) guide.186 187   🤗 Transformers relies on `black` and `ruff` to format its source code188   consistently. After you make changes, apply automatic style corrections and code verifications189   that can't be automated in one go with:190 191   ```bash192   make fixup193   ```194 195   This target is also optimized to only work with files modified by the PR you're working on.196 197   If you prefer to run the checks one after the other, the following command applies the198   style corrections:199 200   ```bash201   make style202   ```203 204   🤗 Transformers also uses `ruff` and a few custom scripts to check for coding mistakes. Quality205   controls are run by the CI, but you can run the same checks with:206 207   ```bash208   make quality209   ```210 211   Finally, we have a lot of scripts to make sure we didn't forget to update212   some files when adding a new model. You can run these scripts with:213 214   ```bash215   make repo-consistency216   ```217 218   To learn more about those checks and how to fix any issues with them, check out the219   [Checks on a Pull Request](https://huggingface.co/docs/transformers/pr_checks) guide.220 221   If you're modifying documents under `docs/source` directory, make sure the documentation can still be built. This check will also run in the CI when you open a pull request. To run a local check222   make sure you install the documentation builder:223   224   ```bash225   pip install ".[docs]"226   ```227 228   Run the following command from the root of the repository:229 230   ```bash231   doc-builder build transformers docs/source/en --build_dir ~/tmp/test-build232   ```233 234   This will build the documentation in the `~/tmp/test-build` folder where you can inspect the generated235   Markdown files with your favorite editor. You can also preview the docs on GitHub when you open a pull request.236 237   Once you're happy with your changes, add changed files with `git add` and238   record your changes locally with `git commit`:239 240   ```bash241   git add modified_file.py242   git commit243   ```244 245   Please remember to write [good commit246   messages](https://chris.beams.io/posts/git-commit/) to clearly communicate the changes you made!247 248   To keep your copy of the code up to date with the original249   repository, rebase your branch on `upstream/branch` *before* you open a pull request or if requested by a maintainer:250 251   ```bash252   git fetch upstream253   git rebase upstream/main254   ```255 256   Push your changes to your branch:257 258   ```bash259   git push -u origin a-descriptive-name-for-my-changes260   ```261 262   If you've already opened a pull request, you'll need to force push with the `--force` flag. Otherwise, if the pull request hasn't been opened yet, you can just push your changes normally.263 2646. Now you can go to your fork of the repository on GitHub and click on **Pull request** to open a pull request. Make sure you tick off all the boxes in our [checklist](https://github.com/huggingface/transformers/blob/main/CONTRIBUTING.md/#pull-request-checklist) below. When you're ready, you can send your changes to the project maintainers for review.265 2667. It's ok if maintainers request changes, it happens to our core contributors267   too! So everyone can see the changes in the pull request, work in your local268   branch and push the changes to your fork. They will automatically appear in269   the pull request.270 271### Pull request checklist272 273☐ The pull request title should summarize your contribution.<br>274☐ If your pull request addresses an issue, please mention the issue number in the pull275request description to make sure they are linked (and people viewing the issue know you276are working on it).<br>277☐ To indicate a work in progress please prefix the title with `[WIP]`. These are278useful to avoid duplicated work, and to differentiate it from PRs ready to be merged.279☐ Make sure existing tests pass.<br>280☐ If adding a new feature, also add tests for it.<br>281   - If you are adding a new model, make sure you use282     `ModelTester.all_model_classes = (MyModel, MyModelWithLMHead,...)` to trigger the common tests.283   - If you are adding new `@slow` tests, make sure they pass using284     `RUN_SLOW=1 python -m pytest tests/models/my_new_model/test_my_new_model.py`.285   - If you are adding a new tokenizer, write tests and make sure286     `RUN_SLOW=1 python -m pytest tests/models/{your_model_name}/test_tokenization_{your_model_name}.py` passes.287   CircleCI does not run the slow tests, but GitHub Actions does every night!<br>288 289☐ All public methods must have informative docstrings (see290[`modeling_bert.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/models/bert/modeling_bert.py)291for an example).<br>292☐ Due to the rapidly growing repository, don't add any images, videos and other293non-text files that'll significantly weigh down the repository. Instead, use a Hub294repository such as [`hf-internal-testing`](https://huggingface.co/hf-internal-testing)295to host these files and reference them by URL. We recommend placing documentation296related images in the following repository:297[huggingface/documentation-images](https://huggingface.co/datasets/huggingface/documentation-images).298You can open a PR on this dataset repostitory and ask a Hugging Face member to merge it.299 300For more information about the checks run on a pull request, take a look at our [Checks on a Pull Request](https://huggingface.co/docs/transformers/pr_checks) guide.301 302### Tests303 304An extensive test suite is included to test the library behavior and several examples. Library tests can be found in305the [tests](https://github.com/huggingface/transformers/tree/main/tests) folder and examples tests in the306[examples](https://github.com/huggingface/transformers/tree/main/examples) folder.307 308We like `pytest` and `pytest-xdist` because it's faster. From the root of the309repository, specify a *path to a subfolder or a test file* to run the test.310 311```bash312python -m pytest -n auto --dist=loadfile -s -v ./tests/models/my_new_model313```314 315Similarly, for the `examples` directory, specify a *path to a subfolder or test file* to run the test. For example, the following command tests the text classification subfolder in the PyTorch `examples` directory:316 317```bash318pip install -r examples/xxx/requirements.txt  # only needed the first time319python -m pytest -n auto --dist=loadfile -s -v ./examples/pytorch/text-classification320```321 322In fact, this is actually how our `make test` and `make test-examples` commands are implemented (not including the `pip install`)!323 324You can also specify a smaller set of tests in order to test only the feature325you're working on.326 327By default, slow tests are skipped but you can set the `RUN_SLOW` environment variable to328`yes` to run them. This will download many gigabytes of models so make sure you329have enough disk space, a good internet connection or a lot of patience!330 331<Tip warning={true}>332 333Remember to specify a *path to a subfolder or a test file* to run the test. Otherwise, you'll run all the tests in the `tests` or `examples` folder, which will take a very long time!334 335</Tip>336 337```bash338RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./tests/models/my_new_model339RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./examples/pytorch/text-classification340```341 342Like the slow tests, there are other environment variables available which not enabled by default during testing:343- `RUN_CUSTOM_TOKENIZERS`: Enables tests for custom tokenizers.344- `RUN_PT_FLAX_CROSS_TESTS`: Enables tests for PyTorch + Flax integration.345- `RUN_PT_TF_CROSS_TESTS`: Enables tests for TensorFlow + PyTorch integration.346 347More environment variables and additional information can be found in the [testing_utils.py](src/transformers/testing_utils.py).348 349🤗 Transformers uses `pytest` as a test runner only. It doesn't use any350`pytest`-specific features in the test suite itself.351 352This means `unittest` is fully supported. Here's how to run tests with353`unittest`:354 355```bash356python -m unittest discover -s tests -t . -v357python -m unittest discover -s examples -t examples -v358```359 360### Style guide361 362For documentation strings, 🤗 Transformers follows the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html).363Check our [documentation writing guide](https://github.com/huggingface/transformers/tree/main/docs#writing-documentation---specification)364for more information.365 366### Develop on Windows367 368On Windows (unless you're working in [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/) or WSL), you need to configure git to transform Windows `CRLF` line endings to Linux `LF` line endings:369 370```bash371git config core.autocrlf input372```373 374One way to run the `make` command on Windows is with MSYS2:375 3761. [Download MSYS2](https://www.msys2.org/), and we assume it's installed in `C:\msys64`.3772. Open the command line `C:\msys64\msys2.exe` (it should be available from the **Start** menu).3783. Run in the shell: `pacman -Syu` and install `make` with `pacman -S make`.3794. Add `C:\msys64\usr\bin` to your PATH environment variable.380 381You can now use `make` from any terminal (Powershell, cmd.exe, etc.)! 🎉382 383### Sync a forked repository with upstream main (the Hugging Face repository)384 385When updating the main branch of a forked repository, please follow these steps to avoid pinging the upstream repository which adds reference notes to each upstream PR, and sends unnecessary notifications to the developers involved in these PRs.386 3871. When possible, avoid syncing with the upstream using a branch and PR on the forked repository. Instead, merge directly into the forked main.3882. If a PR is absolutely necessary, use the following steps after checking out your branch:389 390```bash391git checkout -b your-branch-for-syncing392git pull --squash --no-commit upstream main393git commit -m '<your message without GitHub references>'394git push --set-upstream origin your-branch-for-syncing395```396