|
1 | | -# Hi 感谢对本项目感兴趣 |
| 1 | +<!-- The content will be also use in `docs/CONTRIBUTING/CONTRIBUTING.md` by `pymdownx.snippets` --> |
| 2 | +<!-- Do not use any **relative link** and **GitHub-specific syntax** ！--> |
| 3 | +<!-- Do not rename or move the file --> |
2 | 4 |
|
3 | | -## 代码贡献 |
| 5 | +# Contributing |
4 | 6 |
|
5 | | -> **Note** |
6 | | -> |
7 | | -> 我们最低支持的版本是`python3.8`，你可以随意使用`python3.8`以上的版本。 |
8 | | -> |
9 | | -> 但是请注意，您的代码要能通过`py >= 3.8`的所有版本的代码风格检查与测试。 |
| 7 | +> The guide is modified from [mkdocstrings](https://mkdocstrings.github.io/contributing/#contributing) |
10 | 8 |
|
11 | | -我们推荐使用[虚拟环境](https://docs.python.org/3/library/venv.html#creating-virtual-environments)来进行开发 |
| 9 | +Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. |
12 | 10 |
|
13 | | -在激活虚拟环境后，运行[./scripts/init.sh](./scripts/init-dev.sh)来为你初始化: |
| 11 | +## Environment setup |
14 | 12 |
|
15 | | -- [requirements](./requirements-dev.txt) |
16 | | -- [hatch](https://github.com/pypa/hatch) |
17 | | -- [pre-commit](https://pre-commit.com/) |
18 | | -- [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) |
| 13 | +First, `fork` and `clone` the repository, then `cd` to the directory. |
19 | 14 |
|
20 | | -## 代码风格 |
| 15 | +We use [`hatch`](https://github.com/pypa/hatch) and [`pre-commit`](https://pre-commit.com/) to manage our project. |
21 | 16 |
|
22 | | -由于本项目主要是python语言，所以我们只强制要求python代码风格。 |
| 17 | +You can install them with: |
23 | 18 |
|
24 | | -但是涉及到其他语言（例如 `bash`, `toml` 等）的部分，也请尽力保证样式正确。 |
| 19 | +```shell |
| 20 | +# https://pypa.github.io/pipx/ |
| 21 | +python3 -m pip install --user pipx |
25 | 22 |
|
26 | | -> **Note** |
27 | | -> 我们启用了大量而严格的`lint`规则，如果你使用`vscode`，我们推荐你安装[./.vscode/extensions.json](./.vscode/extensions.json)中的插件来帮助你实时检查错误 |
28 | | -> |
29 | | -> 如果你打不过检查器，可以使用`# noqa`和`# type: ignore`来跳过检查 |
30 | | -> |
31 | | -> 当然，这些规则可能过于严格，你可以发起一个`issue`或者`pull request`来讨论是否需要修改规则 |
| 23 | +pipx install hatch |
| 24 | +pipx install pre-commit |
| 25 | +``` |
32 | 26 |
|
33 | | -### python代码风格(请查看[./pyproject.toml](./pyproject.toml)了解我们的风格) |
| 27 | +Then, initialize the env with: |
34 | 28 |
|
35 | | -- [Ruff](https://github.com/astral-sh/ruff): 代码质量检查 |
36 | | -- [Blcak](https://github.com/psf/black): 代码格式规范 |
37 | | -- [Pyright](https://github.com/Microsoft/pyright/): 静态类型检查 |
| 29 | +```shell |
| 30 | +# Init pre-commit |
| 31 | +# https://pre-commit.com/#3-install-the-git-hook-scripts |
| 32 | +pre-commit install |
| 33 | +pre-commit run --all-files |
38 | 34 |
|
39 | | -您需要通过以上检查，`pre-commit` 会确保这点。 |
| 35 | +# https://hatch.pypa.io/latest/environment/ |
| 36 | +hatch shell |
| 37 | +``` |
40 | 38 |
|
41 | | -你也可以[手动检查](./scripts/lint.sh)和[自动修复](./scripts/format.sh)。 |
| 39 | +That's all! Now, you can start to develop. |
42 | 40 |
|
43 | | -> **Note** |
44 | | -> `Pyright`检查将发生两次 |
45 | | -> |
46 | | -> - 在`pre-commit`中，`Pyright`不会检查第三方依赖，并且`python`版本为支持的最低版本 |
47 | | -> - 而在`Github Actions`或[手动检查](./scripts/lint.sh)中，`Pyright`将在激活的虚拟环境中检查所有依赖 |
| 41 | +## Code style |
48 | 42 |
|
49 | | -## 代码测试 |
| 43 | +The source code is in `src/` |
50 | 44 |
|
51 | | -测试文件位于[./tests/](./tests/) |
| 45 | +We use [Ruff](https://github.com/astral-sh/ruff), [Blcak](https://github.com/psf/black), [Pyright](https://github.com/Microsoft/pyright/) |
| 46 | + and [Codespell](https://github.com/codespell-project/codespell) to check our code style and lint. |
52 | 47 |
|
53 | | -我们使用`pytest`来完成测试，测试将在`Github Actions`中进行。 |
| 48 | +Please check `pyproject.toml` to know our style. |
54 | 49 |
|
55 | | -你也可以[手动测试](./scripts/pytest.sh)。 |
| 50 | +If you want to format or lint-fix your code, you can use the following command: |
| 51 | + |
| 52 | +```shell |
| 53 | +hatch run lint |
| 54 | +``` |
| 55 | + |
| 56 | +or, with `pre-commit`: |
| 57 | + |
| 58 | +```shell |
| 59 | +pre-commit run -a |
| 60 | +``` |
| 61 | + |
| 62 | +or, dry run: |
| 63 | + |
| 64 | +```shell |
| 65 | +hatch run lint-check |
| 66 | +``` |
| 67 | + |
| 68 | +!!! tip |
| 69 | + If you use `VSCode`, we strongly recommend you to install the extensions in `.vscode/extensions.json`.<br> |
| 70 | + Because our code style rules are quite strict.<br> |
| 71 | + These extensions can help you know where need to be fixed when coding. |
| 72 | + |
| 73 | +## Testing |
| 74 | + |
| 75 | +We use [pytest](https://docs.pytest.org/en/stable/) to test our code. |
| 76 | + |
| 77 | +The test source code is in `tests/` |
| 78 | + |
| 79 | +You can run the testing with: |
| 80 | + |
| 81 | +```shell |
| 82 | +hatch run test |
| 83 | +``` |
| 84 | + |
| 85 | +## Documentation |
| 86 | + |
| 87 | +We use [mkdocs](https://www.mkdocs.org), [mkdocs-material](https://squidfunk.github.io/mkdocs-material), [mkdocstrings](https://mkdocstrings.github.io) to build our documentation. |
| 88 | + |
| 89 | +The documentation source code is in `docs/`, `mkdocs.yml`, |
| 90 | + may be there is also some source code in `scripts/` or somewhere (check `mkdocs.yml` to find that). |
| 91 | + |
| 92 | +Live-reloading docs: |
| 93 | + |
| 94 | +```shell |
| 95 | +hatch run docs:mkdocs serve |
| 96 | +``` |
| 97 | + |
| 98 | +Build docs: |
| 99 | + |
| 100 | +```shell |
| 101 | +hatch run docs:docs-build |
| 102 | +``` |
| 103 | + |
| 104 | +## PR |
| 105 | + |
| 106 | +- PRs should target the `main` branch. |
| 107 | +- Keep branches up to date by `rebase` before merging. |
| 108 | +- Do not add multiple unrelated things in same PR. |
| 109 | +- Do not submit PRs where you just take existing lines and reformat them without changing what they do. |
| 110 | +- Do not change other parts of the code that are not yours for formatting reasons. |
| 111 | +- Do not use your clone's main branch to make a PR - create a branch and PR that. |
| 112 | + |
| 113 | +### Edit `CHANGELOG.md` |
| 114 | + |
| 115 | +If you have made the corresponding changes, please record them in `CHANGELOG.md`. |
| 116 | + |
| 117 | +### Commit message convention |
| 118 | + |
| 119 | +Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), |
| 120 | +or, `pre-commit` may be reject your commit. |
| 121 | + |
| 122 | +!!! info |
| 123 | + If you don't know how to finish these, it's okay, feel free to initiate a PR, I will help you continue. |
| 124 | + |
| 125 | +## More |
| 126 | + |
| 127 | +There may still be some useful commands in `pyproject.toml`, you can refer to [hatch/environment/scripts](https://hatch.pypa.io/latest/config/environment/overview/#scripts) to use them. |
| 128 | + |
| 129 | +!!! info |
| 130 | + If you find that the commands given in the above examples are incorrect, please open an issue, we greatly appreciate it. |
| 131 | + |
| 132 | +--- |
| 133 | + |
| 134 | +## 😢 |
| 135 | + |
| 136 | +!!! warning |
| 137 | + The following 👇 content is for the maintainers of this project, may be you don't need to read it. |
| 138 | + |
| 139 | +--- |
| 140 | + |
| 141 | +## deploy-docs |
| 142 | + |
| 143 | +please refer to `.github/workflows/docs.yml` |
| 144 | + |
| 145 | +## CI: lint-test |
| 146 | + |
| 147 | +please refer to `.github/workflows/lint-test.yml` |
| 148 | + |
| 149 | +## CI: pre-commit-ci auto-update |
| 150 | + |
| 151 | +Every Monday, `pre-commit-ci` will send a PR for automatic hook version updates, which will trigger a local `ver_sync` hook. |
| 152 | + |
| 153 | +The `ver_sync` hook will maintain lint tools version consistency between `.pre-commit-config.yaml` and `pyproject.toml`. |
| 154 | + |
| 155 | +Please check whether the `ver_sync` works properly, then you can accept the PR. |
| 156 | + |
| 157 | +## Publish and Release 🚀 |
| 158 | + |
| 159 | +**^^First, edit `CHANGELOG.md` to record the changes.^^** |
| 160 | + |
| 161 | +Then, please refer to: |
| 162 | + |
| 163 | +- `.github/workflows/publish.yml` |
| 164 | +- <https://github.com/frankie567/hatch-regex-commit> |
| 165 | +- <https://hatch.pypa.io/latest/version/#updating> |
| 166 | + |
| 167 | +Update version with: |
| 168 | + |
| 169 | +```shell |
| 170 | +hatch version {new_version} |
| 171 | +``` |
| 172 | + |
| 173 | +It will create a commit and tag automatically, then, push the **tag** to GitHub. |
| 174 | + |
| 175 | +After that, the `publish.yml` workflow will build and publish the package to PyPI. |
| 176 | + |
| 177 | +> Don't forget to make a `approve` in environment `pypi` for the workflow. |
| 178 | +
|
| 179 | +Finally, edit the `draft release` created by `publish.yml` workflow, and publish the release. |
| 180 | + |
| 181 | +!!! warning |
| 182 | + The creating of tag needs signature verification,<br> |
| 183 | + please refer to <https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification> |
0 commit comments