From 2510a2a6c3818563fbc2d59615bc4a36b3160ce1 Mon Sep 17 00:00:00 2001 From: ADoyle Date: Fri, 20 Jan 2023 23:19:36 +0800 Subject: [PATCH] docs: update documents for CONTRIBUTING And fix keymap typo --- CONTRIBUTING.md | 56 +++++++++++++++++++++++--- CONTRIBUTING.zh.md | 58 +++++++++++++++++++++++++++ README.md | 18 ++------- README.zh.md | 21 ++-------- doc/dev/code-styles.md | 20 ++++++++++ doc/dev/dco.md | 89 ++++++++++++++++++++++++++++++++++++++++++ doc/dev/git-message.md | 55 ++++++++++++++++++++++++++ doc/{ => dev}/test.md | 0 doc/usage/keymaps.md | 4 +- 9 files changed, 283 insertions(+), 38 deletions(-) create mode 100644 CONTRIBUTING.zh.md create mode 100644 doc/dev/code-styles.md create mode 100644 doc/dev/dco.md create mode 100644 doc/dev/git-message.md rename doc/{ => dev}/test.md (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2dbaad3..1164ea0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,52 @@ -## How to contribute +# Contributing -- All code and text must be written in English. -- All commits must follow the [DCO](https://developercertificate.org/). -- Commit message must follow the [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/). -- [How to test](./doc/test.md) +## Any comments and suggestions are always welcome + +**Before opening new Issue/Discussion/PR, you should search related [Issues][issue]/[Discussions][discussion]/[PRs][PR] first** for avoiding to create duplicated links. + +- For new feature request, open a [discussion][], describe your demand concisely and clearly. +- For new feature submit, open a [PR][], describe your demand and design concisely and clearly. +- For bug report, open an [issue][], describe the bug concisely and clearly. +- For bug fix, open a [PR][], concisely and clearly describe what you fixed. +- For question and suggestion, open a [discussion][]. +- For anything not mentioned above, open a [discussion][]. + +### No +1 + +Do not post duplicated and useless comments like `+1`, `LOL`, `Me too`, `I too would like to see this issue fixed.`, `When is this issue going to be fixed?`. + +Such comments do not help fix issues. Please don't be offended if project admins delete such comments. + +Please [react to comments with emoji][github-reaction] instead of. + +### Use English AMAP + +For non-native English speakers, please communicate in English as much as possible. +It is recommended to use [DeepL Translator](https://www.deepl.com/translator). + +## Before making a Pull Request + +Read below links before making any contributions. + +- [Developer Certificate of Origin](./doc/dev/dco.md) +- [Code Styles](./doc/dev/code-styles.md) +- [Git Message Style](./doc/dev/git-message.md) +- [Test](./doc/dev/test.md) + +## Make a Pull Request + +All PRs should follow below conditions. + +- [ ] Git message is [valid](./doc/dev/git-message.md). +- [ ] Code style lint pass. +- [ ] Test cases all passed without errors. +- [ ] Squash one Git commit per PR. +- [ ] All git commits follow the [DCO](./doc/dev/dco.md). + + + + +[issue]: https://github.com/adoyle-h/one.nvim/issues +[discussion]: https://github.com/adoyle-h/one.nvim/discussions +[PR]: https://github.com/adoyle-h/one.nvim/pulls +[github-reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/ diff --git a/CONTRIBUTING.zh.md b/CONTRIBUTING.zh.md new file mode 100644 index 0000000..dac778a --- /dev/null +++ b/CONTRIBUTING.zh.md @@ -0,0 +1,58 @@ +# Contributing + +## 提建议，修 Bug，做贡献 + +欢迎提供任何建议或者意见。 + +**在创建新的 Issue/Discussion/PR 之前，你必须先搜索相关 [Issue][]/[Discussion][]/[PR][]**，避免创建重复的链接。 + +- 请求新功能。请开一个 [discussion][]，简短且清晰地描述你的需求。 +- 提交新功能。请开一个 [PR][]，简短且清晰地描述你的需求和设计。 +- 报告 BUG。请开一个 [issue][]，简短且清晰地描述你发现的问题。 +- 修复 BUG。请开一个 [PR][]，简短且清晰地描述你修了什么。 +- 提问和建议。请开一个 [discussion][]。 +- 其他上面未提到的内容，请开一个 [discussion][] 来讨论。 + +### 禁止 +1 + +不要发重复或无用的内容，比如 `+1`，`哈哈`，`附议`，`我希望这问题能够得到修复`，`这问题啥时候修好？`。 + +这样的评论无助于问题的解决。如果项目管理员删除了此类评论，请别生气。 + +请[贴 emoji 标签反馈到评论上](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/)。 + +### 尽量用英文 + +对于非英语母语的人，请尽可能使用英语交流。 +推荐使用 [DeepL Translator](https://www.deepl.com/translator)。 + +你也可以使用中文反馈意见。不过希望你尽可能使用英文。 +因为我们处于国际社区，英文更通用，方便外国人阅读理解你的意见。 +注意不要中英文混杂（专业词汇除外），请写完整的英文或中文语句。 + +## 创建 Pull Request 之前 + +在做贡献之前，请阅读以下链接。 + +- [Developer Certificate of Origin](./doc/dev/dco.md) +- [Code Styles](./doc/dev/code-styles.md) +- [Git Message Style](./doc/dev/git-message.md) +- [Test](./doc/dev/test.md) + +## 创建 Pull Request + +所有 PR 必须遵守以下条件。 + +- [ ] Git message 必须[有效](./doc/dev/git-message.md)。 +- [ ] 代码风格检查通过。 +- [ ] 测试案例全部通过，无 error。 +- [ ] 每个 PR 只有一个 Git commit。 +- [ ] 所有 git commit 都已签署 [DCO](./doc/dev/dco.md)。 + + + + +[issue]: https://github.com/adoyle-h/one.nvim/issues +[discussion]: https://github.com/adoyle-h/one.nvim/discussions +[PR]: https://github.com/adoyle-h/one.nvim/pulls +[github-reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/ diff --git a/README.md b/README.md index 28d7a0a..dcb4570 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,8 @@ All-in-one neovim configuration framework implemented with Lua. It is highly fle Click to expend/collapse plugin list - Plugin Manager: [vim-plug](lua/one/plugin-manager/vim-plug.lua) (default) or [packer](lua/one/plugin-manager/packer.lua) + - Vim Options: [vim-options](lua/one/plugins/vim-options.lua) + - Utilities: [plenary](https://github.com/nvim-lua/plenary.nvim) and [Penlight](https://github.com/lunarmodules/Penlight) and [nui](https://github.com/MunifTanjim/nui.nvim) - Dashboard: [alpha.nvim](lua/one/plugins/alpha.lua) - Outline: [aerial](lua/one/plugins/aerial.lua) (default) or [majutsushi/tagbar](lua/one/plugins/tagbar.lua) - File Explorer: [neo-tree](lua/one/plugins/neo-tree.lua) (default) or [nerdtree](lua/one/plugins/nerdtree.lua) or [nvim-tree](lua/one/plugins/nvim-tree.lua) @@ -74,6 +76,7 @@ All-in-one neovim configuration framework implemented with Lua. It is highly fle - Color Highlighter: [ccc.nvim](lua/one/plugins/colors/ccc.lua) (default) or [vim-hexokinase](lua/one/plugins/colors/hexokinase.lua) or [nvim-colorizer](lua/one/plugins/colors/colorizer.lua) - Translation: [translate.nvim](lua/one/plugins/translate.lua) - [Games](lua/one/plugins/funny.lua) + - one.nvim enhanced plugin: [one](lua/one/plugins/one.lua) @@ -255,20 +258,7 @@ Enable [profiling](./lua/one/plugins/profiling.lua) plugin, and invoke `:Startup ## Suggestion, Bug Reporting, Contributing -Any comments and suggestions are always welcome. - -**Before open an issue/discussion/PR, You should search related [issue][]/[discussion][]/[PR][] first** for avoiding to create duplicated links. - -- For new feature request, open a [discussion][], describe your demand concisely and clearly. -- For new feature submit, open a [PR][], describe your demand and design concisely and clearly. -- For bug report, open an [issue][], describe the bug concisely and clearly. -- For bug fix, open a [PR][], concisely and clearly describe what you fixed. -- For question and suggestion, open a [discussion][]. -- For anything not mentioned above, open a [discussion][]. - -Do not post duplicated and useless contents like `+1`, `LOL`. React to comments with emoji instead of. - -And read [how to contribute](CONTRIBUTING.md). +Please read [./CONTRIBUTING.md](./CONTRIBUTING.md) before opening new Issue/Discussion/PR and posting any comments. ## Copyright and License diff --git a/README.zh.md b/README.zh.md index d8bc0a6..f427c3d 100644 --- a/README.zh.md +++ b/README.zh.md @@ -17,6 +17,8 @@ Click [./README.md](./README.md) to read English documents. 点击展开/折叠插件列表 - 插件管理器: [vim-plug](lua/one/plugin-manager/vim-plug.lua) (默认) 或 [packer](lua/one/plugin-manager/packer.lua) + - Vim 选项: [vim-options](lua/one/plugins/vim-options.lua) + - 工具函数: [plenary](https://github.com/nvim-lua/plenary.nvim) 和 [Penlight](https://github.com/lunarmodules/Penlight) 和 [nui](https://github.com/MunifTanjim/nui.nvim) - 面板: [alpha.nvim](lua/one/plugins/alpha.lua) - 大纲: [aerial](lua/one/plugins/aerial.lua) (默认) 或 [majutsushi/tagbar](lua/one/plugins/tagbar.lua) - 文件浏览器: [neo-tree](lua/one/plugins/neo-tree.lua) (默认) 或 [nerdtree](lua/one/plugins/nerdtree.lua) 或 [nvim-tree](lua/one/plugins/nvim-tree.lua) @@ -74,6 +76,7 @@ Click [./README.md](./README.md) to read English documents. - 颜色着色: [ccc.nvim](lua/one/plugins/colors/ccc.lua) (默认) 或 [vim-hexokinase](lua/one/plugins/colors/hexokinase.lua) 或 [nvim-colorizer](lua/one/plugins/colors/colorizer.lua) - 翻译: [translate.nvim](lua/one/plugins/translate.lua) - [游戏](lua/one/plugins/funny.lua) + - One.nvim 增强插件: [one](lua/one/plugins/one.lua) @@ -255,23 +258,7 @@ require('one').setup { ## 提建议，修 Bug，做贡献 -欢迎提供任何建议或者意见。 - -**在开 issue/discussion/PR 之前，你必须先搜索相关 [issue][]/[discussion][]/[PR][]**，避免创建重复的链接。 - -- 请求新功能。请开一个 [discussion][]，简短且清晰地描述你的需求。 -- 提交新功能。请开一个 [PR][]，简短且清晰地描述你的需求和设计。 -- 报告 BUG。请开一个 [issue][]，简短且清晰地描述你发现的问题。 -- 修复 BUG。请开一个 [PR][]，简短且清晰地描述你修了什么。 -- 提问和建议。请开一个 [discussion][]。 -- 其他上面未提到的内容，请开一个 [discussion][] 来讨论。 - -不要发重复或无用的内容，比如 `+1`，`哈哈`。请贴 emoji 标签反馈到评论上。 - -你可以使用中文反馈意见。但希望你尽可能使用英文，不要中英文混杂，而是写下完整的英文语句。 -因为我们处于国际社区，英文更通用，方便外国人阅读理解你的意见。 - -请阅读[如何为本项目贡献](./CONTRIBUTING.md)。 +在创建新的 Issue/Discussion/PR，以及发表评论之前，请先阅读 [./CONTRIBUTING.zh.md](./CONTRIBUTING.zh.md)。 ## 版权声明 diff --git a/doc/dev/code-styles.md b/doc/dev/code-styles.md new file mode 100644 index 0000000..1363ed3 --- /dev/null +++ b/doc/dev/code-styles.md @@ -0,0 +1,20 @@ +# Code Styles + +## First of all + +- Your IDE must support [editorconfig](http://editorconfig.org/) and recognize the [`.editorconfig`](./.editorconfig) file in project. +- All code and text must be written in English. + +## File naming + +All file names must match the regex `[a-z0-9-_]`, except `Dockerfile` and other particular files. + +## Shell script code styles + +- `[[ ... ]]` is preferred over `[ ... ]`, `test` and `/usr/bin/[`. +- Function declaration `func() {...}` is preferred over `function func() {...}`. +- Read-only Variables. Use `readonly` or `declare -r` to ensure they're read only. +- Local Variables. Declare function-specific variables with `local`. Declaration and assignment should be on different lines. +- Use `$(command)` instead of backticks. +- `eval` should be avoided in most scenarios. +- Constants and environment variable names must be all caps, separated with underscores. diff --git a/doc/dev/dco.md b/doc/dev/dco.md new file mode 100644 index 0000000..525ff3a --- /dev/null +++ b/doc/dev/dco.md @@ -0,0 +1,89 @@ +# Developer Certificate of Origin + +The project uses a mechanism known as a Developer Certificate of Origin (DCO) to manage process. + +A DCO is a lightweight way for a developer to certify that they wrote or otherwise have the right +to submit code or documentation to a project. The way a developer does this is by adding +a Signed-off-by line to a commit. When they do this they are agreeing to the DCO. + +The full text of the DCO can be found at https://developercertificate.org . It reads: + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +1 Letterman Drive +Suite D4700 +San Francisco, CA, 94129 + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +If you are willing to agree to these terms, you just add a line to every git commit message: + +``` +Signed-off-by: Some Developer somedev@example.com +``` + +If you set your user.name and user.email as part of your git configuration, +you can sign your commit automatically with `git commit -sS`. + +An example signed commit message might look like: + +``` +An example commit message + +Signed-off-by: Some Developer somedev@example.com +``` + +If more than one person works on something it’s possible for more than one person to sign off on it. For example, + +``` +An example commit message + +Signed-off-by: Some Developer somedev@example.com +Signed-off-by: Another Developer anotherdev@example.com +``` + + +See `git help commit`, + +``` +-s, --signoff + Add Signed-off-by line by the committer at the end of the commit log message. The meaning of a signoff depends on the + project, but it typically certifies that committer has the rights to submit this work under the same license and + agrees to a Developer Certificate of Origin (see http://developercertificate.org/ for more information). + +-S[], --gpg-sign[=] + GPG-sign commits. The keyid argument is optional and defaults to the committer identity; if specified, it must be + stuck to the option without a space. +``` diff --git a/doc/dev/git-message.md b/doc/dev/git-message.md new file mode 100644 index 0000000..e30d7b9 --- /dev/null +++ b/doc/dev/git-message.md @@ -0,0 +1,55 @@ +# Git Commit Message Style + +Generally follows the [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/). + +## Commit Message Format + +``` +[(scope)][!]: + +[optional body] + +[optional footer] +``` + +`[(scope)]` is optional. + +## Type + +Must be one of the following: + +- **build**: Changes that affect the build system or external dependencies +- **ci**: Changes to our CI configuration files and scripts +- **docs**: Documentation only changes +- **feat**: A new feature +- **fix**: A bug fix +- **perf**: A code change that improves performance +- **refactor**: A code change that neither fixes a bug nor adds a feature +- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) +- **test**: Adding missing tests or correcting existing tests +- **chore**: Other changes that don't modify src or test files + + +## Breaking Change + +Commit message with optional `!` to draw attention to breaking change. + +``` +chore!: drop Node 6 from testing matrix + +BREAKING CHANGE: dropping Node 6 which hits end of life in April +``` + +A commit that has the text `BREAKING CHANGE:` at the beginning of its optional body or footer section +introduces a breaking API change (correlating with MAJOR in semantic versioning). +A BREAKING CHANGE can be part of commits of any type. + +## Sign the DCO for PR + +Please sign our Developer Certificate of Origin (DCO) before sending pull requests. For any code changes to be accepted, the DCO must be signed. It's very simple. See [this document](./dco.md). + +## Squash git commits for PR + +Each Pull Request should do one thing in only one commit. + +You can use `git rebase -i` to squash some commits into one. diff --git a/doc/test.md b/doc/dev/test.md similarity index 100% rename from doc/test.md rename to doc/dev/test.md diff --git a/doc/usage/keymaps.md b/doc/usage/keymaps.md index 46dd8c0..3be3d99 100644 --- a/doc/usage/keymaps.md +++ b/doc/usage/keymaps.md @@ -278,8 +278,8 @@ If bufferline plugin enabled, some keymaps will be overridden. See [Buffer Line] - `` = Focus to previous window - `p` = Focus to last accessed window. - `q` = Close current window -- `|` = Open split window -- `\` or `n` = Open vsplit window +- `|` = Open window (vsplit) +- `\` or `n` = Open window (split) - `r` = Enter window resize mode - `h` = Focus to left window - `j` = Focus to bottom window