diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fa0081b24c5..817ba56aaf3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,12 @@ # How to contribute to transformers? Everyone is welcome to contribute, and we value everybody's contribution. Code -is thus not the only way to contribute. Answering questions, helping others, -reaching out and improving the documentations are immensely valuable to the -community. +is thus not the only way to help the community. Answering questions, helping +others, reaching out and improving the documentations are immensely valuable to +the community. It also helps us if you spread the word: reference the library from blog posts -on the awesome projects it made possible, shout out on twitter every time it has +on the awesome projects it made possible, shout out on Twitter every time it has helped you, or simply star the repo to say "thank you". ## You can contribute in so many ways! @@ -14,7 +14,7 @@ helped you, or simply star the repo to say "thank you". There are 4 ways you can contribute to transformers: * Fixing outstanding issues with the existing code; * Implementing new models; -* Contributing to the examples, or to the documentation; +* Contributing to the examples or to the documentation; * Submitting issues related to bugs or desired new features. *All are equally valuable to the community.* @@ -28,18 +28,17 @@ feedback. ### Did you find a bug? The transformers are robust and reliable thanks to the users who notify us of -the problems they encounter. +the problems they encounter. So thank you for reporting an issue. -So thank you for reporting an issue. First, we would really appreciate it if you -could **make sure the bug was not already reported** (use the search bar on -Github under Issues). +First, we would really appreciate it if you could **make sure the bug was not +already reported** (use the search bar on Github under Issues). Did not find it? :( So we can act quickly on it, please follow these steps: * Include your **OS type and version**, the versions of **Python**, **PyTorch** and **Tensorflow** when applicable; * A short, self-contained, code snippet that allows us to reproduce the bug in - less than 30s. + less than 30s; * Provide the *full* traceback if an exception is raised. To get the OS and software versions, execute the following code and copy-paste @@ -54,13 +53,14 @@ import tensorflow; print("Tensorflow", tensorflow.__version__) ### Do you want to implement a new model? -Please provide the following: +Awesome! Please provide the following information: -* Short description of the model and link to the paper -* Link to the implementation if open-source -* Link to the model weights if they are available +* Short description of the model and link to the paper; +* Link to the implementation if it is open-source; +* Link to the model weights if they are available. -Let us know if you are willing to contribute so we can best guide you. +If you are willing to contribute the model yourself, let us know so we can best +guide you. ### Do you want a new feature (that is not a model)? @@ -73,19 +73,19 @@ A world-class feature request addresses the following points: about it! * Is it something you worked on and think could benefit the community? Awesome! Tell us what problem it solved for you. -2. Write a *full paragraph* describing the feature. -3. Provide a **code snippet** that demonstrates its future use. -4. In case this is related to a paper, please provide a link +2. Write a *full paragraph* describing the feature; +3. Provide a **code snippet** that demonstrates its future use; +4. In case this is related to a paper, please attach a link; 5. Attach any additional information (drawings, screenshots, etc.) you think may help. -If your issue is well-written we're already 80% of the way there by the time you +If your issue is well written we're already 80% of the way there by the time you post it. ## Start contributing! (Pull Requests) Before writing code, we strongly advise you to search through the exising PRs or -issues to make sure that nobody is already working on the same thing. It is -always a good idea to open an issue to get some feedback. +issues to make sure that nobody is already working on the same thing. If you are +unsure, it is always a good idea to open an issue to get some feedback. You will need basic `git` proficiency to be able to contribute to `transformers`. `git` is not the easiest tool to use but it has the greatest @@ -95,7 +95,7 @@ Git](https://git-scm.com/book/en/v2) is a very good reference. Follow these steps to start contributing: 1. Fork the [repository](https://github.com/huggingface/transformers) by - clicking on the 'Fork' button. This creates a copy of the code + clicking on the 'Fork' button on the repository's page. This creates a copy of the code under your github user account. 2. Clone your fork to your local disk, and add the base repository as a remote: @@ -113,7 +113,7 @@ Follow these steps to start contributing: **do not** work on the `master` branch. -4. Set up a development environment by running in a virtual environment: +4. Set up a development environment by running the following command in a virtual environment: ```bash $ pip install -r requirements-dev.txt @@ -146,13 +146,19 @@ Follow these steps to start contributing: 6. Once you are satisfied (**and the checklist below is happy too**), go to the webpage of your fork on Github. Click on 'Pull request' to send your changes to the project maintainers for review. + +7. It's ok if maintainers ask you for changes. It happens to core contributors + too! So everyone can see the changes in the Pull request, work in your local + branch and push the changes to your fork. They will automatically appear in + the pull request. ### Checklist 1. The title of your pull request should be a summary of its contribution; 2. If your pull request adresses an issue, please mention the issue number in - the pull request description to make sure they are linked; + 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]`. These are useful to avoid duplicated work, and to differentiate it from PRs ready to be merged;