|
| 1 | +# Contributing to PaddleNLP |
| 2 | + |
| 3 | +We highly welcome and value your contributions to `PaddleNLP`. The first step to start your contribution is to sign the [PaddlePaddle Contributor License Agreement](https://cla-assistant.io/PaddlePaddle/PaddleNLP). |
| 4 | + |
| 5 | +This document explains our workflow and work style: |
| 6 | + |
| 7 | +## Workflow |
| 8 | + |
| 9 | +PaddlePaddle uses the [Git branching model](http://nvie.com/posts/a-successful-git-branching-model/). The following steps guide usual contributions. |
| 10 | + |
| 11 | +#### 1. Fork |
| 12 | + |
| 13 | + Our development community has been growing fastly; it doesn't make sense for everyone to write into the official repo. So, please file Pull Requests from your fork. To make a fork, just head over to the GitHub page and click the ["Fork" button](https://help.github.com/articles/fork-a-repo/). |
| 14 | + |
| 15 | +#### 2. Clone |
| 16 | + |
| 17 | + To make a copy of your fork to your local computers, please run |
| 18 | + |
| 19 | + ```bash |
| 20 | + git clone https://github.com/<your-github-account>/PaddleNLP |
| 21 | + cd PaddleNLP |
| 22 | + ``` |
| 23 | + |
| 24 | +#### 3. Create the local feature branch |
| 25 | + |
| 26 | + For daily works like adding a new feature or fixing a bug, please open your feature branch before coding: |
| 27 | + |
| 28 | + ```bash |
| 29 | + git checkout -b my-cool-feature |
| 30 | + ``` |
| 31 | + |
| 32 | +#### 4. Set up the development environment |
| 33 | + |
| 34 | + Before you start coding, you need to setup the development environment. We highly recommend doing all your development in a virtual environment such as |
| 35 | + [venv](https://docs.python.org/3/library/venv.html) or [conda](https://docs.conda.io/en/latest/). After you setup and activated your virtual environment, |
| 36 | + run the following command: |
| 37 | + |
| 38 | + ```bash |
| 39 | + make install |
| 40 | + ``` |
| 41 | + |
| 42 | + This will setup all the dependencies of `PaddleNLP` as well as the [`pre-commit`](http://pre-commit.com/) tool. |
| 43 | + |
| 44 | + If you are working on the `examples` or `applications` module and require importing from `PaddleNLP`, make sure you install `PaddleNLP` in editable mode. |
| 45 | + If `PaddleNLP` is already installed in the virtual environment, remove it with `pip uninstall paddlenlp` before reinstalling it in editable mode with |
| 46 | + `pip install -e .` |
| 47 | + |
| 48 | +#### 5. Develop |
| 49 | + |
| 50 | + As you develop your new exciting feature, keep in mind that it should be covered by unit tests. All of our unit tests can be found under the `tests` directory. |
| 51 | + You can either modify existing unit test to cover the new feature, or create a new test from scratch. |
| 52 | + As you finish up the your code, you should make sure the test suite passes. You can run the tests impacted by your changes like this: |
| 53 | + |
| 54 | + ```bash |
| 55 | + pytest tests/<test_to_run>.py |
| 56 | + ``` |
| 57 | + |
| 58 | +#### 6. Commit |
| 59 | + |
| 60 | + We utilizes [`pre-commit`](http://pre-commit.com/) (with [black](https://black.readthedocs.io/en/stable/), [isort](https://pycqa.github.io/isort/) and |
| 61 | + [flake8](https://flake8.pycqa.org/en/latest/) under the hood) to check the style of code and documentation in every commit. When you run run `git commit`, you will see |
| 62 | + something like the following: |
| 63 | + |
| 64 | + ``` |
| 65 | + ➜ (my-virtual-env) git commit -m "commiting my cool feature" |
| 66 | + black....................................................................Passed |
| 67 | + isort....................................................................Passed |
| 68 | + flake8...................................................................Passed |
| 69 | + check for merge conflicts................................................Passed |
| 70 | + check for broken symlinks............................(no files to check)Skipped |
| 71 | + detect private key.......................................................Passed |
| 72 | + fix end of files.....................................(no files to check)Skipped |
| 73 | + trim trailing whitespace.............................(no files to check)Skipped |
| 74 | + CRLF end-lines checker...............................(no files to check)Skipped |
| 75 | + CRLF end-lines remover...............................(no files to check)Skipped |
| 76 | + No-tabs checker......................................(no files to check)Skipped |
| 77 | + Tabs remover.........................................(no files to check)Skipped |
| 78 | + copyright_checker........................................................Passed |
| 79 | + ``` |
| 80 | + |
| 81 | + But most of the time things don't go so smoothly. When your code or documentation doesn't meet the standard, the `pre-commit` check will fail. |
| 82 | + ``` |
| 83 | + ➜ (my-virtual-env) git commit -m "commiting my cool feature" |
| 84 | + black....................................................................Passed |
| 85 | + isort....................................................................Failed |
| 86 | + - hook id: isort |
| 87 | + - files were modified by this hook |
| 88 | +
|
| 89 | + Fixing examples/information_extraction/waybill_ie/run_ernie_crf.py |
| 90 | +
|
| 91 | + flake8...................................................................Passed |
| 92 | + check for merge conflicts................................................Passed |
| 93 | + check for broken symlinks............................(no files to check)Skipped |
| 94 | + detect private key.......................................................Passed |
| 95 | + fix end of files.....................................(no files to check)Skipped |
| 96 | + trim trailing whitespace.............................(no files to check)Skipped |
| 97 | + CRLF end-lines checker...............................(no files to check)Skipped |
| 98 | + CRLF end-lines remover...............................(no files to check)Skipped |
| 99 | + No-tabs checker......................................(no files to check)Skipped |
| 100 | + Tabs remover.........................................(no files to check)Skipped |
| 101 | + copyright_checker........................................................Passed |
| 102 | + ``` |
| 103 | + |
| 104 | + But **don't panic**! |
| 105 | + Our tooling will fix most of the style errors automatically. Some errors will need to be addressed manually. Fortunately, the error messages are straight forward and |
| 106 | + the errors are usually simple to fix. After addressing the errors, you can run `git add <files>` and `git commit` again, which will trigger `pre-commit` again. |
| 107 | + Once the `pre-commit` checks pass, you are ready to push the code. |
| 108 | + |
| 109 | + [Google][http://google.com/] or [StackOverflow](https://stackoverflow.com/) are great tools to help you understand the code style errors. |
| 110 | + Don't worry if you still can't figure it out. You can commit with `git commit -m "style error" --no-verify` and we are happy to help you once you create a Pull Request. |
| 111 | + |
| 112 | +7. Keep pulling |
| 113 | + |
| 114 | + An experienced Git user pulls from the official repo often -- daily or even hourly, so they notice conflicts with others work early, and it's easier to resolve smaller conflicts. |
| 115 | + |
| 116 | + ```bash |
| 117 | + git remote add upstream https://github.com/PaddlePaddle/PaddleNLP |
| 118 | + git pull upstream develop |
| 119 | + ``` |
| 120 | + |
| 121 | +8. Push and file a pull request |
| 122 | + |
| 123 | + You can "push" your local work into your forked repo: |
| 124 | + |
| 125 | + ```bash |
| 126 | + git push origin my-cool-stuff |
| 127 | + ``` |
| 128 | + |
| 129 | + The push allows you to create a pull request, requesting owners of this [official repo](https://github.com/PaddlePaddle/PaddleNLP) to pull your change into the official one. |
| 130 | + |
| 131 | + To create a pull request, please follow [these steps](https://help.github.com/articles/creating-a-pull-request/). |
| 132 | + |
| 133 | +9. Delete local and remote branches |
| 134 | + |
| 135 | + To keep your local workspace and your fork clean, you might want to remove merged branches: |
| 136 | + |
| 137 | + ```bash |
| 138 | + git push origin my-cool-stuff |
| 139 | + git checkout develop |
| 140 | + git pull upstream develop |
| 141 | + git branch -d my-cool-stuff |
| 142 | + ``` |
| 143 | + |
| 144 | +### Code Review |
| 145 | + |
| 146 | +- Please feel free to ping your reviewers by sending them the URL of your pull request via IM or email. Please do this after your pull request passes the CI. |
| 147 | + |
| 148 | +- Please answer reviewers' every comment. If you are to follow the comment, please write "Done"; Otherwise, please start a discussion under the comment. |
| 149 | + |
| 150 | +- If you don't want your reviewers to get overwhelmed by email notifications, you might reply their comments by [in a batch](https://help.github.com/articles/reviewing-proposed-changes-in-a-pull-request/). |
0 commit comments